@core-tecnologias-empresariales/core-formatter

Formateo e internacionalización de valores (números, moneda, fechas, teléfonos, identificadores fiscales, unidades) para el ecosistema Core Tecnología Empresarial — API única y parametrizable por país/locale, nunca funciones fijas por país (formatCLP(), formatChileDate(), etc.).

Para qué sirve

CorePyme, Core Tributario, Core Contador, CoreEmpresas, backend o frontend: cualquier producto Core que necesite mostrarle un número/fecha/moneda/teléfono a un usuario final, respetando su país/locale/timezone, sin reimplementar las reglas de cada país.

Para qué NO sirve

No calcula tributación, no valida documentos SII, no valida dígitos verificadores en profundidad — sólo formatea. Eso pertenece a dominios específicos (Core Tributario, un validador especializado).

Instalación

pnpm add @core-tecnologias-empresariales/core-formatter

Uso

import { formatter } from "@core-tecnologias-empresariales/core-formatter";

formatter.currency(1250000, { country: "CL" }); // "$1.250.000"
formatter.currency(1250000, { country: "US" }); // "$1,250,000.00"
formatter.date(new Date(), { country: "CL", style: "long" }); // "30 de agosto de 2026"
formatter.taxId("123456785", { country: "CL" }); // "12.345.678-5"
formatter.phone("+56912345678", { country: "CL" }); // "+56 912345678"
formatter.list(["Ventas", "Inventario", "Clientes"], { locale: "es-CL" }); // "Ventas, Inventario y Clientes"
formatter.mask("123456789", { visibleStart: 3, visibleEnd: 2 }); // "123****89"

Cobertura mundial (no sólo Latinoamérica)

• country() / nombre de país — CUALQUIER código ISO 3166-1 alpha-2 del mundo, vía Intl.DisplayNames (CLDR real, sin lista manual).
• currency() / moneda — ~246 territorios con su ISO 4217 real, tabla generada desde el dataset público mledoze/countries (no es una dependencia en tiempo de ejecución — se extrajo una sola vez, para no arrastrar los ~5 MB de banderas/mapas del paquete completo a un formatter que también corre en frontend).
• locale() / timezone — curado sólo para ~65 mercados reales (no existe una fuente estándar única de "el locale/timezone por defecto de un país"; países multilingües o con varios husos son ambiguos por diseño). Fuera de esa tabla, locale() pide el valor explícito en vez de adivinar — extensible con registerCountry().
• taxIdType() — nunca lanza: para un país sin tipo curado, devuelve un genérico honesto ("Tax ID" + el nombre real del país) en vez de fingir una sigla no verificada.
• phone() — cualquier país soportado por libphonenumber-js (el mismo dataset que usa libphonenumber de Google).

API

Convención uniforme formatter.<tipo>(value, options):

number · compact · percent · currency · currencySymbol · currencyName · date · time · dateTime · relativeDate · taxId · taxIdType · phone · isValidPhone · postalCode · weight · distance · volume · temperature · fileSize · duration · boolean · list · mask · country · locale · registerCountry

Todas aceptan { country?, locale?, timezone? } (país/locale/timezone son conceptos independientes — nunca se asume country → currency ni country → locale).

Errores

InvalidCountryError (código no es ISO 3166-1 válido) · InvalidCurrencyError · InvalidLocaleError (país sin locale curado y sin locale explícito) · InvalidTaxIdError · UnsupportedFormatError.

Valores vacíos

null/undefined en cualquier format* numérico/fecha devuelve "—" por defecto, configurable con emptyValue.

Deferido (fuera de esta pasada)

• numberToWords, address — no estaban en la lista de prioridad MVP del spec original.
• Intl.DurationFormat para duration({ style: "long" }) con locale real — no disponible todavía en todos los runtimes de Node que soporta el proyecto; hoy es español fijo.
• Formato propio de taxId()/postalCode() más allá de Chile/EE.UU./Brasil — se agrega cuando un producto Core lo necesite de verdad, no por adelantado.

Seguridad

No almacena secretos ni credenciales. No envía datos a servicios externos — todo el procesamiento es local (Intl, tablas estáticas, libphonenumber-js).