From 854f1e51d5ef0ad246f108b4917503421b43d185 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 11:15:01 +0100 Subject: [PATCH 1/7] docs: extend Faker class jsdocs --- src/faker.ts | 153 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 149 insertions(+), 4 deletions(-) diff --git a/src/faker.ts b/src/faker.ts index 2d6d2936fa9..e32bdc6eb0e 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -33,6 +33,29 @@ import { VehicleModule } from './modules/vehicle'; import { WordModule } from './modules/word'; import { mergeLocales } from './utils/merge-locales'; +/** + * The main Faker class containing all modules that can be used to generate data. + * + * Please have a look at the individual modules and methods for more information and examples. + * + * @example + * import { faker } from '@fakerjs/faker'; + * // const { faker } = require('@fakerjs/faker'); + * + * // faker.seed(1234); + * + * faker.person.firstName(); // 'John' + * faker.person.lastName(); // 'Doe' + * + * @example + * import { Faker, de } from '@fakerjs/faker'; + * // const { Faker, de } = require('@fakerjs/faker'); + * + * const customFaker = new Faker({ locale: [de] }); + * + * customFaker.person.firstName(); // 'Max' + * customFaker.person.lastName(); // 'Baumeister' + */ export class Faker { readonly definitions: LocaleDefinition; private _defaultRefDate: () => Date = () => new Date(); @@ -50,6 +73,15 @@ export class Faker { * @param dateOrSource The function or the static value used to generate the `refDate` date instance. * The function must return a new valid `Date` instance for every call. * Defaults to `() => new Date()`. + * + * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results) + * @see faker.seed() for reproducible results. + * + * @example + * faker.seed(1234); + * faker.date.past(); // Changes based on the current date + * faker.setDefaultRefDate(() => new Date('2020-01-01')); + * faker.date.past(); // Reproducible '2019-07-03T08:27:58.118Z' */ setDefaultRefDate( dateOrSource: string | Date | number | (() => Date) = () => new Date() @@ -124,8 +156,23 @@ export class Faker { /** * Creates a new instance of Faker. * + * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ... + * + * You only need to use the constructor if you need custom fallback logic or a custom locale. + * + * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html). + * * @param options The options to use. * @param options.locale The locale data to use. + * + * @example + * import { Faker, de } from '@fakerjs/faker'; + * // const { Faker, de } = require('@fakerjs/faker'); + * + * const customFaker = new Faker({ locale: [de] }); + * + * customFaker.person.firstName(); // 'Max' + * customFaker.person.lastName(); // 'Baumeister' */ constructor(options: { /** @@ -139,9 +186,16 @@ export class Faker { /** * Creates a new instance of Faker. * + * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ... + * + * You only need to use the constructor if you need custom fallback logic or a custom locale. + * + * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html). + * * @param options The options to use. * @param options.locales The locale data to use. - * @param options.locale The locale data to use. + * @param options.locale The name of the main locale to use. + * @param options.localeFallback The name of the fallback locale to use. * * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead. */ @@ -151,12 +205,56 @@ export class Faker { localeFallback?: string; }); // This is somehow required for `ConstructorParameters[0]` to work + /** + * Creates a new instance of Faker. + * + * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ... + * + * You only need to use the constructor if you need custom fallback logic or a custom locale. + * + * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html). + * + * @param options The options to use. + * @param options.locale The locale data to use or the name of the main locale. + * @param options.locales The locale data to use. + * @param options.localeFallback The name of the fallback locale to use. + * + * @example + * import { Faker, de } from '@fakerjs/faker'; + * // const { Faker, de } = require('@fakerjs/faker'); + * + * const customFaker = new Faker({ locale: [de] }); + * + * customFaker.person.firstName(); // 'Max' + * customFaker.person.lastName(); // 'Baumeister' + */ constructor( options: - | { locale: LocaleDefinition | LocaleDefinition[] } | { + /** + * The locale data to use for this instance. + * If an array is provided, the first locale that has a definition for a given property will be used. + * + * @see mergeLocales + */ + locale: LocaleDefinition | LocaleDefinition[]; + } + | { + /** + * DEPRECATED: The locale data to use for this instance. + */ locales: Record; + /** + * DEPRECATED: The name of the main locale to use. + * + * @default 'en' + */ locale?: string; + /** + * DEPRECATED: The name of the fallback locale to use. + * + * @default 'en' + */ localeFallback?: string; } ); @@ -221,6 +319,9 @@ export class Faker { * @param seed The seed to use. Defaults to a random number. * @returns The seed that was set. * + * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results) + * @see faker.setDefaultRefDate() when generating relative dates. + * * @example * // Consistent values for tests: * faker.seed(42) @@ -231,7 +332,6 @@ export class Faker { * faker.number.int(10); // 4 * faker.number.int(10); // 8 * - * @example * // Random but reproducible tests: * // Simply log the seed, and if you need to reproduce it, insert the seed here * console.log('Running test with seed:', faker.seed()); @@ -253,6 +353,9 @@ export class Faker { * @param seedArray The seed array to use. * @returns The seed array that was set. * + * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results) + * @see faker.setDefaultRefDate() when generating relative dates. + * * @example * // Consistent values for tests: * faker.seed([42, 13, 17]) @@ -263,12 +366,54 @@ export class Faker { * faker.number.int(10); // 4 * faker.number.int(10); // 8 * - * @example * // Random but reproducible tests: * // Simply log the seed, and if you need to reproduce it, insert the seed here * console.log('Running test with seed:', faker.seed()); */ seed(seedArray: number[]): number[]; + /** + * Sets the seed or generates a new one. + * + * Please note that generated values are dependent on both the seed and the + * number of calls that have been made since it was set. + * + * This method is intended to allow for consistent values in a tests, so you + * might want to use hardcoded values as the seed. + * + * In addition to that it can be used for creating truly random tests + * (by passing no arguments), that still can be reproduced if needed, + * by logging the result and explicitly setting it if needed. + * + * @param seed The seed or seed array to use. + * @returns The seed that was set. + * + * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results) + * @see faker.setDefaultRefDate() when generating relative dates. + * + * @example + * // Consistent values for tests (using a number): + * faker.seed(42) + * faker.number.int(10); // 4 + * faker.number.int(10); // 8 + * + * faker.seed(42) + * faker.number.int(10); // 4 + * faker.number.int(10); // 8 + * + * // Consistent values for tests (using an array): + * faker.seed([42, 13, 17]) + * faker.number.int(10); // 4 + * faker.number.int(10); // 8 + * + * faker.seed([42, 13, 17]) + * faker.number.int(10); // 4 + * faker.number.int(10); // 8 + * + * // Random but reproducible tests: + * // Simply log the seed, and if you need to reproduce it, insert the seed here + * console.log('Running test with seed:', faker.seed()); + */ + seed(seed?: number | number[]): number | number[]; seed( seed: number | number[] = Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER) ): number | number[] { From d031b925ed541c27385612317141ba8f9e371ee3 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 11:54:23 +0100 Subject: [PATCH 2/7] chore: apply suggestions --- src/faker.ts | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/faker.ts b/src/faker.ts index e32bdc6eb0e..facd76fcd97 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -51,10 +51,13 @@ import { mergeLocales } from './utils/merge-locales'; * import { Faker, de } from '@fakerjs/faker'; * // const { Faker, de } = require('@fakerjs/faker'); * + * // create a Faker instance with only de data and no en fallback * const customFaker = new Faker({ locale: [de] }); * * customFaker.person.firstName(); // 'Max' * customFaker.person.lastName(); // 'Baumeister' + * + * customFaker.music.genre() // throws Error as this data is not available in `de` */ export class Faker { readonly definitions: LocaleDefinition; @@ -79,9 +82,24 @@ export class Faker { * * @example * faker.seed(1234); - * faker.date.past(); // Changes based on the current date - * faker.setDefaultRefDate(() => new Date('2020-01-01')); + * + * // Default behavior + * // faker.setDefaultRefDate(); + * faker.date.past(); // Changes based on the current date/time + * + * // Use a static ref date + * faker.setDefaultRefDate(new Date('2020-01-01')); * faker.date.past(); // Reproducible '2019-07-03T08:27:58.118Z' + * + * // Use a ref date that changes every time it is used + * let clock = new Date("2020-01-01").getTime(); + * faker.setDefaultRefDate(() => { + * clock += 1000; // +1s + * return new Date(clock); + * }); + * + * faker.defaultRefDate() // 2020-01-01T00:00:01Z + * faker.defaultRefDate() // 2020-01-01T00:00:02Z */ setDefaultRefDate( dateOrSource: string | Date | number | (() => Date) = () => new Date() From dfe7066a3617d712f2a39695f620a90873e0c14f Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 11:59:24 +0100 Subject: [PATCH 3/7] chore: apply suggestions --- src/faker.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/faker.ts b/src/faker.ts index facd76fcd97..59b4dee9e23 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -260,18 +260,24 @@ export class Faker { | { /** * DEPRECATED: The locale data to use for this instance. + * + * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead. */ locales: Record; /** * DEPRECATED: The name of the main locale to use. * * @default 'en' + * + * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead. */ locale?: string; /** * DEPRECATED: The name of the fallback locale to use. * * @default 'en' + * + * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead. */ localeFallback?: string; } From a25623f65f2d6940d255c739e655f1f320349199 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 12:05:18 +0100 Subject: [PATCH 4/7] chore: apply suggestions --- src/faker.ts | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/src/faker.ts b/src/faker.ts index 59b4dee9e23..113790f5ee4 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -39,8 +39,8 @@ import { mergeLocales } from './utils/merge-locales'; * Please have a look at the individual modules and methods for more information and examples. * * @example - * import { faker } from '@fakerjs/faker'; - * // const { faker } = require('@fakerjs/faker'); + * import { faker } from '@faker-js/faker'; + * // const { faker } = require('@faker-js/faker'); * * // faker.seed(1234); * @@ -48,16 +48,16 @@ import { mergeLocales } from './utils/merge-locales'; * faker.person.lastName(); // 'Doe' * * @example - * import { Faker, de } from '@fakerjs/faker'; - * // const { Faker, de } = require('@fakerjs/faker'); + * import { Faker, es } from '@faker-js/faker'; + * // const { Faker, es } = require('@faker-js/faker'); * - * // create a Faker instance with only de data and no en fallback - * const customFaker = new Faker({ locale: [de] }); + * // create a Faker instance with only es data and no en fallback + * const customFaker = new Faker({ locale: [es] }); * - * customFaker.person.firstName(); // 'Max' - * customFaker.person.lastName(); // 'Baumeister' + * customFaker.person.firstName(); // 'Javier' + * customFaker.person.lastName(); // 'Ocampo Corrales' * - * customFaker.music.genre() // throws Error as this data is not available in `de` + * customFaker.music.genre(); // throws Error as this data is not available in `es` */ export class Faker { readonly definitions: LocaleDefinition; @@ -184,13 +184,16 @@ export class Faker { * @param options.locale The locale data to use. * * @example - * import { Faker, de } from '@fakerjs/faker'; - * // const { Faker, de } = require('@fakerjs/faker'); + * import { Faker, es } from '@faker-js/faker'; + * // const { Faker, es } = require('@faker-js/faker'); * - * const customFaker = new Faker({ locale: [de] }); + * // create a Faker instance with only es data and no en fallback + * const customFaker = new Faker({ locale: [es] }); * - * customFaker.person.firstName(); // 'Max' - * customFaker.person.lastName(); // 'Baumeister' + * customFaker.person.firstName(); // 'Javier' + * customFaker.person.lastName(); // 'Ocampo Corrales' + * + * customFaker.music.genre(); // throws Error as this data is not available in `es` */ constructor(options: { /** @@ -238,13 +241,16 @@ export class Faker { * @param options.localeFallback The name of the fallback locale to use. * * @example - * import { Faker, de } from '@fakerjs/faker'; - * // const { Faker, de } = require('@fakerjs/faker'); + * import { Faker, es } from '@faker-js/faker'; + * // const { Faker, es } = require('@faker-js/faker'); + * + * // create a Faker instance with only es data and no en fallback + * const customFaker = new Faker({ locale: [es] }); * - * const customFaker = new Faker({ locale: [de] }); + * customFaker.person.firstName(); // 'Javier' + * customFaker.person.lastName(); // 'Ocampo Corrales' * - * customFaker.person.firstName(); // 'Max' - * customFaker.person.lastName(); // 'Baumeister' + * customFaker.music.genre(); // throws Error as this data is not available in `es` */ constructor( options: From 5e3754ce0771a1269b9280d9f3a96575c5ff18f3 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 12:10:59 +0100 Subject: [PATCH 5/7] docs: document why one should create own Faker instances --- src/faker.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/faker.ts b/src/faker.ts index 113790f5ee4..a5e41cd5053 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -51,7 +51,7 @@ import { mergeLocales } from './utils/merge-locales'; * import { Faker, es } from '@faker-js/faker'; * // const { Faker, es } = require('@faker-js/faker'); * - * // create a Faker instance with only es data and no en fallback + * // create a Faker instance with only es data and no en fallback (=> smaller bundle size) * const customFaker = new Faker({ locale: [es] }); * * customFaker.person.firstName(); // 'Javier' @@ -187,7 +187,7 @@ export class Faker { * import { Faker, es } from '@faker-js/faker'; * // const { Faker, es } = require('@faker-js/faker'); * - * // create a Faker instance with only es data and no en fallback + * // create a Faker instance with only es data and no en fallback (=> smaller bundle size) * const customFaker = new Faker({ locale: [es] }); * * customFaker.person.firstName(); // 'Javier' @@ -244,7 +244,7 @@ export class Faker { * import { Faker, es } from '@faker-js/faker'; * // const { Faker, es } = require('@faker-js/faker'); * - * // create a Faker instance with only es data and no en fallback + * // create a Faker instance with only es data and no en fallback (=> smaller bundle size) * const customFaker = new Faker({ locale: [es] }); * * customFaker.person.firstName(); // 'Javier' From 046828b907e8e2f723cda1a61fcef707ccfc3721 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 20:23:24 +0100 Subject: [PATCH 6/7] chore: apply suggestions --- src/faker.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/faker.ts b/src/faker.ts index a5e41cd5053..4146cd3692f 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -34,7 +34,7 @@ import { WordModule } from './modules/word'; import { mergeLocales } from './utils/merge-locales'; /** - * The main Faker class containing all modules that can be used to generate data. + * The is Faker's main class containing all modules that can be used to generate data. * * Please have a look at the individual modules and methods for more information and examples. * From 0266333fa31e0733a3316a78a4ae589cc94b094d Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 22 Mar 2023 21:30:55 +0100 Subject: [PATCH 7/7] docs: remove duplicate deprecation hint --- src/faker.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/faker.ts b/src/faker.ts index 4146cd3692f..b799418950c 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -265,13 +265,13 @@ export class Faker { } | { /** - * DEPRECATED: The locale data to use for this instance. + * The locale data to use for this instance. * * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead. */ locales: Record; /** - * DEPRECATED: The name of the main locale to use. + * The name of the main locale to use. * * @default 'en' * @@ -279,7 +279,7 @@ export class Faker { */ locale?: string; /** - * DEPRECATED: The name of the fallback locale to use. + * The name of the fallback locale to use. * * @default 'en' *