@core-tecnologias-empresariales/core-time

Autoridad temporal del ecosistema Core Tecnología Empresarial: UTC como estándar de persistencia, timezones IANA, conversión local↔UTC con validación de DST, y separación entre instante y fecha de negocio.

Por qué existe

El navegador nunca debe ser la autoridad de tiempo para auditoría, createdAt, eventos, expiraciones críticas ni operaciones tributarias. core-time es el único punto donde el backend genera y convierte instantes.

import { now, nowIn, toUTC, fromUTC, toBusinessDate, parse } from "@core-tecnologias-empresariales/core-time";

now();                                          // "2026-09-03T01:30:00.000Z" — instante UTC actual
nowIn("America/Santiago");                       // { instant, timezone, local: "2026-09-02T21:30:00-04:00" }

toUTC("2026-09-02T21:30:00", "America/Santiago"); // "2026-09-03T01:30:00.000Z"
fromUTC("2026-09-03T01:30:00.000Z", "America/Santiago"); // "2026-09-02 21:30:00"

toBusinessDate("2026-09-03T03:59:59.000Z", "America/Santiago"); // "2026-09-02" — 23:59:59 hora Chile

parse("2026-09-03T01:30:00Z");   // { kind: "instant", instant: ... }
parse("2026-09-02T21:30:00");    // { kind: "localDateTime", local: ... }
parse("2026-09-02");             // { kind: "localDate", date: ... }
parse("03/09/2026 01:30");       // throws InvalidDateError — formato ambiguo, rechazado

Validación de DST

toUTC() nunca adivina durante una transición de horario: si la hora local no existe (salto de primavera) o es ambigua (ocurre dos veces al retroceder el reloj), lanza NonexistentLocalTimeError/AmbiguousLocalTimeError en vez de elegir un offset arbitrario.

Errores tipados

InvalidTimezoneError, InvalidDateError, InvalidInstantError, AmbiguousLocalTimeError, NonexistentLocalTimeError.

Para qué NO sirve (ponytail: diferido / fuera de alcance)

• Formateo para presentación ("02-09-2026 21:30:00" con locale/estilo) — eso es core-formatter (formatter.date/time/dateTime), que ya envuelve Intl.DateTimeFormat con locale/timezone. core-time no lo duplica.
• timezoneForCountry() — core-formatter's country(code).timezone ya cubre esto para los mercados curados; no se duplicó la tabla acá.
• Reglas tributarias, folios, DTE — eso es de Core Tributario.
• Temporal — se evaluó pero no está estable en la matriz de runtimes objetivo; la implementación usa Intl/Date nativos, abstraídos detrás de esta API para poder migrar sin romper consumidores.

Instalación

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

Desarrollo

pnpm build
pnpm test