Dates

A Date property or type argument is forged as a random date inside the configured window — by default between 2000-01-01 and 4000-01-01.

Basic usage

interface Order { createdAt: Date; deliveredAt?: Date }

const order = Forger.create<Order>()!;
// { createdAt: Date('2093-08-14T07:19:22'), deliveredAt: Date('2035-03-21T22:46:56') }

const anyDate = Forger.create<Date>()!;

Constraining the window

dateMin and dateMax are inclusive bounds; both accept Date instances or strings:

const birthday = Forger.create<Date>({
  dateMin: new Date(1990, 0, 1),
  dateMax: new Date(2000, 11, 31),
})!;

const in2020 = Forger.create<Date>({
  dateMin: '2020-01-01',
  dateMax: '2020-12-31',
})!;

String bounds are converted to dates at generation time, so JSON-friendly settings objects work out of the box.

Inverted ranges are fixed, not thrown

If dateMin is after dateMax, Forger widens the range: the maximum becomes dateMin + 24 hours. A misconfigured window therefore still produces a valid date:

const oops = Forger.create<Date>({
  dateMin: new Date(2030, 0, 1),
  dateMax: new Date(2020, 0, 1),
})!;
// a date within [2030-01-01, 2030-01-02]

Relative windows

Because settings are plain objects, windows can be computed per test:

const lastWeek = () => ({
  dateMin: new Date(Date.now() - 7 * 24 * 3600 * 1000),
  dateMax: new Date(),
});

const event = Forger.create<Event>(lastWeek())!;

More recipes: Cookbook. Full option reference: Date settings.

08 September 2026