Faker

Appearance

Date ​

Module to generate dates.

Overview ​

To quickly generate a date in the past, use recent() (last day) or past() (last year). To quickly generate a date in the future, use soon() (next day) or future() (next year). For a realistic birthdate for an adult, use birthdate().

For more control, any of these methods can be customized with further options, or use between() to generate a single date between two dates, or betweens() for multiple dates.

If you need to generate a date range (start-end), you can do so using either of these two methods:

  • const start = faker.date.soon(); const end = faker.date.soon({ refDate: start });
  • const [start, end] = faker.date.betweens({ from, to, count: 2 }); // does not work with tsconfig's noUncheckedIndexedAccess: true

Dates can be specified as Javascript Date objects, strings or UNIX timestamps. For example to generate a date between 1st January 2000 and now, use:

ts
faker.date.between({ from: '2000-01-01', to: Date.now() });

You can generate random localized month and weekday names using month() and weekday().

These methods have additional concerns about reproducibility, see Reproducible Results.

anytime ​

Generates a random date that can be either in the past or in the future.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

Returns: Date

ts
function anytime(
  options: {
    refDate?: string | Date | number;
  } = {}
): Date;

Examples

ts
faker.date.anytime() // '2022-07-31T01:33:29.567Z'

between ​

Generates a random date between the given boundaries.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }

The options object.

options.fromstring | number | Date

The early date boundary.

options.tostring | number | Date

The late date boundary.

Returns: Date

Throws: If from or to are not provided. If from is after to.

ts
function between(options: {
  from: string | Date | number;
  to: string | Date | number;
}): Date;

Examples

ts
faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'

betweens ​

Generates random dates between the given boundaries. The dates will be returned in an array sorted in chronological order.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }

The options object.

options.count?number | { min: number; max: number; }3

The number of dates to generate.

options.fromstring | number | Date

The early date boundary.

options.tostring | number | Date

The late date boundary.

Returns: Date[]

Throws: If from or to are not provided. If from is after to.

ts
function betweens(options: {
  from: string | Date | number;
  to: string | Date | number;
  count?:
    | number
    | {
        min: number;
        max: number;
      };
}): Date[];

Examples

ts
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })
// [
//   2022-07-02T06:00:00.000Z,
//   2024-12-31T12:00:00.000Z,
//   2027-07-02T18:00:00.000Z
// ]
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
// [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: { min: 2, max: 5 }})
// [
//   2021-12-19T06:35:40.191Z,
//   2022-09-10T08:03:51.351Z,
//   2023-04-19T11:41:17.501Z
// ]

birthdate ​

Returns a random birthdate. By default, the birthdate is generated for an adult between 18 and 80 years old. But you can customize the 'age' range or the 'year' range to generate a more specific birthdate.

Available since v7.0.0

Parameters

NameTypeDefaultDescription
options?{ ... } | { ... }{}

The options to use to generate the birthdate.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

options.maxnumber

The maximum age/year to generate a birthdate for/in.

options.minnumber

The minimum age/year to generate a birthdate for/in.

options.mode'age' | 'year'

Either 'age' or 'year' to generate a birthdate based on the age or year range.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date. Only used when mode is 'age'.

Returns: Date

ts
function birthdate(
  options?:
    | {
        refDate?: string | Date | number;
      }
    | {
        mode: 'age' | 'year';
        min: number;
        max: number;
        refDate?: string | Date | number;
      }
): Date;

Examples

ts
faker.date.birthdate() // 1977-07-10T01:37:30.719Z
faker.date.birthdate({ mode: 'age', min: 18, max: 65 }) // 2003-11-02T20:03:20.116Z
faker.date.birthdate({ mode: 'year', min: 1900, max: 2000 }) // 1940-08-20T08:53:07.538Z

future ​

Generates a random date in the future.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

options.years?number1

The range of years the date may be in the future.

Returns: Date

ts
function future(
  options: {
    years?: number;
    refDate?: string | Date | number;
  } = {}
): Date;

Examples

ts
faker.date.future() // '2022-11-19T05:52:49.100Z'
faker.date.future({ years: 10 }) // '2030-11-23T09:38:28.710Z'
faker.date.future({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-12-13T22:45:10.252Z'

month ​

Returns a random name of a month.

Available since v3.0.1

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options to use.

options.abbreviated?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

Whether to return the name of a month in the context of a date.

In the default en locale this has no effect, however, in other locales like fr or ru, this may affect grammar or capitalization, for example 'январь' with { context: false } and 'января' with { context: true } in ru.

Returns: string

ts
function month(
  options: {
    abbreviated?: boolean;
    context?: boolean;
  } = {}
): string;

Examples

ts
faker.date.month() // 'October'
faker.date.month({ abbreviated: true }) // 'Feb'
faker.date.month({ context: true }) // 'June'
faker.date.month({ abbreviated: true, context: true }) // 'Sep'

past ​

Generates a random date in the past.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

options.years?number1

The range of years the date may be in the past.

Returns: Date

ts
function past(
  options: {
    years?: number;
    refDate?: string | Date | number;
  } = {}
): Date;

Examples

ts
faker.date.past() // '2021-12-03T05:40:44.408Z'
faker.date.past({ years: 10 }) // '2017-10-25T21:34:19.488Z'
faker.date.past({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2017-08-18T02:59:12.350Z'

recent ​

Generates a random date in the recent past.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.days?number1

The range of days the date may be in the past.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

Returns: Date

ts
function recent(
  options: {
    days?: number;
    refDate?: string | Date | number;
  } = {}
): Date;

Examples

ts
faker.date.recent() // '2022-02-04T02:09:35.077Z'
faker.date.recent({ days: 10 }) // '2022-01-29T06:12:12.829Z'
faker.date.recent({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2019-12-27T18:11:19.117Z'

soon ​

Generates a random date in the near future.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options object.

options.days?number1

The range of days the date may be in the future.

options.refDate?string | number | Datefaker.defaultRefDate()

The date to use as reference point for the newly generated date.

Returns: Date

ts
function soon(
  options: {
    days?: number;
    refDate?: string | Date | number;
  } = {}
): Date;

Examples

ts
faker.date.soon() // '2022-02-05T09:55:39.216Z'
faker.date.soon({ days: 10 }) // '2022-02-11T05:14:39.138Z'
faker.date.soon({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-01-01T02:40:44.990Z'

timeZone ​

Returns a random IANA time zone name.

The returned time zone is not tied to the current locale.

Available since v9.0.0

Returns: string

ts
function timeZone(): string;

Examples

ts
faker.location.timeZone() // 'Pacific/Guam'

weekday ​

Returns a random day of the week.

Available since v3.0.1

Parameters

NameTypeDefaultDescription
options{ ... }{}

The optional options to use.

options.abbreviated?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

Whether to return the day of the week in the context of a date.

In the default en locale this has no effect, however, in other locales like fr or ru, this may affect grammar or capitalization, for example 'Lundi' with { context: false } and 'lundi' with { context: true } in fr.

Returns: string

ts
function weekday(
  options: {
    abbreviated?: boolean;
    context?: boolean;
  } = {}
): string;

Examples

ts
faker.date.weekday() // 'Monday'
faker.date.weekday({ abbreviated: true }) // 'Thu'
faker.date.weekday({ context: true }) // 'Thursday'
faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'

Released under the MIT License.

Copyright © 2022-present Faker.