Conversor de Timestamp Unix para Data

Segundos, milissegundos e tudo abaixo disso

O tempo Unix é definido em segundos. O Date do JavaScript trabalha em milissegundos. Quase todo bug de data numa base de código mista começa nessa fronteira.

Os sintomas são fáceis de reconhecer quando você os conhece. Um valor em segundos entregue a algo que espera milissegundos cai na madrugada de 1º de janeiro de 1970 - se uma data na sua interface aparece como 1970, praticamente sempre o motivo é esse. Um valor em milissegundos lido como segundos cai por volta do ano 55.000, o que normalmente é percebido, mas nem sempre, porque há código de exibição que o mostra sem reclamar.

A unidade aqui é deduzida pela quantidade de dígitos, uma heurística, mas previsível e explicável: um timestamp atual tem 10 dígitos em segundos, 13 em milissegundos, 16 em microssegundos e 19 em nanossegundos, e as faixas não se sobrepõem para nenhuma data com que alguém trabalhe de verdade. A unidade escolhida é exibida, não presumida, e você pode trocá-la. Timestamps em microssegundos aparecem no Postgres e em traces do Chrome; em nanossegundos, no Go, no Prometheus e no InfluxDB. Valores em nanossegundos passam do que um número JavaScript representa com exatidão, então a conversão é feita com BigInt.

O que um timestamp não contém

Um timestamp Unix é um instante e nada mais. Não carrega fuso horário, deslocamento nem calendário. Duas pessoas lendo o mesmo timestamp em Tóquio e em Lisboa estão olhando para o mesmo momento e vão anotar corretamente horários locais diferentes, o que é uma vantagem: um instante não tem ambiguidade, algo que um horário local nunca consegue.

A consequência é que um timestamp não diz que dia era localmente, e convertê-lo em data exige escolher um fuso. É por isso que toda saída aqui traz o fuso, sempre com UTC ao lado do seu horário local para comparar diretamente.

Isso também significa que um timestamp é a forma errada de guardar algo intrinsecamente local. Uma reunião recorrente às 9h, um aniversário, o horário de funcionamento de uma loja: são horários locais ligados a um fuso e a um conjunto de regras, e guardá-los como instantes os quebra na próxima vez que o deslocamento do fuso mudar. Guarde o horário local e o nome do fuso, e calcule o instante quando precisar.

Segundos bissextos

O tempo Unix é definido como se todo dia tivesse exatamente 86.400 segundos. A Terra não colabora, então segundos bissextos são inseridos no UTC para mantê-lo alinhado à rotação do planeta - vinte e sete desde 1972.

Como a definição não tem espaço para eles, o tempo Unix trata um segundo bissexto repetindo um valor em vez de acrescentar um. Não existe timestamp Unix que represente o próprio segundo bissexto, e por isso a diferença entre o tempo Unix e o TAI cresceu ao longo das décadas em vez de ficar fixa. Todo código que calcula tempo decorrido subtraindo dois timestamps Unix erra silenciosamente pelo número de segundos bissextos que caíram no intervalo, o que quase nunca importa e às vezes importa muito.

Grandes provedores evitam a descontinuidade com smearing: Google e AWS distribuem o segundo extra por uma janela antes e depois do evento, para que os relógios nunca repitam um valor, ao custo de ficarem levemente atrasados durante um dia. Repare que esses relógios discordam dos que não fazem smearing durante essa janela, algo que vale saber se você compara timestamps entre provedores.

2038 e as outras fronteiras

Um inteiro de 32 bits com sinal se esgota às 03:14:07 UTC de 19 de janeiro de 2038, e o segundo seguinte volta para dezembro de 1901. Tudo o que ainda guarda tempo Unix num campo de 32 bits - sistemas embarcados, formatos de arquivo antigos, colunas de banco nunca ampliadas - falha nesse momento. Por isso timestamps depois dessa data são sinalizados aqui. Armazenamento em 64 bits empurra o limite para muito além da idade do universo e é o que os sistemas atuais usam.

Armazenamento de 32 bits sem sinal move a fronteira para 2106, ao custo de não representar nada antes de 1970. Timestamps negativos funcionam aqui: -86400 é 31 de dezembro de 1969, e datas até o início do calendário gregoriano são convertidas normalmente. O Date do JavaScript tem o próprio teto de 8,64e15 milissegundos para cada lado da época, cerca de 273 mil anos, e valores além disso são informados como fora do intervalo, em vez de aparecerem como Invalid Date.

Os formatos de texto e qual deles emitir

A ISO 8601 é o padrão internacional para escrever datas e horas, e a RFC 3339 é o perfil mais estrito dela que os protocolos da internet adotam. A forma da RFC 3339 - 2026-03-14T09:30:00Z, ou com um deslocamento como +09:00 - é a que você deve emitir de uma API, porque ordena corretamente como texto, não é ambígua e é interpretada em qualquer lugar.

O Z significa UTC, e um deslocamento como +09:00 significa uma diferença fixa em relação a ele. Nenhum dos dois é um fuso horário. Asia/Tokyo é um fuso horário: um conjunto de regras que diz qual é o deslocamento em qualquer data, incluindo o histórico de mudanças. Um deslocamento informa o que o relógio marcava; só o nome do fuso informa quando ele vai marcar aquilo no futuro.

Formatos a evitar nos dados: qualquer um com ano de dois dígitos, qualquer um que use barras, e as datas RFC 2822 dos cabeçalhos de e-mail, que carregam abreviações de fuso já obsoletas. As abreviações são o pior de tudo: CST é Central Standard Time na América do Norte, mas também China Standard Time e Cuba Standard Time, e IST cobre Índia, Irlanda e Israel.

Guardar tempo em um banco de dados

O timestamptz do PostgreSQL é o tipo que a maioria das aplicações realmente quer. Apesar do nome, ele não guarda um fuso: converte a entrada para UTC na escrita e a apresenta no fuso da sessão na leitura, que é exatamente o comportamento desejado para um instante. Já o timestamp simples guarda o texto de relógio de parede que você forneceu, sem fuso nenhum, e comparar dois valores desses vindos de origens diferentes produz um absurdo silencioso.

O DATETIME do MySQL se comporta como o tipo simples, e o TIMESTAMP converte para UTC mas está limitado à faixa de 32 bits que termina em 2038, uma restrição concreta para qualquer sistema que guarde datas futuras. O SQLite não tem tipo de data algum e guarda a convenção que você escolher - normalmente texto ISO 8601 ou um inteiro.

A disciplina que sobrevive a tudo isso é guardar instantes em UTC, converter nas bordas e manter o fuso do usuário em uma coluna separada quando for preciso exibir ou agendar para ele. Quando o valor é de fato um horário local de relógio de parede - o horário de funcionamento de uma loja, uma reunião recorrente às 09:00 -, guarde o horário local e o nome do fuso e calcule o instante na hora em que precisar dele, porque o deslocamento pode mudar por força de lei.

Os relógios discordam, e alguns andam para trás

O relógio de parede de uma máquina é ajustado pelo NTP, o que significa que ele pode saltar para a frente ou recuar. Medir uma duração subtraindo duas leituras desse relógio produz, portanto, tempos negativos de vez em quando e tempos errados com frequência. Os relógios monotônicos existem para isso: só avançam, e são o que performance.now, clock_gettime com CLOCK_MONOTONIC e toda biblioteca de benchmark utilizam.

Entre máquinas o problema é pior, porque dois servidores nunca estão exatamente sincronizados. Ordenar eventos de um sistema distribuído pelos seus carimbos de tempo produz sequências que contradizem a causalidade - uma resposta registrada antes da mensagem que ela responde -, e é por isso que existem relógios lógicos e números de sequência.

Para aplicações comuns o conselho prático é mais modesto: não use um carimbo de tempo como identificador único, não presuma que dois eventos com o mesmo carimbo aconteceram simultaneamente, e conte com uma diferença de pelo menos alguns segundos entre relógios ao comparar qualquer coisa registrada em máquinas diferentes. A validação de tokens admite uma tolerância de desvio exatamente por esse motivo.

Mostrar um horário para uma pessoa

Um instante armazenado precisa ser exibido no fuso de quem lê, no formato da localidade dessa pessoa e no idioma dela. Em JavaScript, a API Intl.DateTimeFormat faz as três coisas a partir das configurações do navegador, e cuida dos detalhes que as pessoas erram quando fazem à mão: nomes de mês no idioma certo, a ordem certa entre dia e mês, e relógio de doze ou vinte e quatro horas conforme a convenção local, não conforme o gosto de quem programa.

Tempos relativos - três horas atrás, em dois dias - são mais simpáticos para eventos recentes e piores para os antigos, já que ninguém consegue fazer nada com um 431 dias atrás. O padrão comum é usar o relativo dentro de um ou dois dias e depois passar para a data absoluta, deixando o carimbo completo disponível ao passar o mouse ou tocar e segurar.

Dois detalhes fazem diferença visível. Exiba as datas no fuso do usuário e não no do servidor, o que significa enviar um instante e formatar no cliente em vez de formatar uma string no servidor. E rotule com o fuso tudo que possa ser ambíguo, porque um horário de reunião sem fuso é a maneira mais confiável de fazer alguém chegar uma hora atrasado.

Datas que não existem e outros casos-limite

Agendar qualquer coisa para as 02:30 em um fuso com horário de verão garante um incidente anual: esse horário não existe na transição da primavera e acontece duas vezes na do outono. Tarefas que precisam rodar exatamente uma vez pertencem ao UTC, ou a um horário fora da janela entre uma e três horas, onde acontecem as transições.

A aritmética de calendário tem suas próprias armadilhas. Somar um mês a 31 de janeiro não tem resposta única, e as bibliotecas divergem entre 28 de fevereiro e 3 de março. Somar 24 horas não é o mesmo que somar um dia quando há uma transição no meio. Anos bissextos exigem a regra completa - divisível por quatro, exceto os séculos, exceto aqueles divisíveis por 400 - e o 29 de fevereiro quebra a lógica de aniversários a cada quatro anos.

E os limites são reais. O tempo em 32 bits com sinal termina em 19 de janeiro de 2038, o que ainda importa para dispositivos embarcados e colunas antigas de banco de dados; o Date do JavaScript cobre cerca de 273.000 anos para cada lado de 1970 e reporta como inválido qualquer coisa além disso. Vale testar os dois se os seus dados incluem datas muito distantes no futuro, como costuma acontecer em sistemas de financiamento imobiliário, previdência e arquivamento.