Guia de uso

Guía de uso

Todos los países exponen la misma forma. Aprendés un país y sabés los 23.

módulo	funciones	presente en
documento	format strip validate mask	todos, uno a tres por país
currency	format parse symbol code	todos
phone	format validate mask countryCode	todos
zipcode	format validate mask	todos

Documentos

Cada país expone uno o más documentos con el mismo contrato. format embellece, strip desarma, validate verifica el dígito verificador y mask es la plantilla para mostrar o para alimentar un input.

import { br, cl, ar, co } from '@zeluizr/palta'

br.cpf.format('11144477735')          // '111.444.777-35'
br.cpf.validate('111.444.777-35')     // true
br.cpf.strip('111.444.777-35')        // '11144477735'
br.cpf.mask                           // '###.###.###-##'

br.cnpj.format('11222333000181')      // '11.222.333/0001-81'
br.cnpj.validate('11.222.333/0001-81')// true

cl.rut.format('123456785')            // '12.345.678-5'
cl.rut.validate('12.345.678-5')       // true

ar.cuit.format('20123456786')         // '20-12345678-6'
ar.dni.format('1234567')              // '1.234.567'

co.nit.format('9001234561')           // '900.123.456-1'

format y validate aceptan el valor sucio o limpio, da igual: por dentro se normaliza primero. No hace falta llamar strip antes.

br.cpf.validate('111.444.777-35')  // true
br.cpf.validate('11144477735')     // true
br.cpf.validate(' 111 444 777 35 ')// true

Comportamiento con entradas vacías

Los módulos de documento son defensivos: nunca lanzan.

br.cpf.format('')          // ''
br.cpf.validate(null)      // false
br.cpf.strip(undefined)    // ''

Esa es una regla del proyecto, no un accidente. Está en Contribuir y se verifica en los tests de cada país.

Chile y la letra K

El RUT chileno puede terminar en K. cl.rut además expone getCheckDigit, que calcula el dígito verificador de un cuerpo sin él.

cl.rut.getCheckDigit('12345678')   // '5'
cl.rut.format('123456785')         // '12.345.678-5'

Moneda

import { br, cl } from '@zeluizr/palta'

br.currency.format(1234.5)                     // 'R$ 1.234,50'
br.currency.format(1234.5, { symbol: false })  // '1.234,50'
br.currency.format(1234.5, { decimals: 0 })    // 'R$ 1.235'
br.currency.parse('R$ 1.234,50')               // 1234.5

br.currency.symbol                             // 'R$'
br.currency.code                               // 'BRL'

cl.currency.format(1234.5)                     // '$1.235'
cl.currency.parse('$1.235')                    // 1235

Cada país usa su convención local: separador de miles, separador decimal, posición del símbolo y cantidad de decimales por defecto. Chile, Colombia y Paraguay redondean a cero decimales porque sus monedas no usan centavos en la práctica.

Las opciones de format:

opción	tipo	qué hace
decimals	number	cantidad de decimales; por defecto la del país
symbol	boolean	incluir el símbolo; true por defecto

Los 23 países respetan las dos opciones. Hasta la 1.2.0, Haití, México y Puerto Rico las ignoraban en silencio.

format es defensivo desde la 1.3.0: con cualquier valor no finito devuelve '' en vez de lanzar o de renderizar un NaN. Aun así, si el número viene de un formulario o de una API, convertirlo y verificarlo antes te deja decidir qué mostrar en ese caso.

const n = Number(input)
const texto = Number.isFinite(n) ? br.currency.format(n) : ''

La tabla completa de monedas, símbolos y ejemplos está en Países.

Teléfonos

import { br, cl } from '@zeluizr/palta'

cl.phone.format('912345678')      // '+56 9 1234 5678'
br.phone.format('11987654321')    // '(11) 98765-4321'
br.phone.format('1133334444')     // '(11) 3333-4444'

br.phone.format('11987654321', { international: true })
// '+55 (11) 98765-4321'

br.phone.validate('11987654321')  // true
br.phone.countryCode              // '+55'

Brasil es la excepción de la casa: devuelve formato nacional salvo que pidas { international: true }. Todos los demás países devuelven formato internacional por defecto. Es la única asimetría de la API y conviene tenerla presente.

mask puede ser un string o un objeto con mobile y landline en los países que distinguen móvil de fijo — Brasil, Ecuador y Venezuela.

br.phone.mask
// { mobile: '(##) #####-####', landline: '(##) ####-####' }

cl.phone.mask
// '+56 # #### ####'

Si tu código lee mask genéricamente, tratá los dos casos:

const m = br.phone.mask
const plantilla = typeof m === 'string' ? m : m.mobile

Códigos postales

import { br } from '@zeluizr/palta'

br.zipcode.format('01310100')     // '01310-100'
br.zipcode.validate('01310-100')  // true
br.zipcode.mask                   // '#####-###'

Argentina usa el formato alfanumérico CPA, con letra de provincia adelante y tres letras de control atrás:

import { ar } from '@zeluizr/palta'

ar.zipcode.mask                   // 'A####AAA'
ar.zipcode.validate('C1425DKE')   // true

Medidas

measurements es global, no por país. Tiene su propia página: Medidas.

import { measurements } from '@zeluizr/palta'

measurements.length.format(150, 'cm')      // '1,50 m'
measurements.weight.format(2500, 'g')      // '2,50 kg'
measurements.length.convert(1, 'm', 'cm')  // 100

Detección automática

detect() recibe un valor y trata de decir de qué país y de qué tipo es. Tiene su propia página, con el orden de resolución y sus límites: Detección.

import { detect } from '@zeluizr/palta'

detect('111.444.777-35')
// { country: 'BR', type: 'cpf', valid: true, formatted: '111.444.777-35' }

detect('holaaa')  // null

Siguiente paso: Referencia de API o Recetas.