Helpers

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.

arrayElement

Returns random element from the given array.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>			The type of the entries to pick from.
array	readonly T[]	`['a', 'b', 'c']`	Array to pick the value from.

Returns: T

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

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 entries to pick from.
array	readonly T[]	`['a', 'b', 'c']`	Array to pick the value from.
count?	number		Number 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.

Returns: T[]

faker.helpers.arrayElements<T>(array: readonly T[] = ['a', 'b', 'c'], count?: number): T[]
faker.helpers.arrayElements() // => ["c","b"]
faker.helpers.arrayElements(['cat', 'dog', 'mouse']) // ['mouse', 'cat']
faker.helpers.arrayElements([1, 2, 3, 4, 5], 2) // [4, 2]

fake

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.address.zipCode()} ${faker.address.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 {{name.firstName}} {{name.lastName}}!')

This would use the faker.name.firstName() and faker.name.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:

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

Currently it is not possible to set more than a single parameter.

It is also NOT possible to use any non-faker methods or plain javascript in such templates.

Available since v7.4.0

Parameters

Name	Type	Default	Description
str	string		The template string that will get interpolated. Must not be empty.

Returns: string

faker.helpers.fake(str: string): string
faker.helpers.fake('{{name.lastName}}') // 'Barrows'
faker.helpers.fake('{{name.lastName}}, {{name.firstName}} {{name.suffix}}') // 'Durgan, Noe MD'
faker.helpers.fake('This is static test.') // 'This is static test.'
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'

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
<T>			The type of result of the given callback.
callback	() => T		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: T

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

mustache

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

Available since v2.0.1

Parameters

Name	Type	Default	Description
str	string		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, data: Record<string, (substring: string, args: any[]) => string | string>): string
faker.helpers.mustache() // => ""
faker.helpers.mustache('I found {{count}} instances of "{{word}}".', {
  count: () => `${faker.datatype.number()}`,
  word: "this word",
}) // 'I found 57591 instances of "this word".'

objectKey

Returns a random key from given object or undefined if no key could be found.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>	Record<string, unknown>		Missing
object	T		The object to be used.

Returns: keyof T

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

objectValue

Returns a random value from given object or undefined if no key could be found.

Available since v6.3.0

Parameters

Name	Type	Default	Description
<T>	Record<string, unknown>		Missing
object	T		The object to be used.

Returns: T[keyof T]

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

regexpStyleStringParse

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 to parse.

Returns: string

faker.helpers.regexpStyleStringParse(string: string = ''): string
faker.helpers.regexpStyleStringParse() // => ""
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'

repeatString

Deprecated

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

Repeats the given string the given number of times.

Available since v5.0.0

Parameters

Name	Type	Default	Description
string	string	`''`	The string to repeat.
num	number	`0`	The number of times to repeat it.

Returns: string

faker.helpers.repeatString(string: string = '', num: number = 0): string
faker.helpers.repeatString() // => ""
faker.helpers.repeatString('Hello world! ') // ''
faker.helpers.repeatString('Hello world! ', 1) // 'Hello world! '
faker.helpers.repeatString('Hello world! ', 2) // 'Hello world! Hello world! '

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-5578-6858-4663-4283"
faker.helpers.replaceCreditCardSymbols() // '6453-4876-8626-8995-3771'
faker.helpers.replaceCreditCardSymbols('1234-[4-9]-##!!-L') // '1234-9-5298-2'

replaceSymbolWithNumber

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() // ''
faker.helpers.replaceSymbolWithNumber('#####') // '04812'
faker.helpers.replaceSymbolWithNumber('!####') // '27378'
faker.helpers.replaceSymbolWithNumber('Your pin is: !####') // '29841'

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() // ''
faker.helpers.replaceSymbols('#####') // '98441'
faker.helpers.replaceSymbols('?????') // 'ZYRQQ'
faker.helpers.replaceSymbols('*****') // '4Z3P7'
faker.helpers.replaceSymbols('Your pin is: #?*#?*') // '0T85L1'

shuffle

Takes an array and randomizes it in place then returns it.

Uses the modern version of the Fisher–Yates algorithm.

Available since v2.0.1

Parameters

Name	Type	Default	Description
<T>			The type of the entries to shuffle.
o?	T[]	`[]`	The array to shuffle.

Returns: T[]

faker.helpers.shuffle<T>(o?: T[] = []): T[]
faker.helpers.shuffle() // => []
faker.helpers.shuffle() // []
faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ]

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() // ''
faker.helpers.slugify("Hello world!") // 'Hello-world'

unique

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
<Method>	(parameters: any[]) => RecordKey		The type of the method to execute.
method	Method		The method used to generate the values.
args?	Parameters<Method>		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		The function used to determine whether a value was already returned. Defaults to check the existence of the key.
options.currentIterations?	number		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		This parameter does nothing.
options.store?	Record<RecordKey, RecordKey>		The store of unique entries. Defaults to a global store.

Returns: ReturnType<Method>

faker.helpers.unique<Method>(method: Method, args?: Parameters<Method>, 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<Method>
faker.helpers.unique(faker.name.firstName) // 'Corbin'

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.

Available since v6.0.0

Parameters

Name	Type	Description
<T>		The type of the entries.
source	() => T \| readonly 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.helpers.uniqueArray(faker.random.word, 50)
faker.helpers.uniqueArray(faker.definitions.name.first_name, 6)
faker.helpers.uniqueArray(["Hello", "World", "Goodbye"], 2)

Helpers #

arrayElement #

Parameters

arrayElements #

Parameters

fake #

Parameters

See Also

maybe #

Parameters

mustache #

Parameters

objectKey #

Parameters

objectValue #

Parameters

regexpStyleStringParse #

Parameters

repeatString #

Parameters

replaceCreditCardSymbols #

Parameters

replaceSymbolWithNumber #

Parameters

replaceSymbols #

Parameters

shuffle #

Parameters

slugify #

Parameters

unique #

Parameters

uniqueArray #

Parameters

Helpers

arrayElement

arrayElements

fake

maybe

mustache

objectKey

objectValue

regexpStyleStringParse

repeatString

replaceCreditCardSymbols

replaceSymbolWithNumber

replaceSymbols

shuffle

slugify

unique

uniqueArray