date-fns / Luxon

Q: Apenas Luxon ou date-fns também?

Se cada data tocar um fuso horário do usuário, apenas Luxon é suficiente. Adicione date-fns quando precisar de seus helpers de calendário tree-shakeable e toda a matemática permanecer em UTC.

Q: JavaScript Date em APIs?

Serializar strings ISO 8601 em JSON, não objetos Date (eles se tornam strings UTC de qualquer maneira). Documente que os consumidores da API devem enviar offset ou Z.

Backends falham silenciosamente em fusos horários. Luxon lida com zonas IANA e horário de verão (DST); date-fns lida com aritmética de calendário. Use ambos deliberadamente ou padronize apenas em Luxon.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { DateTime } from "luxon";
 
// Armazene ISO UTC no Postgres
const scheduledAtUtc = DateTime.utc(2026, 7, 9, 14, 30).toISO();
 
// Converta para e-mail voltado para o 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());

Quando usar isso:

Ciclos de faturamento, prazos de SLA e janelas de relatórios em hora local
Convertendo "9:00 AM Chicago" selecionado pelo usuário para UTC para armazenamento
Semanas de transição de horário de verão (adiantar na primavera, voltar no outono)
date-fns quando nenhuma matemática de zona for necessária (durações, dias úteis em UTC)

Exemplo de Trabalho

// 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(`slot inválido: ${local.invalidReason}`);
  }
  return local.toUTC().toISO()!;
}
 
export function nextBillingRunUtc(
  anchorUtc: string,
  customerZone: string
): string {
  const local = DateTime.fromISO(anchorUtc, { zone: "utc" }).setZone(customerZone);
  // Cobrar às 00:05 local no dia 1º
  const next = local.plus({ months: 1 }).startOf("month").set({
    hour: 0,
    minute: 5,
    second: 0,
    millisecond: 0,
  });
  return next.toUTC().toISO()!;
}

// API: sempre retorne UTC + dica de exibição 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,
  };
});

Regras do banco de dados:

Postgres: timestamptz para instantes; text ou date apenas quando verdadeiramente local do calendário
Nunca armazene abreviações "EST" - use IANA America/New_York
Tarefas Cron: documente a zona na definição da tarefa e no runbook

Divisão de Bibliotecas

Tarefa	Biblioteca	Exemplo
Conversão de zona IANA	Luxon	`setZone("Europe/Berlin")`
Agendamento seguro contra DST	Luxon	`plus({ months: 1 })` na zona
Dias úteis (UTC)	date-fns	`addBusinessDays`
Duração entre datas	date-fns	`differenceInMinutes`
Formato para logs	Luxon	`toISO()` sempre UTC

Novos serviços podem usar apenas Luxon e pular date-fns para reduzir sobreposição.
Não adicione moment - API não mantida e mutável.

Antipatterns

// ERRADO: analisa como zona local do servidor
new Date("2026-07-09 09:00:00");
 
// ERRADO: EST é ambíguo (EST vs EDT)
const tz = "EST";
 
// CERTO: offset explícito ou IANA
DateTime.fromISO("2026-07-09T09:00:00-05:00");
DateTime.now().setZone("America/Chicago");

FAQs

Apenas Luxon ou date-fns também?

Se cada data tocar um fuso horário do usuário, apenas Luxon é suficiente. Adicione date-fns quando precisar de seus helpers de calendário tree-shakeable e toda a matemática permanecer em UTC.

Como testar as bordas do horário de verão?

Datas de fixture: segundo domingo de março e primeiro domingo de novembro para zonas dos EUA. Afirme a saída UTC, não as strings formatadas.

JavaScript Date em APIs?

Serializar strings ISO 8601 em JSON, não objetos Date (eles se tornam strings UTC de qualquer maneira). Documente que os consumidores da API devem enviar offset ou Z.

Relacionados

Noções Básicas de Bibliotecas Essenciais - uma biblioteca por preocupação
Agendamento e Cron - trabalhos repetíveis com zonas
zod - valide strings de datetime nas fronteiras

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { DateTime } from "luxon";
 
// Armazene ISO UTC no Postgres
const scheduledAtUtc = DateTime.utc(2026, 7, 9, 14, 30).toISO();
 
// Converta para e-mail voltado para o 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());

Quando usar isso:

Ciclos de faturamento, prazos de SLA e janelas de relatórios em hora local
Convertendo "9:00 AM Chicago" selecionado pelo usuário para UTC para armazenamento
Semanas de transição de horário de verão (adiantar na primavera, voltar no outono)
date-fns quando nenhuma matemática de zona for necessária (durações, dias úteis em UTC)

Exemplo de Trabalho

// 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(`slot inválido: ${local.invalidReason}`);
  }
  return local.toUTC().toISO()!;
}
 
export function nextBillingRunUtc(
  anchorUtc: string,
  customerZone: string
): string {
  const local = DateTime.fromISO(anchorUtc, { zone: "utc" }).setZone(customerZone);
  // Cobrar às 00:05 local no dia 1º
  const next = local.plus({ months: 1 }).startOf("month").set({
    hour: 0,
    minute: 5,
    second: 0,
    millisecond: 0,
  });
  return next.toUTC().toISO()!;
}

// API: sempre retorne UTC + dica de exibição 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,
  };
});

Regras do banco de dados:

Postgres: timestamptz para instantes; text ou date apenas quando verdadeiramente local do calendário
Nunca armazene abreviações "EST" - use IANA America/New_York
Tarefas Cron: documente a zona na definição da tarefa e no runbook

Divisão de Bibliotecas

Tarefa	Biblioteca	Exemplo
Conversão de zona IANA	Luxon	`setZone("Europe/Berlin")`
Agendamento seguro contra DST	Luxon	`plus({ months: 1 })` na zona
Dias úteis (UTC)	date-fns	`addBusinessDays`
Duração entre datas	date-fns	`differenceInMinutes`
Formato para logs	Luxon	`toISO()` sempre UTC

Novos serviços podem usar apenas Luxon e pular date-fns para reduzir sobreposição.
Não adicione moment - API não mantida e mutável.

Antipatterns

// ERRADO: analisa como zona local do servidor
new Date("2026-07-09 09:00:00");
 
// ERRADO: EST é ambíguo (EST vs EDT)
const tz = "EST";
 
// CERTO: offset explícito ou IANA
DateTime.fromISO("2026-07-09T09:00:00-05:00");
DateTime.now().setZone("America/Chicago");

FAQs

Apenas Luxon ou date-fns também?

Como testar as bordas do horário de verão?

Datas de fixture: segundo domingo de março e primeiro domingo de novembro para zonas dos EUA. Afirme a saída UTC, não as strings formatadas.

JavaScript Date em APIs?

Serializar strings ISO 8601 em JSON, não objetos Date (eles se tornam strings UTC de qualquer maneira). Documente que os consumidores da API devem enviar offset ou Z.

Relacionados

Noções Básicas de Bibliotecas Essenciais - uma biblioteca por preocupação
Agendamento e Cron - trabalhos repetíveis com zonas
zod - valide strings de datetime nas fronteiras

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

date-fns / Luxon

Buscar na documentação

date-fns / Luxon