address-faker
Version:
address faker
1,219 lines (1,213 loc) • 92.7 kB
TypeScript
/**
* A proxy for LocaleDefinition that marks all properties as required and throws an error when an entry is accessed that is not defined.
*/
type LocaleProxy = Readonly<{
[key in keyof LocaleDefinition]-?: LocaleProxyCategory<LocaleDefinition[key]>;
}>;
type LocaleProxyCategory<T> = Readonly<{
[key in keyof T]-?: LocaleProxyEntry<T[key]>;
}>;
type LocaleProxyEntry<T> = unknown extends T ? T : Readonly<NonNullable<T>>;
/**
* Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods (without methods requiring localized data).
*/
declare class SimpleHelpersModule extends SimpleModuleBase {
/**
* Slugifies the given string.
* For that all spaces (` `) are replaced by hyphens (`-`)
* and most non word characters except for dots and hyphens will be removed.
*
* @param string The input to slugify. Defaults to `''`.
*
* @example
* faker.helpers.slugify() // ''
* faker.helpers.slugify("Hello world!") // 'Hello-world'
*
* @since 2.0.1
*/
slugify(string?: string): string;
/**
* Parses the given string symbol by symbols and replaces the placeholder appropriately.
*
* - `#` will be replaced with a digit (`0` - `9`).
* - `?` will be replaced with an upper letter ('A' - 'Z')
* - and `*` will be replaced with either a digit or letter.
*
* @param string The template string to parse. Defaults to `''`.
*
* @example
* faker.helpers.replaceSymbols() // ''
* faker.helpers.replaceSymbols('#####') // '98441'
* faker.helpers.replaceSymbols('?????') // 'ZYRQQ'
* faker.helpers.replaceSymbols('*****') // '4Z3P7'
* faker.helpers.replaceSymbols('Your pin is: #?*#?*') // 'Your pin is: 0T85L1'
*
* @since 3.0.0
*/
replaceSymbols(string?: string): string;
/**
* Replaces the symbols and patterns in a credit card schema including Luhn checksum.
*
* This method supports both range patterns `[4-9]` as well as the patterns used by `replaceSymbolWithNumber()`.
* `L` will be replaced with the appropriate Luhn checksum.
*
* @param string The credit card format pattern. Defaults to `'6453-####-####-####-###L'`.
* @param symbol The symbol to replace with a digit. Defaults to `'#'`.
*
* @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, symbol?: string): string;
/**
* Generates a string matching the given regex like expressions.
*
* This function doesn't provide full support of actual `RegExp`.
* Features such as grouping, anchors and character classes are not supported.
* If you are looking for a library that randomly generates strings based on
* `RegExp`s, see [randexp.js](https://github.com/fent/randexp.js)
*
* Supported patterns:
* - `x{times}` => Repeat the `x` exactly `times` times.
* - `x{min,max}` => Repeat the `x` `min` to `max` times.
* - `[x-y]` => Randomly get a character between `x` and `y` (inclusive).
* - `[x-y]{times}` => Randomly get a character between `x` and `y` (inclusive) and repeat it `times` times.
* - `[x-y]{min,max}` => Randomly get a character between `x` and `y` (inclusive) and repeat it `min` to `max` times.
* - `[^...]` => Randomly get an ASCII number or letter character that is not in the given range. (e.g. `[^0-9]` will get a random non-numeric character).
* - `[-...]` => Include dashes in the range. Must be placed after the negate character `^` and before any character sets if used (e.g. `[^-0-9]` will not get any numeric characters or dashes).
* - `/[x-y]/i` => Randomly gets an uppercase or lowercase character between `x` and `y` (inclusive).
* - `x?` => Randomly decide to include or not include `x`.
* - `[x-y]?` => Randomly decide to include or not include characters between `x` and `y` (inclusive).
* - `x*` => Repeat `x` 0 or more times.
* - `[x-y]*` => Repeat characters between `x` and `y` (inclusive) 0 or more times.
* - `x+` => Repeat `x` 1 or more times.
* - `[x-y]+` => Repeat characters between `x` and `y` (inclusive) 1 or more times.
* - `.` => returns a wildcard ASCII character that can be any number, character or symbol. Can be combined with quantifiers as well.
*
* @param pattern The template string/RegExp to generate a matching string for.
*
* @throws If min value is more than max value in quantifier, e.g. `#{10,5}`.
* @throws If an invalid quantifier symbol is passed in.
*
* @example
* faker.helpers.fromRegExp('#{5}') // '#####'
* faker.helpers.fromRegExp('#{2,9}') // '#######'
* faker.helpers.fromRegExp('[1-7]') // '5'
* faker.helpers.fromRegExp('#{3}test[1-5]') // '###test3'
* faker.helpers.fromRegExp('[0-9a-dmno]') // '5'
* faker.helpers.fromRegExp('[^a-zA-Z0-8]') // '9'
* faker.helpers.fromRegExp('[a-d0-6]{2,8}') // 'a0dc45b0'
* faker.helpers.fromRegExp('[-a-z]{5}') // 'a-zab'
* faker.helpers.fromRegExp(/[A-Z0-9]{4}-[A-Z0-9]{4}/) // 'BS4G-485H'
* faker.helpers.fromRegExp(/[A-Z]{5}/i) // 'pDKfh'
* faker.helpers.fromRegExp(/.{5}/) // '14(#B'
* faker.helpers.fromRegExp(/Joh?n/) // 'Jon'
* faker.helpers.fromRegExp(/ABC*DE/) // 'ABDE'
* faker.helpers.fromRegExp(/bee+p/) // 'beeeeeeeep'
*
* @since 8.0.0
*/
fromRegExp(pattern: string | RegExp): string;
/**
* Takes an array and randomizes it in place then returns it.
*
* @template T The type of the elements to shuffle.
*
* @param list The array to shuffle.
* @param options The options to use when shuffling.
* @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
*
* @example
* faker.helpers.shuffle(['a', 'b', 'c'], { inplace: true }) // [ 'b', 'c', 'a' ]
*
* @since 8.0.0
*/
shuffle<const T>(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.
*
* @template T The type of the elements to shuffle.
*
* @param list The array to shuffle.
* @param options The options to use when shuffling.
* @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
*
* @example
* faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ]
* faker.helpers.shuffle(['a', 'b', 'c'], { inplace: false }) // [ 'b', 'c', 'a' ]
*
* @since 2.0.1
*/
shuffle<const T>(list: ReadonlyArray<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.
*
* @template T The type of the elements to shuffle.
*
* @param list The array to shuffle.
* @param options The options to use when shuffling.
* @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
*
* @example
* faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ]
* faker.helpers.shuffle(['a', 'b', 'c'], { inplace: true }) // [ 'b', 'c', 'a' ]
* faker.helpers.shuffle(['a', 'b', 'c'], { inplace: false }) // [ 'b', 'c', 'a' ]
*
* @since 2.0.1
*/
shuffle<const T>(list: T[], options?: {
/**
* Whether to shuffle the array in place or return a new array.
*
* @default false
*/
inplace?: boolean;
}): T[];
/**
* Takes an array of strings or function that returns a string
* and outputs a unique array of strings based on that source.
* This method does not store the unique state between invocations.
*
* If there are not enough unique values to satisfy the length, if
* the source is an array, it will only return as many items as are
* in the array. If the source is a function, it will return after
* a maximum number of attempts has been reached.
*
* @template T The type of the elements.
*
* @param source The strings to choose from or a function that generates a string.
* @param length The number of elements to generate.
*
* @example
* faker.helpers.uniqueArray(faker.word.sample, 3) // ['mob', 'junior', 'ripe']
* faker.helpers.uniqueArray(faker.definitions.person.first_name.generic, 6) // ['Silas', 'Montana', 'Lorenzo', 'Alayna', 'Aditya', 'Antone']
* faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2) // ['World', 'Goodbye']
*
* @since 6.0.0
*/
uniqueArray<const T>(source: ReadonlyArray<T> | (() => T), length: number): T[];
/**
* Replaces the `{{placeholder}}` patterns in the given string mustache style.
*
* @param text The template string to parse.
* @param data The data used to populate the placeholders.
* This is a record where the key is the template placeholder,
* whereas the value is either a string or a function suitable for `String.replace()`.
*
* @example
* faker.helpers.mustache('I found {{count}} instances of "{{word}}".', {
* count: () => `${faker.number.int()}`,
* word: "this word",
* }) // 'I found 57591 instances of "this word".'
*
* @since 2.0.1
*/
mustache(text: string | undefined, data: Record<string, string | Parameters<string['replace']>[1]>): string;
/**
* Returns the result of the callback if the probability check was successful, otherwise `undefined`.
*
* @template TResult The type of result of the given callback.
*
* @param callback The callback to that will be invoked if the probability check was successful.
* @param options The options to use.
* @param options.probability The probability (`[0.00, 1.00]`) of the callback being invoked. Defaults to `0.5`.
*
* @example
* 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<const TResult>(callback: () => TResult, options?: {
/**
* The probability (`[0.00, 1.00]`) of the callback being invoked.
*
* @default 0.5
*/
probability?: number;
}): TResult | undefined;
/**
* Returns a random key from the given object.
*
* @template T The type of the object to select from.
*
* @param object The object to be used.
*
* @throws If the given object is empty.
*
* @example
* faker.helpers.objectKey({ Cheetah: 120, Falcon: 390, Snail: 0.03 }) // 'Falcon'
*
* @since 6.3.0
*/
objectKey<const T extends Record<string, unknown>>(object: T): keyof T;
/**
* Returns a random value from the given object.
*
* @template T The type of object to select from.
*
* @param object The object to be used.
*
* @throws If the given object is empty.
*
* @example
* faker.helpers.objectValue({ Cheetah: 120, Falcon: 390, Snail: 0.03 }) // 390
*
* @since 6.3.0
*/
objectValue<const T extends Record<string, unknown>>(object: T): T[keyof T];
/**
* Returns a random `[key, value]` pair from the given object.
*
* @template T The type of the object to select from.
*
* @param object The object to be used.
*
* @throws If the given object is empty.
*
* @example
* faker.helpers.objectEntry({ Cheetah: 120, Falcon: 390, Snail: 0.03 }) // ['Snail', 0.03]
*
* @since 8.0.0
*/
objectEntry<const T extends Record<string, unknown>>(object: T): [keyof T, T[keyof T]];
/**
* Returns random element from the given array.
*
* @template T The type of the elements to pick from.
*
* @param array The array to pick the value from.
*
* @throws If the given array is empty.
*
* @example
* faker.helpers.arrayElement(['cat', 'dog', 'mouse']) // 'dog'
*
* @since 6.3.0
*/
arrayElement<const T>(array: ReadonlyArray<T>): T;
/**
* Returns a weighted random element from the given array. Each element of the array should be an object with two keys `weight` and `value`.
*
* - Each `weight` key should be a number representing the probability of selecting the value, relative to the sum of the weights. Weights can be any positive float or integer.
* - Each `value` key should be the corresponding value.
*
* For example, if there are two values A and B, with weights 1 and 2 respectively, then the probability of picking A is 1/3 and the probability of picking B is 2/3.
*
* @template T The type of the elements to pick from.
*
* @param array Array to pick the value from.
* @param array[].weight The weight of the value.
* @param array[].value The value to pick.
*
* @example
* faker.helpers.weightedArrayElement([{ weight: 5, value: 'sunny' }, { weight: 4, value: 'rainy' }, { weight: 1, value: 'snowy' }]) // 'sunny', 50% of the time, 'rainy' 40% of the time, 'snowy' 10% of the time
*
* @since 8.0.0
*/
weightedArrayElement<const T>(array: ReadonlyArray<{
/**
* The weight of the value.
*/
weight: number;
/**
* The value to pick.
*/
value: T;
}>): T;
/**
* Returns a subset with random elements of the given array in random order.
*
* @template T The type of the elements to pick from.
*
* @param array Array to pick the value from.
* @param count Number or range of elements to pick.
* When not provided, random number of elements will be picked.
* When value exceeds array boundaries, it will be limited to stay inside.
*
* @example
* faker.helpers.arrayElements(['cat', 'dog', 'mouse']) // ['mouse', 'cat']
* faker.helpers.arrayElements([1, 2, 3, 4, 5], 2) // [4, 2]
* faker.helpers.arrayElements([1, 2, 3, 4, 5], { min: 2, max: 4 }) // [3, 5, 1]
*
* @since 6.3.0
*/
arrayElements<const T>(array: ReadonlyArray<T>, count?: number | {
/**
* The minimum number of elements to pick.
*/
min: number;
/**
* The maximum number of elements to pick.
*/
max: number;
}): T[];
/**
* Returns a random value from an Enum object.
*
* This does the same as `objectValue` except that it ignores (the values assigned to) the numeric keys added for TypeScript enums.
*
* @template T Type of generic enums, automatically inferred by TypeScript.
*
* @param enumObject Enum to pick the value from.
*
* @example
* enum Color { Red, Green, Blue }
* faker.helpers.enumValue(Color) // 1 (Green)
*
* enum Direction { North = 'North', South = 'South'}
* faker.helpers.enumValue(Direction) // 'South'
*
* enum HttpStatus { Ok = 200, Created = 201, BadRequest = 400, Unauthorized = 401 }
* faker.helpers.enumValue(HttpStatus) // 200 (Ok)
*
* @since 8.0.0
*/
enumValue<T extends Record<string | number, string | number>>(enumObject: T): T[keyof T];
/**
* Helper method that converts the given number or range to a number.
*
* @param numberOrRange The number or range to convert.
* @param numberOrRange.min The minimum value for the range.
* @param numberOrRange.max The maximum value for the range.
*
* @example
* faker.helpers.rangeToNumber(1) // 1
* faker.helpers.rangeToNumber({ min: 1, max: 10 }) // 5
*
* @since 8.0.0
*/
rangeToNumber(numberOrRange: number | {
/**
* The minimum value for the range.
*/
min: number;
/**
* The maximum value for the range.
*/
max: number;
}): number;
/**
* Generates an array containing values returned by the given method.
*
* @template TResult The type of elements.
*
* @param method The method used to generate the values.
* The method will be called with `(_, index)`, to allow using the index in the generated value e.g. as id.
* @param options The optional options object.
* @param options.count The number or range of elements to generate. Defaults to `3`.
*
* @example
* faker.helpers.multiple(() => faker.person.firstName()) // [ 'Aniya', 'Norval', 'Dallin' ]
* faker.helpers.multiple(() => faker.person.firstName(), { count: 3 }) // [ 'Santos', 'Lavinia', 'Lavinia' ]
* faker.helpers.multiple((_, i) => `${faker.color.human()}-${i + 1}`) // [ 'orange-1', 'orchid-2', 'sky blue-3' ]
*
* @since 8.0.0
*/
multiple<const TResult>(method: (v: unknown, index: number) => TResult, options?: {
/**
* 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;
};
}): TResult[];
}
/**
* Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods.
*
* ### Overview
*
* A particularly helpful method is [`arrayElement()`](https://fakerjs.dev/api/helpers.html#arrayelement) which returns a random element from an array. This is useful when adding custom data that Faker doesn't contain.
*
* There are alternatives of this method for objects ([`objectKey()`](https://fakerjs.dev/api/helpers.html#objectkey) and [`objectValue()`](https://fakerjs.dev/api/helpers.html#objectvalue)) and enums ([`enumValue()`](https://fakerjs.dev/api/helpers.html#enumvalue)). You can also return multiple elements ([`arrayElements()`](https://fakerjs.dev/api/helpers.html#arrayelements)) or elements according to a weighting ([`weightedArrayElement()`](https://fakerjs.dev/api/helpers.html#weightedarrayelement)).
*
* A number of methods can generate strings according to various patterns: [`replaceSymbols()`](https://fakerjs.dev/api/helpers.html#replacesymbols) and [`fromRegExp()`](https://fakerjs.dev/api/helpers.html#fromregexp).
*/
declare class HelpersModule extends SimpleHelpersModule {
protected readonly faker: Faker;
constructor(faker: Faker);
/**
* Generator for combining faker methods based on a static string input.
*
* Note: We recommend using string template literals instead of `fake()`,
* which are faster and strongly typed (if you are using TypeScript),
* e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
*
* This method is useful if you have to build a random string from a static, non-executable source
* (e.g. string coming from a user, stored in a database or a file).
*
* It checks the given string for placeholders and replaces them by calling faker methods:
*
* ```js
* const hello = faker.helpers.fake('Hi, my name is {{person.firstName}} {{person.lastName}}!');
* ```
*
* This would use the `faker.person.firstName()` and `faker.person.lastName()` method to resolve the placeholders respectively.
*
* It is also possible to provide parameters. At first, they will be parsed as json,
* and if that isn't possible, we will fall back to string:
*
* ```js
* const message = faker.helpers.fake('You can call me at {{phone.number(+!# !## #### #####!)}}.');
* ```
*
* It is also possible to use multiple parameters (comma separated).
*
* ```js
* const message = faker.helpers.fake('Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.');
* ```
*
* It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
*
* @param pattern The pattern string that will get interpolated.
*
* @see faker.helpers.mustache(): For using custom functions to resolve templates.
*
* @example
* faker.helpers.fake('{{person.lastName}}') // 'Barrows'
* faker.helpers.fake('{{person.lastName}}, {{person.firstName}} {{person.suffix}}') // 'Durgan, Noe MD'
* faker.helpers.fake('This is static test.') // 'This is static test.'
* faker.helpers.fake('Good Morning {{person.firstName}}!') // 'Good Morning Estelle!'
* faker.helpers.fake('You can visit me at {{location.streetAddress(true)}}.') // 'You can visit me at 3393 Ronny Way Apt. 742.'
* faker.helpers.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails'
* faker.helpers.fake('Your PIN number is: {{string.numeric(4, {"exclude": ["0"]})}}') // 'Your PIN number is: 4834'
*
* @since 7.4.0
*/
fake(pattern: string): string;
/**
* Generator for combining faker methods based on an array containing static string inputs.
*
* Note: We recommend using string template literals instead of `fake()`,
* which are faster and strongly typed (if you are using TypeScript),
* e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
*
* This method is useful if you have to build a random string from a static, non-executable source
* (e.g. string coming from a user, stored in a database or a file).
*
* It checks the given string for placeholders and replaces them by calling faker methods:
*
* ```js
* const hello = faker.helpers.fake(['Hi, my name is {{person.firstName}} {{person.lastName}}!']);
* ```
*
* This would use the `faker.person.firstName()` and `faker.person.lastName()` method to resolve the placeholders respectively.
*
* It is also possible to provide parameters. At first, they will be parsed as json,
* and if that isn't possible, it will fall back to string:
*
* ```js
* const message = faker.helpers.fake([
* 'You can call me at {{phone.number(+!# !## #### #####!)}}.',
* 'My email is {{internet.email}}.',
* ]);
* ```
*
* It is also possible to use multiple parameters (comma separated).
*
* ```js
* const message = faker.helpers.fake(['Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.']);
* ```
*
* It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
*
* @param patterns The array to select a pattern from, that will then get interpolated. Must not be empty.
*
* @see faker.helpers.mustache(): For using custom functions to resolve templates.
*
* @example
* faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
*
* @since 8.0.0
*/
fake(patterns: ReadonlyArray<string>): string;
/**
* Generator for combining faker methods based on a static string input or an array of static string inputs.
*
* Note: We recommend using string template literals instead of `fake()`,
* which are faster and strongly typed (if you are using TypeScript),
* e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
*
* This method is useful if you have to build a random string from a static, non-executable source
* (e.g. string coming from a user, stored in a database or a file).
*
* It checks the given string for placeholders and replaces them by calling faker methods:
*
* ```js
* const hello = faker.helpers.fake('Hi, my name is {{person.firstName}} {{person.lastName}}!');
* ```
*
* This would use the `faker.person.firstName()` and `faker.person.lastName()` method to resolve the placeholders respectively.
*
* It is also possible to provide parameters. At first, they will be parsed as json,
* and if that isn't possible, it will fall back to string:
*
* ```js
* const message = faker.helpers.fake('You can call me at {{phone.number(+!# !## #### #####!)}}.');
* ```
*
* It is also possible to use multiple parameters (comma separated).
*
* ```js
* const message = faker.helpers.fake('Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.');
* ```
*
* It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
*
* @param pattern The pattern string that will get interpolated. If an array is passed, a random element will be picked and interpolated.
*
* @see faker.helpers.mustache(): For using custom functions to resolve templates.
*
* @example
* faker.helpers.fake('{{person.lastName}}') // 'Barrows'
* faker.helpers.fake('{{person.lastName}}, {{person.firstName}} {{person.suffix}}') // 'Durgan, Noe MD'
* faker.helpers.fake('This is static test.') // 'This is static test.'
* faker.helpers.fake('Good Morning {{person.firstName}}!') // 'Good Morning Estelle!'
* faker.helpers.fake('You can visit me at {{location.streetAddress(true)}}.') // 'You can visit me at 3393 Ronny Way Apt. 742.'
* faker.helpers.fake('I flipped the coin and got: {{helpers.arrayElement(["heads", "tails"])}}') // 'I flipped the coin and got: tails'
* faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
*
* @since 7.4.0
*/
fake(pattern: string | ReadonlyArray<string>): string;
}
/**
* Interface for a random number generator.
*
* **Note:** Normally there is no need to implement this interface directly,
* unless you want to achieve a specific goal with it.
*
* This interface enables you to use random generators from third party libraries such as [pure-rand](https://github.com/dubzzz/pure-rand).
*
* Instances are expected to be ready for use before being passed to any Faker constructor,
* this includes being `seed()`ed with either a random or fixed value.
*
* For more information please refer to the [documentation](https://fakerjs.dev/guide/randomizer.html).
*
* @example
* import { Faker, Randomizer, SimpleFaker } from '@faker-js/faker';
* import { RandomGenerator, xoroshiro128plus } from 'pure-rand';
*
* function generatePureRandRandomizer(
* seed: number | number[] = Date.now() ^ (Math.random() * 0x100000000),
* factory: (seed: number) => RandomGenerator = xoroshiro128plus
* ): Randomizer {
* const self = {
* next: () => (self.generator.unsafeNext() >>> 0) / 0x100000000,
* seed: (seed: number | number[]) => {
* self.generator = factory(typeof seed === 'number' ? seed : seed[0]);
* },
* } as Randomizer & { generator: RandomGenerator };
* self.seed(seed);
* return self;
* }
*
* const randomizer = generatePureRandRandomizer();
*
* const simpleFaker = new SimpleFaker({ randomizer });
*
* const faker = new Faker({
* locale: ...,
* randomizer,
* });
*
* @since 8.2.0
*/
interface Randomizer {
/**
* Generates a random float between 0 (inclusive) and 1 (exclusive).
*
* @example
* randomizer.next() // 0.3404027920160495
* randomizer.next() // 0.929890375900335
* randomizer.next() // 0.5866362918861691
*
* @since 8.2.0
*/
next(): number;
/**
* Sets the seed to use.
*
* @param seed The seed to use.
*
* @example
* // Random seeds
* randomizer.seed(Date.now() ^ (Math.random() * 0x100000000));
* // Fixed seeds (for reproducibility)
* randomizer.seed(42);
* randomizer.seed([42, 13.37]);
*
* @since 8.2.0
*/
seed(seed: number | number[]): void;
}
/**
* Module to generate boolean values.
*
* ### Overview
*
* For a simple random true or false value, use [`boolean()`](https://fakerjs.dev/api/datatype.html#boolean).
*/
declare class DatatypeModule extends SimpleModuleBase {
/**
* Returns the boolean value true or false.
*
* **Note:**
* A probability of `0.75` results in `true` being returned `75%` of the calls; likewise `0.3` => `30%`.
* If the probability is `<= 0.0`, it will always return `false`.
* If the probability is `>= 1.0`, it will always return `true`.
* The probability is limited to two decimal places.
*
* @param options The optional options object or the probability (`[0.00, 1.00]`) of returning `true`.
* @param options.probability The probability (`[0.00, 1.00]`) of returning `true`. Defaults to `0.5`.
*
* @example
* faker.datatype.boolean() // false
* faker.datatype.boolean(0.9) // true
* faker.datatype.boolean({ probability: 0.1 }) // false
*
* @since 5.5.0
*/
boolean(options?: number | {
/**
* The probability (`[0.00, 1.00]`) of returning `true`.
*
* @default 0.5
*/
probability?: number;
}): boolean;
}
/**
* Type that provides auto-suggestions but also any string.
*
* @see https://github.com/microsoft/TypeScript/issues/29729#issuecomment-471566609
*/
type LiteralUnion<TSuggested extends TBase, TBase = string> = TSuggested | (TBase & {
zz_IGNORE_ME?: never;
});
type Casing = 'upper' | 'lower' | 'mixed';
type LowerAlphaChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
type UpperAlphaChar = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
type NumericChar = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
type AlphaChar = LowerAlphaChar | UpperAlphaChar;
type AlphaNumericChar = AlphaChar | NumericChar;
/**
* Module to generate string related entries.
*
* ### Overview
*
* For a string containing just A-Z characters, use [`alpha()`](https://fakerjs.dev/api/string.html#alpha). To add digits too, use [`alphanumeric()`](https://fakerjs.dev/api/string.html#alphanumeric). If you only want punctuation marks/symbols, use [`symbol()`](https://fakerjs.dev/api/string.html). For a full set of ASCII characters, use [`sample()`](https://fakerjs.dev/api/string.html#sample). For a custom set of characters, use [`fromCharacters()`](https://fakerjs.dev/api/string.html#fromcharacters).
*
* For strings of base-ten digits, use [`numeric()`](https://fakerjs.dev/api/string.html#numeric). For other bases, use [`binary()`](https://fakerjs.dev/api/string.html#binary), [`octal()`](https://fakerjs.dev/api/string.html#octal), or [`hexadecimal()`](https://fakerjs.dev/api/string.html#hexadecimal)).
*
* You can generate standard ID strings using [`uuid()`](https://fakerjs.dev/api/string.html#uuid) or [`nanoid()`](https://fakerjs.dev/api/string.html#nanoid).
*
* ### Related modules
*
* - Emoji can be found at [`faker.internet.emoji()`](https://fakerjs.dev/api/internet.html#emoji).
* - The [`faker.helpers`](https://fakerjs.dev/api/helpers.html) module includes a number of string related methods.
*/
declare class StringModule extends SimpleModuleBase {
/**
* Generates a string from the given characters.
*
* @param characters The characters to use for the string. Can be a string or an array of characters.
* If it is an array, then each element is treated as a single character even if it is a string with multiple characters.
* @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
* @param length.min The minimum length of the string to generate.
* @param length.max The maximum length of the string to generate.
*
* @example
* faker.string.fromCharacters('abc') // 'c'
* faker.string.fromCharacters(['a', 'b', 'c']) // 'a'
* faker.string.fromCharacters('abc', 10) // 'cbbbacbacb'
* faker.string.fromCharacters('abc', { min: 5, max: 10 }) // 'abcaaaba'
*
* @since 8.0.0
*/
fromCharacters(characters: string | ReadonlyArray<string>, length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string to generate.
*/
max: number;
}): string;
/**
* Generating a string consisting of letters in the English alphabet.
*
* @param options Either the length of the string to generate or the optional options object.
* @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.casing The casing of the characters. Defaults to `'mixed'`.
* @param options.exclude An array with characters which should be excluded in the generated string. Defaults to `[]`.
*
* @example
* faker.string.alpha() // 'b'
* faker.string.alpha(10) // 'fEcAaCVbaR'
* faker.string.alpha({ length: { min: 5, max: 10 } }) // 'HcVrCf'
* faker.string.alpha({ casing: 'lower' }) // 'r'
* faker.string.alpha({ exclude: ['W'] }) // 'Z'
* faker.string.alpha({ length: 5, casing: 'upper', exclude: ['A'] }) // 'DTCIC'
*
* @since 8.0.0
*/
alpha(options?: number | {
/**
* The length of the string to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string 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?: ReadonlyArray<LiteralUnion<AlphaChar>> | string;
}): string;
/**
* Generating a string consisting of alpha characters and digits.
*
* @param options Either the length of the string to generate or the optional options object.
* @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.casing The casing of the characters. Defaults to `'mixed'`.
* @param options.exclude An array of characters and digits which should be excluded in the generated string. Defaults to `[]`.
*
* @example
* faker.string.alphanumeric() // '2'
* faker.string.alphanumeric(5) // '3e5V7'
* faker.string.alphanumeric({ length: { min: 5, max: 10 } }) // 'muaApG'
* faker.string.alphanumeric({ casing: 'upper' }) // 'A'
* faker.string.alphanumeric({ exclude: ['W'] }) // 'r'
* faker.string.alphanumeric({ length: 5, exclude: ["a"] }) // 'x1Z7f'
*
* @since 8.0.0
*/
alphanumeric(options?: number | {
/**
* The length of the string to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string 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?: ReadonlyArray<LiteralUnion<AlphaNumericChar>> | string;
}): string;
/**
* Returns a [binary](https://en.wikipedia.org/wiki/Binary_number) string.
*
* @param options The optional options object.
* @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.prefix Prefix for the generated number. Defaults to `'0b'`.
*
* @see faker.number.binary(): For generating a binary number (within a range).
*
* @example
* faker.string.binary() // '0b1'
* faker.string.binary({ length: 10 }) // '0b1101011011'
* faker.string.binary({ length: { min: 5, max: 10 } }) // '0b11101011'
* faker.string.binary({ prefix: '0b' }) // '0b1'
* faker.string.binary({ length: 10, prefix: 'bin_' }) // 'bin_1101011011'
*
* @since 8.0.0
*/
binary(options?: {
/**
* The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string (excluding the prefix) to generate.
*/
min: number;
/**
* The maximum length of the string (excluding the prefix) to generate.
*/
max: number;
};
/**
* Prefix for the generated number.
*
* @default '0b'
*/
prefix?: string;
}): string;
/**
* Returns an [octal](https://en.wikipedia.org/wiki/Octal) string.
*
* @param options The optional options object.
* @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.prefix Prefix for the generated number. Defaults to `'0o'`.
*
* @see faker.number.octal(): For generating an octal number (within a range).
*
* @example
* faker.string.octal() // '0o3'
* faker.string.octal({ length: 10 }) // '0o1526216210'
* faker.string.octal({ length: { min: 5, max: 10 } }) // '0o15263214'
* faker.string.octal({ prefix: '0o' }) // '0o7'
* faker.string.octal({ length: 10, prefix: 'oct_' }) // 'oct_1542153414'
*
* @since 8.0.0
*/
octal(options?: {
/**
* The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string (excluding the prefix) to generate.
*/
min: number;
/**
* The maximum length of the string (excluding the prefix) to generate.
*/
max: number;
};
/**
* Prefix for the generated number.
*
* @default '0o'
*/
prefix?: string;
}): string;
/**
* Returns a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) string.
*
* @param options The optional options object.
* @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.casing Casing of the generated number. Defaults to `'mixed'`.
* @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
*
* @example
* faker.string.hexadecimal() // '0xB'
* faker.string.hexadecimal({ length: 10 }) // '0xaE13d044cB'
* faker.string.hexadecimal({ length: { min: 5, max: 10 } }) // '0x7dEf7FCD'
* faker.string.hexadecimal({ prefix: '0x' }) // '0xE'
* faker.string.hexadecimal({ casing: 'lower' }) // '0xf'
* faker.string.hexadecimal({ length: 10, prefix: '#' }) // '#f12a974eB1'
* faker.string.hexadecimal({ length: 10, casing: 'upper' }) // '0xE3F38014FB'
* faker.string.hexadecimal({ casing: 'lower', prefix: '' }) // 'd'
* faker.string.hexadecimal({ length: 10, casing: 'mixed', prefix: '0x' }) // '0xAdE330a4D1'
*
* @since 8.0.0
*/
hexadecimal(options?: {
/**
* The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string (excluding the prefix) to generate.
*/
min: number;
/**
* The maximum length of the string (excluding the prefix) to generate.
*/
max: number;
};
/**
* Casing of the generated number.
*
* @default 'mixed'
*/
casing?: Casing;
/**
* Prefix for the generated number.
*
* @default '0x'
*/
prefix?: string;
}): string;
/**
* Generates a given length string of digits.
*
* @param options Either the length of the string to generate or the optional options object.
* @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
* @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
* @param options.exclude An array of digits which should be excluded in the generated string. Defaults to `[]`.
*
* @see faker.number.int(): For generating a number (within a range).
*
* @example
* faker.string.numeric() // '2'
* faker.string.numeric(5) // '31507'
* faker.string.numeric(42) // '06434563150765416546479875435481513188548'
* faker.string.numeric({ length: { min: 5, max: 10 } }) // '197089478'
* faker.string.numeric({ length: 42, allowLeadingZeros: false }) // '72564846278453876543517840713421451546115'
* faker.string.numeric({ length: 6, exclude: ['0'] }) // '943228'
*
* @since 8.0.0
*/
numeric(options?: number | {
/**
* The length of the string to generate either as a fixed length or as a length range.
*
* @default 1
*/
length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string 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?: ReadonlyArray<LiteralUnion<NumericChar>> | string;
}): string;
/**
* Returns a string containing UTF-16 chars between 33 and 125 (`!` to `}`).
*
* @param length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `10`.
* @param length.min The minimum length of the string to generate.
* @param length.max The maximum length of the string to generate.
*
* @example
* faker.string.sample() // 'Zo!.:*e>wR'
* faker.string.sample(5) // '6Bye8'
* faker.string.sample({ min: 5, max: 10 }) // 'FeKunG'
*
* @since 8.0.0
*/
sample(length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string to generate.
*/
max: number;
}): string;
/**
* Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
*
* @example
* faker.string.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
*
* @since 8.0.0
*/
uuid(): string;
/**
* Returns a ULID ([Universally Unique Lexicographically Sortable Identifier](https://github.com/ulid/spec)).
*
* @param options The optional options object.
* @param options.refDate The timestamp to encode into the ULID.
* The encoded timestamp is represented by the first 10 characters of the result.
* Defaults to `faker.defaultRefDate()`.
*
* @example
* faker.string.ulid() // '01ARZ3NDEKTSV4RRFFQ69G5FAV'
* faker.string.ulid({ refDate: '2020-01-01T00:00:00.000Z' }) // '01DXF6DT00CX9QNNW7PNXQ3YR8'
*
* @since 9.1.0
*/
ulid(options?: {
/**
* The date to use as reference point for the newly generated ULID encoded timestamp.
* The encoded timestamp is represented by the first 10 characters of the result.
*
* @default faker.defaultRefDate()
*/
refDate?: string | Date | number;
}): string;
/**
* Generates a [Nano ID](https://github.com/ai/nanoid).
*
* @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `21`.
* @param length.min The minimum length of the Nano ID to generate.
* @param length.max The maximum length of the Nano ID to generate.
*
* @example
* faker.string.nanoid() // ptL0KpX_yRMI98JFr6B3n
* faker.string.nanoid(10) // VsvwSdm_Am
* faker.string.nanoid({ min: 13, max: 37 }) // KIRsdEL9jxVgqhBDlm
*
* @since 8.0.0
*/
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;
}): string;
/**
* Returns a string containing only special characters from the following list:
*
* ```txt
* ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
* ```
*
* @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
* @param length.min The minimum length of the string to generate.
* @param length.max The maximum length of the string to generate.
*
* @example
* faker.string.symbol() // '$'
* faker.string.symbol(5) // '#*!.~'
* faker.string.symbol({ min: 5, max: 10 }) // ')|@*>^+'
*
* @since 8.0.0
*/
symbol(length?: number | {
/**
* The minimum length of the string to generate.
*/
min: number;
/**
* The maximum length of the string to generate.
*/
max: number;
}): string;
}
/**
* Module to generate numbers of any kind.
*
* ### Overview
*
* For simple integers, use [`int()`](https://fakerjs.dev/api/number.html#int). For decimal/floating-point numbers, use [`float()`](https://fakerjs.dev/api/number.html#float).
*
* For numbers not in base-10, you can use [`hex()`](https://fakerjs.dev/api/number.html#hex), [`octal()`](https://fakerjs.dev/api/number.html#octal) and [`binary()`](https://fakerjs.dev/api/number.html#binary)`.
*
* ### Related modules
*
* - For numeric strings of a given length, use [`faker.string.numeric()`](https://fakerjs.dev/api/string.html#numeric).
* - For credit card numbers, use [`faker.finance.creditCardNumber()`](https://fakerjs.dev/api/finance.html#creditcardnumber).
*/
declare class NumberModule extends SimpleModuleBase {
/**
* Returns a single random integer between zero and the given max value or the given range.
* The bounds are inclusive.
*
* @param options Maximum value or options object.
* @param options.min Lower bound for generated number. Defaults to `0`.
* @param options.max Upper bound for generated number. Defaults to `Number.MAX_SAFE_INTEGER`.
* @param options.multipleOf Generated number will be a multiple of the given integer. Defaults to `1`.
*
* @throws When `min` is greater than `max`.
* @throws When there are no suitable integers between `min` and `max`.
* @throws When `multipleOf` is not a positive integer.
*
* @see faker.string.numeric(): For generating a `string` of digits with a given length (range).
*
* @example
* faker.number.int() // 2900970162509863
* faker.number.int(100) // 52
* faker.number.int({ min: 1000000 }) // 2900970162509863
* faker.number.int({ max: 100 }) // 42
* faker.number.int({ min: 10, max: 100 }) // 57
* faker.number.int({ min: 10, max: 100, multipleOf: 10 }) // 50
*
* @since 8.0.0
*/
int(options?: number | {
/**
* Lower bound for generated number.
*
* @default 0
*/
min?: number;
/**
* Upper bound for generated number.
*
* @default Number.MAX_SAFE_INTEGER
*/
max?: number;
/**
* Generated number will be a multiple of the given integer.
*
* @default 1
*/
multipleOf?: number;
}): number;
/**
* Returns a single random floating-point number, by default between `0.0` and `1.0`. To change the range, pass a `min` and `max` value. To limit the number of decimal places, pass a `multipleOf` or `fractionDigits` parameter.
*
* @param options Upper bound or options object.
* @param options.min Lower bound for generated number, inclusive