Tag: Programación

satisfies operator: el operador de TypeScript que no estás usando

Tiempo estimado de lectura: 5 min

• Valida sin perder inferencia: El operador satisfies valida que una expresión cumpla un tipo sin cambiar el tipo inferido del valor.
• Mejora la DX en repos grandes: Conserva literales y autocompletado donde las anotaciones tradicionales causan upcast o las aserciones apagan la seguridad.
• Casos de uso claros: Constants, routes, design tokens y mapeos estáticos se benefician más.
• Complemento con as const: Úsalo junto a as const para validación más inmutabilidad absoluta.
• No es para runtime: No reemplaza validación en tiempo de ejecución para datos dinámicos.

Introducción

satisfies operator: el operador de TypeScript que no estás usando es la frase que deberías leer en todos los PRs donde alguien fuerza tipos con as o sacrifica la inferencia de literales. Introducido en TypeScript 4.9, satisfies arregla —sin drama— un problema de tipado que hemos parcheado mal durante años.

Resumen rápido (lectores con prisa)

Qué es: Un operador de TypeScript que valida que un valor cumple un tipo sin cambiar la inferencia del valor.
Cuándo usarlo: Para constantes exportadas, rutas, tokens de diseño y mapeos estáticos donde quieres conservar literales.
Por qué importa: Mantiene autocompletado y seguridad de tipos en grandes bases de código.
Cómo funciona: Verifica el contrato en tiempo de compilación y deja intacta la inferencia literal.

¿Qué hace exactamente el satisfies operator y por qué importa?

El operador satisfies valida que una expresión cumpla con un tipo, pero no cambia el tipo inferido del valor. Es decir: verifica el contrato y deja intacta la inferencia literal del valor. Eso suena pequeño; en equipos con bases de código grandes es una diferencia estructural.

Comparación con anotación y aserción

• La anotación const x: T = ... valida pero hace upcast: pierde literales.
• La aserción const x = ... as T fuerza sin validar: apaga la seguridad.
• const x = ... satisfies T valida y conserva la inferencia.

Ejemplo práctico: tema de colores que no deberías arruinar

Sin satisfies, acabas escribiendo código que obliga al IDE a perder información útil:

type Color = string | [number, number, number];

const theme: Record = {
  primary: "blue",
  secondary: [255, 0, 0]
};

theme.primary.startsWith("b"); // Error: theme.primary es Color, no string literal

Con satisfies:

const theme = {
  primary: "blue",
  secondary: [255, 0, 0]
} satisfies Record;

theme.primary.startsWith("b"); // OK — TypeScript sabe que es string
theme.secondary[0];            // OK — sabe que es number

Validación sin amputación de tipos. Eso es todo.

Casos de uso donde satisfies aporta valor real

– Configuraciones públicas (constants.ts). Valores exportados y consumidos desde varios módulos se benefician de mantener literales.
– Rutas y diccionarios (routing). keyof typeof ROUTES debe devolver claves concretas, no string.
– Design tokens y paletas. Necesitas diferenciar hex strings de tuplas RGB sin perder método de string/array.
– API clients estáticos o mapeos entre endpoints y tipos de respuesta.

Ejemplo de rutas

type RouteConfig = Record;

const ROUTES = {
  home:      { path: "/",    protected: false },
  dashboard: { path: "/app", protected: true  },
} satisfies RouteConfig;

// keyof typeof ROUTES => "home" | "dashboard"

Si hubieras usado : RouteConfig, perderías esas claves y con ellas, seguridad y autocompletado.

Patrón avanzado: satisfies + as const

Úsalos juntos cuando quieras validación + inmutabilidad absoluta:

const ENDPOINTS = {
  users:   "/api/users",
  session: "/api/session",
} satisfies Record as const;

// ENDPOINTS.users es literal "/api/users" y readonly

Esto es ideal para inyectar constantes que se comparten por toda la app sin riesgo de mutación accidental.

Cuándo no usar satisfies

No es una bala de plata. No lo apliques en cada tipo local ni donde el valor no necesite exportarse o conservar literales.

• Definición y consumo inmediato en el mismo scope → anotación clásica puede ser más clara.
• Datos dinámicos desde la red → valida en runtime (Zod, io-ts) y transforma antes de confiar en tipos.

Recuerda: satisfies es para diseño estático y claridad, no para validar payloads de clientes externos en producción.

Cómo adoptarlo en un repo sin romper nada

1. Audit rápido: busca ficheros constants, theme, routes, tokens.
2. Busca patrones problemáticos: as const seguido de as Type, o const X: Record<...> = {...}.
3. Reemplaza por satisfies donde quieras conservar literales.
4. Añade tests de tipo (tsd) para casos críticos y ejecuta tsc --noEmit en CI.
5. Actualiza guía de estilo y explica el porqué en CONTRIBUTING.md.

Comando grep útil:
grep -R --line-number -E "as const.*as |: Record<|: {[A-Za-z0-9_]+: .*}" src/

Impacto en equipo y mantenimiento

Adoptar satisfies reduce errores sutiles: llamadas a funciones con claves incorrectas, fallos de autocompletado que llevan a as any, y la necesidad de escribir casts defensivos. A nivel de DX, mejora el autocompletado y la intención del código. A nivel de arquitectura, reduce deuda técnica silenciosa: menos as T, menos // @ts-ignore.

Cierre práctico

No es una moda; es una herramienta ergonométrica del tipo system. Si tu repo exporta constantes que consumen otros módulos, haz una pasada hoy mismo y reemplaza las anotaciones que hacen upcast por satisfies. Empieza por constants.ts, theme.ts, routes.ts. Verás menos PRs con as any y más código que documenta intención y comportamiento real.

Implementarlo es simple. Ignorarlo es caro. Esto no acaba aquí: la próxima vez que veas un as en un PR, pregúntate si deberías usar satisfies en su lugar.

Referencia oficial (anuncio): la sección relevante y la documentación general.

FAQ

¿Cansado de que las fechas te arruinen la noche? Bienvenido a Temporal

Tiempo estimado de lectura: 6 min

• Temporal reemplaza a Date para lógica de negocio: menos bugs y contratos más claros.
• Almacena Instants en DB (ISO UTC canonical) y convierte a zonas locales solo en UI.
• Polyfill hoy, tipos con TypeScript 6.0: feature-detect y carga condicional.
• Migración por capas y tests: evita PR monstruo, prioriza fronteras y añade reglas ESLint.

Resumen rápido (lectores con prisa)

Temporal es la API moderna para manejar tiempo en JS. Usa Instant para puntos absolutos (DB/logs), ZonedDateTime para eventos con zona y PlainDate para fechas sin hora. TypeScript 6.0 trae tipos; usa el polyfill donde el runtime no lo implemente.

Configuración y polyfill

TypeScript 6.0 trae los tipos de Temporal, pero el runtime puede no implementarlo aún en todos los motores.

Para usarlo hoy en Node o navegadores, instala el polyfill oficial:

npm install @js-temporal/polyfill

En el punto de entrada (server o client) haz feature-detect y carga el polyfill solo si hace falta:

if (!globalThis.Temporal) {
  await import('@js-temporal/polyfill');
}

Asegura tsconfig:

{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["esnext"],
    "strict": true
  }
}

Qué cambia en tu arquitectura (reglas rápidas)

• No más new Date() para lógica de negocio.
• Almacena timestamps en DB como Instant (ISO) — UTC canonical.
• Muestra/convierte a zonas locales con ZonedDateTime solo donde importe (UI, emails, calendarios).
• En tests y serialización: convierte a strings para persistir; rehidrata con Temporal.from() al cargar.

Casos prácticos y patrones — copia, pega y aplícalo

1) Obtener “ahora” correctamente

// Instant (UTC preciso, para auditoría/logs)
const nowInstant = Temporal.Now.instant();

// ZonedDateTime (evento con zona)
const nowZoned = Temporal.Now.zonedDateTimeISO();

// PlainDate (cumpleaños, sin hora ni zona)
const today = Temporal.Now.plainDateISO();

2) Sumar y restar sin mutar

const hoy = Temporal.Now.plainDateISO();
const dentroDe7Dias = hoy.add({ days: 7 }); // creado nuevo, hoy no cambia

3) Guardar en BD (mejor práctica)

• Guarda Instants como strings: instant.toString() → “2024-05-01T12:00:00Z”.
• Razonamiento: Instant es un punto absoluto; si reconstituyes en otro país, sigues teniendo el mismo momento.

const timestamp = Temporal.Now.instant().toString();
// INSERT INTO events (created_at) VALUES (timestamp);

Recuperación:

const instantFromDb = Temporal.Instant.from(dbValue);
const zonedInMadrid = instantFromDb.toZonedDateTimeISO('Europe/Madrid');

4) Mostrar en UI (zona del usuario)

const instant = Temporal.Instant.from(event.created_at);
const inUserTZ = instant.toZonedDateTimeISO(user.timeZone);
const formatted = inUserTZ.toLocaleString('es-ES', { dateStyle: 'medium', timeStyle: 'short' });

5) Schedules y DST (sin manualidades)

const vuelo = Temporal.ZonedDateTime.from('2024-10-15T14:30:00+09:00[Asia/Tokyo]');
const llegadaMadrid = vuelo.withTimeZone('Europe/Madrid');
// Temporal aplica reglas de DST correctamente.

Migración práctica y estrategia (no pegues un PR monstruo)

Plan corto y efectivo:

1. Detecta usos

• grep/rg por new Date(, Date.now(), .toISOString(), getUTC*, setUTC*.
• Haz una lista priorizada: endpoints, parsers de JSON, jobs, filas de cola.

2. Protege el repo

Añade rule de ESLint que prohíba new Date en código nuevo:

// .eslintrc.json
"rules": {
  "no-restricted-syntax": [
    "error",
    {
      "selector": "NewExpression[callee.name='Date']",
      "message": "Usa Temporal en lugar de Date"
    }
  ]
}

3. Cambia en capas

• Fronteras primero: parsers de requests, handlers, webhooks.
• Library layer: utilidades de fecha centralizadas.
• UI: formateadores y locales.

4. Persistencia y API contract

• Define y documenta: “todos los timestamps en la DB son Instant ISO strings”.
• Añade validaciones en los endpoints que aceptan timestamps (Zod / Zod schemas o runtime checks).

5. Tests y CI

• En jest/mocha, añade el polyfill en setupTests: import '@js-temporal/polyfill';
• Añade pruebas para zona horaria, DST y serialización.

Peculiaridades y errores que verás (y cómo arreglarlos)

• Serialización: Temporal types no siempre serializan como esperas en JSON.stringify. Convierte a string explícitamente.
• Redux / Hydration: almacena ISO strings en store si necesitas serialización. Temporal objects son inmutables pero no pensados para serializar automáticamente.
• Comparaciones: usa Temporal.PlainDate.compare o Instant.avoid numeric timezone math.
• Interoperabilidad con libs: elimina gradualmente date-fns/moment; si dependes de ellas, mantén adaptadores hasta reemplazar lógica.

Decisiones de diseño: Instant vs ZonedDateTime vs PlainDate

• Instant → logs, audit, DB primary timestamp.
• ZonedDateTime → eventos programados que dependen de la hora local.
• PlainDate → cumpleaños, fechainterna sin hora.
• Duration → expiraciones, TTLs, duraciones humanas.

Ejemplo real: reserva de vuelo (correcto)

• Guardar en DB: Vuelo.departureInstant (Instant)
• Guardar metadatos: Vuelo.departureTZ = 'Asia/Tokyo'
• Mostrar en UI: instant.toZonedDateTimeISO(tz).toLocaleString(...)

Performance y bundle

El polyfill tiene coste. Si tu app es frontend, lazy-load the polyfill: solo usuarios que lo necesiten (browsers sin Temporal nativo) lo cargarán.

En server (Node), añade polyfill en arranque. No suele ser un problema de perf si lo colocas correctamente.

Checklist rápido antes de mergear cambios de fecha

• Todos los endpoints aceptan/retornan ISO Instant cuando corresponde.
• Tests cubren conversiones entre zonas y casos límites (fin de mes, cambio DST).
• No quedan new Date() en la lógica de negocio.
• Documentación para frontend/backend: cómo serializar y rehidratar.

Metáfora breve: por qué vale la pena

Date era un martillo con un tornillo. Temporal es el juego de herramientas correcto para el tiempo. No es más trabajo: es menos debugging.

Cierre (CTA claro)

¿Quieres el script que escanea tu repo, lista todas las ocurrencias de Date y genera un plan de migración automático por prioridad? Respóndeme con “MIGRAR FECHAS” y te lo entrego: branch de prueba, report con 100 entradas ordenadas, y PR template para cada cambio.

Esto no acaba aquí. La siguiente nota: cómo reescribir utilidades de date-fns a Temporal con transformaciones seguras y codemods semi-automáticos. ¿Lo hacemos?

Si te interesa integrar estas prácticas con flujos de trabajo y automatización de repos, revisa Dominicode Labs para plantillas y herramientas que aceleran migraciones y codemods.

FAQ