Referencia de API

Referencia de API

Los contratos viven en src/types.ts y son idénticos en los 23 países. No se inventan contratos nuevos: un módulo nuevo implementa uno de estos.

Exports raíz

import {
  ar, bo, br, cl, co, cr, cu, do_, ec, gt, hn, ht,
  jm, mx, ni, pa, pe, pr, py, sv, tt, uy, ve,
  detect,
  measurements,
} from '@zeluizr/palta'

export	tipo	descripción
los 23 códigos de país	namespace	currency, phone, zipcode y uno a tres documentos
detect	función	identifica país y tipo de un documento
measurements	namespace	length, weight, volume

do_ es República Dominicana. El guion bajo existe porque do es palabra reservada de JavaScript; el subpath @zeluizr/palta/do no lo lleva.

DocumentModule

interface DocumentModule {
  format(value: string): string
  strip(value: string): string
  validate(value: string): boolean
  mask: string
}

miembro	entrada	salida	notas
format	valor limpio o formateado	string formateado	'' si la entrada es vacía o inválida
strip	valor limpio o formateado	solo dígitos, y K donde aplica	'' si la entrada es vacía
validate	valor limpio o formateado	boolean	verifica largo y dígito verificador
mask	—	plantilla, por ejemplo ###.###.###-##	# dígito, A/L/X letra o alfanumérico

Los cuatro son defensivos: format(''), validate(null) y strip(undefined) nunca lanzan.

CurrencyModule

interface CurrencyModule {
  format(value: number, options?: { decimals?: number; symbol?: boolean }): string
  parse(value: string): number
  symbol: string
  code: string
}

miembro	descripción
format	número a string local; decimals sobrescribe el default del país, symbol: false lo omite
parse	string local a número; ignora símbolo, miles y espacios
symbol	símbolo local, por ejemplo R$, ₡, S/
code	código ISO 4217, por ejemplo BRL, CRC, PEN

Desde la 1.3.0 los dos son defensivos en los 23 países. format devuelve '' con cualquier valor no finito (NaN, Infinity, null, undefined), la misma política de measurements.format, y parse devuelve 0 con cualquier entrada que no sea un string parseable. Ninguno lanza.

pr.currency.format(null)   // ''
br.currency.format(NaN)    // ''
ht.currency.parse(null)    // 0

Con un valor finito, format da exactamente el mismo resultado de siempre.

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

PhoneModule

interface PhoneModule {
  format(value: string, options?: { international?: boolean }): string
  validate(value: string): boolean
  mask: string | { mobile: string; landline: string }
  countryCode: string
}

miembro	descripción
format	formato internacional por defecto en todos los países menos Brasil, que devuelve nacional salvo { international: true }
validate	verifica largo y prefijos válidos del país
mask	string, o un objeto con mobile y landline en Brasil, Ecuador y Venezuela
countryCode	prefijo internacional, por ejemplo +55

ZipcodeModule

interface ZipcodeModule {
  format(value: string): string
  validate(value: string): boolean
  mask: string
}

Algunos países exponen además strip, con la misma semántica que en los documentos.

detect

function detect(value: string): DetectResult | null

interface DetectResult {
  country: string    // código ISO de dos letras en mayúscula
  type: string       // 'cpf', 'rut', 'cuit', ...
  valid: boolean
  formatted: string
}

Devuelve null cuando no reconoce el valor. Los detalles están en Detección.

MeasurementModule

interface MeasurementModule<U extends string> {
  convert(value: number, from: U, to: U): number
  format(value: number, unit: U, options?: { decimals?: number }): string
}

type LengthUnit = 'mm' | 'cm' | 'm' | 'km' | 'in' | 'ft'
type WeightUnit = 'mg' | 'g' | 'kg' | 'oz' | 'lb'
type VolumeUnit = 'ml' | 'l' | 'fl oz'

convert devuelve NaN con entradas no finitas. format devuelve ''. Los factores y la auto-escala están en Medidas.

Utilidades internas

Estas funciones no se exportan en el paquete público. Están en src/utils.ts y son la base de todos los módulos; te importan si vas a contribuir.

función	qué hace
onlyDigits(v)	deja solo dígitos
onlyDigitsAndK(v)	deja dígitos y K, en mayúscula — para el RUT chileno
padLeft(v, len, char)	rellena a la izquierda
safeStr(v)	convierte null, undefined y no-strings a ''

safeStr es lo que hace que la regla defensiva se cumpla sin repetir guardas en cada módulo.

Excepciones conocidas

Dos módulos se apartan hoy del contrato general. Están documentados acá para que no te sorprendan; si te topás con ellos, un issue o un PR es bienvenido.

módulo	desvío	issue
bo.nit	mask es un string vacío	—
mx.rfc	mask es un objeto { fisica, moral }, no un string	—

Los cinco desvíos de currency y phone que estaban acá se cerraron en la 1.3.0 (#61, #62, #63, #64). mx.currency implementa parse y conserva strip como extra; ni.phone expone countryCode y conserva code como alias deprecado. Si seguís en 1.2.0, los desvíos siguen ahí.

Ver también: Países para los valores concretos de cada país.