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.
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
Name | Type | Default | Description |
---|---|---|---|
options | { ... } | {} | The optional options object. |
options.refDate? | Date | number | string | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
Returns: Date
faker.date.anytime(options: {
refDate: Date | number | string
} = {}): Date
faker.date.anytime() // '2022-07-31T01:33:29.567Z'
See Also
Source
between
Generates a random date between the given boundaries.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options | Date | number | string | { ... } | The optional options object. | |
options.from | Date | number | string | The early date boundary. | |
options.to | Date | number | string | The late date boundary. | |
legacyTo? | Date | number | string | Deprecated, use |
Returns: Date
faker.date.between(options: Date | number | string | {
from: Date | number | string,
to: Date | number | string
}, legacyTo?: Date | number | string): Date
faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'
Source
betweens
Generates random dates between the given boundaries.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options | Date | number | string | { ... } | The optional options object. | |
options.count? | number | { max: number, min: number } | 3 | The number of dates to generate. |
options.from | Date | number | string | The early date boundary. | |
options.to | Date | number | string | The late date boundary. | |
legacyTo? | Date | number | string | Deprecated, use | |
legacyCount? | number | 3 | Deprecated, use |
Returns: Date[]
faker.date.betweens(options: Date | number | string | {
count: number | {
max: number,
min: number
},
from: Date | number | string,
to: Date | number | string
}, legacyTo?: Date | number | string, legacyCount?: number = 3): Date[]
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
// ]
Source
birthdate
Returns a random birthdate.
Available since v7.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
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 | 80 | The maximum age or year to generate a birthdate. |
options.min? | number | 18 | The minimum age or year to generate a birthdate. |
options.mode? | 'age' | 'year' | 'year' | The mode to generate the birthdate. Supported modes are There are two modes available
|
options.refDate? | Date | number | string | faker.defaultRefDate() | 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() // 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
Source
future
Generates a random date in the future.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | number | { ... } | {} | The optional options object. |
options.refDate? | Date | number | string | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
options.years? | number | 1 | The range of years the date may be in the future. |
legacyRefDate? | Date | number | string | Deprecated, use |
Returns: Date
faker.date.future(options?: number | {
refDate: Date | number | string,
years: number
} = {}, legacyRefDate?: Date | number | string): Date
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'
Source
month
Returns a random name of a month.
Available since v3.0.1
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | { ... } | {} | The optional options to use. |
options.abbr? | boolean | false | Whether to return an abbreviation. DEPRECATED: Use |
options.abbreviated? | boolean | false | Whether to return an abbreviation. |
options.context? | boolean | false | Whether to return the name of a month in the context of a date. In the default |
Returns: string
faker.date.month(options?: {
abbr: boolean,
abbreviated: boolean,
context: boolean
} = {}): string
faker.date.month() // 'October'
faker.date.month({ abbreviated: true }) // 'Feb'
faker.date.month({ context: true }) // 'June'
faker.date.month({ abbreviated: true, context: true }) // 'Sep'
Source
past
Generates a random date in the past.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | number | { ... } | {} | The optional options object. |
options.refDate? | Date | number | string | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
options.years? | number | 1 | The range of years the date may be in the past. |
legacyRefDate? | Date | number | string | Deprecated, use |
Returns: Date
faker.date.past(options?: number | {
refDate: Date | number | string,
years: number
} = {}, legacyRefDate?: Date | number | string): Date
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'
Source
recent
Generates a random date in the recent past.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | number | { ... } | {} | The optional options object. |
options.days? | number | 1 | The range of days the date may be in the past. |
options.refDate? | Date | number | string | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
legacyRefDate? | Date | number | string | Deprecated, use |
Returns: Date
faker.date.recent(options?: number | {
days: number,
refDate: Date | number | string
} = {}, legacyRefDate?: Date | number | string): Date
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'
Source
soon
Generates a random date in the near future.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | number | { ... } | {} | The optional options object. |
options.days? | number | 1 | The range of days the date may be in the future. |
options.refDate? | Date | number | string | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
legacyRefDate? | Date | number | string | Deprecated, use |
Returns: Date
faker.date.soon(options?: number | {
days: number,
refDate: Date | number | string
} = {}, legacyRefDate?: Date | number | string): Date
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'
Source
weekday
Returns a random day of the week.
Available since v3.0.1
Parameters
Name | Type | Default | Description |
---|---|---|---|
options? | { ... } | {} | The optional options to use. |
options.abbr? | boolean | false | Whether to return an abbreviation. DEPRECATED: Use |
options.abbreviated? | boolean | false | Whether to return an abbreviation. |
options.context? | boolean | false | Whether to return the day of the week in the context of a date. In the default |
Returns: string
faker.date.weekday(options?: {
abbr: boolean,
abbreviated: boolean,
context: boolean
} = {}): string
faker.date.weekday() // 'Monday'
faker.date.weekday({ abbreviated: true }) // 'Thu'
faker.date.weekday({ context: true }) // 'Thursday'
faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'