Normalitzar i formatar l'entrada

La gent escriu el mateix NIF de moltes maneres: 12345678z, 12.345.678-Z, 1234567L sense el zero inicial, o un NIE antic de 10 caràcters. La biblioteca les accepta totes, comprova el document que representen i us dona una única forma canònica per desar. La neteja mai no converteix un document no vàlid en vàlid: només admet més maneres d’escriure’n un de vàlid.

Què fa la normalització

normalize() retorna la forma canònica: la de les fonts oficials, i la que heu de desar. Per ordre:

1. Treu els espais en blanc en qualsevol posició, cosa que també retalla els extrems, i els punts (NORM-2), els guions i les barres (NORM-3).
2. Converteix les minúscules en majúscules (NORM-1).
3. Redueix el NIE antic de 10 caràcters, X0 + 7 xifres + lletra, a la seva forma de 9 caràcters (NIE-3).
4. Afegeix els zeros inicials a un DNI escrit amb menys de 8 xifres (NORM-4).

import { normalize } from "nif-dni-nie-cif-validation";

normalize(" 12.345.678-z ");  // "12345678Z"
normalize("b/1234567/4");     // "B12345674"
normalize("x-0123456-7l");    // "X1234567L": la forma antiga del NIE, reduïda
normalize("1234567L");        // "01234567L": s'hi torna a afegir el zero inicial
normalize("12345678\tZ");     // "12345678Z": també tabuladors i altres espais en blanc

normalize() no valida: retorna la cadena neta encara que el document no sigui vàlid. La resta de signes de puntuació es mantenen expressament (un guió baix, una coma, un guió mitjà (–)), de manera que aquest valor continua sense ser vàlid, igual que els caràcters d’altres alfabets que s’assemblen als llatins:

import { isValidNif, normalize } from "nif-dni-nie-cif-validation";

normalize("12_345_678Z");  // "12_345_678Z": els guions baixos no són separadors
isValidNif("12_345_678Z"); // false

Tots els validadors, validate() i tots els esquemes normalitzen primer l’entrada, amb les mateixes regles, de manera que isValidNif(x) i validate(x).valid sempre coincideixen.

Consell

Deseu validate(value).normalized (o normalize(value) després d’una comprovació correcta), mai l’entrada tal com és. Així, dos usuaris que escriuen el mateix document de maneres diferents obtenen el mateix valor desat, i les cerques i les restriccions d’unicitat funcionen.

Validar i normalitzar en una sola crida

validate() retorna la forma canònica a normalized, juntament amb el resultat:

import { validate } from "nif-dni-nie-cif-validation";

validate(" b-1234567-4 ").normalized; // "B12345674"
validate("x01234567l").normalized;    // "X1234567L"
validate("12345678A").normalized;     // "12345678A": hi és encara que la lletra sigui incorrecta
validate("hello").normalized;         // null: no es reconeix com a cap document

normalized hi és tan bon punt el format és reconeixible, encara que el caràcter de control sigui incorrecte, perquè el pugueu mostrar a l’usuari al costat de l’error.

Desactivar la normalització

{ normalize: false } desactiva l’eliminació de separadors i l’emplenament amb zeros. Les minúscules i la forma antiga del NIE es continuen acceptant, com a la versió 1:

import { isValidNif } from "nif-dni-nie-cif-validation";

isValidNif(" 12.345.678-Z ", { normalize: false }); // false: es rebutgen els separadors
isValidNif("12345678z", { normalize: false });      // true: les minúscules continuen sent vàlides
isValidNif("X01234567L", { normalize: false });     // true: i també la forma antiga del NIE

Feu-lo servir per rebutjar els separadors i els DNI escrits sense els zeros inicials. No exigeix la forma canònica: les minúscules i la forma antiga del NIE es continuen acceptant (NORM-1, NIE-3).

NIF-IVA i el prefix ES

Un prefix ES no és neteja: ES seguit d’un NIF és un NIF-IVA, un identificador diferent (VAT-1). normalize() el conserva, i validate() el rebutja tret que passeu allowVatPrefix:

import { normalize, validate } from "nif-dni-nie-cif-validation";

normalize("es-12345678-z");                                   // "ES12345678Z"
validate("ES12345678Z").error?.code;                          // "INVALID_FORMAT"
validate("es 12345678 z", { allowVatPrefix: true }).normalized; // "12345678Z"

normalized mai no conserva el prefix. Per desar un NIF-IVA, afegiu-hi ES, o feu servir zSpanishVat() i els altres esquemes de NIF-IVA, la sortida dels quals el manté.

Mostrar un número: format()

Cap font oficial no defineix com cal agrupar un NIF per mostrar-lo. format() divideix la forma canònica en les parts que defineixen les regles, unides per un guió, un espai o res:

Tipus	Parts	Exemple
DNI	8 xifres · lletra	12345678-Z
NIE	prefix · 7 xifres · lletra	X-1234567-L
NIF K/L/M	prefix · 7 xifres · lletra	K-1234567-L
CIF	clau d’entitat · 7 xifres · control	B-1234567-4

import { format } from "nif-dni-nie-cif-validation";

format("12345678z");                     // "12345678-Z"
format("x01234567l");                    // "X-1234567-L"
format(" b-1234567-4 ");                 // "B-1234567-4"
format("B12345674", { separator: " " }); // "B 1234567 4"
format("B12345674", { separator: "" });  // "B12345674"
format("12345678A");                     // null: només es formaten documents vàlids

format() valida amb les opcions per defecte i retorna null per a qualsevol valor no vàlid, de manera que la podeu cridar amb l’entrada sense processar. Mai no afegeix el prefix ES.

Separadors que accepta la biblioteca

Entrada	S’accepta?	Regla
Minúscules (12345678z)	Sí, fins i tot amb normalize: false	NORM-1
Espais, tabuladors, salts de línia, punts	Sí	NORM-2
Guions (-) i barres (/)	Sí	NORM-3
Un DNI sense els zeros inicials (1234567L)	Sí	NORM-4
La forma antiga del NIE (X01234567L)	Sí, fins i tot amb normalize: false	NIE-3
Guions baixos, comes, guions mitjans (–) i altres signes	No	—
Prefix ES	Només amb allowVatPrefix, o a les funcions de NIF-IVA	VAT-1