Date

Module to generate dates.

Between

Generates a random date between the given boundaries.

Parameters

NameTypeDefaultDescription
fromDate | number | string

The early date boundary.

toDate | number | string

The late date boundary.

Returns: Date

faker.date.between(from: Date | number | string, to: Date | number | string): Date
faker.date.between() // => "2022-05-27T07:18:29.825Z"
faker.date.between('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z') // '2026-05-16T02:22:53.002Z'

Betweens

Generates n random dates between the given boundaries.

Parameters

NameTypeDefaultDescription
fromDate | number | string

The early date boundary.

toDate | number | string

The late date boundary.

numnumber3

The number of dates to generate.

Returns: Date[]

faker.date.betweens(from: Date | number | string, to: Date | number | string, num: number = 3): Date[]
faker.date.betweens() // => ["2022-05-27T07:18:29.826Z","2022-05-27T07:18:2...
faker.date.betweens('2020-01-01T00:00:00.000Z', '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('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z', 2)
// [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]

Birthdate

Returns a random birthdate.

Parameters

NameTypeDefaultDescription
options{ ... }{}

The options to use to generate the birthdate. If no options are set, an age between 18 and 80 (inclusive) is generated.

options.max?number

The maximum age or year to generate a birthdate.

options.min?number

The minimum age or year to generate a birthdate.

options.mode?'age' | 'year'year

The mode to generate the birthdate. Supported modes are 'age' and 'year' .

There are two modes available 'age' and 'year':

  • 'age': The min and max options define the age of the person (e.g. 18 - 42).
  • 'year': The min and max options define the range the birthdate may be in (e.g. 1900 - 2000).
options.refDate?Date | number | stringnow

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

Returns: Date

faker.date.birthdate(options: {
  max: number,
  min: number,
  mode: 'age' | 'year',
  refDate: Date | number | string
} = {}): Date
faker.date.birthdate() // => "1976-07-29T02:25:31.672Z"
faker.date.birthdate() // 1977-07-10T01:37:30.719Z
faker.date.birthdate({ min: 18, max: 65, mode: 'age' }) // 2003-11-02T20:03:20.116Z
faker.date.birthdate({ min: 1900, max: 2000, mode: 'year' }) // 1940-08-20T08:53:07.538Z

Future

Generates a random date in the future.

Parameters

NameTypeDefaultDescription
years?number1

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

refDate?Date | number | string

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

Returns: Date

faker.date.future(years?: number = 1, refDate?: Date | number | string): Date
faker.date.future() // => "2022-12-13T14:54:52.900Z"
faker.date.future() // '2022-11-19T05:52:49.100Z'
faker.date.future(10) // '2030-11-23T09:38:28.710Z'
faker.date.future(10, '2020-01-01T00:00:00.000Z') // '2020-12-13T22:45:10.252Z'

Month

Returns a random name of a month.

Parameters

NameTypeDefaultDescription
options?{ ... }

The optional options to use.

options.abbr?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

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

Returns: string

faker.date.month(options?: {
  abbr: boolean,
  context: boolean
}): string
faker.date.month() // => "July"
faker.date.month() // 'October'
faker.date.month({ abbr: true }) // 'Feb'
faker.date.month({ context: true }) // 'June'
faker.date.month({ abbr: true, context: true }) // 'Sep'

Past

Generates a random date in the past.

Parameters

NameTypeDefaultDescription
years?number1

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

refDate?Date | number | string

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

Returns: Date

faker.date.past(years?: number = 1, refDate?: Date | number | string): Date
faker.date.past() // => "2021-11-07T23:42:06.783Z"
faker.date.past() // '2021-12-03T05:40:44.408Z'
faker.date.past(10) // '2017-10-25T21:34:19.488Z'
faker.date.past(10, '2020-01-01T00:00:00.000Z') // '2017-08-18T02:59:12.350Z'

Recent

Generates a random date in the recent past.

Parameters

NameTypeDefaultDescription
days?number1

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

refDate?Date | number | string

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

Returns: Date

faker.date.recent(days?: number = 1, refDate?: Date | number | string): Date
faker.date.recent() // => "2022-05-26T18:08:11.906Z"
faker.date.recent() // '2022-02-04T02:09:35.077Z'
faker.date.recent(10) // '2022-01-29T06:12:12.829Z'
faker.date.recent(10, '2020-01-01T00:00:00.000Z') // '2019-12-27T18:11:19.117Z'

Soon

Generates a random date in the near future.

Parameters

NameTypeDefaultDescription
days?number1

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

refDate?Date | number | string

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

Returns: Date

faker.date.soon(days?: number = 1, refDate?: Date | number | string): Date
faker.date.soon() // => "2022-05-27T20:28:47.783Z"
faker.date.soon() // '2022-02-05T09:55:39.216Z'
faker.date.soon(10) // '2022-02-11T05:14:39.138Z'
faker.date.soon(10, '2020-01-01T00:00:00.000Z') // '2020-01-01T02:40:44.990Z'

Weekday

Returns a random day of the week.

Parameters

NameTypeDefaultDescription
options?{ ... }

The optional options to use.

options.abbr?booleanfalse

Whether to return an abbreviation.

options.context?booleanfalse

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

Returns: string

faker.date.weekday(options?: {
  abbr: boolean,
  context: boolean
}): string
faker.date.weekday() // => "Wednesday"
faker.date.weekday() // 'Monday'
faker.date.weekday({ abbr: true }) // 'Thu'
faker.date.weekday({ context: true }) // 'Thursday'
faker.date.weekday({ abbr: true, context: true }) // 'Fri'