diff --git a/README.md b/README.md index e9c64f4da2c..bb67fadadf5 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ The API covers the following modules: | Name | `faker.name.firstName()` | Cameron | | Phone | `faker.phone.phoneNumber()` | +1 291-299-0192 | | Random | `faker.random.locale()` | fr_CA | -| Science | `faker.science.unit()` | { name: 'meter', symbol: 'm' } | +| Science | `faker.science.unit()` | `{ name: 'meter', symbol: 'm' }` | | System | `faker.system.directoryPath()` | /root | | Vehicle | `faker.vehicle.vehicle()` | Lamborghini Camry | | Word | `faker.word.adjective()` | adorable | diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts index ceca9628e89..b58f435e04b 100644 --- a/docs/.vitepress/components/api-docs/method.ts +++ b/docs/.vitepress/components/api-docs/method.ts @@ -6,6 +6,7 @@ export interface Method { readonly returns: string; readonly examples: string; // HTML readonly deprecated: boolean; + readonly since: string; readonly seeAlsos: string[]; } diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue index 2851b9454c9..56fcb3492ce 100644 --- a/docs/.vitepress/components/api-docs/method.vue +++ b/docs/.vitepress/components/api-docs/method.vue @@ -19,6 +19,12 @@ function seeAlsoToUrl(see: string): string {
+
+

+ Available since v +

+
+ ``` -### Remove all references to `faker` from your project. The new package is located at `@faker-js/faker` +## Remove all references to `faker` from your project. The new package is located at `@faker-js/faker` :::warning You **MUST** swap all references from the `faker` package to the new `@faker-js/faker` package. @@ -28,13 +26,13 @@ If you depend on a specific version of Faker you still can reference the version `npm i @faker-js/faker@5.5.3 -D` will work just fine 😄. ::: -### TypeScript +## TypeScript :::tip TypeScript Improvements Faker now ships with its own types! Remove `@types/faker` from your `package.json` to avoid conflicts. ::: -### Tree-shaking +## Tree-shaking :::warning Tree shaking is not yet fully supported due to some structural issues. But we plan to make Faker fully tree-shakable in the future. diff --git a/docs/guide/migration-guide-v6.md b/docs/guide/migration-guide-v6.md index 0a7060b1b73..6a91a1439ff 100644 --- a/docs/guide/migration-guide-v6.md +++ b/docs/guide/migration-guide-v6.md @@ -1,12 +1,10 @@ # Migrating from Faker v6 to v7 -[[toc]] - -### Node 12 no longer supported +## Node 12 no longer supported You need at least Node 14 to use Faker. -### Default export removed +## Default export removed If you were previously importing faker like this: @@ -20,7 +18,7 @@ You must instead use: import { faker } from '@faker-js/faker'; ``` -### Deprecated methods changed +## Deprecated methods changed Several methods were renamed or moved: @@ -39,7 +37,7 @@ Several methods were renamed or moved: | faker.datatype.hexaDecimal | faker.datatype.hexadecimal | | faker.name.title | faker.name.jobTitle | -### Deprecated methods removed +## Deprecated methods removed Some methods were removed without a direct alternative. If you are using any of these methods you should build an object containing the specific properties you need. diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index d5b8f590257..9f0a9bb8b9d 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -39,7 +39,7 @@ export function processModuleMethods(project: ProjectReflection): PageIndex { } export function extractModuleName(module: DeclarationReflection): string { - return module.name.replace('_', ''); + return module.name.replace(/Module$/, ''); } function extractModuleFieldName(module: DeclarationReflection): string { @@ -50,7 +50,7 @@ function extractModuleFieldName(module: DeclarationReflection): string { /** * Analyzes and writes the documentation for a module and its methods such as `faker.animal.cat()`. * - * @param direct The module to process. + * @param module The module to process. * @returns The generated pages. */ function processModuleMethod(module: DeclarationReflection): PageIndex { diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 62b65ee8d2e..7a8309ee84b 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -21,6 +21,7 @@ import { faker } from '../../src'; import { extractRawExamples, extractSeeAlsos, + extractSince, formatTypescript, isDeprecated, joinTagParts, @@ -153,6 +154,7 @@ export function analyzeSignature( title: prettyMethodName, description: mdToHtml(toBlock(signature.comment)), parameters: parameters, + since: extractSince(signature), returns: typeToText(signature.type), examples: mdToHtml(`${code}ts\n${examples}${code}`), deprecated: isDeprecated(signature), diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts index 783bf974150..651a0119a2b 100644 --- a/scripts/apidoc/utils.ts +++ b/scripts/apidoc/utils.ts @@ -146,3 +146,14 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined { export function isDeprecated(signature: SignatureReflection): boolean { return extractTagContent('@deprecated', signature).length > 0; } + +/** + * Extracts the "since" tag from the provided signature. + * + * @param signature The signature to check. + * + * @returns the contents of the @since tag + */ +export function extractSince(signature: SignatureReflection): string { + return extractTagContent('@since', signature).join().trim(); +} diff --git a/src/faker.ts b/src/faker.ts index 9534e373a8c..0283bd6dd6e 100644 --- a/src/faker.ts +++ b/src/faker.ts @@ -1,32 +1,32 @@ import type { LocaleDefinition } from './definitions'; import { FakerError } from './errors/faker-error'; import type { KnownLocale } from './locales'; -import { Address } from './modules/address'; -import { Animal } from './modules/animal'; -import { Color } from './modules/color'; -import { Commerce } from './modules/commerce'; -import { Company } from './modules/company'; -import { Database } from './modules/database'; -import { Datatype } from './modules/datatype'; -import { _Date } from './modules/date'; -import { Fake } from './modules/fake'; -import { Finance } from './modules/finance'; -import { Git } from './modules/git'; -import { Hacker } from './modules/hacker'; -import { Helpers } from './modules/helpers'; -import { Image } from './modules/image'; -import { Internet } from './modules/internet'; -import { Lorem } from './modules/lorem'; -import { Mersenne } from './modules/mersenne'; -import { Music } from './modules/music'; -import { Name } from './modules/name'; -import { Phone } from './modules/phone'; -import { Random } from './modules/random'; -import { Science } from './modules/science'; -import { System } from './modules/system'; -import { Unique } from './modules/unique'; -import { Vehicle } from './modules/vehicle'; -import { Word } from './modules/word'; +import { AddressModule } from './modules/address'; +import { AnimalModule } from './modules/animal'; +import { ColorModule } from './modules/color'; +import { CommerceModule } from './modules/commerce'; +import { CompanyModule } from './modules/company'; +import { DatabaseModule } from './modules/database'; +import { DatatypeModule } from './modules/datatype'; +import { DateModule } from './modules/date'; +import { FakeModule } from './modules/fake'; +import { FinanceModule } from './modules/finance'; +import { GitModule } from './modules/git'; +import { HackerModule } from './modules/hacker'; +import { HelpersModule } from './modules/helpers'; +import { ImageModule } from './modules/image'; +import { InternetModule } from './modules/internet'; +import { LoremModule } from './modules/lorem'; +import { MersenneModule } from './modules/mersenne'; +import { MusicModule } from './modules/music'; +import { NameModule } from './modules/name'; +import { PhoneModule } from './modules/phone'; +import { RandomModule } from './modules/random'; +import { ScienceModule } from './modules/science'; +import { SystemModule } from './modules/system'; +import { UniqueModule } from './modules/unique'; +import { VehicleModule } from './modules/vehicle'; +import { WordModule } from './modules/word'; import type { LiteralUnion } from './utils/types'; export type UsableLocale = LiteralUnion; @@ -76,36 +76,36 @@ export class Faker { readonly definitions: LocaleDefinition = this.initDefinitions(); - readonly fake: Fake['fake'] = new Fake(this).fake; - readonly unique: Unique['unique'] = new Unique(this).unique; + readonly fake: FakeModule['fake'] = new FakeModule(this).fake; + readonly unique: UniqueModule['unique'] = new UniqueModule(this).unique; - readonly mersenne: Mersenne = new Mersenne(); - readonly random: Random = new Random(this); + readonly mersenne: MersenneModule = new MersenneModule(); + readonly random: RandomModule = new RandomModule(this); - readonly helpers: Helpers = new Helpers(this); + readonly helpers: HelpersModule = new HelpersModule(this); - readonly datatype: Datatype = new Datatype(this); + readonly datatype: DatatypeModule = new DatatypeModule(this); - readonly address: Address = new Address(this); - readonly animal: Animal = new Animal(this); - readonly color: Color = new Color(this); - readonly commerce: Commerce = new Commerce(this); - readonly company: Company = new Company(this); - readonly database: Database = new Database(this); - readonly date: _Date = new _Date(this); - readonly finance = new Finance(this); - readonly git: Git = new Git(this); - readonly hacker: Hacker = new Hacker(this); - readonly image: Image = new Image(this); - readonly internet: Internet = new Internet(this); - readonly lorem: Lorem = new Lorem(this); - readonly music: Music = new Music(this); - readonly name: Name = new Name(this); - readonly phone: Phone = new Phone(this); - readonly science: Science = new Science(this); - readonly system: System = new System(this); - readonly vehicle: Vehicle = new Vehicle(this); - readonly word: Word = new Word(this); + readonly address: AddressModule = new AddressModule(this); + readonly animal: AnimalModule = new AnimalModule(this); + readonly color: ColorModule = new ColorModule(this); + readonly commerce: CommerceModule = new CommerceModule(this); + readonly company: CompanyModule = new CompanyModule(this); + readonly database: DatabaseModule = new DatabaseModule(this); + readonly date: DateModule = new DateModule(this); + readonly finance = new FinanceModule(this); + readonly git: GitModule = new GitModule(this); + readonly hacker: HackerModule = new HackerModule(this); + readonly image: ImageModule = new ImageModule(this); + readonly internet: InternetModule = new InternetModule(this); + readonly lorem: LoremModule = new LoremModule(this); + readonly music: MusicModule = new MusicModule(this); + readonly name: NameModule = new NameModule(this); + readonly phone: PhoneModule = new PhoneModule(this); + readonly science: ScienceModule = new ScienceModule(this); + readonly system: SystemModule = new SystemModule(this); + readonly vehicle: VehicleModule = new VehicleModule(this); + readonly word: WordModule = new WordModule(this); constructor(opts: FakerOptions) { if (!opts) { diff --git a/src/index.ts b/src/index.ts index e3b223b0750..984a8c758d5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -29,17 +29,41 @@ export type { } from './definitions'; export { FakerError } from './errors/faker-error'; export type { FakerOptions, UsableLocale, UsedLocales } from './faker'; +export type { AddressModule } from './modules/address'; +export type { AnimalModule } from './modules/animal'; export type { Casing, ColorFormat, + ColorModule, CSSFunction, CSSSpace, NumberColorFormat, StringColorFormat, } from './modules/color'; +export type { CommerceModule } from './modules/commerce'; +export type { CompanyModule } from './modules/company'; +export type { DatabaseModule } from './modules/database'; +export type { DatatypeModule } from './modules/datatype'; +export type { DateModule } from './modules/date'; +export type { FakeModule } from './modules/fake'; +export type { FinanceModule } from './modules/finance'; +export type { GitModule } from './modules/git'; +export type { HackerModule } from './modules/hacker'; +export type { HelpersModule } from './modules/helpers'; +export type { ImageModule } from './modules/image'; +export type { InternetModule } from './modules/internet'; +export type { LoremModule } from './modules/lorem'; +export type { MersenneModule } from './modules/mersenne'; +export type { MusicModule } from './modules/music'; export { Gender, Sex } from './modules/name'; -export type { GenderType, SexType } from './modules/name'; -export type { ChemicalElement, Unit } from './modules/science'; +export type { GenderType, NameModule, SexType } from './modules/name'; +export type { PhoneModule } from './modules/phone'; +export type { RandomModule } from './modules/random'; +export type { ChemicalElement, ScienceModule, Unit } from './modules/science'; +export type { SystemModule } from './modules/system'; +export type { UniqueModule } from './modules/unique'; +export type { VehicleModule } from './modules/vehicle'; +export type { WordModule } from './modules/word'; export { Faker }; // since we are requiring the top level of faker, load all locales by default diff --git a/src/modules/address/index.ts b/src/modules/address/index.ts index 967962ffb61..695d8249169 100644 --- a/src/modules/address/index.ts +++ b/src/modules/address/index.ts @@ -4,10 +4,10 @@ import { deprecated } from '../../internal/deprecated'; /** * Module to generate addresses and locations. */ -export class Address { +export class AddressModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Address.prototype)) { + for (const name of Object.getOwnPropertyNames(AddressModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -28,6 +28,7 @@ export class Address { * faker.address.zipCode() // '17839' * faker.address.zipCode('####') // '6925' * + * @since 2.0.1 */ zipCode(format?: string): string { // if zip format is not specified, use the zip format defined for the locale @@ -54,6 +55,8 @@ export class Address { * @example * fakerUS.address.zipCodeByState("AK") // '99595' * fakerUS.address.zipCodeByState("??") // '47683-9880' + * + * @since 5.0.0 */ zipCodeByState(state: string): string { const zipRange = this.faker.definitions.address.postcode_by_state?.[state]; @@ -70,6 +73,8 @@ export class Address { * * @example * faker.address.city() // 'East Jarretmouth' + * + * @since 2.0.1 */ city(format?: string | number): string { if (format != null) { @@ -97,6 +102,8 @@ export class Address { * @example * faker.address.cityPrefix() // 'East' * + * @since 2.0.1 + * * @deprecated * Use `faker.address.city()` instead. */ @@ -120,6 +127,8 @@ export class Address { * @example * faker.address.citySuffix() // 'mouth' * + * @since 2.0.1 + * * @deprecated * Use `faker.address.city()` instead. */ @@ -141,6 +150,8 @@ export class Address { * * @example * faker.address.cityName() // 'San Rafael' + * + * @since 5.5.0 */ cityName(): string { return this.faker.helpers.arrayElement( @@ -153,6 +164,8 @@ export class Address { * * @example * faker.address.buildingNumber() // '379' + * + * @since 6.2.0 */ buildingNumber(): string { const format = this.faker.helpers.arrayElement( @@ -167,6 +180,8 @@ export class Address { * * @example * faker.address.street() // 'Schroeder Isle' + * + * @since 7.0.0 */ street(): string { const format = this.faker.helpers.arrayElement( @@ -180,6 +195,8 @@ export class Address { * * @example * fakerDE.address.streetName() // 'Cavill Avenue' + * + * @since 2.0.1 */ streetName(): string { if (this.faker.definitions.address.street_name == null) { @@ -208,6 +225,8 @@ export class Address { * faker.address.streetAddress() // '0917 O'Conner Estates' * faker.address.streetAddress(false) // '34830 Erdman Hollow' * faker.address.streetAddress(true) // '3393 Ronny Way Apt. 742' + * + * @since 2.0.1 */ streetAddress(useFullAddress: boolean = false): string { const formats = this.faker.definitions.address.street_address; @@ -224,6 +243,8 @@ export class Address { * @example * faker.address.streetSuffix() // 'Streets' * + * @since 2.0.1 + * * @deprecated Use faker.address.street() instead. */ streetSuffix(): string { @@ -246,6 +267,8 @@ export class Address { * @example * fakerGH.address.streetPrefix() // 'Boame' * + * @since 3.0.0 + * * @deprecated Use faker.address.street() instead. */ streetPrefix(): string { @@ -266,6 +289,8 @@ export class Address { * * @example * faker.address.secondaryAddress() // 'Apt. 861' + * + * @since 2.0.1 */ secondaryAddress(): string { return this.faker.helpers.replaceSymbolWithNumber( @@ -280,6 +305,8 @@ export class Address { * * @example * faker.address.county() // 'Cambridgeshire' + * + * @since 2.0.1 */ county(): string { return this.faker.helpers.arrayElement( @@ -292,6 +319,8 @@ export class Address { * * @example * faker.address.country() // 'Greece' + * + * @since 2.0.1 */ country(): string { return this.faker.helpers.arrayElement( @@ -309,6 +338,8 @@ export class Address { * faker.address.countryCode() // 'SJ' * faker.address.countryCode('alpha-2') // 'GA' * faker.address.countryCode('alpha-3') // 'TJK' + * + * @since 3.0.0 */ countryCode(alphaCode: 'alpha-2' | 'alpha-3' = 'alpha-2'): string { const key = @@ -322,6 +353,8 @@ export class Address { * * @example * faker.address.state() // 'Georgia' + * + * @since 2.0.1 */ state(): string { return this.faker.helpers.arrayElement( @@ -334,6 +367,8 @@ export class Address { * * @example * faker.address.stateAbbr() // 'ND' + * + * @since 2.0.1 */ stateAbbr(): string { return this.faker.helpers.arrayElement( @@ -351,6 +386,8 @@ export class Address { * @example * faker.address.latitude() // '-30.9501' * faker.address.latitude(10, -10, 5) // '2.68452' + * + * @since 2.0.1 */ latitude(max: number = 90, min: number = -90, precision: number = 4): string { return this.faker.datatype @@ -372,6 +409,8 @@ export class Address { * @example * faker.address.longitude() // '-154.0226' * faker.address.longitude(10, -10, 5) // '-4.03620' + * + * @since 2.0.1 */ longitude( max: number = 180, @@ -397,6 +436,8 @@ export class Address { * faker.address.direction() // 'Northeast' * faker.address.direction(false) // 'South' * faker.address.direction(true) // 'NE' + * + * @since 5.0.0 */ direction(useAbbr: boolean = false): string { if (!useAbbr) { @@ -419,6 +460,8 @@ export class Address { * faker.address.cardinalDirection() // 'North' * faker.address.cardinalDirection(false) // 'South' * faker.address.cardinalDirection(true) // 'N' + * + * @since 5.0.0 */ cardinalDirection(useAbbr: boolean = false): string { if (!useAbbr) { @@ -441,6 +484,8 @@ export class Address { * faker.address.ordinalDirection() // 'Northeast' * faker.address.ordinalDirection(false) // 'Northwest' * faker.address.ordinalDirection(true) // 'NE' + * + * @since 5.0.0 */ ordinalDirection(useAbbr: boolean = false): string { if (!useAbbr) { @@ -465,6 +510,8 @@ export class Address { * faker.address.nearbyGPSCoordinate() // [ '33.8475', '-170.5953' ] * faker.address.nearbyGPSCoordinate([33, -170]) // [ '33.0165', '-170.0636' ] * faker.address.nearbyGPSCoordinate([33, -170], 1000, true) // [ '37.9163', '-179.2408' ] + * + * @since 5.0.0 */ nearbyGPSCoordinate( coordinate?: [latitude: number, longitude: number], @@ -521,6 +568,8 @@ export class Address { * * @example * faker.address.timeZone() // 'Pacific/Guam' + * + * @since 5.1.0 */ timeZone(): string { return this.faker.helpers.arrayElement( diff --git a/src/modules/animal/index.ts b/src/modules/animal/index.ts index d5d0ef08ae8..4a0af052523 100644 --- a/src/modules/animal/index.ts +++ b/src/modules/animal/index.ts @@ -3,10 +3,10 @@ import type { Faker } from '../..'; /** * Module to generate animal related entries. */ -export class Animal { +export class AnimalModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Animal.prototype)) { + for (const name of Object.getOwnPropertyNames(AnimalModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -19,6 +19,8 @@ export class Animal { * * @example * faker.animal.dog() // 'Irish Water Spaniel' + * + * @since 5.5.0 */ dog(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.dog); @@ -29,6 +31,8 @@ export class Animal { * * @example * faker.animal.cat() // 'Singapura' + * + * @since 5.5.0 */ cat(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.cat); @@ -39,6 +43,8 @@ export class Animal { * * @example * faker.animal.snake() // 'Eyelash viper' + * + * @since 5.5.0 */ snake(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.snake); @@ -49,6 +55,8 @@ export class Animal { * * @example * faker.animal.bear() // 'Asian black bear' + * + * @since 5.5.0 */ bear(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.bear); @@ -59,6 +67,8 @@ export class Animal { * * @example * faker.animal.lion() // 'Northeast Congo Lion' + * + * @since 5.5.0 */ lion(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.lion); @@ -69,6 +79,8 @@ export class Animal { * * @example * faker.animal.cetacean() // 'Spinner Dolphin' + * + * @since 5.5.0 */ cetacean(): string { return this.faker.helpers.arrayElement( @@ -81,6 +93,8 @@ export class Animal { * * @example * faker.animal.horse() // 'Swedish Warmblood' + * + * @since 5.5.0 */ horse(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.horse); @@ -91,6 +105,8 @@ export class Animal { * * @example * faker.animal.bird() // 'Buller's Shearwater' + * + * @since 5.5.0 */ bird(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.bird); @@ -101,6 +117,8 @@ export class Animal { * * @example * faker.animal.cow() // 'Brava' + * + * @since 5.5.0 */ cow(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.cow); @@ -111,6 +129,8 @@ export class Animal { * * @example * faker.animal.fish() // 'Mandarin fish' + * + * @since 5.5.0 */ fish(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.fish); @@ -121,6 +141,8 @@ export class Animal { * * @example * faker.animal.crocodilia() // 'Philippine Crocodile' + * + * @since 5.5.0 */ crocodilia(): string { return this.faker.helpers.arrayElement( @@ -133,6 +155,8 @@ export class Animal { * * @example * faker.animal.insect() // 'Pyramid ant' + * + * @since 5.5.0 */ insect(): string { return this.faker.helpers.arrayElement( @@ -145,6 +169,8 @@ export class Animal { * * @example * faker.animal.rabbit() // 'Florida White' + * + * @since 5.5.0 */ rabbit(): string { return this.faker.helpers.arrayElement( @@ -157,6 +183,8 @@ export class Animal { * * @example * faker.animal.rodent() // 'Cuscomys ashanika' + * + * @since 7.4.0 */ rodent(): string { return this.faker.helpers.arrayElement( @@ -169,6 +197,8 @@ export class Animal { * * @example * faker.animal.type() // 'crocodilia' + * + * @since 5.5.0 */ type(): string { return this.faker.helpers.arrayElement(this.faker.definitions.animal.type); diff --git a/src/modules/color/index.ts b/src/modules/color/index.ts index faa898d4c97..c6dbb0a476e 100644 --- a/src/modules/color/index.ts +++ b/src/modules/color/index.ts @@ -154,10 +154,10 @@ function toColorFormat( /** * Module to generate colors. */ -export class Color { +export class ColorModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Color.prototype)) { + for (const name of Object.getOwnPropertyNames(ColorModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -170,6 +170,8 @@ export class Color { * * @example * faker.color.human() // 'red' + * + * @since 7.0.0 */ human(): string { return this.faker.helpers.arrayElement(this.faker.definitions.color.human); @@ -181,6 +183,8 @@ export class Color { * * @example * faker.color.space() // 'sRGB' + * + * @since 7.0.0 */ space(): string { return this.faker.helpers.arrayElement(this.faker.definitions.color.space); @@ -191,6 +195,8 @@ export class Color { * * @example * faker.color.cssSupportedFunction() // 'rgb' + * + * @since 7.0.0 */ cssSupportedFunction(): string { return this.faker.helpers.arrayElement(CSS_FUNCTIONS); @@ -201,6 +207,8 @@ export class Color { * * @example * faker.color.cssSupportedSpace() // 'display-p3' + * + * @since 7.0.0 */ cssSupportedSpace(): string { return this.faker.helpers.arrayElement(CSS_SPACES); @@ -211,6 +219,8 @@ export class Color { * * @example * faker.color.rgb() // '0xffffFF' + * + * @since 7.0.0 */ rgb(): string; /** @@ -231,6 +241,8 @@ export class Color { * faker.color.rgb({ format: 'hex', casing: 'lower' }) // '#ffffff' * faker.color.rgb({ format: 'css' }) // 'rgb(255, 0, 0)' * faker.color.rgb({ format: 'binary' }) // '10000000 00000000 11111111' + * + * @since 7.0.0 */ rgb(options?: { prefix?: string; @@ -249,6 +261,8 @@ export class Color { * faker.color.rgb() // '0xffffFF' * faker.color.rgb({ format: 'decimal' }) // [255, 255, 255] * faker.color.rgb({ format: 'decimal', includeAlpha: true }) // [255, 255, 255, 0.4] + * + * @since 7.0.0 */ rgb(options?: { format?: NumberColorFormat; @@ -274,6 +288,8 @@ export class Color { * faker.color.rgb({ format: 'css' }) // 'rgb(255, 0, 0)' * faker.color.rgb({ format: 'binary' }) // '10000000 00000000 11111111' * faker.color.rgb({ format: 'decimal', includeAlpha: true }) // [255, 255, 255, 0.4] + * + * @since 7.0.0 */ rgb(options?: { prefix?: string; @@ -321,6 +337,8 @@ export class Color { * * @example * faker.color.cmyk() // [0.31, 0.52, 0.32, 0.43] + * + * @since 7.0.0 */ cmyk(): number[]; /** @@ -333,6 +351,8 @@ export class Color { * faker.color.cmyk() // [0.31, 0.52, 0.32, 0.43] * faker.color.cmyk({ format: 'css' }) // cmyk(100%, 0%, 0%, 0%) * faker.color.cmyk({ format: 'binary' }) // (8-32 bits) x 4 + * + * @since 7.0.0 */ cmyk(options?: { format?: StringColorFormat }): string; /** @@ -344,6 +364,8 @@ export class Color { * @example * faker.color.cmyk() // [0.31, 0.52, 0.32, 0.43] * faker.color.cmyk({ format: 'decimal' }) // [0.31, 0.52, 0.32, 0.43] + * + * @since 7.0.0 */ cmyk(options?: { format?: NumberColorFormat }): number[]; /** @@ -357,6 +379,8 @@ export class Color { * faker.color.cmyk({ format: 'decimal' }) // [0.31, 0.52, 0.32, 0.43] * faker.color.cmyk({ format: 'css' }) // cmyk(100%, 0%, 0%, 0%) * faker.color.cmyk({ format: 'binary' }) // (8-32 bits) x 4 + * + * @since 7.0.0 */ cmyk(options?: { format?: ColorFormat }): string | number[]; cmyk(options?: { format?: ColorFormat }): string | number[] { @@ -371,6 +395,8 @@ export class Color { * * @example * faker.color.hsl() // [201, 0.23, 0.32] + * + * @since 7.0.0 */ hsl(): number[]; /** @@ -386,6 +412,8 @@ export class Color { * faker.color.hsl({ format: 'css', includeAlpha: true }) // hsl(0deg 100% 50% / 0.5) * faker.color.hsl({ format: 'binary' }) // (8-32 bits) x 3 * faker.color.hsl({ format: 'binary', includeAlpha: true }) // (8-32 bits) x 4 + * + * @since 7.0.0 */ hsl(options?: { format?: StringColorFormat; includeAlpha?: boolean }): string; /** @@ -399,6 +427,8 @@ export class Color { * faker.color.hsl() // [201, 0.23, 0.32] * faker.color.hsl({ format: 'decimal' }) // [300, 0.21, 0.52] * faker.color.hsl({ format: 'decimal', includeAlpha: true }) // [300, 0.21, 0.52, 0.28] + * + * @since 7.0.0 */ hsl(options?: { format?: NumberColorFormat; @@ -419,6 +449,8 @@ export class Color { * faker.color.hsl({ format: 'css', includeAlpha: true }) // hsl(0deg 100% 50% / 0.5) * faker.color.hsl({ format: 'binary' }) // (8-32 bits) x 3 * faker.color.hsl({ format: 'binary', includeAlpha: true }) // (8-32 bits) x 4 + * + * @since 7.0.0 */ hsl(options?: { format?: ColorFormat; @@ -444,6 +476,8 @@ export class Color { * * @example * faker.color.hwb() // [201, 0.21, 0.31] + * + * @since 7.0.0 */ hwb(): number[]; /** @@ -456,6 +490,8 @@ export class Color { * faker.color.hwb() // [201, 0.21, 0.31] * faker.color.hwb({ format: 'css' }) // hwb(194 0% 0%) * faker.color.hwb({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ hwb(options?: { format?: StringColorFormat }): string; /** @@ -467,6 +503,8 @@ export class Color { * @example * faker.color.hwb() // [201, 0.21, 0.31] * faker.color.hwb({ format: 'decimal' }) // [201, 0.21, 0.31] + * + * @since 7.0.0 */ hwb(options?: { format?: NumberColorFormat }): number[]; /** @@ -480,6 +518,8 @@ export class Color { * faker.color.hwb({ format: 'decimal' }) // [201, 0.21, 0.31] * faker.color.hwb({ format: 'css' }) // hwb(194 0% 0%) * faker.color.hwb({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ hwb(options?: { format?: ColorFormat }): string | number[]; /** @@ -493,6 +533,8 @@ export class Color { * faker.color.hwb({ format: 'decimal' }) // [201, 0.21, 0.31] * faker.color.hwb({ format: 'css' }) // hwb(194 0% 0%) * faker.color.hwb({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ hwb(options?: { format?: ColorFormat }): string | number[] { const hsl: number[] = [this.faker.datatype.number({ min: 0, max: 360 })]; @@ -507,6 +549,8 @@ export class Color { * * @example * faker.color.lab() // [0.832133, -80.3245, 100.1234] + * + * @since 7.0.0 */ lab(): number[]; /** @@ -519,6 +563,8 @@ export class Color { * faker.color.lab() // [0.832133, -80.3245, 100.1234] * faker.color.lab({ format: 'css' }) // lab(29.2345% 39.3825 20.0664) * faker.color.lab({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ lab(options?: { format?: StringColorFormat }): string; /** @@ -530,6 +576,8 @@ export class Color { * @example * faker.color.lab() // [0.832133, -80.3245, 100.1234] * faker.color.lab({ format: 'decimal' }) // [0.856773, -80.2345, 100.2341] + * + * @since 7.0.0 */ lab(options?: { format?: NumberColorFormat }): number[]; /** @@ -543,6 +591,8 @@ export class Color { * faker.color.lab({ format: 'decimal' }) // [0.856773, -80.2345, 100.2341] * faker.color.lab({ format: 'css' }) // lab(29.2345% 39.3825 20.0664) * faker.color.lab({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ lab(options?: { format?: ColorFormat }): string | number[]; lab(options?: { format?: ColorFormat }): string | number[] { @@ -565,6 +615,8 @@ export class Color { * * @example * faker.color.lch() // [0.522345, 72.2, 56.2] + * + * @since 7.0.0 */ lch(): number[]; /** @@ -580,6 +632,8 @@ export class Color { * faker.color.lch() // [0.522345, 72.2, 56.2] * faker.color.lch({ format: 'css' }) // lch(52.2345% 72.2 56.2) * faker.color.lch({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ lch(options?: { format?: StringColorFormat }): string; /** @@ -594,6 +648,8 @@ export class Color { * @example * faker.color.lch() // [0.522345, 72.2, 56.2] * faker.color.lch({ format: 'decimal' }) // [0.522345, 72.2, 56.2] + * + * @since 7.0.0 */ lch(options?: { format?: NumberColorFormat }): number[]; /** @@ -610,6 +666,8 @@ export class Color { * faker.color.lch({ format: 'decimal' }) // [0.522345, 72.2, 56.2] * faker.color.lch({ format: 'css' }) // lch(52.2345% 72.2 56.2) * faker.color.lch({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ lch(options?: { format?: ColorFormat }): string | number[]; lch(options?: { format?: ColorFormat }): string | number[] { @@ -629,6 +687,8 @@ export class Color { * * @example * faker.color.colorByCSSColorSpace() // [0.93, 1, 0.82] + * + * @since 7.0.0 */ colorByCSSColorSpace(): number[]; /** @@ -642,6 +702,8 @@ export class Color { * faker.color.colorByCSSColorSpace() // [0.93, 1, 0.82] * faker.color.colorByCSSColorSpace({ format: 'css', space: 'display-p3' }) // color(display-p3 0.12 1 0.23) * faker.color.colorByCSSColorSpace({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ colorByCSSColorSpace(options?: { format?: StringColorFormat; @@ -657,6 +719,8 @@ export class Color { * @example * faker.color.colorByCSSColorSpace() // [0.93, 1, 0.82] * faker.color.colorByCSSColorSpace({ format: 'decimal' }) // [0.12, 0.21, 0.31] + * + * @since 7.0.0 */ colorByCSSColorSpace(options?: { format?: NumberColorFormat; @@ -674,6 +738,8 @@ export class Color { * faker.color.colorByCSSColorSpace({ format: 'decimal' }) // [0.12, 0.21, 0.31] * faker.color.colorByCSSColorSpace({ format: 'css', space: 'display-p3' }) // color(display-p3 0.12 1 0.23) * faker.color.colorByCSSColorSpace({ format: 'binary' }) // (8-32 bits x 3) + * + * @since 7.0.0 */ colorByCSSColorSpace(options?: { format?: ColorFormat; diff --git a/src/modules/commerce/index.ts b/src/modules/commerce/index.ts index 1c589f4d805..11ed8d7bd03 100644 --- a/src/modules/commerce/index.ts +++ b/src/modules/commerce/index.ts @@ -4,10 +4,10 @@ import { deprecated } from '../../internal/deprecated'; /** * Module to generate commerce and product related entries. */ -export class Commerce { +export class CommerceModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Commerce.prototype)) { + for (const name of Object.getOwnPropertyNames(CommerceModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -23,6 +23,8 @@ export class Commerce { * @example * faker.commerce.color() // 'red' * + * @since 3.0.0 + * * @deprecated * Use `faker.color.human()` instead. */ @@ -41,6 +43,8 @@ export class Commerce { * * @example * faker.commerce.department() // 'Garden' + * + * @since 3.0.0 */ department(): string { return this.faker.helpers.arrayElement( @@ -53,6 +57,8 @@ export class Commerce { * * @example * faker.commerce.productName() // 'Incredible Soft Gloves' + * + * @since 3.0.0 */ productName(): string { return `${this.productAdjective()} ${this.productMaterial()} ${this.product()}`; @@ -72,6 +78,8 @@ export class Commerce { * faker.commerce.price(100, 200) // 154.00 * faker.commerce.price(100, 200, 0) // 133 * faker.commerce.price(100, 200, 0, '$') // $114 + * + * @since 3.0.0 */ price( min: number = 1, @@ -98,6 +106,8 @@ export class Commerce { * * @example * faker.commerce.productAdjective() // 'Handcrafted' + * + * @since 3.0.0 */ productAdjective(): string { return this.faker.helpers.arrayElement( @@ -110,6 +120,8 @@ export class Commerce { * * @example * faker.commerce.productMaterial() // 'Rubber' + * + * @since 3.0.0 */ productMaterial(): string { return this.faker.helpers.arrayElement( @@ -122,6 +134,8 @@ export class Commerce { * * @example * faker.commerce.product() // 'Computer' + * + * @since 3.0.0 */ product(): string { return this.faker.helpers.arrayElement( @@ -134,6 +148,8 @@ export class Commerce { * * @example * faker.commerce.productDescription() // 'Andy shoes are designed to keeping...' + * + * @since 5.0.0 */ productDescription(): string { return this.faker.helpers.arrayElement( diff --git a/src/modules/company/index.ts b/src/modules/company/index.ts index 2a8b2db922e..2b17a6ed419 100644 --- a/src/modules/company/index.ts +++ b/src/modules/company/index.ts @@ -4,10 +4,10 @@ import { deprecated } from '../../internal/deprecated'; /** * Module to generate company related entries. */ -export class Company { +export class CompanyModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Company.prototype)) { + for (const name of Object.getOwnPropertyNames(CompanyModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -20,6 +20,8 @@ export class Company { * * @example * faker.company.suffixes() // [ 'Inc', 'and Sons', 'LLC', 'Group' ] + * + * @since 2.0.1 */ suffixes(): string[] { // Don't want the source array exposed to modification, so return a copy @@ -33,6 +35,8 @@ export class Company { * * @example * faker.company.name() // 'Zieme, Hauck and McClure' + * + * @since 7.4.0 */ name(format?: number): string { if (format != null) { @@ -70,6 +74,8 @@ export class Company { * @example * faker.company.companyName() // 'Zieme, Hauck and McClure' * + * @since 2.0.1 + * * @deprecated Use `faker.company.name()` instead */ companyName(format?: number): string { @@ -88,6 +94,8 @@ export class Company { * * @example * faker.company.companySuffix() // 'and Sons' + * + * @since 2.0.1 */ companySuffix(): string { return this.faker.helpers.arrayElement(this.suffixes()); @@ -98,6 +106,8 @@ export class Company { * * @example * faker.company.catchPhrase() // 'Upgradable systematic flexibility' + * + * @since 2.0.1 */ catchPhrase(): string { return [ @@ -112,6 +122,8 @@ export class Company { * * @example * faker.company.bs() // 'cultivate synergistic e-markets' + * + * @since 2.0.1 */ bs(): string { return [this.bsBuzz(), this.bsAdjective(), this.bsNoun()].join(' '); @@ -122,6 +134,8 @@ export class Company { * * @example * faker.company.catchPhraseAdjective() // 'Multi-tiered' + * + * @since 2.0.1 */ catchPhraseAdjective(): string { return this.faker.helpers.arrayElement( @@ -134,6 +148,8 @@ export class Company { * * @example * faker.company.catchPhraseDescriptor() // 'composite' + * + * @since 2.0.1 */ catchPhraseDescriptor(): string { return this.faker.helpers.arrayElement( @@ -146,6 +162,8 @@ export class Company { * * @example * faker.company.catchPhraseNoun() // 'leverage' + * + * @since 2.0.1 */ catchPhraseNoun(): string { return this.faker.helpers.arrayElement(this.faker.definitions.company.noun); @@ -156,6 +174,8 @@ export class Company { * * @example * faker.company.bsAdjective() // 'one-to-one' + * + * @since 2.0.1 */ bsAdjective(): string { return this.faker.helpers.arrayElement( @@ -168,6 +188,8 @@ export class Company { * * @example * faker.company.bsBuzz() // 'empower' + * + * @since 2.0.1 */ bsBuzz(): string { return this.faker.helpers.arrayElement( @@ -180,6 +202,8 @@ export class Company { * * @example * faker.company.bsNoun() // 'paradigms' + * + * @since 2.0.1 */ bsNoun(): string { return this.faker.helpers.arrayElement( diff --git a/src/modules/database/index.ts b/src/modules/database/index.ts index 69e073159f0..8a4291f9ceb 100644 --- a/src/modules/database/index.ts +++ b/src/modules/database/index.ts @@ -3,10 +3,10 @@ import type { Faker } from '../..'; /** * Module to generate database related entries. */ -export class Database { +export class DatabaseModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Database.prototype)) { + for (const name of Object.getOwnPropertyNames(DatabaseModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -19,6 +19,8 @@ export class Database { * * @example * faker.database.column() // 'createdAt' + * + * @since 4.0.0 */ column(): string { return this.faker.helpers.arrayElement( @@ -31,6 +33,8 @@ export class Database { * * @example * faker.database.type() // 'timestamp' + * + * @since 4.0.0 */ type(): string { return this.faker.helpers.arrayElement( @@ -43,6 +47,8 @@ export class Database { * * @example * faker.database.collation() // 'utf8_unicode_ci' + * + * @since 4.0.0 */ collation(): string { return this.faker.helpers.arrayElement( @@ -55,6 +61,8 @@ export class Database { * * @example * faker.database.engine() // 'ARCHIVE' + * + * @since 4.0.0 */ engine(): string { return this.faker.helpers.arrayElement( @@ -67,6 +75,8 @@ export class Database { * * @example * faker.database.mongodbObjectId() // 'e175cac316a79afdd0ad3afb' + * + * @since 6.2.0 */ mongodbObjectId(): string { return this.faker.datatype.hexadecimal({ diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts index 4af14d125b8..9991175d55d 100644 --- a/src/modules/datatype/index.ts +++ b/src/modules/datatype/index.ts @@ -5,10 +5,10 @@ import { deprecated } from '../../internal/deprecated'; /** * Module to generate various primitive values and data types. */ -export class Datatype { +export class DatatypeModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Datatype.prototype)) { + for (const name of Object.getOwnPropertyNames(DatatypeModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -34,6 +34,8 @@ export class Datatype { * faker.datatype.number({ max: 100 }) // 42 * faker.datatype.number({ precision: 0.01 }) // 64246.18 * faker.datatype.number({ min: 10, max: 100, precision: 0.01 }) // 36.94 + * + * @since 5.5.0 */ number( options: number | { min?: number; max?: number; precision?: number } = 99999 @@ -76,6 +78,8 @@ export class Datatype { * faker.datatype.float({ max: 100 }) // 28.11 * faker.datatype.float({ precision: 0.1 }) // 84055.3 * faker.datatype.float({ min: 10, max: 100, precision: 0.001 }) // 57.315 + * + * @since 5.5.0 */ float( options?: number | { min?: number; max?: number; precision?: number } @@ -112,6 +116,8 @@ export class Datatype { * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z' * faker.datatype.datetime(1893456000000) // '2022-03-28T07:00:56.876Z' * faker.datatype.datetime({ min: 1577836800000, max: 1893456000000 }) // '2021-09-12T07:13:00.255Z' + * + * @since 5.5.0 */ datetime(options: number | { min?: number; max?: number } = {}): Date { const minMax = 8640000000000000; @@ -138,6 +144,8 @@ export class Datatype { * @example * faker.datatype.string() // 'Zo!.:*e>wR' * faker.datatype.string(5) // '6Bye8' + * + * @since 5.5.0 */ string(length = 10): string { const maxLength = Math.pow(2, 20); @@ -164,6 +172,8 @@ export class Datatype { * * @example * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252' + * + * @since 5.5.0 */ uuid(): string { const RFC4122_TEMPLATE = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'; @@ -180,6 +190,8 @@ export class Datatype { * * @example * faker.datatype.boolean() // false + * + * @since 5.5.0 */ boolean(): boolean { return !!this.number(1); @@ -202,6 +214,8 @@ export class Datatype { * faker.datatype.hexadecimal({ length: 10, case: 'upper' }) // '0xE3F38014FB' * faker.datatype.hexadecimal({ prefix: '', case: 'lower' }) // 'd' * faker.datatype.hexadecimal({ length: 10, prefix: '0x', case: 'mixed' }) // '0xAdE330a4D1' + * + * @since 6.1.2 */ hexadecimal( options: @@ -265,6 +279,8 @@ export class Datatype { * * @example * faker.datatype.json() // `{"foo":"mxz.v8ISij","bar":29154,"bike":8658,"a":"GxTlw$nuC:","b":40693,"name":"%'77"}` + * + * @since 5.5.0 */ json(): string { const properties = ['foo', 'bar', 'bike', 'a', 'b', 'name', 'prop']; @@ -285,6 +301,8 @@ export class Datatype { * @example * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ] * faker.datatype.array(3) // [ 61845, 'SK7H$W3:d*', 'm[%7N8*GVK' ] + * + * @since 5.5.0 */ array(length = 10): Array { return Array.from({ length }).map(() => @@ -307,6 +325,8 @@ export class Datatype { * faker.datatype.bigInt({ min: 1000000n }) // 431433n * faker.datatype.bigInt({ max: 100n }) // 42n * faker.datatype.bigInt({ min: 10n, max: 100n }) // 36n + * + * @since 6.0.0 */ bigInt( options?: diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts index 23cf6222bbf..111fc4bae6f 100644 --- a/src/modules/date/index.ts +++ b/src/modules/date/index.ts @@ -20,12 +20,10 @@ function toDate(date?: string | Date | number): Date { /** * Module to generate dates. */ -// disabled until modules are renamed to something with a suffix -// eslint-disable-next-line @typescript-eslint/naming-convention -export class _Date { +export class DateModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(_Date.prototype)) { + for (const name of Object.getOwnPropertyNames(DateModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -45,6 +43,8 @@ export class _Date { * faker.date.past() // '2021-12-03T05:40:44.408Z' * faker.date.past(10) // '2017-10-25T21:34:19.488Z' * faker.date.past(10, '2020-01-01T00:00:00.000Z') // '2017-08-18T02:59:12.350Z' + * + * @since 2.0.1 */ past(years?: number, refDate?: string | Date | number): Date { const date = toDate(refDate); @@ -72,6 +72,8 @@ export class _Date { * faker.date.future() // '2022-11-19T05:52:49.100Z' * faker.date.future(10) // '2030-11-23T09:38:28.710Z' * faker.date.future(10, '2020-01-01T00:00:00.000Z') // '2020-12-13T22:45:10.252Z' + * + * @since 2.0.1 */ future(years?: number, refDate?: string | Date | number): Date { const date = toDate(refDate); @@ -95,6 +97,8 @@ export class _Date { * * @example * faker.date.between('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z') // '2026-05-16T02:22:53.002Z' + * + * @since 2.0.1 */ between(from: string | Date | number, to: string | Date | number): Date { const fromMs = toDate(from).getTime(); @@ -120,6 +124,8 @@ export class _Date { * // ] * faker.date.betweens('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z', 2) * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ] + * + * @since 5.4.0 */ betweens( from: string | Date | number, @@ -147,6 +153,8 @@ export class _Date { * faker.date.recent() // '2022-02-04T02:09:35.077Z' * faker.date.recent(10) // '2022-01-29T06:12:12.829Z' * faker.date.recent(10, '2020-01-01T00:00:00.000Z') // '2019-12-27T18:11:19.117Z' + * + * @since 2.0.1 */ recent(days?: number, refDate?: string | Date | number): Date { const date = toDate(refDate); @@ -174,6 +182,8 @@ export class _Date { * faker.date.soon() // '2022-02-05T09:55:39.216Z' * faker.date.soon(10) // '2022-02-11T05:14:39.138Z' * faker.date.soon(10, '2020-01-01T00:00:00.000Z') // '2020-01-01T02:40:44.990Z' + * + * @since 5.0.0 */ soon(days?: number, refDate?: string | Date | number): Date { const date = toDate(refDate); @@ -201,6 +211,8 @@ export class _Date { * faker.date.month({ abbr: true }) // 'Feb' * faker.date.month({ context: true }) // 'June' * faker.date.month({ abbr: true, context: true }) // 'Sep' + * + * @since 3.0.1 */ month(options?: { abbr?: boolean; context?: boolean }): string { const abbr = options?.abbr ?? false; @@ -235,6 +247,8 @@ export class _Date { * faker.date.weekday({ abbr: true }) // 'Thu' * faker.date.weekday({ context: true }) // 'Thursday' * faker.date.weekday({ abbr: true, context: true }) // 'Fri' + * + * @since 3.0.1 */ weekday(options?: { abbr?: boolean; context?: boolean }): string { const abbr = options?.abbr ?? false; @@ -276,6 +290,8 @@ export class _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 + * + * @since 7.0.0 */ birthdate( options: { diff --git a/src/modules/fake/index.ts b/src/modules/fake/index.ts index 64d3bab20bf..94ad4325149 100644 --- a/src/modules/fake/index.ts +++ b/src/modules/fake/index.ts @@ -6,10 +6,10 @@ import { deprecated } from '../../internal/deprecated'; * * @deprecated */ -export class Fake { +export class FakeModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Fake.prototype)) { + for (const name of Object.getOwnPropertyNames(FakeModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -59,6 +59,8 @@ export class Fake { * faker.fake('You can call me at {{phone.number(!## ### #####!)}}.') // 'You can call me at 202 555 973722.' * faker.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails' * + * @since 3.0.0 + * * @deprecated Use faker.helpers.fake() instead. */ fake(str: string): string { diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts index c6f799764a5..d1580603e24 100644 --- a/src/modules/finance/index.ts +++ b/src/modules/finance/index.ts @@ -5,10 +5,10 @@ import iban from './iban'; /** * Module to generate finance related entries. */ -export class Finance { +export class FinanceModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Finance.prototype)) { + for (const name of Object.getOwnPropertyNames(FinanceModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -24,6 +24,8 @@ export class Finance { * @example * faker.finance.account() // 92842238 * faker.finance.account(5) // 32564 + * + * @since 2.0.1 */ account(length?: number): string { length = length || 8; @@ -41,6 +43,8 @@ export class Finance { * * @example * faker.finance.accountName() // 'Personal Loan Account' + * + * @since 2.0.1 */ accountName(): string { return [ @@ -56,6 +60,8 @@ export class Finance { * * @example * faker.finance.routingNumber() // '522814402' + * + * @since 5.0.0 */ routingNumber(): string { const routingNumber = @@ -85,6 +91,8 @@ export class Finance { * faker.finance.mask(3) // '(...342)' * faker.finance.mask(3, false) // '...236' * faker.finance.mask(3, false, false) // '298' + * + * @since 2.0.1 */ mask(length?: number, parens?: boolean, ellipsis?: boolean): string { // set defaults @@ -125,6 +133,8 @@ export class Finance { * faker.finance.amount(5, 10, 0) // '8' * faker.finance.amount(5, 10, 2, '$') // '$5.85' * faker.finance.amount(5, 10, 5, '', true) // '9,75067' + * + * @since 2.0.1 */ amount( min: number = 0, @@ -156,6 +166,8 @@ export class Finance { * * @example * faker.finance.transactionType() // 'payment' + * + * @since 2.0.1 */ transactionType(): string { return this.faker.helpers.arrayElement( @@ -169,6 +181,8 @@ export class Finance { * * @example * faker.finance.currencyCode() // 'USD' + * + * @since 2.0.1 */ currencyCode(): string { return this.faker.helpers.objectValue( @@ -181,6 +195,8 @@ export class Finance { * * @example * faker.finance.currencyName() // 'US Dollar' + * + * @since 2.0.1 */ currencyName(): string { return this.faker.helpers.objectKey( @@ -193,6 +209,8 @@ export class Finance { * * @example * faker.finance.currencySymbol() // '$' + * + * @since 2.0.1 */ currencySymbol(): string { let symbol: string; @@ -209,6 +227,8 @@ export class Finance { * * @example * faker.finance.bitcoinAddress() // '3ySdvCkTLVy7gKD4j6JfSaf5d' + * + * @since 3.1.0 */ bitcoinAddress(): string { const addressLength = this.faker.datatype.number({ min: 25, max: 34 }); @@ -228,6 +248,8 @@ export class Finance { * * @example * faker.finance.litecoinAddress() // 'MoQaSTGWBRXkWfyxKbNKuPrAWGELzcW' + * + * @since 5.0.0 */ litecoinAddress(): string { const addressLength = this.faker.datatype.number({ min: 26, max: 33 }); @@ -251,6 +273,8 @@ export class Finance { * faker.finance.creditCardNumber() // '4427163488662' * faker.finance.creditCardNumber('visa') // '4882664999007' * faker.finance.creditCardNumber('63[7-9]#-####-####-###L') // '6375-3265-4676-6646' + * + * @since 5.0.0 */ creditCardNumber(issuer = ''): string { let format: string; @@ -276,6 +300,8 @@ export class Finance { * * @example * faker.finance.creditCardCVV() // '506' + * + * @since 5.0.0 */ creditCardCVV(): string { let cvv = ''; @@ -290,6 +316,8 @@ export class Finance { * * @example * faker.finance.creditCardIssuer() // 'discover' + * + * @since 6.3.0 */ creditCardIssuer(): string { return this.faker.helpers.objectKey( @@ -306,6 +334,8 @@ export class Finance { * @example * faker.finance.pin() // '5067' * faker.finance.pin(6) // '213789' + * + * @since 6.2.0 */ pin(length: number = 4): string { if (length < 1) { @@ -319,6 +349,8 @@ export class Finance { * * @example * faker.finance.ethereumAddress() // '0xf03dfeecbafc5147241cc4c4ca20b3c9dfd04c4a' + * + * @since 5.0.0 */ ethereumAddress(): string { const address = this.faker.datatype.hexadecimal({ @@ -339,6 +371,8 @@ export class Finance { * faker.finance.iban() // 'TR736918640040966092800056' * faker.finance.iban(true) // 'FR20 8008 2330 8984 74S3 Z620 224' * faker.finance.iban(true, 'DE') // 'DE84 1022 7075 0900 1170 01' + * + * @since 4.0.0 */ iban(formatted: boolean = false, countryCode?: string): string { const ibanFormat = countryCode @@ -397,6 +431,8 @@ export class Finance { * * @example * faker.finance.bic() // 'WYAUPGX1432' + * + * @since 4.0.0 */ bic(): string { const bankIdentifier = this.faker.random.alpha({ @@ -420,6 +456,8 @@ export class Finance { * @example * faker.finance.transactionDescription() * // 'invoice transaction at Kilback - Durgan using card ending with ***(...4316) for UAH 783.82 in account ***16168663' + * + * @since 5.1.0 */ transactionDescription(): string { const amount = this.amount(); diff --git a/src/modules/git/index.ts b/src/modules/git/index.ts index be8d02f172e..d92e34540c8 100644 --- a/src/modules/git/index.ts +++ b/src/modules/git/index.ts @@ -3,10 +3,10 @@ import type { Faker } from '../..'; /** * Module to generate git related entries. */ -export class Git { +export class GitModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Git.prototype)) { + for (const name of Object.getOwnPropertyNames(GitModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -19,6 +19,8 @@ export class Git { * * @example * faker.git.branch() // 'feed-parse' + * + * @since 5.0.0 */ branch(): string { const noun = this.faker.hacker.noun().replace(' ', '-'); @@ -42,6 +44,8 @@ export class Git { * // Date: Sat Feb 05 2022 15:09:18 GMT+0100 (Mitteleuropäische Normalzeit) * // * // copy primary system + * + * @since 5.0.0 */ commitEntry( options: { @@ -80,6 +84,8 @@ export class Git { * * @example * faker.git.commitMessage() // 'reboot cross-platform driver' + * + * @since 5.0.0 */ commitMessage(): string { return `${this.faker.hacker.verb()} ${this.faker.hacker.adjective()} ${this.faker.hacker.noun()}`; @@ -90,6 +96,8 @@ export class Git { * * @example * faker.git.commitSha() // '2c6e3880fd94ddb7ef72d34e683cdc0c47bec6e6' + * + * @since 5.0.0 */ commitSha(): string { return this.faker.datatype.hexadecimal({ @@ -104,6 +112,8 @@ export class Git { * * @example * faker.git.shortSha() // '6155732' + * + * @since 5.0.0 */ shortSha(): string { return this.faker.datatype.hexadecimal({ diff --git a/src/modules/hacker/index.ts b/src/modules/hacker/index.ts index ee1bbc5c32e..d842d74e2a3 100644 --- a/src/modules/hacker/index.ts +++ b/src/modules/hacker/index.ts @@ -3,10 +3,10 @@ import type { Faker } from '../..'; /** * Module to generate hacker/IT words and phrases. */ -export class Hacker { +export class HackerModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Hacker.prototype)) { + for (const name of Object.getOwnPropertyNames(HackerModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -19,6 +19,8 @@ export class Hacker { * * @example * faker.hacker.abbreviation() // 'THX' + * + * @since 2.0.1 */ abbreviation(): string { return this.faker.helpers.arrayElement( @@ -31,6 +33,8 @@ export class Hacker { * * @example * faker.hacker.adjective() // 'cross-platform' + * + * @since 2.0.1 */ adjective(): string { return this.faker.helpers.arrayElement( @@ -43,6 +47,8 @@ export class Hacker { * * @example * faker.hacker.noun() // 'system' + * + * @since 2.0.1 */ noun(): string { return this.faker.helpers.arrayElement(this.faker.definitions.hacker.noun); @@ -53,6 +59,8 @@ export class Hacker { * * @example * faker.hacker.verb() // 'copy' + * + * @since 2.0.1 */ verb(): string { return this.faker.helpers.arrayElement(this.faker.definitions.hacker.verb); @@ -63,6 +71,8 @@ export class Hacker { * * @example * faker.hacker.ingverb() // 'navigating' + * + * @since 2.0.1 */ ingverb(): string { return this.faker.helpers.arrayElement( @@ -76,6 +86,8 @@ export class Hacker { * @example * faker.hacker.phrase() * // 'If we override the card, we can get to the HDD feed through the back-end HDD sensor!' + * + * @since 2.0.1 */ phrase(): string { const data = { diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts index 5228c605fa7..f6aa55ac985 100644 --- a/src/modules/helpers/index.ts +++ b/src/modules/helpers/index.ts @@ -9,10 +9,10 @@ import * as uniqueExec from './unique'; * Module with various helper methods that transform the method input rather than returning values from locales. * The transformation process may call methods that use the locale data. */ -export class Helpers { +export class HelpersModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Helpers.prototype)) { + for (const name of Object.getOwnPropertyNames(HelpersModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -30,6 +30,8 @@ export class Helpers { * @example * faker.helpers.slugify() // '' * faker.helpers.slugify("Hello world!") // 'Hello-world' + * + * @since 2.0.1 */ slugify(string: string = ''): string { return string @@ -49,6 +51,8 @@ export class Helpers { * faker.helpers.replaceSymbolWithNumber('#####') // '04812' * faker.helpers.replaceSymbolWithNumber('!####') // '27378' * faker.helpers.replaceSymbolWithNumber('Your pin is: !####') // '29841' + * + * @since 2.0.1 */ replaceSymbolWithNumber(string: string = '', symbol: string = '#'): string { let str = ''; @@ -79,6 +83,8 @@ export class Helpers { * faker.helpers.replaceSymbols('?????') // 'ZYRQQ' * faker.helpers.replaceSymbols('*****') // '4Z3P7' * faker.helpers.replaceSymbols('Your pin is: #?*#?*') // '0T85L1' + * + * @since 3.0.0 */ replaceSymbols(string: string = ''): string { const alpha = [ @@ -139,6 +145,8 @@ export class Helpers { * @example * faker.helpers.replaceCreditCardSymbols() // '6453-4876-8626-8995-3771' * faker.helpers.replaceCreditCardSymbols('1234-[4-9]-##!!-L') // '1234-9-5298-2' + * + * @since 5.0.0 */ replaceCreditCardSymbols( string: string = '6453-####-####-####-###L', @@ -164,6 +172,8 @@ export class Helpers { * faker.helpers.repeatString('Hello world! ', 1) // 'Hello world! ' * faker.helpers.repeatString('Hello world! ', 2) // 'Hello world! Hello world! ' * + * @since 5.0.0 + * * @deprecated Use [String.prototype.repeat()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat) instead. */ repeatString(string = '', num = 0): string { @@ -192,6 +202,8 @@ export class Helpers { * faker.helpers.regexpStyleStringParse('#{2,9}') // '#######' * faker.helpers.regexpStyleStringParse('[500-15000]') // '8375' * faker.helpers.regexpStyleStringParse('#{3}test[1-5]') // '###test3' + * + * @since 5.0.0 */ regexpStyleStringParse(string: string = ''): string { // Deal with range repeat `{min,max}` @@ -262,6 +274,8 @@ export class Helpers { * @example * faker.helpers.shuffle() // [] * faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ] + * + * @since 2.0.1 */ shuffle(o?: T[]): T[] { if (o == null || o.length === 0) { @@ -290,6 +304,8 @@ export class Helpers { * faker.helpers.uniqueArray(faker.random.word, 50) * faker.helpers.uniqueArray(faker.definitions.name.first_name, 6) * faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2) + * + * @since 6.0.0 */ uniqueArray(source: readonly T[] | (() => T), length: number): T[] { if (Array.isArray(source)) { @@ -323,6 +339,8 @@ export class Helpers { * count: () => `${faker.datatype.number()}`, * word: "this word", * }) // 'I found 57591 instances of "this word".' + * + * @since 2.0.1 */ mustache( str: string | undefined, @@ -355,6 +373,8 @@ export class Helpers { * faker.helpers.maybe(() => 'Hello World!') // 'Hello World!' * faker.helpers.maybe(() => 'Hello World!', { probability: 0.1 }) // undefined * faker.helpers.maybe(() => 'Hello World!', { probability: 0.9 }) // 'Hello World!' + * + * @since 6.3.0 */ maybe( callback: () => T, @@ -374,6 +394,8 @@ export class Helpers { * * @example * faker.helpers.objectKey({ myProperty: 'myValue' }) // 'myProperty' + * + * @since 6.3.0 */ objectKey>(object: T): keyof T { const array: Array = Object.keys(object); @@ -387,6 +409,8 @@ export class Helpers { * * @example * faker.helpers.objectValue({ myProperty: 'myValue' }) // 'myValue' + * + * @since 6.3.0 */ objectValue>(object: T): T[keyof T] { const key = this.faker.helpers.objectKey(object); @@ -401,6 +425,8 @@ export class Helpers { * * @example * faker.helpers.arrayElement(['cat', 'dog', 'mouse']) // 'dog' + * + * @since 6.3.0 */ arrayElement( // TODO @Shinigami92 2022-04-30: We want to remove this default value, but currently it's not possible because some definitions could be empty @@ -427,6 +453,8 @@ export class Helpers { * @example * faker.helpers.arrayElements(['cat', 'dog', 'mouse']) // ['mouse', 'cat'] * faker.helpers.arrayElements([1, 2, 3, 4, 5], 2) // [4, 2] + * + * @since 6.3.0 */ arrayElements( // TODO @Shinigami92 2022-04-30: We want to remove this default value, but currently it's not possible because some definitions could be empty @@ -503,6 +531,8 @@ export class Helpers { * faker.helpers.fake('Good Morning {{name.firstName}}!') // 'Good Morning Estelle!' * faker.helpers.fake('You can call me at {{phone.number(!## ### #####!)}}.') // 'You can call me at 202 555 973722.' * faker.helpers.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails' + * + * @since 7.4.0 */ fake(str: string): string { // if incoming str parameter is not provided, return error message @@ -611,6 +641,8 @@ export class Helpers { * * @example * faker.helpers.unique(faker.name.firstName) // 'Corbin' + * + * @since 7.5.0 */ unique RecordKey>( method: Method, diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts index 08cef08ff59..1a709505da9 100644 --- a/src/modules/image/index.ts +++ b/src/modules/image/index.ts @@ -10,7 +10,7 @@ import { Unsplash } from './providers/unsplash'; * * Default provider is unsplash image provider. */ -export class Image { +export class ImageModule { readonly lorempixel: Lorempixel; readonly unsplash: Unsplash; readonly lorempicsum: LoremPicsum; @@ -18,7 +18,7 @@ export class Image { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Image.prototype)) { + for (const name of Object.getOwnPropertyNames(ImageModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -42,9 +42,11 @@ export class Image { * faker.image.image() // 'https://loremflickr.com/640/480/city' * faker.image.image(1234, 2345) // 'https://loremflickr.com/1234/2345/sports' * faker.image.image(1234, 2345, true) // 'https://loremflickr.com/1234/2345/nature?56789' + * + * @since 2.0.1 */ image(width?: number, height?: number, randomize?: boolean): string { - const categories: MethodsOf = [ + const categories: MethodsOf = [ 'abstract', 'animals', 'business', @@ -72,6 +74,8 @@ export class Image { * @example * faker.image.avatar() * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/170.jpg' + * + * @since 2.0.1 */ avatar(): string { return this.faker.internet.avatar(); @@ -90,6 +94,8 @@ export class Image { * faker.image.imageUrl(1234, 2345) // 'https://loremflickr.com/1234/2345' * faker.image.imageUrl(1234, 2345, 'cat') // 'https://loremflickr.com/1234/2345/cat' * faker.image.imageUrl(1234, 2345, 'cat', true) // 'https://loremflickr.com/1234/2345/cat?6849' + * + * @since 2.0.1 */ imageUrl( width?: number, @@ -122,6 +128,8 @@ export class Image { * faker.image.abstract() // 'https://loremflickr.com/640/480/abstract' * faker.image.abstract(1234, 2345) // 'https://loremflickr.com/1234/2345/abstract' * faker.image.abstract(1234, 2345, true) // 'https://loremflickr.com/1234/2345/abstract?56789' + * + * @since 2.0.1 */ abstract(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'abstract', randomize); @@ -138,6 +146,8 @@ export class Image { * faker.image.animals() // 'https://loremflickr.com/640/480/animals' * faker.image.animals(1234, 2345) // 'https://loremflickr.com/1234/2345/animals' * faker.image.animals(1234, 2345, true) // 'https://loremflickr.com/1234/2345/animals?56789' + * + * @since 2.0.1 */ animals(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'animals', randomize); @@ -154,6 +164,8 @@ export class Image { * faker.image.business() // 'https://loremflickr.com/640/480/business' * faker.image.business(1234, 2345) // 'https://loremflickr.com/1234/2345/business' * faker.image.business(1234, 2345, true) // 'https://loremflickr.com/1234/2345/business?56789' + * + * @since 2.0.1 */ business(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'business', randomize); @@ -170,6 +182,8 @@ export class Image { * faker.image.cats() // 'https://loremflickr.com/640/480/cats' * faker.image.cats(1234, 2345) // 'https://loremflickr.com/1234/2345/cats' * faker.image.cats(1234, 2345, true) // 'https://loremflickr.com/1234/2345/cats?56789' + * + * @since 2.0.1 */ cats(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'cats', randomize); @@ -186,6 +200,8 @@ export class Image { * faker.image.city() // 'https://loremflickr.com/640/480/city' * faker.image.city(1234, 2345) // 'https://loremflickr.com/1234/2345/city' * faker.image.city(1234, 2345, true) // 'https://loremflickr.com/1234/2345/city?56789' + * + * @since 2.0.1 */ city(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'city', randomize); @@ -202,6 +218,8 @@ export class Image { * faker.image.food() // 'https://loremflickr.com/640/480/food' * faker.image.food(1234, 2345) // 'https://loremflickr.com/1234/2345/food' * faker.image.food(1234, 2345, true) // 'https://loremflickr.com/1234/2345/food?56789' + * + * @since 2.0.1 */ food(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'food', randomize); @@ -218,6 +236,8 @@ export class Image { * faker.image.nightlife() // 'https://loremflickr.com/640/480/nightlife' * faker.image.nightlife(1234, 2345) // 'https://loremflickr.com/1234/2345/nightlife' * faker.image.nightlife(1234, 2345, true) // 'https://loremflickr.com/1234/2345/nightlife?56789' + * + * @since 2.0.1 */ nightlife(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'nightlife', randomize); @@ -234,6 +254,8 @@ export class Image { * faker.image.fashion() // 'https://loremflickr.com/640/480/fashion' * faker.image.fashion(1234, 2345) // 'https://loremflickr.com/1234/2345/fashion' * faker.image.fashion(1234, 2345, true) // 'https://loremflickr.com/1234/2345/fashion?56789' + * + * @since 2.0.1 */ fashion(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'fashion', randomize); @@ -250,6 +272,8 @@ export class Image { * faker.image.people() // 'https://loremflickr.com/640/480/people' * faker.image.people(1234, 2345) // 'https://loremflickr.com/1234/2345/people' * faker.image.people(1234, 2345, true) // 'https://loremflickr.com/1234/2345/people?56789' + * + * @since 2.0.1 */ people(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'people', randomize); @@ -266,6 +290,8 @@ export class Image { * faker.image.nature() // 'https://loremflickr.com/640/480/nature' * faker.image.nature(1234, 2345) // 'https://loremflickr.com/1234/2345/nature' * faker.image.nature(1234, 2345, true) // 'https://loremflickr.com/1234/2345/nature?56789' + * + * @since 2.0.1 */ nature(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'nature', randomize); @@ -282,6 +308,8 @@ export class Image { * faker.image.sports() // 'https://loremflickr.com/640/480/sports' * faker.image.sports(1234, 2345) // 'https://loremflickr.com/1234/2345/sports' * faker.image.sports(1234, 2345, true) // 'https://loremflickr.com/1234/2345/sports?56789' + * + * @since 2.0.1 */ sports(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'sports', randomize); @@ -298,6 +326,8 @@ export class Image { * faker.image.technics() // 'https://loremflickr.com/640/480/technics' * faker.image.technics(1234, 2345) // 'https://loremflickr.com/1234/2345/technics' * faker.image.technics(1234, 2345, true) // 'https://loremflickr.com/1234/2345/technics?56789' + * + * @since 2.0.1 */ technics(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'technics', randomize); @@ -314,6 +344,8 @@ export class Image { * faker.image.transport() // 'https://loremflickr.com/640/480/transport' * faker.image.transport(1234, 2345) // 'https://loremflickr.com/1234/2345/transport' * faker.image.transport(1234, 2345, true) // 'https://loremflickr.com/1234/2345/transport?56789' + * + * @since 2.0.1 */ transport(width?: number, height?: number, randomize?: boolean): string { return this.imageUrl(width, height, 'transport', randomize); @@ -328,6 +360,8 @@ export class Image { * * @example * faker.image.dataUri() // 'data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns%3D%22http...' + * + * @since 4.0.0 */ dataUri(width?: number, height?: number, color: string = 'grey'): string { const svgString = `(); @@ -156,6 +168,8 @@ export class System { * @example * faker.system.fileExt() // 'emf' * faker.system.fileExt('application/json') // 'json' + * + * @since 3.1.0 */ fileExt(mimeType?: string): string { if (typeof mimeType === 'string') { @@ -183,6 +197,8 @@ export class System { * * @example * faker.system.directoryPath() // '/etc/mail' + * + * @since 3.1.0 */ directoryPath(): string { const paths = this.faker.definitions.system.directoryPaths; @@ -194,6 +210,8 @@ export class System { * * @example * faker.system.filePath() // '/usr/local/src/money.dotx' + * + * @since 3.1.0 */ // TODO @prisis 2022-01-25: add a parameter to have the possibility to have one or two ext on file. filePath(): string { @@ -205,6 +223,8 @@ export class System { * * @example * faker.system.semver() // '1.1.2' + * + * @since 3.1.0 */ semver(): string { return [ @@ -226,6 +246,8 @@ export class System { * faker.system.networkInterface({ interfaceType: 'wl' }) // 'wlo1' * faker.system.networkInterface({ interfaceSchema: 'mac' }) // 'enx000c29c00000' * faker.system.networkInterface({ interfaceType: 'en', interfaceSchema: 'pci' }) // 'enp5s0f1d0' + * + * @since 7.4.0 */ networkInterface( options: { @@ -288,6 +310,8 @@ export class System { * faker.system.cron({ includeYear: false }) // '45 23 * * 6' * faker.system.cron({ includeNonStandard: false }) // '45 23 * * 6' * faker.system.cron({ includeNonStandard: true }) // '@yearly' + * + * @since 7.5.0 */ cron( options: { diff --git a/src/modules/unique/index.ts b/src/modules/unique/index.ts index 6c02d6d885e..fd817ec498b 100644 --- a/src/modules/unique/index.ts +++ b/src/modules/unique/index.ts @@ -7,10 +7,10 @@ import type { RecordKey } from '../helpers/unique'; * * @deprecated */ -export class Unique { +export class UniqueModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Unique.prototype)) { + for (const name of Object.getOwnPropertyNames(UniqueModule.prototype)) { if ( name === 'constructor' || name === 'maxTime' || @@ -44,6 +44,8 @@ export class Unique { * @example * faker.unique(faker.name.firstName) // 'Corbin' * + * @since 5.0.0 + * * @deprecated Use faker.helpers.unique() instead. */ unique RecordKey>( diff --git a/src/modules/vehicle/index.ts b/src/modules/vehicle/index.ts index 903dab539e8..cd01ece30c9 100644 --- a/src/modules/vehicle/index.ts +++ b/src/modules/vehicle/index.ts @@ -3,10 +3,10 @@ import type { Faker } from '../..'; /** * Module to generate vehicle related entries. */ -export class Vehicle { +export class VehicleModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Vehicle.prototype)) { + for (const name of Object.getOwnPropertyNames(VehicleModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -19,6 +19,8 @@ export class Vehicle { * * @example * faker.vehicle.vehicle() // 'BMW Explorer' + * + * @since 5.0.0 */ vehicle(): string { return `${this.manufacturer()} ${this.model()}`; @@ -29,6 +31,8 @@ export class Vehicle { * * @example * faker.vehicle.manufacturer() // 'Ford' + * + * @since 5.0.0 */ manufacturer(): string { return this.faker.helpers.arrayElement( @@ -41,6 +45,8 @@ export class Vehicle { * * @example * faker.vehicle.model() // 'Explorer' + * + * @since 5.0.0 */ model(): string { return this.faker.helpers.arrayElement( @@ -53,6 +59,8 @@ export class Vehicle { * * @example * faker.vehicle.type() // 'Coupe' + * + * @since 5.0.0 */ type(): string { return this.faker.helpers.arrayElement(this.faker.definitions.vehicle.type); @@ -63,6 +71,8 @@ export class Vehicle { * * @example * faker.vehicle.fuel() // 'Electric' + * + * @since 5.0.0 */ fuel(): string { return this.faker.helpers.arrayElement(this.faker.definitions.vehicle.fuel); @@ -73,6 +83,8 @@ export class Vehicle { * * @example * faker.vehicle.vin() // 'YV1MH682762184654' + * + * @since 5.0.0 */ vin(): string { const bannedChars = ['o', 'i', 'q', 'O', 'I', 'Q']; @@ -95,6 +107,8 @@ export class Vehicle { * * @example * faker.vehicle.color() // 'red' + * + * @since 5.0.0 */ color(): string { return this.faker.color.human(); @@ -105,6 +119,8 @@ export class Vehicle { * * @example * faker.vehicle.vrm() // 'MF56UPA' + * + * @since 5.4.0 */ vrm(): string { return `${this.faker.random.alpha({ @@ -124,6 +140,8 @@ export class Vehicle { * * @example * faker.vehicle.bicycle() // 'Adventure Road Bicycle' + * + * @since 5.5.0 */ bicycle(): string { return this.faker.helpers.arrayElement( diff --git a/src/modules/word/index.ts b/src/modules/word/index.ts index 5968d225b3b..725c0c4263f 100644 --- a/src/modules/word/index.ts +++ b/src/modules/word/index.ts @@ -28,10 +28,10 @@ function filterWordListByLength(options: { /** * Module to return various types of words. */ -export class Word { +export class WordModule { constructor(private readonly faker: Faker) { // Bind `this` so namespaced is working correctly - for (const name of Object.getOwnPropertyNames(Word.prototype)) { + for (const name of Object.getOwnPropertyNames(WordModule.prototype)) { if (name === 'constructor' || typeof this[name] !== 'function') { continue; } @@ -48,6 +48,8 @@ export class Word { * faker.word.adjective() // 'pungent' * faker.word.adjective(5) // 'slimy' * faker.word.adjective(100) // 'complete' + * + * @since 6.0.0 */ adjective(length?: number): string { return this.faker.helpers.arrayElement( @@ -67,6 +69,8 @@ export class Word { * faker.word.adverb() // 'quarrelsomely' * faker.word.adverb(5) // 'madly' * faker.word.adverb(100) // 'sadly' + * + * @since 6.0.0 */ adverb(length?: number): string { return this.faker.helpers.arrayElement( @@ -86,6 +90,8 @@ export class Word { * faker.word.conjunction() // 'in order that' * faker.word.conjunction(5) // 'since' * faker.word.conjunction(100) // 'as long as' + * + * @since 6.0.0 */ conjunction(length?: number): string { return this.faker.helpers.arrayElement( @@ -105,6 +111,8 @@ export class Word { * faker.word.interjection() // 'gah' * faker.word.interjection(5) // 'fooey' * faker.word.interjection(100) // 'yowza' + * + * @since 6.0.0 */ interjection(length?: number): string { return this.faker.helpers.arrayElement( @@ -124,6 +132,8 @@ export class Word { * faker.word.noun() // 'external' * faker.word.noun(5) // 'front' * faker.word.noun(100) // 'care' + * + * @since 6.0.0 */ noun(length?: number): string { return this.faker.helpers.arrayElement( @@ -143,6 +153,8 @@ export class Word { * faker.word.preposition() // 'without' * faker.word.preposition(5) // 'abaft' * faker.word.preposition(100) // 'an' + * + * @since 6.0.0 */ preposition(length?: number): string { return this.faker.helpers.arrayElement( @@ -162,6 +174,8 @@ export class Word { * faker.word.verb() // 'act' * faker.word.verb(5) // 'tinge' * faker.word.verb(100) // 'mess' + * + * @since 6.0.0 */ verb(length?: number): string { return this.faker.helpers.arrayElement( diff --git a/test/__snapshots__/datatype.spec.ts.snap b/test/__snapshots__/datatype.spec.ts.snap index 7980ec5c2d3..0c92b8fee86 100644 --- a/test/__snapshots__/datatype.spec.ts.snap +++ b/test/__snapshots__/datatype.spec.ts.snap @@ -76,8 +76,6 @@ exports[`datatype > 42 > hexadecimal > with casing 1`] = `"0x8"`; exports[`datatype > 42 > hexadecimal > with length 1`] = `"0x8BE4ABdd39321aD7d3fe01FfCE404F4d6db0906bd8"`; -exports[`datatype > 42 > hexadecimal > with length and casing 1`] = `"0x8be4abdd39321ad7d3fe"`; - exports[`datatype > 42 > hexadecimal > with length, prefix, and casing 1`] = `"0x8be4abdd39321ad7d3fe"`; exports[`datatype > 42 > hexadecimal > with prefix 1`] = `"0x8"`; @@ -194,8 +192,6 @@ exports[`datatype > 1211 > hexadecimal > with casing 1`] = `"0xe"`; exports[`datatype > 1211 > hexadecimal > with length 1`] = `"0xEaDB42F0e3f4A973fAB0AeefCE96DFCF49cD438dF9"`; -exports[`datatype > 1211 > hexadecimal > with length and casing 1`] = `"0xeadb42f0e3f4a973fab0"`; - exports[`datatype > 1211 > hexadecimal > with length, prefix, and casing 1`] = `"0xeadb42f0e3f4a973fab0"`; exports[`datatype > 1211 > hexadecimal > with prefix 1`] = `"0xE"`; @@ -312,8 +308,6 @@ exports[`datatype > 1337 > hexadecimal > with casing 1`] = `"0x5"`; exports[`datatype > 1337 > hexadecimal > with length 1`] = `"0x5c346ba075bd57F5A62B82d72AF39CBBB07a98cbA8"`; -exports[`datatype > 1337 > hexadecimal > with length and casing 1`] = `"0x5c346ba075bd57f5a62b"`; - exports[`datatype > 1337 > hexadecimal > with length, prefix, and casing 1`] = `"0x5c346ba075bd57f5a62b"`; exports[`datatype > 1337 > hexadecimal > with prefix 1`] = `"0x5"`; diff --git a/test/mersenne.spec.ts b/test/mersenne.spec.ts index 4ed803af823..62b65a69be6 100644 --- a/test/mersenne.spec.ts +++ b/test/mersenne.spec.ts @@ -1,6 +1,6 @@ import { beforeAll, beforeEach, describe, expect, it } from 'vitest'; import { FakerError } from '../src/errors/faker-error'; -import { Mersenne } from '../src/modules/mersenne'; +import { MersenneModule } from '../src/modules/mersenne'; import { seededRuns } from './support/seededRuns'; const minMaxTestCases = [ @@ -14,10 +14,10 @@ const functionNames = ['rand']; const NON_SEEDED_BASED_RUN = 25; describe('mersenne twister', () => { - let mersenne: Mersenne; + let mersenne: MersenneModule; beforeEach(() => { - mersenne = new Mersenne(); + mersenne = new MersenneModule(); }); for (const seed of [...seededRuns, [42, 1, 2], [1337, 1, 2], [1211, 1, 2]]) { diff --git a/test/scripts/apidoc/examplesAndDeprecations.spec.ts b/test/scripts/apidoc/examplesAndDeprecations.spec.ts index 83443c524d6..4c94dedd442 100644 --- a/test/scripts/apidoc/examplesAndDeprecations.spec.ts +++ b/test/scripts/apidoc/examplesAndDeprecations.spec.ts @@ -9,6 +9,7 @@ import { selectApiModules } from '../../../scripts/apidoc/moduleMethods'; import { extractRawExamples, extractSeeAlsos, + extractSince, extractTagContent, isDeprecated, } from '../../../scripts/apidoc/utils'; @@ -119,6 +120,8 @@ describe('examples and deprecations', () => { expect(link, 'Expect method reference to contain ()').toContain(')'); } }); + + expect(extractSince(signature), '@since to be present').toBeTruthy(); }); }); }); diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index b11d40a5e8b..43407ab980b 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -240,4 +240,13 @@ export class SignatureTest { methodWithMultipleSeeMarkers(): number { return 0; } + + /** + * Test with since marker. + * + * @since 1.0.0 + */ + methodWithSinceMarker(): number { + return 0; + } } diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json index 4aaa97b5fce..15145f533e6 100644 --- a/test/scripts/apidoc/signature.expected.json +++ b/test/scripts/apidoc/signature.expected.json @@ -11,6 +11,7 @@ "description": "

The boolean parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.defaultBooleanParamMethod(c: boolean = true): number\n
\n
", "deprecated": false, @@ -27,6 +28,7 @@ "description": "

The function parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.functionParamMethod(fn: (a: string) => number): number\n
\n
", "deprecated": false, @@ -43,6 +45,7 @@ "description": "

'a' or 'b'.

\n" } ], + "since": "", "returns": "string", "examples": "
ts
faker.literalUnionParamMethod(value: 'a' | 'b' | string): string\n
\n
", "deprecated": false, @@ -53,6 +56,7 @@ "title": "Method With Deprecated", "description": "

Test with deprecated and see marker.

\n", "parameters": [], + "since": "", "returns": "number", "examples": "
ts
faker.methodWithDeprecated(): number\n
\n
", "deprecated": true, @@ -63,6 +67,7 @@ "title": "Method With Example", "description": "

Test with example marker.

\n", "parameters": [], + "since": "", "returns": "number", "examples": "
ts
faker.methodWithExample(): number\ntest.apidoc.methodWithExample() // 0\n
\n
", "deprecated": false, @@ -73,6 +78,7 @@ "title": "Method With Multiple See Markers", "description": "

Test with multiple see markers.

\n", "parameters": [], + "since": "", "returns": "number", "examples": "
ts
faker.methodWithMultipleSeeMarkers(): number\n
\n
", "deprecated": false, @@ -81,6 +87,17 @@ "test.apidoc.methodWithDeprecated()" ] }, + "methodWithSinceMarker": { + "name": "methodWithSinceMarker", + "title": "Method With Since Marker", + "description": "

Test with since marker.

\n", + "parameters": [], + "since": "1.0.0", + "returns": "number", + "examples": "
ts
faker.methodWithSinceMarker(): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, "multiParamMethod": { "name": "multiParamMethod", "title": "Multi Param Method", @@ -103,6 +120,7 @@ "description": "

The boolean parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.multiParamMethod(a: number, b?: string, c: boolean = true): number\n
\n
", "deprecated": false, @@ -113,6 +131,7 @@ "title": "No Param Method", "description": "

Test with no parameters.

\n", "parameters": [], + "since": "", "returns": "number", "examples": "
ts
faker.noParamMethod(): number\n
\n
", "deprecated": false, @@ -129,6 +148,7 @@ "description": "

The string parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.optionalStringParamMethod(b?: string): number\n
\n
", "deprecated": false, @@ -173,6 +193,7 @@ "description": "

The number parameter. It also has a more complex description.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.optionsInlineParamMethodWithDefaults(a: {\n  value: number\n} = { value: 1 }, b: {\n  value: number\n} = { value: 1 }, c: {\n  value: number\n}): number\n
\n
", "deprecated": false, @@ -201,6 +222,7 @@ "description": "

Parameter with inner jsdocs default.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.optionsInterfaceParamMethodWithDefaults(a: ParameterOptionsInterfaceA = { value: 1 }, b: ParameterOptionsInterfaceB = { value: 1 }, c: ParameterOptionsInterfaceC): number\n
\n
", "deprecated": false, @@ -237,6 +259,7 @@ "description": "

The method parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.optionsParamMethod(options: {\n  a: number,\n  b: string,\n  c: boolean,\n  d: () => string\n}): number\n
\n
", "deprecated": false, @@ -265,6 +288,7 @@ "description": "

Parameter with inner jsdocs default.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number\n
\n
", "deprecated": false, @@ -281,6 +305,7 @@ "description": "

The number parameter.

\n" } ], + "since": "", "returns": "number", "examples": "
ts
faker.requiredNumberParamMethod(a: number): number\n
\n
", "deprecated": false, @@ -297,6 +322,7 @@ "description": "

'a' or 'b'.

\n" } ], + "since": "", "returns": "string", "examples": "
ts
faker.stringUnionParamMethod(value: 'a' | 'b'): string\n
\n
", "deprecated": false,