multi-dni-validator

Una librería sencilla, rápida y escalable en TypeScript/JavaScript para validar, generar dígitos verificadores y formatear documentos de identidad (DNI, RUT, Cédulas, CPF, CURP, etc.) de diversos países. 🌍

Ofrece soporte para Tree Shaking, lo que significa que puedes importar estrictamente el validador del país que necesites para mantener tu empaquetado final o bundle lo más ligero posible.

📦 Instalación

Usando npm:

npm install multi-dni-validator

Usando yarn:

yarn add multi-dni-validator

🚀 Uso Rápido (Función General)

La librería cuenta con funciones generales que te permiten consultar el DNI dinámicamente según el código del país requerido. Esto es ideal para formularios de registro internacionales.

import { validateDNI, generateDV, formatDNI } from 'multi-dni-validator';

// 1. Validando un número (Ejemplo Chile 'cl')
const isValid = validateDNI('cl', '12345678-5');
console.log(isValid); // true

// 2. Obteniendo el Dígito/Letra Validadora correspondiente
const dv = generateDV('cl', '12345678'); 
console.log(dv); // '5'

// 3. Formateando un DNI según el estándar del país
const formatted = formatDNI('cl', '123456785');
console.log(formatted); // '12.345.678-5'

🍃 Uso Avanzado / Tree Shaking

Si tu aplicación únicamente opera en un mercado y solo necesitas a uno o pocos países, te recomendamos importar las funciones de manera directa:

import { validateCL, formatCL, generateDvCL } from 'multi-dni-validator';
import { validateES, formatES } from 'multi-dni-validator';
import { validateBR, formatBR } from 'multi-dni-validator';

// Chile
const esValidoCL = validateCL('12.345.678-5');
const formateadoCL = formatCL('123456785'); // '12.345.678-5'

// España (Soporta número de DNI clásico y NIE de extranjeros)
const esValidoES = validateES('12345678Z');
const formateadoES = formatES('12345678Z'); // '12345678-Z'

// Brasil (Soporta CPF)
const esValidoBR = validateBR('111.444.777-35');
const formateadoBR = formatBR('11144477735'); // '111.444.777-35'

🏳️ Países Soportados

Con validación de dígito verificador

Estos países cuentan con validación completa: validate, generateDV y format.

| País | Código | Validar | Generar DV | Formatear | Formato | |------------|--------|------------------|------------------|------------------|------------------------| | Chile 🇨🇱 | cl | validateCL | generateDvCL | formatCL | 99.999.999-* | | España 🇪🇸 | es | validateES | generateDvES | formatES | 99999999-a | | Brasil 🇧🇷 | br | validateBR | generateDvBR | formatBR | 999.999.999-99 | | Ecuador 🇪🇨| ec | validateEC | generateDvEC | formatEC | 999999999-9 | | Uruguay 🇺🇾| uy | validateUY | generateDvUY | formatUY | 9.999.999-9 |

Con validación estructural

Estos países cuentan con validación de estructura (largo y patrón) y formato. Los algoritmos de dígito verificador se irán incorporando en futuras versiones.

| País | Código | Validar | Formatear | Formato | |--------------|--------|------------------|------------------|--------------------------| | México 🇲🇽 | mx | validateMX | formatMX | aaaa999999aaaaaa99 | | Colombia 🇨🇴 | co | validateCO | formatCO | 99.999.999.999 | | Argentina 🇦🇷| ar | validateAR | formatAR | 99.999.999 | | Perú 🇵🇪 | pe | validatePE | formatPE | 99999999 | | Paraguay 🇵🇾 | py | validatePY | formatPY | 9.999.999 | | Guyana 🇬🇾 | gy | validateGY | formatGY | 999999999 | | Suriname 🇸🇷 | sr | validateSR | formatSR | aa999999 | | Bolivia 🇧🇴 | bo | validateBO | formatBO | 9999999-a | | Venezuela 🇻🇪| ve | validateVE | formatVE | a-99.999.999 |

Leyenda de formatos

| Símbolo | Significado | |---------|----------------------| | 9 | Dígito numérico | | a | Letra alfabética | | * | Dígito o letra (K) |

📐 Ejemplos de Formato

import { formatDNI } from 'multi-dni-validator';

formatDNI('cl', '123456785');        // '12.345.678-5'
formatDNI('es', '12345678Z');        // '12345678-Z'
formatDNI('br', '11144477735');      // '111.444.777-35'
formatDNI('ec', '1712345670');       // '171234567-0'
formatDNI('uy', '12345678');         // '1.234.567-8'
formatDNI('mx', 'garc850101hdfrrl09'); // 'GARC850101HDFRRL09'
formatDNI('co', '1234567890');       // '1.234.567.890'
formatDNI('ar', '12345678');         // '12.345.678'
formatDNI('pe', '12345678');         // '12345678'
formatDNI('py', '1234567');          // '1.234.567'
formatDNI('gy', '123456789');        // '123456789'
formatDNI('sr', 'ab123456');         // 'AB123456'
formatDNI('bo', '1234567LP');        // '1234567-LP'
formatDNI('ve', 'V12345678');        // 'V-12.345.678'

💡 Nota sobre el formato: Los módulos internos realizan normalización automática. Limpian puntos, espacios y guiones antes de validar (p.ej.: 12.345.678-5 equivale a procesar 123456785), por lo que no es necesario que prepares o recortes los valores previamente.

🤝 Por Qué Usar Esta Librería

Esta herramienta estructura la lógica de validación separando cada país en su propio archivo de negocio. Esto facilita enormemente ir añadiendo más algoritmos matemáticos internacionales en futuras versiones de la librería sin impactar ni hacer pesado el flujo de los demás validadores.

📝 Licencia

Distribuido bajo la Licencia MIT. Libre para uso en cualquier aplicación comercial o personal.