Helpers

Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods.

Overview

A particularly helpful method is 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() and objectValue()) and enums (enumValue()). You can also return multiple elements (arrayElements()) or elements according to a weighting (weightedArrayElement()).

A number of methods can generate strings according to various patterns: replaceSymbols(), replaceSymbolWithNumber(), and fromRegExp().

arrayElement

Returns random element from the given array.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>			The type of the elements to pick from.
array	T[]		The array to pick the value from.

Returns: T

Throws: If the given array is empty.

faker.helpers.arrayElement<T>(array: readonly T[]): T
faker.helpers.arrayElement(['cat', 'dog', 'mouse']) // 'dog'

Source

• View Source

arrayElements

Returns a subset with random elements of the given array in random order.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>			The type of the elements to pick from.
array	T[]		Array to pick the value from.
count?	number | { ... }		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.
count.max	number		The maximum number of elements to pick.
count.min	number		The minimum number of elements to pick.

Returns: T[]

faker.helpers.arrayElements<T>(array: readonly T[], count?: number | {
  max: number,
  min: number
}): T[]
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]

Source

• View Source

enumValue

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.

Available since v8.0.0

Parameters

Name	Type	Default	Description
<T>	Record<number | string, number | string>		Type of generic enums, automatically inferred by TypeScript.
enumObject	T		Enum to pick the value from.

Returns: T[keyof T]

faker.helpers.enumValue<T>(enumObject: T): T[keyof T]
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)

Source

• View Source

fake

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:

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:

const message = faker.helpers.fake('You can call me at {{phone.number(+!# !## #### #####!)}}.');

It is also possible to use multiple parameters (comma separated).

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.

Available since v7.4.0

Parameters

Name	Type	Default	Description
pattern	string | string[]		The pattern string that will get interpolated. If an array is passed, a random element will be picked and interpolated.

Returns: string

faker.helpers.fake(pattern: readonly string[] | string): string
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'

See Also

• faker.helpers.mustache(): For using custom functions to resolve templates.

Source

• View Source

fromRegExp

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 RegExps, see 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.

Available since v8.0.0

Parameters

Name	Type	Default	Description
pattern	RegExp | string		The template string/RegExp to generate a matching string for.

Returns: string

Throws: If min value is more than max value in quantifier, e.g. #{10,5}. If an invalid quantifier symbol is passed in.

faker.helpers.fromRegExp(pattern: RegExp | string): string
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'

Source

• View Source

maybe

Returns the result of the callback if the probability check was successful, otherwise undefined.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<TResult>			The type of result of the given callback.
callback	() => TResult		The callback to that will be invoked if the probability check was successful.
options	{ ... }	{}	The options to use.
options.probability?	number	0.5	The probability ([0.00, 1.00]) of the callback being invoked.

Returns: TResult | undefined

faker.helpers.maybe<TResult>(callback: () => TResult, options: {
  probability: number
} = {}): undefined | TResult
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!'

Source

• View Source

multiple

Generates an array containing values returned by the given method.

Available since v8.0.0

Parameters

Name	Type	Default	Description
<TResult>			The type of elements.
method	() => TResult		The method used to generate the values.
options	{ ... }	{}	The optional options object.
options.count?	number | { max: number, min: number }	3	The number or range of elements to generate.

Returns: TResult[]

faker.helpers.multiple<TResult>(method: () => TResult, options: {
  count: number | {
  max: number,
  min: number
}
} = {}): TResult[]
faker.helpers.multiple(faker.person.firstName) // [ 'Aniya', 'Norval', 'Dallin' ]
faker.helpers.multiple(faker.person.firstName, { count: 3 }) // [ 'Santos', 'Lavinia', 'Lavinia' ]

Source

• View Source

mustache

Replaces the {{placeholder}} patterns in the given string mustache style.

Available since v2.0.1

Parameters

Name	Type	Default	Description
str	string | undefined		The template string to parse.
data	Record<string, ((substring: string, args: any[]) => string) | string>		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().

Returns: string

faker.helpers.mustache(str: string | undefined, data: Record<string, ((substring: string, args: any[]) => string) | string>): string
faker.helpers.mustache('I found {{count}} instances of "{{word}}".', {
  count: () => `${faker.number.int()}`,
  word: "this word",
}) // 'I found 57591 instances of "this word".'

Source

• View Source

objectEntry

Returns a random [key, value] pair from the given object.

Available since v8.0.0

Parameters

Name	Type	Default	Description
<T>	Record<string, unknown>		The type of the object to select from.
object	T		The object to be used.

Returns: [keyof T, T[keyof T]]

Throws: If the given object is empty.

faker.helpers.objectEntry<T>(object: T): [keyof T, T[keyof T]]
faker.helpers.objectEntry({ prop1: 'value1', prop2: 'value2' }) // ['prop1', 'value1']

Source

• View Source

objectKey

Returns a random key from given object.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>	Record<string, unknown>		The type of the object to select from.
object	T		The object to be used.

Returns: keyof T

Throws: If the given object is empty.

faker.helpers.objectKey<T>(object: T): keyof T
faker.helpers.objectKey({ myProperty: 'myValue' }) // 'myProperty'

Source

• View Source

objectValue

Returns a random value from given object.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>	Record<string, unknown>		The type of object to select from.
object	T		The object to be used.

Returns: T[keyof T]

Throws: If the given object is empty.

faker.helpers.objectValue<T>(object: T): T[keyof T]
faker.helpers.objectValue({ myProperty: 'myValue' }) // 'myValue'

Source

• View Source

rangeToNumber

Helper method that converts the given number or range to a number.

Available since v8.0.0

Parameters

Name	Type	Default	Description
numberOrRange	number | { ... }		The number or range to convert.
numberOrRange.max	number		The maximum value for the range.
numberOrRange.min	number		The minimum value for the range.

Returns: number

faker.helpers.rangeToNumber(numberOrRange: number | {
  max: number,
  min: number
}): number
faker.helpers.rangeToNumber(1) // 1
faker.helpers.rangeToNumber({ min: 1, max: 10 }) // 5

Source

• View Source

regexpStyleStringParse

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.helpers.fromRegExp() instead.

Replaces the regex like expressions in the given string with matching values.

Supported patterns:

• .{times} => Repeat the character exactly times times.
• .{min,max} => Repeat the character min to max times.
• [min-max] => Generate a number between min and max (inclusive).

Available since v5.0.0

Parameters

Name	Type	Default	Description
string	string	''	The template string to parse.

Returns: string

faker.helpers.regexpStyleStringParse(string: string = ''): string
faker.helpers.regexpStyleStringParse() // ''
faker.helpers.regexpStyleStringParse('#{5}') // '#####'
faker.helpers.regexpStyleStringParse('#{2,9}') // '#######'
faker.helpers.regexpStyleStringParse('[500-15000]') // '8375'
faker.helpers.regexpStyleStringParse('#{3}test[1-5]') // '###test3'

See Also

• faker.helpers.fromRegExp(): For generating a string matching the given regex-like expressions.

Source

• View Source

replaceCreditCardSymbols

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.

Available since v5.0.0

Parameters

Name	Type	Default	Description
string	string	'6453-####-####-####-###L'	The credit card format pattern.
symbol	string	'#'	The symbol to replace with a digit.

Returns: string

faker.helpers.replaceCreditCardSymbols(string: string = '6453-####-####-####-###L', symbol: string = '#'): string
faker.helpers.replaceCreditCardSymbols() // '6453-4876-8626-8995-3771'
faker.helpers.replaceCreditCardSymbols('1234-[4-9]-##!!-L') // '1234-9-5298-2'

Source

• View Source

replaceSymbolWithNumber

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.string.numeric() instead. Example: value.replace(/#+/g, (m) => faker.string.numeric(m.length));

Parses the given string symbol by symbol and replaces the placeholders with digits (0 - 9). ! will be replaced by digits >=2 (2 - 9).

Available since v2.0.1

Parameters

Name	Type	Default	Description
string	string	''	The template string to parse.
symbol	string	'#'	The symbol to replace with digits.

Returns: string

faker.helpers.replaceSymbolWithNumber(string: string = '', symbol: string = '#'): string
faker.helpers.replaceSymbolWithNumber() // ''
faker.helpers.replaceSymbolWithNumber('#####') // '04812'
faker.helpers.replaceSymbolWithNumber('!####') // '27378'
faker.helpers.replaceSymbolWithNumber('Your pin is: !####') // '29841'

See Also

• faker.string.numeric(): For the replacement method.

Source

• View Source

replaceSymbols

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.

Available since v3.0.0

Parameters

Name	Type	Default	Description
string	string	''	The template string to parse.

Returns: string

faker.helpers.replaceSymbols(string: string = ''): string
faker.helpers.replaceSymbols() // ''
faker.helpers.replaceSymbols('#####') // '98441'
faker.helpers.replaceSymbols('?????') // 'ZYRQQ'
faker.helpers.replaceSymbols('*****') // '4Z3P7'
faker.helpers.replaceSymbols('Your pin is: #?*#?*') // '0T85L1'

Source

• View Source

shuffle

Returns a randomized version of the array.

Available since v2.0.1

Parameters

Name	Type	Default	Description
<T>			The type of the elements to shuffle.
list	T[]		The array to shuffle.
options?	{ ... }	{}	The options to use when shuffling.
options.inplace?	boolean	false	Whether to shuffle the array in place or return a new array.

Returns: T[]

faker.helpers.shuffle<T>(list: T[], options?: {
  inplace: boolean
} = {}): T[]
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' ]

Source

• View Source

slugify

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.

Available since v2.0.1

Parameters

Name	Type	Default	Description
string	string	''	The input to slugify.

Returns: string

faker.helpers.slugify(string: string = ''): string
faker.helpers.slugify() // ''
faker.helpers.slugify("Hello world!") // 'Hello-world'

Source

• View Source

unique

Deprecated

This method is deprecated and will be removed in a future version.

Please find a dedicated npm package instead, or even create one on your own if you want to. More info can be found in issue faker-js/faker #1785.

Generates a unique result using the results of the given method. Used unique entries will be stored internally and filtered from subsequent calls.

Available since v7.5.0

Parameters

Name	Type	Default	Description
<TMethod>	(parameters: any[]) => RecordKey		The type of the method to execute.
method	TMethod		The method used to generate the values.
args	Parameters<TMethod>	[]	The arguments used to call the method.
options	{ ... }	{}	The optional options used to configure this method.
options.compare?	(obj: Record<RecordKey, RecordKey>, key: RecordKey) => -1 | 0	(obj, key) => (obj[key] === undefined ? -1 : 0)	The function used to determine whether a value was already returned. Defaults to check the existence of the key.
options.currentIterations?	number	0	This parameter does nothing.
options.exclude?	RecordKey | RecordKey[]	[]	The value or values that should be excluded/skipped.
options.maxRetries?	number	50	The total number of attempts to try before throwing an error.
options.maxTime?	number	50	The time in milliseconds this method may take before throwing an error.
options.startTime?	number	new Date().getTime()	This parameter does nothing.
options.store?	Record<RecordKey, RecordKey>		The store of unique entries. Defaults to a global store.

Returns: ReturnType<TMethod>

faker.helpers.unique<TMethod>(method: TMethod, args: Parameters<TMethod> = [], options: {
  compare: (obj: Record<RecordKey, RecordKey>, key: RecordKey) => -1 | 0,
  currentIterations: number,
  exclude: RecordKey | RecordKey[],
  maxRetries: number,
  maxTime: number,
  startTime: number,
  store: Record<RecordKey, RecordKey>
} = {}): ReturnType<TMethod>
faker.helpers.unique(faker.person.firstName) // 'Corbin'

See Also

• https://github.com/faker-js/faker/issues/1785#issuecomment-1407773744

Source

• View Source

uniqueArray

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.

Available since v6.0.0

Parameters

Name	Type	Default	Description
<T>			The type of the elements.
source	(() => T) | T[]		The strings to choose from or a function that generates a string.
length	number		The number of elements to generate.

Returns: T[]

faker.helpers.uniqueArray<T>(source: (() => T) | readonly T[], length: number): T[]
faker.helpers.uniqueArray(faker.word.sample, 50)
faker.helpers.uniqueArray(faker.definitions.person.first_name, 6)
faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2)

Source

• View Source

weightedArrayElement

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.

Available since v8.0.0

Parameters

Name	Type	Default	Description
<T>			The type of the elements to pick from.
array	Array<{ ... }>		Array to pick the value from.
array[].value	T		The value to pick.
array[].weight	number		The weight of the value.

Returns: T

faker.helpers.weightedArrayElement<T>(array: readonly Array<{
  value: T,
  weight: number
}>): T
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

Source

• View Source