FAQ

Preguntas frecuentes

¿Por qué República Dominicana se llama do_?

do es palabra reservada de JavaScript y no puede ser el nombre de un export. En el import raíz el namespace lleva guion bajo; el subpath no.

import { do_ } from '@zeluizr/palta'
import { cedula } from '@zeluizr/palta/do'

¿Por qué Brasil formatea teléfonos distinto a todos los demás?

Porque en Brasil el formato nacional (11) 98765-4321 es el que la gente reconoce, y mostrar +55 en un checkout brasileño se lee como un error. Es la única asimetría de la API.

br.phone.format('11987654321')                          // '(11) 98765-4321'
br.phone.format('11987654321', { international: true }) // '+55 (11) 98765-4321'
cl.phone.format('912345678')                            // '+56 9 1234 5678'

¿Tengo que limpiar el valor antes de validar?

No. format y validate normalizan por dentro.

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

strip existe para cuando querés guardar el valor limpio, no como paso previo.

¿Qué pasa si le paso null o un string vacío?

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

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

currency.format y currency.parse también lo cumplen desde la 1.3.0: format devuelve '' con cualquier valor no finito y parse devuelve 0 con cualquier entrada que no sea un string parseable. Hasta la 1.2.0, format lanzaba en Puerto Rico y renderizaba NaN en el resto.

Igual conviene verificar el número antes si viene de afuera, para elegir vos qué mostrar cuando no es válido.

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

¿Por qué Chile y Colombia formatean sin decimales?

Porque sus monedas no usan centavos en la práctica. Podés forzarlos:

cl.currency.format(1234.5)                  // '$1.235'
cl.currency.format(1234.5, { decimals: 2 }) // '$1.234,50'

Cuatro países usan dólar. ¿Formatean igual?

No. Ecuador, El Salvador, Panamá y Puerto Rico usan USD, pero cada uno con su convención local de espaciado y símbolo. Usá el módulo del país correcto, no cualquiera de los cuatro.

¿detect() cubre los 23 países?

No, y no está pensada para eso. Cubre los documentos principales de nueve países. Si ya sabés el país, llamá al módulo directo: es más rápido y no tiene ambigüedad. Los detalles están en Detección.

detect() me devolvió el país equivocado

Varios documentos comparten largo. Un número de 8 dígitos puede ser CI uruguaya, DNI peruano, DNI argentino o RUT chileno; detect() prueba en orden y devuelve el primero que valida. Cuando conocés el origen del dato, no uses detect().

¿Cómo reduzco el tamaño del bundle?

Importá por subpath:

import { cpf } from '@zeluizr/palta/br'

El import raíz también funciona bien con un bundler que hace tree-shaking, porque el paquete declara "sideEffects": false.

¿Funciona en Node 16?

Sí. El paquete declara engines: node >= 16 y la salida compilada no usa APIs exclusivas de versiones nuevas. El toolchain de desarrollo pide más — vitest 4 exige Node 20 y la CI corre en Node 22 — pero eso no afecta a quien lo instala. Importa sobre todo en VTEX IO.

¿Funciona en el navegador?

Sí. Son funciones puras sin APIs de Node. Se puede usar en React, Vue o Svelte sin configuración especial. Hay un ejemplo en demo/index.html.

¿Tiene dependencias?

Ninguna en runtime. Solo devDependencies para el tooling: tsup, typescript, vitest y @vitest/coverage-v8.

¿Qué significan los # de las máscaras?

# es un dígito. A, L y X marcan letras o caracteres alfanuméricos según el documento. En Brasil, Ecuador y Venezuela phone.mask es un objeto con mobile y landline en vez de un string.

br.cpf.mask    // '###.###.###-##'
ar.zipcode.mask // 'A####AAA'
br.phone.mask  // { mobile: '(##) #####-####', landline: '(##) ####-####' }

¿Por qué measurements no está por país?

Porque las unidades son las mismas en todos lados. El módulo es global y auto-escala para mostrar: cm >= 100 pasa a m, g >= 1000 a kg, ml >= 1000 a l. Ver Medidas.

Encontré un documento mal validado

Abrí un issue con el valor exacto, lo que devuelve y lo que esperabas. Un ejemplo reproducible vale más que cualquier descripción. El flujo completo está en Contribuir.