Validador de Marco Temporal (ISO 8601)

Marco temporal: ancorar um instante em um único inteiro

Um marco temporal (ou Unix timestamp / epoch) e o número de unidades (tipicamente segundos, milissegundos, microssegundos ou nanossegundos) decorridas desde a época Unix: meia-noite UTC de 1970-01-01. E a forma mais compacta e independente de linguagem de representar um instante, e por isso domina bancos de dados, logs, sistemas distribuidos e cabeçalhos de protocolo. Este validador checa marcos bem formados e ajuda a identificar a unidade (s/ms/us/ns) automaticamente.

Diferente de strings ISO 8601, um timestamp e inequivoco: e sempre UTC, sem fuso e sem DST a interpretar. Exibição e responsabilidade de quem consome — guarde o inteiro, renderize a hora local na borda. A desvantagem: um timestamp e opaco para humanos, e a unidade errada desloca silenciosamente o valor em 3, 6 ou 9 ordens de grandeza.

Variantes: segundos, milissegundos, microssegundos, nanossegundos

Em 2024 a quantidade de dígitos e a forma mais fácil de detectar a unidade (regra da magnitude). Por volta de 2024 as fronteiras são:

• Segundos (10 dígitos) — 1700000000 = 2023-11-14T22:13:20Z. Usado pelo Unix time(2), Postgres EXTRACT(EPOCH FROM ts), Linux, MySQL UNIX_TIMESTAMP().
• Milissegundos (13 dígitos) — 1700000000000. JavaScript Date.now(), Java System.currentTimeMillis(), Kafka.
• Microssegundos (16 dígitos) — 1700000000000000. timestamp interno do Postgres, Python datetime.timestamp() * 1e6.
• Nanossegundos (19 dígitos) — 1700000000000000000. Go time.UnixNano(), Prometheus interno, traces do OpenTelemetry.

Detecção de magnitude em pseudo-código: if (ts < 1e10) segundos; else if (ts < 1e13) ms; else if (ts < 1e16) us; else ns; — funciona para todo valor realista entre ~2001 e ~2286.

Regras de validação

Um validador de timestamp robusto combina duas checagens:

• Sintatica — inteiro (ou string de dígitos), opcionalmente negativo. Regex: /^-?\d+$/.
• Semântica / sanidade — a data resultante deve cair em uma janela plausivel (ex.: 1970-2100). Rejeite valores de 12 dígitos como 123456789012, que não são segundos nem ms válidos.

function detectUnit(n) {
  if (n < 1e10) return 's';
  if (n < 1e13) return 'ms';
  if (n < 1e16) return 'us';
  return 'ns';
}

O problema Y2038

Um inteiro de 32 bits com sinal so conta até 2^31 - 1 = 2147483647. Esse valor como segundo Unix e 2038-01-19T03:14:07Z — o momento em que sistemas Unix de 32 bits viram pra 1901. E o Y2K moderno, e afeta dispositivos embarcados, firmware de IoT, colunas TIMESTAMP antigas do MySQL, inodes ext3, pacotes NTP e vários formatos de arquivo.

Mitigacoes em produção hoje:

• time_t de 64 bits — padrão na glibc desde a 2.34 em ARM 32, no kernel Linux via CONFIG_64BIT_TIME a partir da 5.6, e padrão em todos os sistemas 64 bits.
• MySQL — troque TIMESTAMP por DATETIME, que armazena o ano literal.
• Postgres — usa microssegundos de 64 bits internamente e e seguro até o ano 294276.
• JavaScript / Java / Python — ja são 64 bits, sem correção necessária.

Timestamps vs ISO 8601 vs RFC 3339

• Timestamp (inteiro) — compacto, inequivoco, difícil de ler. Ideal para armazenamento e protocolos.
• ISO 8601 — string longa e humana, suporta fusos, duracoes e intervalos.
• RFC 3339 — subconjunto estrito do ISO 8601 usado por protocolos de Internet. 2024-03-15T10:30:00Z e RFC 3339; 2024-W11-5 e ISO 8601 mas não RFC 3339.

Timestamps negativos funcionam: -867844800 e o lançamento da Apollo 11 (1969-07-16T13:32:00Z), cerca de 6 meses antes da época. Alguns sistemas legados não aceitam valores negativos — cuidado.

DST, fusos e o caso especial do Brasil

Um timestamp e sempre UTC. Exibir exige fuso, e transicoes de DST causam o clássico bug "1:30 da manha acontece duas vezes". O Brasil aboliu o horário de verão em 2019, então o BRT e hoje fixo em UTC-3 o ano todo (o Acre fica em UTC-5). Isso torna America/Sao_Paulo um fuso bem estável para aplicações novas — mas dados legados de 1985-2019 ainda carregam as regras antigas no tzdata da IANA.

Conversão em linguagens diferentes

// JavaScript (ms)
new Date(1700000000000).toISOString();

// Python (s)
from datetime import datetime, timezone
datetime.fromtimestamp(1700000000, tz=timezone.utc)

// Go (ns)
time.Unix(0, 1700000000000000000).UTC()

// SQL (Postgres)
SELECT to_timestamp(1700000000);

// shell
date -u -d @1700000000

NTP e precisão de relógio

Um timestamp e tão bom quanto o relógio que o produziu. O NTP (Network Time Protocol) mantém servidores a poucos milissegundos do UTC; o chrony e o substituto moderno do ntpd legado no Linux, com melhor recuperacao após suspend/resume. Provedores cloud oferecem NTP gerenciado (AWS Time Sync, Google Public NTP) e high-frequency trading usa PTP (Precision Time Protocol, classe RFC 5905) para precisão sub-microssegundo.

FAQ

Guardar segundos ou milissegundos?

Depende da plataforma. Ecossistemas JavaScript gravitam para ms porque Date.now() retorna ms. Ecossistemas backend Unix/Postgres preferem segundos. Seja consistente dentro de um mesmo sistema — conversão silenciosa de unidade e o bug mais comum.

Y2038 ainda e um risco real?

Sim, principalmente em firmware embarcado, controladores industriais, medidores inteligentes e colunas TIMESTAMP antigas do MySQL que nunca migraram. SOs modernos de 64 bits estão bem, mas a cauda longa legada e grande.

Como converto um timestamp em ms no JavaScript?

new Date(ms). Para segundos, multiplique por 1000 antes: new Date(s * 1000). Para ns, divida por 1e6 — mas Numbers em JavaScript perdem precisão acima de 2^53, então use BigInt para nanossegundos.

Leap seconds são contados?

A época Unix clássica ignora leap seconds — trata todo dia como 86400 segundos. E uma simplificacao deliberada; o leap second real e "smeared" pelo Google Public NTP e pelo AWS Time Sync para evitar a anomalia 23:59:60. O tempo POSIX e, portanto, uma aproximacao do UTC, não uma contagem estrita.

Um timestamp pode ser negativo?

Sim — valores anteriores a 1970-01-01 são negativos. Bibliotecas modernas aceitam, mas C legado, TIMESTAMP do MySQL e muitos formatos de planilha não. Se você guarda datas históricas (nascimentos pre-1970, geologia, história), prefira strings ISO 8601.