From 250fbb71eb68aa469b6b833a61a4d23fb60ad65d Mon Sep 17 00:00:00 2001 From: Shinigami Date: Wed, 18 Jan 2023 21:01:58 +0100 Subject: [PATCH] docs: jsdoc for options (#1644) --- src/modules/color/index.ts | 232 ++++++++++++++++++++++++++++-- src/modules/datatype/index.ts | 122 +++++++++++++++- src/modules/date/index.ts | 264 +++++++++++++++++++++++++++++++--- src/modules/finance/index.ts | 5 + src/modules/git/index.ts | 33 ++++- src/modules/helpers/index.ts | 115 ++++++++++++++- src/modules/image/index.ts | 88 ++++++++++++ src/modules/internet/index.ts | 48 ++++++- src/modules/lorem/index.ts | 128 +++++++++++++++-- src/modules/number/index.ts | 109 +++++++++++++- src/modules/person/index.ts | 15 ++ src/modules/random/index.ts | 48 ++++++- src/modules/string/index.ts | 196 +++++++++++++++++++++++-- src/modules/system/index.ts | 37 ++++- src/modules/word/index.ts | 254 ++++++++++++++++++++++++++++++-- 15 files changed, 1604 insertions(+), 90 deletions(-) diff --git a/src/modules/color/index.ts b/src/modules/color/index.ts index 62a5fa0d975..9831d2589c1 100644 --- a/src/modules/color/index.ts +++ b/src/modules/color/index.ts @@ -249,9 +249,29 @@ export class ColorModule { * @since 7.0.0 */ rgb(options?: { + /** + * Prefix of the generated hex color. Only applied when 'hex' format is used. + * + * @default '0x' + */ prefix?: string; + /** + * Letter type case of the generated hex color. Only applied when `'hex'` format is used. + * + * @default 'mixed' + */ casing?: Casing; + /** + * Format of generated RGB color. + * + * @default 'hex' + */ format?: 'hex' | StringColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ includeAlpha?: boolean; }): string; /** @@ -269,7 +289,17 @@ export class ColorModule { * @since 7.0.0 */ rgb(options?: { + /** + * Format of generated RGB color. + * + * @default 'hex' + */ format?: NumberColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ includeAlpha?: boolean; }): number[]; /** @@ -296,9 +326,29 @@ export class ColorModule { * @since 7.0.0 */ rgb(options?: { + /** + * Prefix of the generated hex color. Only applied when `'hex'` format is used. + * + * @default '0x' + */ prefix?: string; + /** + * Letter type case of the generated hex color. Only applied when `'hex'` format is used. + * + * @default 'mixed' + */ casing?: Casing; + /** + * Format of generated RGB color. + * + * @default 'hex' + */ format?: 'hex' | ColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ includeAlpha?: boolean; }): string | number[]; rgb(options?: { @@ -356,7 +406,14 @@ export class ColorModule { * * @since 7.0.0 */ - cmyk(options?: { format?: StringColorFormat }): string; + cmyk(options?: { + /** + * Format of generated CMYK color. + * + * @default 'decimal' + */ + format?: StringColorFormat; + }): string; /** * Returns a CMYK color. * @@ -369,7 +426,14 @@ export class ColorModule { * * @since 7.0.0 */ - cmyk(options?: { format?: NumberColorFormat }): number[]; + cmyk(options?: { + /** + * Format of generated CMYK color. + * + * @default 'decimal' + */ + format?: NumberColorFormat; + }): number[]; /** * Returns a CMYK color. * @@ -384,7 +448,14 @@ export class ColorModule { * * @since 7.0.0 */ - cmyk(options?: { format?: ColorFormat }): string | number[]; + cmyk(options?: { + /** + * Format of generated CMYK color. + * + * @default 'decimal' + */ + format?: ColorFormat; + }): string | number[]; cmyk(options?: { format?: ColorFormat }): string | number[] { const color: string | number[] = Array.from({ length: 4 }, () => this.faker.number.float() @@ -417,7 +488,20 @@ export class ColorModule { * * @since 7.0.0 */ - hsl(options?: { format?: StringColorFormat; includeAlpha?: boolean }): string; + hsl(options?: { + /** + * Format of generated HSL color. + * + * @default 'decimal' + */ + format?: StringColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ + includeAlpha?: boolean; + }): string; /** * Returns an HSL color. * @@ -433,7 +517,17 @@ export class ColorModule { * @since 7.0.0 */ hsl(options?: { + /** + * Format of generated HSL color. + * + * @default 'decimal' + */ format?: NumberColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ includeAlpha?: boolean; }): number[]; /** @@ -455,7 +549,17 @@ export class ColorModule { * @since 7.0.0 */ hsl(options?: { + /** + * Format of generated HSL color. + * + * @default 'decimal' + */ format?: ColorFormat; + /** + * Adds an alpha value to the color (RGBA). + * + * @default false + */ includeAlpha?: boolean; }): string | number[]; hsl(options?: { @@ -496,7 +600,14 @@ export class ColorModule { * * @since 7.0.0 */ - hwb(options?: { format?: StringColorFormat }): string; + hwb(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: StringColorFormat; + }): string; /** * Returns an HWB color. * @@ -509,7 +620,14 @@ export class ColorModule { * * @since 7.0.0 */ - hwb(options?: { format?: NumberColorFormat }): number[]; + hwb(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: NumberColorFormat; + }): number[]; /** * Returns an HWB color. * @@ -524,7 +642,14 @@ export class ColorModule { * * @since 7.0.0 */ - hwb(options?: { format?: ColorFormat }): string | number[]; + hwb(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: ColorFormat; + }): string | number[]; /** * Returns an HWB color. * @@ -539,7 +664,14 @@ export class ColorModule { * * @since 7.0.0 */ - hwb(options?: { format?: ColorFormat }): string | number[] { + hwb(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: ColorFormat; + }): string | number[] { const hsl: number[] = [this.faker.number.int(360)]; for (let i = 0; i < 2; i++) { hsl.push(this.faker.number.float()); @@ -570,7 +702,14 @@ export class ColorModule { * * @since 7.0.0 */ - lab(options?: { format?: StringColorFormat }): string; + lab(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: StringColorFormat; + }): string; /** * Returns a LAB (CIELAB) color. * @@ -583,7 +722,14 @@ export class ColorModule { * * @since 7.0.0 */ - lab(options?: { format?: NumberColorFormat }): number[]; + lab(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: NumberColorFormat; + }): number[]; /** * Returns a LAB (CIELAB) color. * @@ -598,7 +744,14 @@ export class ColorModule { * * @since 7.0.0 */ - lab(options?: { format?: ColorFormat }): string | number[]; + lab(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: ColorFormat; + }): string | number[]; lab(options?: { format?: ColorFormat }): string | number[] { const lab = [this.faker.number.float({ precision: 0.000001 })]; for (let i = 0; i < 2; i++) { @@ -638,7 +791,14 @@ export class ColorModule { * * @since 7.0.0 */ - lch(options?: { format?: StringColorFormat }): string; + lch(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: StringColorFormat; + }): string; /** * Returns an LCH color. Even though upper bound of * chroma in LCH color space is theoretically unbounded, @@ -654,7 +814,14 @@ export class ColorModule { * * @since 7.0.0 */ - lch(options?: { format?: NumberColorFormat }): number[]; + lch(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: NumberColorFormat; + }): number[]; /** * Returns an LCH color. Even though upper bound of * chroma in LCH color space is theoretically unbounded, @@ -672,7 +839,14 @@ export class ColorModule { * * @since 7.0.0 */ - lch(options?: { format?: ColorFormat }): string | number[]; + lch(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ + format?: ColorFormat; + }): string | number[]; lch(options?: { format?: ColorFormat }): string | number[] { const lch = [this.faker.number.float({ precision: 0.000001 })]; for (let i = 0; i < 2; i++) { @@ -706,7 +880,17 @@ export class ColorModule { * @since 7.0.0 */ colorByCSSColorSpace(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ format?: StringColorFormat; + /** + * Color space to generate the color for. + * + * @default 'sRGB' + */ space?: CSSSpace; }): string; /** @@ -723,7 +907,17 @@ export class ColorModule { * @since 7.0.0 */ colorByCSSColorSpace(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ format?: NumberColorFormat; + /** + * Color space to generate the color for. + * + * @default 'sRGB' + */ space?: CSSSpace; }): number[]; /** @@ -742,7 +936,17 @@ export class ColorModule { * @since 7.0.0 */ colorByCSSColorSpace(options?: { + /** + * Format of generated RGB color. + * + * @default 'decimal' + */ format?: ColorFormat; + /** + * Color space to generate the color for. + * + * @default 'sRGB' + */ space?: CSSSpace; }): string | number[]; colorByCSSColorSpace(options?: { diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts index f62d3a680a0..9a89ba24516 100644 --- a/src/modules/datatype/index.ts +++ b/src/modules/datatype/index.ts @@ -43,7 +43,28 @@ export class DatatypeModule { * @deprecated Use `faker.number.int()` or `faker.number.float()` instead. */ number( - options: number | { min?: number; max?: number; precision?: number } = 99999 + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default min + 99999 + */ + max?: number; + /** + * Precision of the generated number. + * + * @default 1 + */ + precision?: number; + } = 99999 ): number { deprecated({ deprecated: 'faker.datatype.number()', @@ -66,7 +87,7 @@ export class DatatypeModule { * * @param options Precision or options object. * @param options.min Lower bound for generated number. Defaults to `0`. - * @param options.max Upper bound for generated number. Defaults to `99999`. + * @param options.max Upper bound for generated number. Defaults to `min + 99999`. * @param options.precision Precision of the generated number. Defaults to `0.01`. * * @see faker.number.float() @@ -84,7 +105,28 @@ export class DatatypeModule { * @deprecated Use `faker.number.float()` instead. */ float( - options: number | { min?: number; max?: number; precision?: number } = {} + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default min + 99999 + */ + max?: number; + /** + * Precision of the generated number. + * + * @default 0.01 + */ + precision?: number; + } = {} ): number { deprecated({ deprecated: 'faker.datatype.float()', @@ -123,7 +165,28 @@ export class DatatypeModule { * * @since 5.5.0 */ - datetime(options: number | { min?: number; max?: number } = {}): Date { + datetime( + options: + | number + | { + /** + * Lower bound for milliseconds since base date. + * + * When not provided or smaller than `-8640000000000000`, `1990-01-01` is considered as minimum generated date. + * + * @default 631152000000 + */ + min?: number; + /** + * Upper bound for milliseconds since base date. + * + * When not provided or larger than `8640000000000000`, `2100-01-01` is considered as maximum generated date. + * + * @default 4102444800000 + */ + max?: number; + } = {} + ): Date { const minMax = 8640000000000000; let min = typeof options === 'number' ? undefined : options.min; @@ -206,7 +269,18 @@ export class DatatypeModule { * * @since 5.5.0 */ - boolean(options: number | { probability?: number } = {}): boolean { + boolean( + options: + | number + | { + /** + * The probability (`[0.00, 1.00]`) of returning `true`. + * + * @default 0.5 + */ + probability?: number; + } = {} + ): boolean { if (typeof options === 'number') { options = { probability: options, @@ -252,8 +326,23 @@ export class DatatypeModule { */ hexadecimal( options: { + /** + * Length of the generated number. + * + * @default 1 + */ length?: number; + /** + * Prefix for the generated number. + * + * @default '0x' + */ prefix?: string; + /** + * Case of the generated number. + * + * @default 'mixed' + */ case?: 'lower' | 'upper' | 'mixed'; } = {} ): string { @@ -302,7 +391,18 @@ export class DatatypeModule { * @since 5.5.0 */ array( - length: number | { min: number; max: number } = 10 + length: + | number + | { + /** + * The minimum size of the array. + */ + min: number; + /** + * The maximum size of the array. + */ + max: number; + } = 10 ): Array { return this.faker.helpers.multiple( () => @@ -340,7 +440,17 @@ export class DatatypeModule { | number | string | { + /** + * Lower bound for generated bigint. + * + * @default 0n + */ min?: bigint | boolean | number | string; + /** + * Upper bound for generated bigint. + * + * @default min + 999999999999999n + */ max?: bigint | boolean | number | string; } ): bigint { diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts index c9c2eb5a556..b3c2d71073b 100644 --- a/src/modules/date/index.ts +++ b/src/modules/date/index.ts @@ -38,7 +38,7 @@ export class DateModule { * * @param options The optional options object. * @param options.years The range of years the date may be in the past. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.recent() * @@ -49,12 +49,25 @@ export class DateModule { * * @since 8.0.0 */ - past(options?: { years?: number; refDate?: string | Date | number }): Date; + past(options?: { + /** + * The range of years the date may be in the past. + * + * @default 1 + */ + years?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }): Date; /** * Generates a random date in the past. * * @param years The range of years the date may be in the past. Defaults to `1`. - * @param refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.recent() * @@ -73,7 +86,7 @@ export class DateModule { * * @param options The optional options object. * @param options.years The range of years the date may be in the past. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * @param legacyRefDate Deprecated, use `options.refDate` instead. * * @see faker.date.recent() @@ -89,7 +102,17 @@ export class DateModule { options?: | number | { + /** + * The range of years the date may be in the past. + * + * @default 1 + */ years?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ refDate?: string | Date | number; }, legacyRefDate?: string | Date | number @@ -137,7 +160,7 @@ export class DateModule { * * @param options The optional options object. * @param options.years The range of years the date may be in the future. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.soon() * @@ -148,12 +171,25 @@ export class DateModule { * * @since 8.0.0 */ - future(options?: { years?: number; refDate?: string | Date | number }): Date; + future(options?: { + /** + * The range of years the date may be in the future. + * + * @default 1 + */ + years?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }): Date; /** * Generates a random date in the future. * * @param years The range of years the date may be in the future. Defaults to `1`. - * @param refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.soon() * @@ -172,7 +208,7 @@ export class DateModule { * * @param options The optional options object. * @param options.years The range of years the date may be in the future. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * @param legacyRefDate Deprecated, use `options.refDate` instead. * * @see faker.date.soon() @@ -188,7 +224,17 @@ export class DateModule { options?: | number | { + /** + * The range of years the date may be in the future. + * + * @default 1 + */ years?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ refDate?: string | Date | number; }, legacyRefDate?: string | Date | number @@ -244,7 +290,13 @@ export class DateModule { * @since 8.0.0 */ between(options: { + /** + * The early date boundary. + */ from: string | Date | number; + /** + * The late date boundary. + */ to: string | Date | number; }): Date; /** @@ -280,7 +332,13 @@ export class DateModule { | Date | number | { + /** + * The early date boundary. + */ from: string | Date | number; + /** + * The late date boundary. + */ to: string | Date | number; }, legacyTo?: string | Date | number @@ -342,9 +400,31 @@ export class DateModule { * @since 8.0.0 */ betweens(options: { + /** + * The early date boundary. + */ from: string | Date | number; + /** + * The late date boundary. + */ to: string | Date | number; - count?: number | { min: number; max: number }; + /** + * The number of dates to generate. + * + * @default 3 + */ + count?: + | number + | { + /** + * The minimum number of dates to generate. + */ + min: number; + /** + * The maximum number of dates to generate. + */ + max: number; + }; }): Date[]; /** * Generates random dates between the given boundaries. @@ -408,9 +488,31 @@ export class DateModule { | Date | number | { + /** + * The early date boundary. + */ from: string | Date | number; + /** + * The late date boundary. + */ to: string | Date | number; - count?: number | { min: number; max: number }; + /** + * The number of dates to generate. + * + * @default 3 + */ + count?: + | number + | { + /** + * The minimum number of dates to generate. + */ + min: number; + /** + * The maximum number of dates to generate. + */ + max: number; + }; }, legacyTo?: string | Date | number, legacyCount?: number @@ -450,7 +552,7 @@ export class DateModule { * * @param options The optional options object. * @param options.days The range of days the date may be in the past. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.past() * @@ -461,12 +563,25 @@ export class DateModule { * * @since 8.0.0 */ - recent(options?: { days?: number; refDate?: string | Date | number }): Date; + recent(options?: { + /** + * The range of days the date may be in the past. + * + * @default 1 + */ + days?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }): Date; /** * Generates a random date in the recent past. * * @param days The range of days the date may be in the past. Defaults to `1`. - * @param refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.past() * @@ -485,7 +600,7 @@ export class DateModule { * * @param options The optional options object. * @param options.days The range of days the date may be in the past. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * @param legacyRefDate Deprecated, use `options.refDate` instead. * * @see faker.date.past() @@ -498,7 +613,22 @@ export class DateModule { * @since 8.0.0 */ recent( - options?: number | { days?: number; refDate?: string | Date | number }, + options?: + | number + | { + /** + * The range of days the date may be in the past. + * + * @default 1 + */ + days?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }, legacyRefDate?: string | Date | number ): Date; recent( @@ -539,7 +669,7 @@ export class DateModule { * * @param options The optional options object. * @param options.days The range of days the date may be in the future. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.future() * @@ -550,12 +680,25 @@ export class DateModule { * * @since 8.0.0 */ - soon(options?: { days?: number; refDate?: string | Date | number }): Date; + soon(options?: { + /** + * The range of days the date may be in the future. + * + * @default 1 + */ + days?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }): Date; /** * Generates a random date in the near future. * * @param days The range of days the date may be in the future. Defaults to `1`. - * @param refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * * @see faker.date.future() * @@ -574,7 +717,7 @@ export class DateModule { * * @param options The optional options object. * @param options.days The range of days the date may be in the future. Defaults to `1`. - * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now. + * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `new Date()`. * @param legacyRefDate Deprecated, use `options.refDate` instead. * * @see faker.date.future() @@ -587,7 +730,22 @@ export class DateModule { * @since 8.0.0 */ soon( - options?: number | { days?: number; refDate?: string | Date | number }, + options?: + | number + | { + /** + * The range of days the date may be in the future. + * + * @default 1 + */ + days?: number; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ + refDate?: string | Date | number; + }, legacyRefDate?: string | Date | number ): Date; soon( @@ -638,7 +796,26 @@ export class DateModule { * * @since 3.0.1 */ - month(options: { abbr?: boolean; context?: boolean } = {}): string { + month( + options: { + /** + * Whether to return an abbreviation. + * + * @default false + */ + abbr?: boolean; + /** + * 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`. + * + * @default false + */ + context?: boolean; + } = {} + ): string { const { abbr = false, context = false } = options; const source = this.faker.definitions.date.month; @@ -673,7 +850,26 @@ export class DateModule { * * @since 3.0.1 */ - weekday(options: { abbr?: boolean; context?: boolean } = {}): string { + weekday( + options: { + /** + * Whether to return an abbreviation. + * + * @default false + */ + abbr?: boolean; + /** + * 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`. + * + * @default false + */ + context?: boolean; + } = {} + ): string { const { abbr = false, context = false } = options; const source = this.faker.definitions.date.weekday; @@ -717,9 +913,33 @@ export class DateModule { */ birthdate( options: { + /** + * The minimum age or year to generate a birthdate. + * + * @default 18 + */ min?: number; + /** + * The maximum age or year to generate a birthdate. + * + * @default 80 + */ max?: number; + /** + * 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`). + * + * @default 'year' + */ mode?: 'age' | 'year'; + /** + * The date to use as reference point for the newly generated date. + * + * @default new Date() + */ refDate?: string | Date | number; } = {} ): Date { diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts index bc540afc9ee..8a8d91d27a0 100644 --- a/src/modules/finance/index.ts +++ b/src/modules/finance/index.ts @@ -448,6 +448,11 @@ export class FinanceModule { */ bic( options: { + /** + * Whether to include a three-digit branch code at the end of the generated code. + * + * @default faker.datatype.boolean() + */ includeBranchCode?: boolean; } = {} ): string { diff --git a/src/modules/git/index.ts b/src/modules/git/index.ts index 4d8e2cd01b3..1f6d366fa3f 100644 --- a/src/modules/git/index.ts +++ b/src/modules/git/index.ts @@ -56,7 +56,7 @@ export class GitModule { * 'LF' = '\n', * 'CRLF' = '\r\n' * - * @param options.refDate The date to use as reference point for the commit. Defaults to now. + * @param options.refDate The date to use as reference point for the commit. Defaults to `new Date()`. * * @example * faker.git.commitEntry() @@ -70,8 +70,26 @@ export class GitModule { */ commitEntry( options: { + /** + * Set to `true` to generate a merge message line. + * + * @default faker.datatype.boolean({ probability: 0.2 }) + */ merge?: boolean; + /** + * Choose the end of line character to use. + * + * - 'LF' = '\n', + * - 'CRLF' = '\r\n' + * + * @default 'CRLF' + */ eol?: 'LF' | 'CRLF'; + /** + * The date to use as reference point for the commit. + * + * @default new Date() + */ refDate?: string | Date | number; } = {} ): string { @@ -125,7 +143,7 @@ export class GitModule { * Generates a date string for a git commit using the same format as `git log`. * * @param options The optional options object. - * @param options.refDate The date to use as reference point for the commit. Defaults to now. + * @param options.refDate The date to use as reference point for the commit. Defaults to `new Date()`. * * @example * faker.git.commitDate() // 'Mon Nov 7 14:40:58 2022 +0600' @@ -133,7 +151,16 @@ export class GitModule { * * @since 8.0.0 */ - commitDate(options: { refDate?: string | Date | number } = {}): string { + commitDate( + options: { + /** + * The date to use as reference point for the commit. + * + * @default new Date() + */ + refDate?: string | Date | number; + } = {} + ): string { const { refDate } = options; const dateParts = GIT_DATE_FORMAT_BASE.format( diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts index 7c5ee9972cd..6f636052a5c 100644 --- a/src/modules/helpers/index.ts +++ b/src/modules/helpers/index.ts @@ -258,7 +258,17 @@ export class HelpersModule { * * @since 8.0.0 */ - shuffle(list: T[], options: { inplace: true }): T[]; + shuffle( + list: T[], + options: { + /** + * Whether to shuffle the array in place or return a new array. + * + * @default false + */ + inplace: true; + } + ): T[]; /** * Returns a randomized version of the array. * @@ -273,7 +283,17 @@ export class HelpersModule { * * @since 2.0.1 */ - shuffle(list: readonly T[], options?: { inplace?: false }): T[]; + shuffle( + list: readonly T[], + options?: { + /** + * Whether to shuffle the array in place or return a new array. + * + * @default false + */ + inplace?: false; + } + ): T[]; /** * Returns a randomized version of the array. * @@ -289,7 +309,17 @@ export class HelpersModule { * * @since 2.0.1 */ - shuffle(list: T[], options?: { inplace?: boolean }): T[]; + shuffle( + list: T[], + options?: { + /** + * Whether to shuffle the array in place or return a new array. + * + * @default false + */ + inplace?: boolean; + } + ): T[]; shuffle(list: T[], options: { inplace?: boolean } = {}): T[] { const { inplace = false } = options; @@ -396,7 +426,14 @@ export class HelpersModule { */ maybe( callback: () => T, - options: { probability?: number } = {} + options: { + /** + * The probability (`[0.00, 1.00]`) of the callback being invoked. + * + * @default 0.5 + */ + probability?: number; + } = {} ): T | undefined { if (this.faker.datatype.boolean(options)) { return callback(); @@ -797,7 +834,20 @@ export class HelpersModule { * * @since 8.0.0 */ - rangeToNumber(numberOrRange: number | { min: number; max: number }): number { + rangeToNumber( + numberOrRange: + | number + | { + /** + * The minimum value for the range. + */ + min: number; + /** + * The maximum value for the range. + */ + max: number; + } + ): number { if (typeof numberOrRange === 'number') { return numberOrRange; } @@ -830,12 +880,49 @@ export class HelpersModule { method: Method, args?: Parameters, options: { + /** + * This parameter does nothing. + * + * @default new Date().getTime() + */ startTime?: number; + /** + * The time in milliseconds this method may take before throwing an error. + * + * @default 50 + */ maxTime?: number; + /** + * The total number of attempts to try before throwing an error. + * + * @default 50 + */ maxRetries?: number; + /** + * This parameter does nothing. + * + * @default 0 + */ currentIterations?: number; + /** + * The value or values that should be excluded/skipped. + * + * @default [] + */ exclude?: RecordKey | RecordKey[]; + /** + * The function used to determine whether a value was already returned. + * + * Defaults to check the existence of the key. + * + * @default (obj, key) => (obj[key] === undefined ? -1 : 0) + */ compare?: (obj: Record, key: RecordKey) => 0 | -1; + /** + * The store of unique entries. + * + * Defaults to a global store. + */ store?: Record; } = {} ): ReturnType { @@ -866,7 +953,23 @@ export class HelpersModule { multiple( method: () => T, options: { - count?: number | { min: number; max: number }; + /** + * The number or range of elements to generate. + * + * @default 3 + */ + count?: + | number + | { + /** + * The minimum value for the range. + */ + min: number; + /** + * The maximum value for the range. + */ + max: number; + }; } = {} ): T[] { const count = this.rangeToNumber(options.count ?? 3); diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts index 6a2d6144fed..794a9514bde 100644 --- a/src/modules/image/index.ts +++ b/src/modules/image/index.ts @@ -102,7 +102,17 @@ export class ImageModule { */ url( options: { + /** + * The width of the image. + * + * @default 640 + */ width?: number; + /** + * The height of the image. + * + * @default 480 + */ height?: number; } = {} ): string { @@ -134,8 +144,21 @@ export class ImageModule { */ urlLoremFlickr( options: { + /** + * The width of the image. + * + * @default 640 + */ width?: number; + /** + * The height of the image. + * + * @default 480 + */ height?: number; + /** + * Category to use for the image. + */ category?: string; } = {} ): string { @@ -167,9 +190,29 @@ export class ImageModule { */ urlPicsumPhotos( options: { + /** + * The width of the image. + * + * @default 640 + */ width?: number; + /** + * The height of the image. + * + * @default 480 + */ height?: number; + /** + * Whether the image should be grayscale. + * + * @default false + */ grayscale?: boolean; + /** + * Whether the image should be blurred. + * + * @default false + */ blur?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10; } = {} ): string { @@ -226,11 +269,41 @@ export class ImageModule { */ urlPlaceholder( options: { + /** + * The width of the image. + * + * @default faker.number.int({ min: 1, max: 3999 }) + */ width?: number; + /** + * The height of the image. + * + * @default faker.number.int({ min: 1, max: 3999 }) + */ height?: number; + /** + * The background color of the image. + * + * @default faker.color.rgb({ format: 'hex', prefix: '' }) + */ backgroundColor?: string; + /** + * The text color of the image. + * + * @default faker.color.rgb({ format: 'hex', prefix: '' }) + */ textColor?: string; + /** + * The format of the image. + * + * @default faker.helpers.arrayElement(['gif', 'jpeg', 'jpg', 'png', 'webp']) + */ format?: 'gif' | 'jpeg' | 'jpg' | 'png' | 'webp'; + /** + * The text to display on the image. + * + * @default faker.lorem.words() + */ text?: string; } = {} ): string { @@ -279,8 +352,23 @@ export class ImageModule { */ dataUri( options: { + /** + * The width of the image. + * + * @default 640 + */ width?: number; + /** + * The height of the image. + * + * @default 480 + */ height?: number; + /** + * The color of the image. + * + * @default 'grey' + */ color?: string; } = {} ): string { diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts index 8f5cc8bbba6..f7f022ac64d 100644 --- a/src/modules/internet/index.ts +++ b/src/modules/internet/index.ts @@ -75,7 +75,14 @@ export class InternetModule { firstName?: string, lastName?: string, provider?: string, - options?: { allowSpecialCharacters?: boolean } + options?: { + /** + * Whether special characters such as ``.!#$%&'*+-/=?^_`{|}~`` should be included in the email address. + * + * @default false + */ + allowSpecialCharacters?: boolean; + } ): string { provider = provider || @@ -115,7 +122,14 @@ export class InternetModule { exampleEmail( firstName?: string, lastName?: string, - options?: { allowSpecialCharacters?: boolean } + options?: { + /** + * Whether special characters such as ``.!#$%&'*+-/=?^_`{|}~`` should be included in the email address. + * + * @default false + */ + allowSpecialCharacters?: boolean; + } ): string { const provider = this.faker.helpers.arrayElement( this.faker.definitions.internet.example_email @@ -287,7 +301,14 @@ export class InternetModule { * @since 7.0.0 */ httpStatusCode( - options: { types?: ReadonlyArray } = {} + options: { + /** + * A list of the HTTP status code types that should be used. + * + * @default Object.keys(faker.definitions.internet.http_status_code) + */ + types?: ReadonlyArray; + } = {} ): number { const { types = Object.keys( @@ -316,7 +337,17 @@ export class InternetModule { */ url( options: { + /** + * Whether to append a slash to the end of the url (path). + * + * @default faker.datatype.boolean() + */ appendSlash?: boolean; + /** + * The protocol to use. + * + * @default 'https' + */ protocol?: HTTPProtocolType; } = {} ): string { @@ -578,7 +609,16 @@ export class InternetModule { * * @since 6.2.0 */ - emoji(options: { types?: ReadonlyArray } = {}): string { + emoji( + options: { + /** + * A list of the emoji types that should be used. + * + * @default Object.keys(faker.definitions.internet.emoji) + */ + types?: ReadonlyArray; + } = {} + ): string { const { types = Object.keys( this.faker.definitions.internet.emoji diff --git a/src/modules/lorem/index.ts b/src/modules/lorem/index.ts index 37fb2cd7aff..9c9b514f4a1 100644 --- a/src/modules/lorem/index.ts +++ b/src/modules/lorem/index.ts @@ -45,7 +45,36 @@ export class LoremModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + * + * @default 1 + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -72,7 +101,20 @@ export class LoremModule { * * @since 2.0.1 */ - words(wordCount: number | { min: number; max: number } = 3): string { + words( + wordCount: + | number + | { + /** + * The minimum number of words to generate. + */ + min: number; + /** + * The maximum number of words to generate. + */ + max: number; + } = 3 + ): string { return this.faker.helpers .multiple(() => this.word(), { count: wordCount }) .join(' '); @@ -93,7 +135,18 @@ export class LoremModule { * @since 2.0.1 */ sentence( - wordCount: number | { min: number; max: number } = { min: 3, max: 10 } + wordCount: + | number + | { + /** + * The minimum number of words to generate. + */ + min: number; + /** + * The maximum number of words to generate. + */ + max: number; + } = { min: 3, max: 10 } ): string { const sentence = this.words(wordCount); return `${sentence.charAt(0).toUpperCase() + sentence.substring(1)}.`; @@ -113,7 +166,20 @@ export class LoremModule { * * @since 4.0.0 */ - slug(wordCount: number | { min: number; max: number } = 3): string { + slug( + wordCount: + | number + | { + /** + * The minimum number of words to generate. + */ + min: number; + /** + * The maximum number of words to generate. + */ + max: number; + } = 3 + ): string { const words = this.words(wordCount); return this.faker.helpers.slugify(words); } @@ -137,7 +203,18 @@ export class LoremModule { * @since 2.0.1 */ sentences( - sentenceCount: number | { min: number; max: number } = { min: 2, max: 6 }, + sentenceCount: + | number + | { + /** + * The minimum number of sentences to generate. + */ + min: number; + /** + * The maximum number of sentences to generate. + */ + max: number; + } = { min: 2, max: 6 }, separator: string = ' ' ): string { return this.faker.helpers @@ -159,7 +236,20 @@ export class LoremModule { * * @since 2.0.1 */ - paragraph(sentenceCount: number | { min: number; max: number } = 3): string { + paragraph( + sentenceCount: + | number + | { + /** + * The minimum number of sentences to generate. + */ + min: number; + /** + * The maximum number of sentences to generate. + */ + max: number; + } = 3 + ): string { return this.sentences(sentenceCount); } @@ -196,7 +286,18 @@ export class LoremModule { * @since 2.0.1 */ paragraphs( - paragraphCount: number | { min: number; max: number } = 3, + paragraphCount: + | number + | { + /** + * The minimum number of paragraphs to generate. + */ + min: number; + /** + * The maximum number of paragraphs to generate. + */ + max: number; + } = 3, separator: string = '\n' ): string { return this.faker.helpers @@ -260,7 +361,18 @@ export class LoremModule { * @since 3.1.0 */ lines( - lineCount: number | { min: number; max: number } = { min: 1, max: 5 } + lineCount: + | number + | { + /** + * The minimum number of lines to generate. + */ + min: number; + /** + * The maximum number of lines to generate. + */ + max: number; + } = { min: 1, max: 5 } ): string { return this.sentences(lineCount, '\n'); } diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts index 5a2f0cb6411..13368990d14 100644 --- a/src/modules/number/index.ts +++ b/src/modules/number/index.ts @@ -38,7 +38,24 @@ export class NumberModule { * * @since 8.0.0 */ - int(options: number | { min?: number; max?: number } = {}): number { + int( + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default min + 99999 + */ + max?: number; + } = {} + ): number { if (typeof options === 'number') { options = { max: options }; } @@ -87,7 +104,28 @@ export class NumberModule { * @since 8.0.0 */ float( - options: number | { min?: number; max?: number; precision?: number } = {} + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0.0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default 1.0 + */ + max?: number; + /** + * Precision of the generated number. + * + * @default 0.01 + */ + precision?: number; + } = {} ): number { if (typeof options === 'number') { options = { @@ -132,7 +170,24 @@ export class NumberModule { * * @since 8.0.0 */ - binary(options: number | { min?: number; max?: number } = {}): string { + binary( + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default 1 + */ + max?: number; + } = {} + ): string { if (typeof options === 'number') { options = { max: options }; } @@ -163,7 +218,24 @@ export class NumberModule { * * @since 8.0.0 */ - octal(options: number | { min?: number; max?: number } = {}): string { + octal( + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default 7 + */ + max?: number; + } = {} + ): string { if (typeof options === 'number') { options = { max: options }; } @@ -190,7 +262,24 @@ export class NumberModule { * * @since 8.0.0 */ - hex(options: number | { min?: number; max?: number } = {}): string { + hex( + options: + | number + | { + /** + * Lower bound for generated number. + * + * @default 0 + */ + min?: number; + /** + * Upper bound for generated number. + * + * @default 15 + */ + max?: number; + } = {} + ): string { if (typeof options === 'number') { options = { max: options }; } @@ -228,7 +317,17 @@ export class NumberModule { | string | boolean | { + /** + * Lower bound for generated bigint. + * + * @default 0n + */ min?: bigint | number | string | boolean; + /** + * Upper bound for generated bigint. + * + * @default min + 999999999999999n + */ max?: bigint | number | string | boolean; } = {} ): bigint { diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts index 59202fb0058..03609cbcabc 100644 --- a/src/modules/person/index.ts +++ b/src/modules/person/index.ts @@ -161,8 +161,23 @@ export class PersonModule { */ fullName( options: { + /** + * The optional first name to use. If not specified a random one will be chosen. + * + * @default faker.person.firstName(sex) + */ firstName?: string; + /** + * The optional last name to use. If not specified a random one will be chosen. + * + * @default faker.person.lastName(sex) + */ lastName?: string; + /** + * The optional sex to use. Can be either `'female'` or `'male'`. + * + * @default faker.helpers.arrayElement(['female', 'male']) + */ sex?: SexType; } = {} ): string { diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts index 88f81c63ee6..d558e24b5d7 100644 --- a/src/modules/random/index.ts +++ b/src/modules/random/index.ts @@ -152,7 +152,18 @@ export class RandomModule { * @since 3.1.0 */ words( - count: number | { min: number; max: number } = { min: 1, max: 3 } + count: + | number + | { + /** + * The minimum number of words. + */ + min: number; + /** + * The maximum number of words. + */ + max: number; + } = { min: 1, max: 3 } ): string { return this.faker.helpers.multiple(this.word, { count }).join(' '); } @@ -193,8 +204,23 @@ export class RandomModule { options: | number | { + /** + * The number of characters to generate. + * + * @default 1 + */ count?: number; + /** + * The casing of the characters. + * + * @default 'mixed' + */ casing?: Casing; + /** + * An array with characters to exclude. + * + * @default [] + */ bannedChars?: readonly LiteralUnion[] | string; } = {} ): string { @@ -237,7 +263,17 @@ export class RandomModule { alphaNumeric( count: number = 1, options: { + /** + * The casing of the characters. + * + * @default 'lower' + */ casing?: Casing; + /** + * An array of characters and digits which should be banned in the generated string. + * + * @default [] + */ bannedChars?: readonly LiteralUnion[] | string; } = {} ): string { @@ -278,7 +314,17 @@ export class RandomModule { numeric( length: number = 1, options: { + /** + * Whether leading zeros are allowed or not. + * + * @default true + */ allowLeadingZeros?: boolean; + /** + * An array of digits which should be banned in the generated string. + * + * @default [] + */ bannedDigits?: readonly LiteralUnion[] | string; } = {} ): string { diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts index 99eb8983392..6184c043e36 100644 --- a/src/modules/string/index.ts +++ b/src/modules/string/index.ts @@ -115,7 +115,18 @@ export class StringModule { */ fromCharacters( characters: string | ReadonlyArray, - length: number | { min: number; max: number } = 1 + length: + | number + | { + /** + * The minimum length of the string to generate. + */ + min: number; + /** + * The maximum length of the string to generate. + */ + max: number; + } = 1 ): string { length = this.faker.helpers.rangeToNumber(length); if (length <= 0) { @@ -161,8 +172,34 @@ export class StringModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The number or range of characters to generate. + * + * @default 1 + */ + length?: + | number + | { + /** + * The minimum number of characters to generate. + */ + min: number; + /** + * The maximum number of characters to generate. + */ + max: number; + }; + /** + * The casing of the characters. + * + * @default 'mixed' + */ casing?: Casing; + /** + * An array with characters which should be excluded in the generated string. + * + * @default [] + */ exclude?: readonly LiteralUnion[] | string; } = {} ): string { @@ -225,8 +262,34 @@ export class StringModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The number or range of characters and digits to generate. + * + * @default 1 + */ + length?: + | number + | { + /** + * The minimum number of characters and digits to generate. + */ + min: number; + /** + * The maximum number of characters and digits to generate. + */ + max: number; + }; + /** + * The casing of the characters. + * + * @default 'mixed' + */ casing?: Casing; + /** + * An array of characters and digits which should be excluded in the generated string. + * + * @default [] + */ exclude?: readonly LiteralUnion[] | string; } = {} ): string { @@ -288,7 +351,18 @@ export class StringModule { */ binary( options: { - length?: number | { min: number; max: number }; + length?: + | number + | { + /** + * The minimum number of characters to generate. + */ + min: number; + /** + * The maximum number of characters to generate. + */ + max: number; + }; prefix?: string; } = {} ): string { @@ -319,7 +393,18 @@ export class StringModule { */ octal( options: { - length?: number | { min: number; max: number }; + length?: + | number + | { + /** + * The minimum number of characters to generate. + */ + min: number; + /** + * The maximum number of characters to generate. + */ + max: number; + }; prefix?: string; } = {} ): string { @@ -356,8 +441,34 @@ export class StringModule { */ hexadecimal( options: { - length?: number | { min: number; max: number }; + /** + * The number or range of characters to generate after the prefix. + * + * @default 1 + */ + length?: + | number + | { + /** + * The minimum number of characters to generate after the prefix. + */ + min: number; + /** + * The maximum number of characters to generate after the prefix. + */ + max: number; + }; + /** + * Casing of the generated number. + * + * @default 'mixed' + */ casing?: Casing; + /** + * Prefix for the generated number. + * + * @default '0x' + */ prefix?: string; } = {} ): string { @@ -428,8 +539,34 @@ export class StringModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The number or range of digits to generate. + * + * @default 1 + */ + length?: + | number + | { + /** + * The minimum number of digits to generate. + */ + min: number; + /** + * The maximum number of digits to generate. + */ + max: number; + }; + /** + * Whether leading zeros are allowed or not. + * + * @default true + */ allowLeadingZeros?: boolean; + /** + * An array of digits which should be excluded in the generated string. + * + * @default [] + */ exclude?: readonly LiteralUnion[] | string; } = {} ): string { @@ -493,7 +630,20 @@ export class StringModule { * * @since 8.0.0 */ - sample(length: number | { min: number; max: number } = 10): string { + sample( + length: + | number + | { + /** + * The minimum number of characters to generate. + */ + min: number; + /** + * The maximum number of characters to generate. + */ + max: number; + } = 10 + ): string { length = this.faker.helpers.rangeToNumber(length); if (length >= SAMPLE_MAX_LENGTH) { length = SAMPLE_MAX_LENGTH; @@ -548,7 +698,20 @@ export class StringModule { * * @since 8.0.0 */ - nanoid(length: number | { min: number; max: number } = 21): string { + nanoid( + length: + | number + | { + /** + * The minimum length of the Nano ID to generate. + */ + min: number; + /** + * The maximum length of the Nano ID to generate. + */ + max: number; + } = 21 + ): string { length = this.faker.helpers.rangeToNumber(length); if (length <= 0) { return ''; @@ -590,7 +753,20 @@ export class StringModule { * * @since 8.0.0 */ - special(length: number | { min: number; max: number } = 1): string { + special( + length: + | number + | { + /** + * The minimum number of special characters to generate. + */ + min: number; + /** + * The maximum number of special characters to generate. + */ + max: number; + } = 1 + ): string { return this.fromCharacters( [ '!', diff --git a/src/modules/system/index.ts b/src/modules/system/index.ts index e5413622899..2f3ce371f08 100644 --- a/src/modules/system/index.ts +++ b/src/modules/system/index.ts @@ -63,9 +63,22 @@ export class SystemModule { fileName( options: { /** - * Define how many extensions the file name should have. Defaults to `1`. + * Define how many extensions the file name should have. + * + * @default 1 */ - extensionCount?: number | { min: number; max: number }; + extensionCount?: + | number + | { + /** + * Minimum number of extensions. + */ + min: number; + /** + * Maximum number of extensions. + */ + max: number; + }; } = {} ): string { const { extensionCount = 1 } = options; @@ -250,7 +263,17 @@ export class SystemModule { */ networkInterface( options: { + /** + * The interface type. Can be one of `en`, `wl`, `ww`. + * + * @default faker.helpers.arrayElement(['en', 'wl', 'ww']) + */ interfaceType?: (typeof commonInterfaceTypes)[number]; + /** + * The interface schema. Can be one of `index`, `slot`, `mac`, `pci`. + * + * @default faker.helpers.objectKey(['index' | 'slot' | 'mac' | 'pci']) + */ interfaceSchema?: keyof typeof commonInterfaceSchemas; } = {} ): string { @@ -303,7 +326,17 @@ export class SystemModule { */ cron( options: { + /** + * Whether to include a year in the generated expression. + * + * @default false + */ includeYear?: boolean; + /** + * Whether to include a @yearly, @monthly, @daily, etc text labels in the generated expression. + * + * @default false + */ includeNonStandard?: boolean; } = {} ): string { diff --git a/src/modules/word/index.ts b/src/modules/word/index.ts index 414fe62241a..5548e74f0fe 100644 --- a/src/modules/word/index.ts +++ b/src/modules/word/index.ts @@ -47,7 +47,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -90,7 +117,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -133,7 +187,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -176,7 +257,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -219,7 +327,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -262,7 +397,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -305,7 +467,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -345,7 +534,34 @@ export class WordModule { options: | number | { - length?: number | { min: number; max: number }; + /** + * The expected length of the word. + */ + length?: + | number + | { + /** + * The minimum length of the word. + */ + min: number; + /** + * The maximum length of the word. + */ + max: number; + }; + /** + * The strategy to apply when no words with a matching length are found. + * + * Available error handling strategies: + * + * - `fail`: Throws an error if no words with the given length are found. + * - `shortest`: Returns any of the shortest words. + * - `closest`: Returns any of the words closest to the given length. + * - `longest`: Returns any of the longest words. + * - `any-length`: Returns a word with any length. + * + * @default 'any-length' + */ strategy?: 'fail' | 'closest' | 'shortest' | 'longest' | 'any-length'; } = {} ): string { @@ -388,7 +604,27 @@ export class WordModule { * @since 8.0.0 */ words( - options: number | { count?: number | { min: number; max: number } } = {} + options: + | number + | { + /** + * The number of words to return. + * + * @default { min: 1, max: 3 } + */ + count?: + | number + | { + /** + * The minimum number of words to return. + */ + min: number; + /** + * The maximum number of words to return. + */ + max: number; + }; + } = {} ): string { if (typeof options === 'number') { options = { count: options };