nif-dni-nie-cif-validation/generate

Functions

createGenerator()

createGenerator(seed): Generator

Defined in: generate/index.ts:402

Creates a generator whose values come one after the other from a single seed: a stream of different values that is the same on every run and every platform. Use it for test fixtures that need many distinct documents. (generateDni({ seed }) would return the same DNI at every call.)

The values are the ones of the matching generate* functions, with the same options except seed, and with the same limits: synthetic, for tests only, and they may match a real person or company by chance.

Parameters

seed

number

An integer, reduced modulo 2^32.

Returns

Generator

An object with dni, nie, cif, nif and invalid.

Throws

If seed isn’t an integer.

Examples

const gen = createGenerator(2024);
const users = Array.from({ length: 3 }, () => ({ dni: gen.dni() }));
users.map((user) => user.dni); // ["81176236J", "71082149M", "65052588D"]

const gen = createGenerator(1);
gen.nie({ prefix: "Z", format: true }); // "Z-6270739-R"
validate(gen.invalid("CIF", { reason: "INVALID_FORMAT" })).valid; // false

See

SPEC.md#nif-1

Since

2.0.0

---

generateCif()

generateCif(opts?): string

Defined in: generate/index.ts:270

Generates a valid NIF of a legal person or entity (CIF): an organisation key, 7 digits and the control character (CIF-1 to CIF-4). The control is a digit or a letter as CIF-3 says for the key, never as the legacy cifControl: "lenient" mode would allow. The 7 digits are random, with no province code (CIF-5).

orgKey picks the key. control only makes sense together with the key’s own type, since CIF-3 gives each key one: without orgKey it restricts the keys to the ones that take a letter (N P Q R S W) or a digit (the other eleven); with an orgKey that takes the other type it throws.

Synthetic data, for tests only: the number is valid but made up, and it may match a real company’s by chance. Never use it as a real identifier.

Parameters

opts?

GenerateCifOptions = {}

seed, orgKey, control, format.

Returns

string

A CIF in canonical form, or formatted with format.

Throws

For an unknown orgKey or control, a control that the orgKey can’t take (CIF-3), or a seed that isn’t an integer.

Examples

generateCif({ seed: 1, orgKey: "B" }); // always "B62707393"
generateCif({ seed: 1, orgKey: "P" }); // "P6270739C": P takes a letter

validate(generateCif({ control: "letter" })).valid; // true: N, P, Q, R, S or W
generateCif({ orgKey: "B", control: "letter" }); // throws RangeError

See

• SPEC.md#cif-3
• SPEC.md#cif-4

Since

2.0.0

---

generateDni()

generateDni(opts?): string

Defined in: generate/index.ts:211

Generates a valid DNI (8 digits and a check letter, DNI-1, DNI-2), or with kind a K, L or M NIF (KLM-1, KLM-2). The number is zero-padded, so about one in ten starts with 0. It is never a placeholder such as 00000000T (POLICY-1).

Synthetic data, for tests only: the number is valid but made up, and it may match a real person’s by chance. Never use it as a real identifier. validate() and isValidDni() accept it.

Parameters

opts?

GenerateDniOptions = {}

seed, kind, format.

Returns

string

A DNI in canonical form, or formatted with format.

Throws

For an unknown kind or a seed that isn’t an integer.

Examples

generateDni({ seed: 1 }); // always "62707394X"
isValidDni(generateDni()); // true

generateDni({ seed: 1, kind: "K", format: true }); // "K-6270739-L"

See

• SPEC.md#dni-1
• SPEC.md#klm-2

Since

2.0.0

---

generateInvalid()

generateInvalid(type, opts?): string

Defined in: generate/index.ts:344

Generates a value that validate() rejects, for negative tests: it starts from a valid document of type and breaks one thing, so it looks like the type it stands for. reason is the error.code that validate() gives it, with the default options:

• "INVALID_CONTROL_CHARACTER" (the default): only the control character changes (DNI-2, KLM-2, NIE-2, CIF-3, CIF-4). For a CIF it is wrong with cifControl: "lenient" too.
• "INVALID_LENGTH": too long, or too short (never for a DNI, which NORM-4 pads). It is never an old 10-character NIE (NIE-3), which is valid.
• "INVALID_FORMAT": a letter in the number, or a control character of the wrong class.
• "EMPTY": an empty string or only separators (INPUT-2), for any type.
• "UNSUPPORTED_TYPE": a valid value, rejected only when types of validate() leaves type out (POLICY-2).
• "PLACEHOLDER": a placeholder number, rejected only with rejectPlaceholders (POLICY-1). It exists for "DNI" and "NIE"; any other type throws.
• "NOT_A_STRING" throws: the result is always a string.

Synthetic data, for tests only. The value is made up.

Parameters

type

NifType

The type of document the value stands for.

opts?

GenerateInvalidOptions = {}

seed, reason.

Returns

string

The value, not formatted.

Throws

For an unknown type or reason, for NOT_A_STRING, for PLACEHOLDER with a type that has no placeholder, or a seed that isn’t an integer.

Examples

const value = generateInvalid("DNI", { seed: 1 }); // "62707394A"
validate(value).error?.code; // "INVALID_CONTROL_CHARACTER"

const short = generateInvalid("CIF", { reason: "INVALID_LENGTH" });
validate(short).error?.code; // "INVALID_LENGTH"
const fake = generateInvalid("DNI", { reason: "PLACEHOLDER" });
validate(fake, { rejectPlaceholders: true }).error?.code; // "PLACEHOLDER"

See

SPEC.md#dni-2

Since

2.0.0

---

generateNie()

generateNie(opts?): string

Defined in: generate/index.ts:236

Generates a valid NIE in its canonical 9-character form: X, Y or Z, 7 digits and the check letter (NIE-1, NIE-2). It is never the old 10-character form (NIE-3) and never the placeholder X0000000T (POLICY-1).

Synthetic data, for tests only: the number is valid but made up, and it may match a real person’s by chance. Never use it as a real identifier.

Parameters

opts?

GenerateNieOptions = {}

seed, prefix, format.

Returns

string

An NIE in canonical form, or formatted with format.

Throws

For an unknown prefix or a seed that isn’t an integer.

Examples

generateNie({ seed: 1 }); // always "Y0027357R"
isValidNie(generateNie()); // true

generateNie({ seed: 1, prefix: "Y", format: { separator: " " } }); // "Y 6270739 X"

See

• SPEC.md#nie-1
• SPEC.md#nie-2

Since

2.0.0

---

generateNif()

generateNif(opts?): string

Defined in: generate/index.ts:299

Generates a valid NIF of any of the types (DNI, K/L/M NIF, NIE and CIF by default), one of them chosen at random, with the rules of generateDni, generateNie and generateCif.

Synthetic data, for tests only: the number is valid but made up, and it may match a real person or company by chance. Never use it as a real identifier.

Parameters

opts?

GenerateNifOptions = {}

seed, types, format.

Returns

string

A NIF in canonical form, or formatted with format.

Throws

For an empty or unknown types, or a seed that isn’t an integer.

Examples

generateNif({ seed: 1 }); // always "X5274470H"
isValidNif(generateNif()); // true

generateNif({ seed: 1, types: ["CIF"] }); // "A52744703"
validate(generateNif({ types: ["CIF"] })).type; // "CIF"

See

SPEC.md#nif-1

Since

2.0.0

Interfaces

GenerateCifOptions

Defined in: generate/index.ts:124

Options of generateCif.

Examples

generateCif({ seed: 1, orgKey: "B" }); // "B62707393": a digit control

generateCif({ seed: 1, control: "letter" }); // "R0027357C": N P Q R S or W

See

SPEC.md#cif-3

Since

2.0.0

Extends

• GenerateOptions.GenerateFormatOptions

Properties

control?

optional control?: CifControl

Defined in: generate/index.ts:137

The type of the control character. CIF-3 gives every key exactly one type, so it can never change what a key takes: without orgKey it picks among the keys with that type (letter: N P Q R S W; digit: the other eleven), and with an orgKey that takes the other type it throws a RangeError.

See

SPEC.md#cif-3

format?

optional format?: boolean | FormatOptions

Defined in: generate/index.ts:77

false (the default): the canonical form, upper case and without separators. true or { separator }: the display form of format(), with - or the separator given ("" gives the canonical form).

Inherited from

GenerateFormatOptions.format

orgKey?

optional orgKey?: CifOrganisationKey

Defined in: generate/index.ts:128

The organisation key. Default: one of the 17 keys at random.

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

Inherited from

GenerateOptions.seed

---

GenerateDniOptions

Defined in: generate/index.ts:89

Options of generateDni.

Examples

generateDni({ seed: 1, kind: "K" }); // "K6270739L": K + 7 digits + letter

generateDni({ seed: 1, kind: "K", format: true }); // "K-6270739-L"

See

SPEC.md#klm-1

Since

2.0.0

Extends

• GenerateOptions.GenerateFormatOptions

Properties

format?

optional format?: boolean | FormatOptions

Defined in: generate/index.ts:77

false (the default): the canonical form, upper case and without separators. true or { separator }: the display form of format(), with - or the separator given ("" gives the canonical form).

Inherited from

GenerateFormatOptions.format

kind?

optional kind?: DniKind

Defined in: generate/index.ts:96

"DNI" (the default): 8 digits and a letter. "K", "L" or "M": that NIF, a letter and 7 digits and a check letter (KLM-1).

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

Inherited from

GenerateOptions.seed

---

GenerateFormatOptions

Defined in: generate/index.ts:71

Options of the generators that return a valid document: the output form.

Examples

generateDni({ seed: 1 });                // "62707394X"
generateDni({ seed: 1, format: true });  // "62707394-X"

generateCif({ seed: 1, orgKey: "B", format: { separator: " " } }); // "B 6270739 3"

See

SPEC.md#cif-1

Since

2.0.0

Extended by

• GenerateDniOptions
• GenerateNieOptions
• GenerateCifOptions
• GenerateNifOptions

Properties

format?

optional format?: boolean | FormatOptions

Defined in: generate/index.ts:77

false (the default): the canonical form, upper case and without separators. true or { separator }: the display form of format(), with - or the separator given ("" gives the canonical form).

---

GenerateInvalidOptions

Defined in: generate/index.ts:168

Options of generateInvalid.

Examples

generateInvalid("CIF", { seed: 1, reason: "INVALID_LENGTH" }); // "P0027C"

generateInvalid("DNI", { seed: 1 }); // "62707394A": the default, a wrong control letter

See

SPEC.md#dni-2

Since

2.0.0

Extends

• GenerateOptions

Properties

reason?

optional reason?: NifErrorCode

Defined in: generate/index.ts:174

The error code validate() gives the value. Default: "INVALID_CONTROL_CHARACTER". See generateInvalid for the codes and for what each needs.

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

Inherited from

GenerateOptions.seed

---

GenerateNieOptions

Defined in: generate/index.ts:108

Options of generateNie.

Examples

generateNie({ seed: 1, prefix: "Z" }); // "Z6270739R"

generateNie({ seed: 1, prefix: "Y", format: { separator: " " } }); // "Y 6270739 X"

See

SPEC.md#nie-1

Since

2.0.0

Extends

• GenerateOptions.GenerateFormatOptions

Properties

format?

optional format?: boolean | FormatOptions

Defined in: generate/index.ts:77

false (the default): the canonical form, upper case and without separators. true or { separator }: the display form of format(), with - or the separator given ("" gives the canonical form).

Inherited from

GenerateFormatOptions.format

prefix?

optional prefix?: NiePrefix

Defined in: generate/index.ts:112

The first letter. Default: one of X, Y and Z at random.

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

Inherited from

GenerateOptions.seed

---

GenerateNifOptions

Defined in: generate/index.ts:149

Options of generateNif.

Examples

generateNif({ seed: 1, types: ["DNI", "NIE"] }); // "X5274470H": a DNI or an NIE

generateNif({ seed: 1, types: ["CIF"] }); // "A52744703"

See

SPEC.md#nif-1

Since

2.0.0

Extends

• GenerateOptions.GenerateFormatOptions

Properties

format?

optional format?: boolean | FormatOptions

Defined in: generate/index.ts:77

false (the default): the canonical form, upper case and without separators. true or { separator }: the display form of format(), with - or the separator given ("" gives the canonical form).

Inherited from

GenerateFormatOptions.format

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

Inherited from

GenerateOptions.seed

types?

optional types?: NifType[]

Defined in: generate/index.ts:156

The types to pick from, one of them at random. Default: all four. An empty array throws a RangeError.

---

GenerateOptions

Defined in: generate/index.ts:50

Options that every generator takes.

Examples

generateDni({ seed: 42 }); // "60110375J"
generateDni({ seed: 42 }); // "60110375J": the same seed gives the same value

isValidNie(generateNie()); // true: without a seed, a different value every time

See

SPEC.md#dni-1

Since

2.0.0

Extended by

• GenerateDniOptions
• GenerateNieOptions
• GenerateCifOptions
• GenerateNifOptions
• GenerateInvalidOptions

Properties

seed?

optional seed?: number

Defined in: generate/index.ts:58

An integer that fixes the result: the same seed gives the same value on every platform. It is reduced modulo 2^32. Without it, Math.random is used. A call with a seed always starts from that seed, so it returns the same value each time: use createGenerator for a stream of different values from one seed.

---

Generator

Defined in: generate/index.ts:365

A stream of generated values: every call gives the next value, so the values differ, and the same seed gives the same stream.

Examples

const gen = createGenerator(1);
gen.dni(); // "62707394X", the first DNI of the stream
gen.dni(); // "00273574N", a different one

const a = createGenerator(5).cif({ orgKey: "B" });
const b = createGenerator(5).cif({ orgKey: "B" });
a === b; // true

See

SPEC.md#cif-3

Since

2.0.0

Methods

cif()

cif(opts?): string

Defined in: generate/index.ts:371

The next CIF. See generateCif.

Parameters

opts?

Omit<GenerateCifOptions, "seed">

Returns

string

dni()

dni(opts?): string

Defined in: generate/index.ts:367

The next DNI, or K/L/M NIF. See generateDni.

Parameters

opts?

Omit<GenerateDniOptions, "seed">

Returns

string

invalid()

invalid(type, opts?): string

Defined in: generate/index.ts:375

The next invalid value. See generateInvalid.

Parameters

type

NifType

opts?

Omit<GenerateInvalidOptions, "seed">

Returns

string

nie()

nie(opts?): string

Defined in: generate/index.ts:369

The next NIE. See generateNie.

Parameters

opts?

Omit<GenerateNieOptions, "seed">

Returns

string

nif()

nif(opts?): string

Defined in: generate/index.ts:373

The next NIF of any of the types. See generateNif.

Parameters

opts?

Omit<GenerateNifOptions, "seed">

Returns

string

Type Aliases

CifControl

CifControl = "letter" | "digit"

Defined in: generate/core.ts:65

The control character of a CIF: a digit or a letter (CIF-3).

Examples

generateCif({ seed: 1, control: "letter" }); // "R0027357C"

const control: CifControl = "digit";
validate(generateCif({ control })).valid; // true

See

SPEC.md#cif-3

Since

2.0.0

---

DniKind

DniKind = "DNI" | "K" | "L" | "M"

Defined in: generate/core.ts:41

What generateDni makes: a DNI, or a K, L or M NIF (KLM-1).

Examples

generateDni({ seed: 1, kind: "K" }); // "K6270739L"

const kinds: DniKind[] = ["DNI", "K", "L", "M"];
kinds.every((kind) => isValidDni(generateDni({ kind }))); // true

See

SPEC.md#klm-1

Since

2.0.0

---

NiePrefix

NiePrefix = "X" | "Y" | "Z"

Defined in: generate/core.ts:53

The first letter of an NIE (NIE-1): X, Y or Z.

Examples

generateNie({ seed: 1, prefix: "Z" }); // "Z6270739R"

const prefix: NiePrefix = "Y";
generateNie({ prefix }).startsWith("Y"); // true

See

SPEC.md#nie-1

Since

2.0.0