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.
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:
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
Name | Type | Default | Description |
---|---|---|---|
options | { ... } | {} | The optional options object. |
options.refDate? | string | number | Date | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
Returns: Date
function anytime(
options: {
refDate?: string | Date | number;
} = {}
): Date;
Examples
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 | { ... } | The options object. | |
options.from | string | number | Date | The early date boundary. | |
options.to | string | number | Date | The late date boundary. |
Returns: Date
Throws: If from
or to
are not provided.
If from
is after to
.
function between(options: {
from: string | Date | number;
to: string | Date | number;
}): Date;
Examples
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. The dates will be returned in an array sorted in chronological order.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options | { ... } | The options object. | |
options.count? | number | { min: number; max: number; } | 3 | The number of dates to generate. |
options.from | string | number | Date | The early date boundary. | |
options.to | string | number | Date | The late date boundary. |
Returns: Date[]
Throws: If from
or to
are not provided.
If from
is after to
.
function betweens(options: {
from: string | Date | number;
to: string | Date | number;
count?:
| number
| {
min: number;
max: number;
};
}): Date[];
Examples
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. 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
Name | Type | Default | Description |
---|---|---|---|
options? | { ... } | { ... } | {} | The options to use to generate the birthdate. |
options.refDate? | string | number | Date | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
options.max | number | The maximum age/year to generate a birthdate for/in. | |
options.min | number | The minimum age/year to generate a birthdate for/in. | |
options.mode | 'age' | 'year' | Either | |
options.refDate? | string | number | Date | faker.defaultRefDate() | The date to use as reference point for the newly generated date.
Only used when |
Returns: Date
function birthdate(
options?:
| {
refDate?: string | Date | number;
}
| {
mode: 'age' | 'year';
min: number;
max: number;
refDate?: string | Date | number;
}
): Date;
Examples
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
Source
future
Generates a random date in the future.
Available since v8.0.0
Parameters
Name | Type | Default | Description |
---|---|---|---|
options | { ... } | {} | The optional options object. |
options.refDate? | string | number | Date | 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. |
Returns: Date
function future(
options: {
years?: number;
refDate?: string | Date | number;
} = {}
): Date;
Examples
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.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
function month(
options: {
abbreviated?: boolean;
context?: boolean;
} = {}
): string;
Examples
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 | { ... } | {} | The optional options object. |
options.refDate? | string | number | Date | 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. |
Returns: Date
function past(
options: {
years?: number;
refDate?: string | Date | number;
} = {}
): Date;
Examples
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 | { ... } | {} | The optional options object. |
options.days? | number | 1 | The range of days the date may be in the past. |
options.refDate? | string | number | Date | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
Returns: Date
function recent(
options: {
days?: number;
refDate?: string | Date | number;
} = {}
): Date;
Examples
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 | { ... } | {} | The optional options object. |
options.days? | number | 1 | The range of days the date may be in the future. |
options.refDate? | string | number | Date | faker.defaultRefDate() | The date to use as reference point for the newly generated date. |
Returns: Date
function soon(
options: {
days?: number;
refDate?: string | Date | number;
} = {}
): Date;
Examples
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
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
function timeZone(): string;
Examples
faker.location.timeZone() // 'Pacific/Guam'
See Also
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.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
function weekday(
options: {
abbreviated?: boolean;
context?: boolean;
} = {}
): string;
Examples
faker.date.weekday() // 'Monday'
faker.date.weekday({ abbreviated: true }) // 'Thu'
faker.date.weekday({ context: true }) // 'Thursday'
faker.date.weekday({ abbreviated: true, context: true }) // 'Fri'