Validador de Marco Temporal (ISO 8601)

Marco temporal: ancorar um instante em um unico inteiro

Um marco temporal (ou Unix timestamp / epoch) e o numero de unidades (tipicamente segundos, milissegundos, microssegundos ou nanossegundos) decorridas desde a epoca 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 cabecalhos 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. Exibicao 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 digitos e a forma mais facil de detectar a unidade (regra da magnitude). Por volta de 2024 as fronteiras sao:

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

Deteccao de magnitude em pseudo-codigo: 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 validacao

Um validador de timestamp robusto combina duas checagens:

• Sintatica — inteiro (ou string de digitos), opcionalmente negativo. Regex: /^-?\d+$/.
• Semantica / sanidade — a data resultante deve cair em uma janela plausivel (ex.: 1970-2100). Rejeite valores de 12 digitos como 123456789012, que nao sao segundos nem ms validos.

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 ate 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 varios formatos de arquivo.

Mitigacoes em producao hoje:

• time_t de 64 bits — padrao na glibc desde a 2.34 em ARM 32, no kernel Linux via CONFIG_64BIT_TIME a partir da 5.6, e padrao 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 ate o ano 294276.
• JavaScript / Java / Python — ja sao 64 bits, sem correcao necessaria.

Timestamps vs ISO 8601 vs RFC 3339

• Timestamp (inteiro) — compacto, inequivoco, dificil 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 nao RFC 3339.

Timestamps negativos funcionam: -867844800 e o lancamento da Apollo 11 (1969-07-16T13:32:00Z), cerca de 6 meses antes da epoca. Alguns sistemas legados nao 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 classico bug "1:30 da manha acontece duas vezes". O Brasil aboliu o horario de verao em 2019, entao 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 estavel para aplicacoes novas — mas dados legados de 1985-2019 ainda carregam as regras antigas no tzdata da IANA.

Conversao 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 precisao de relogio

Um timestamp e tao bom quanto o relogio que o produziu. O NTP (Network Time Protocol) mantem servidores a poucos milissegundos do UTC; o chrony e o substituto moderno do ntpd legado no Linux, com melhor recuperacao apos 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 precisao 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 — conversao 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 estao 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 precisao acima de 2^53, entao use BigInt para nanossegundos.

Leap seconds sao contados?

A epoca Unix classica 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, nao uma contagem estrita.

Um timestamp pode ser negativo?

Sim — valores anteriores a 1970-01-01 sao negativos. Bibliotecas modernas aceitam, mas C legado, TIMESTAMP do MySQL e muitos formatos de planilha nao. Se voce guarda datas historicas (nascimentos pre-1970, geologia, historia), prefira strings ISO 8601.