Liña de comandos

O paquete ten unha interface de liña de comandos para scripts de shell, fluxos de datos, traballos de CI e chamadas a ferramentas de axentes de IA. Aplica as mesmas regras ca a biblioteca, cos mesmos identificadores de regra, e non ten dependencias. Execútea con npx, que descarga o paquete a primeira vez, ou instale o paquete e execute nif-dni-nie-cif-validation desde os scripts do seu proxecto. Necesita Node.js 20 ou posterior.

npx nif-dni-nie-cif-validation --help
npx nif-dni-nie-cif-validation validate --help

Comando	Que fai
`validate <value...>`	Valida cada valor, como `validate()`
`type <value>`	Detecta o tipo só polo formato, como `getNifType()`
`normalize <value>`	Mostra a forma canónica, como `normalize()`
`generate <type>`	Xera valores de proba: `dni`, `nie`, `cif` ou `nif`
`check --file <csv> --column <name>`	Valida unha columna dun ficheiro CSV

Validar valores

npx nif-dni-nie-cif-validation validate 12345678Z " x-0123456-7l " b-1234567-4 12345678A
# 12345678Z: valid DNI 12345678Z
# " x-0123456-7l ": valid NIE X1234567L
# b-1234567-4: valid CIF B12345674 (Limited liability company)
# 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] The control character is not correct: for this DNI it should be "Z".

Cada valor ocupa unha liña: valid, co seu tipo e a forma canónica que hai que gardar, ou invalid, coa regra de SPEC.md que fallou, o código de erro e a mensaxe. Un valor con espazos móstrase entre comiñas. Aquí o código de saída é 1, porque un valor non é válido.

As opcións de validate() son flags de validate e check. Sen eles, o comando segue SPEC.md, igual ca a biblioteca:

Flag	Que fai	Opción de `validate()`
`--types DNI,NIE`	Só acepta estes tipos, separados por comas: `DNI`, `NIF_KLM`, `NIE`, `CIF`. Outro tipo dá `UNSUPPORTED_TYPE`	`types`
`--cif-control lenient`	C D F G J U V tamén admiten unha letra como carácter de control, como na v1. Non ten base oficial: úseo só con datos herdados	`cifControl`
`--reject-placeholders`	Rexeita os números de exemplo `00000000T`, `00000001R`, `99999999R` e `X0000000T`	`rejectPlaceholders`
`--allow-vat-prefix`	Tamén acepta un NIF-IVE español: `ES` e un NIF	`allowVatPrefix`
`--locale gl`	A lingua das mensaxes e dos nomes das organizacións: `en` (por defecto), `es`, `ca`, `eu` ou `gl`	`locale`

npx nif-dni-nie-cif-validation validate 12345678A B12345674 --locale gl
# 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] O carácter de control non é correcto: para este DNI debería ser «Z».
# B12345674: valid CIF B12345674 (Sociedade de responsabilidade limitada)
npx nif-dni-nie-cif-validation validate B12345674 --types DNI,NIE
# B12345674: invalid [POLICY-2 UNSUPPORTED_TYPE] This NIF of a legal person or entity (CIF) is not accepted here.

Os códigos de erro e as linguas explícanse en Códigos de erro e mensaxes traducidas.

JSON para scripts e axentes

--json imprime un único documento JSON na saída estándar. En validate é un array cun obxecto por valor, en orde: o valor tal como se pasou (input) e o resultado de validate(). É un array mesmo cun só valor, polo que un script le todas as chamadas da mesma forma.

npx nif-dni-nie-cif-validation validate 12345678A --json
# [
#   {
#     "input": "12345678A",
#     "valid": false,
#     "type": "DNI",
#     "normalized": "12345678A",
#     "error": {
#       "code": "INVALID_CONTROL_CHARACTER",
#       "message": "The control character is not correct: for this DNI it should be \"Z\".",
#       "rule": "DNI-2",
#       "expected": "Z"
#     }
#   }
# ]

Comando	Documento JSON
`validate`	`[{ input, valid, type, normalized, error?, meta? }]`: o valor e o seu resultado, para cada valor
`type`	`{ input, type }`, onde `type` é `null` se non se recoñece o formato
`normalize`	`{ input, normalized }`
`generate`	`{ seed, values }`
`check`	`{ file, column, rows, valid, invalid, errors }`, onde `errors` ten `{ row, input, ...result }` para cada fila non válida

As versións futuras poden engadir campos, pero nunca quitar nin renomear ningún.

Códigos de saída

Código de saída	Cando
`0`	Todo é válido. `normalize`, `generate`, `--help` e `--version` tamén rematan con 0
`1`	Algo non é válido: un valor, unha fila do ficheiro CSV ou un formato que `type` non recoñece
`2`	O comando non é correcto: un comando ou unha opción descoñecidos, un valor de opción incorrecto, un ficheiro que non se pode ler ou unha columna que non existe. A mensaxe vai á saída de erro, e nada á saída estándar

Así, un script pode comprobar un valor sen ler a saída:

if npx nif-dni-nie-cif-validation validate "$NIF" > /dev/null; then echo "valid"; fi

Tipo e forma canónica

npx nif-dni-nie-cif-validation type 12345678A
# DNI
npx nif-dni-nie-cif-validation normalize " x-0123456-7l "
# X1234567L

type dá o tipo que mostra o formato: DNI, NIF_KLM, NIE ou CIF. Non comproba o carácter de control, polo que aquí 12345678A é un DNI, e un DNI non válido para validate. Se o formato non é ningún deles, remata con 1. normalize quita espazos, puntos, guións e barras e dá a forma en maiúsculas, pero non valida: para gardar un valor, valídeo e quede coa súa forma canónica. Consulte Normalizar e formatar a entrada.

Datos de proba

npx nif-dni-nie-cif-validation generate dni --count 3 --seed 42
# 60110375J
# 44829056D
# 85246578E
npx nif-dni-nie-cif-validation generate cif --seed 1 --format
# P-0027357-C

generate imprime valores válidos dun tipo: dni, nie, cif, ou nif para calquera deles. --count indica cantos (ata 1.000.000). Con --seed, os valores son os mesmos en cada execución e en cada máquina; sen el, a semente é aleatoria e --json móstraa, polo que pode volver xerar os mesmos valores. --format dá a forma de presentación, con guións.

Revisar un ficheiro CSV

Para un ficheiro customers.csv cos nomes das columnas na súa primeira fila:

id,nif,name
1,12345678Z,Ana
2,"B-1234567-4","Acme, S.L."
3,12345678A,Luis

npx nif-dni-nie-cif-validation check --file customers.csv --column nif
# row 4: 12345678A: invalid [DNI-2 INVALID_CONTROL_CHARACTER] The control character is not correct: for this DNI it should be "Z".
# 3 rows checked in customers.csv, column "nif": 2 valid, 1 invalid

check valida a columna que indica --column e imprime unha liña por cada fila non válida e, ao final, un resumo. As filas numéranse como nunha folla de cálculo: a primeira fila despois dos nomes é a fila 2. As liñas en branco omítense, e unha cela baleira non é válida (EMPTY). Acepta os mesmos flags ca validate, e --json dá as contas e o resultado de cada fila non válida.

O ficheiro lese como CSV en UTF-8 (RFC 4180): un campo entre comiñas dobres pode conter comas, saltos de liña e comiñas duplicadas, os saltos de liña poden ser CRLF ou LF, e ignórase a marca de orde de bytes (BOM). As follas de cálculo en castelán adoitan gardar os CSV con punto e coma: léaos con --delimiter ";". O ficheiro lese enteiro na memoria; para ficheiros moi grandes, use a biblioteca cun stream, como no exemplo de CSV.