Introduction

@nestjstools/clock

Time abstraction for NestJS

In most applications, time is everywhere:

• timestamps

• expiration logic

• domain rules

• logging

• validations

• comparisons

But calling new Date() directly inside your business logic makes your system:

• Hard to test

• Non-deterministic

• Infrastructure-coupled

• Difficult to reason about

@nestjstools/clock solves this by introducing a clean abstraction over time.

Why use Clock?

Instead of:

const now = new Date();

You write:

const now = this.clock.now();

And now:

• You can inject time

• You can freeze time in tests

• You remove infrastructure concerns from your domain layer

The Problem with new Date()

Direct system time usage:

if (new Date() > expirationDate) { ... }

Creates:

• Hidden side effects

• Hard-to-test services

• Unpredictable unit tests

• Tight coupling to system clock

Time is infrastructure — it should be abstracted.

---

The Solution: IClock

Clock introduces a simple interface:

interface IClock {
  now(): Date
  today(): CalendarDate
}

This allows you to:

• Inject system time

• Replace time in tests