date-fns / Luxon

import { DateTime } from "luxon";
 
// Almacena ISO UTC en Postgres
const scheduledAtUtc = DateTime.utc(2026, 7, 9, 14, 30).toISO();
 
// Convierte para correo electrónico dirigido al cliente (zona explícita)
const display = DateTime.fromISO(scheduledAtUtc, { zone: "utc" })
  .setZone("America/New_York")
  .toFormat("ff ZZZZ");
// "Jul 9, 2026, 10:30 AM EDT"

import { addBusinessDays, differenceInCalendarDays } from "date-fns";
 
const shipDate = addBusinessDays(new Date("2026-07-09"), 3);
const daysUntilDue = differenceInCalendarDays(dueDate, new Date());

// src/scheduling/appointments.ts
import { DateTime } from "luxon";
import { z } from "zod";
 
const bookSchema = z.object({
  slotLocal: z.string().datetime({ offset: true }),
  timeZone: z.string(), // IANA: America/Chicago
});
 
export function toUtcStorage(input: z.infer<typeof bookSchema>): string {
  const local = DateTime.fromISO(input.slotLocal, { zone: input.timeZone });
  if (!local.isValid) {
    throw new Error(`invalid slot: ${local.invalidReason}`);
  }
  return local.toUTC().toISO()!;
}
 
export function nextBillingRunUtc(
  anchorUtc: string,
  customerZone: string
): string {
  const local = DateTime.fromISO(anchorUtc, { zone: "utc" }).setZone(customerZone);
  // Facturar a las 00:05 hora local el día 1
  const next = local.plus({ months: 1 }).startOf("month").set({
    hour: 0,
    minute: 5,
    second: 0,
    millisecond: 0,
  });
  return next.toUTC().toISO()!;
}

// API: siempre devuelve UTC + sugerencia de visualización opcional
app.get("/appointments/:id", async (req) => {
  const row = await db.getAppointment(req.params.id);
  const startsAtUtc = row.starts_at; // timestamptz
  const forUser = DateTime.fromISO(startsAtUtc, { zone: "utc" })
    .setZone(row.user_timezone)
    .toISO();
  return {
    startsAtUtc,
    startsAtLocal: forUser,
    timeZone: row.user_timezone,
  };
});

// INCORRECTO: se analiza como la zona local del servidor
new Date("2026-07-09 09:00:00");
 
// INCORRECTO: EST es ambiguo (EST vs EDT)
const tz = "EST";
 
// CORRECTO: desplazamiento explícito o IANA
DateTime.fromISO("2026-07-09T09:00:00-05:00");
DateTime.now().setZone("America/Chicago");