Ao recuperar dados para um período selecionado, percebemos que nosso cálculo estava errado por alguma margem. No entanto, quando diminuímos a data em um dia, os dados corresponderam exatamente!

Hmmm… Pode haver um problema com a forma como a data está sendo tratada em nosso código. Talvez o fuso horário não esteja sendo tratado corretamente – e sim, eu estava certo!

Ao criar aplicativos que envolvem usuários de fusos horários diferentes, lidar adequadamente com datas pode ser complicado. Armazenar datas em UTC é uma prática recomendada comum para garantir consistência, mas as coisas podem ficar complicadas quando os usuários inserem datas em seu fuso horário local, especialmente durante a filtragem e consulta.

Os desenvolvedores geralmente recorrem ao objeto JavaScript Date nativo para lidar com essas conversões. No entanto, essa abordagem pode levar a inconsistências entre ambientes, como Node.js e consoles de navegador como o Chrome. Neste artigo, exploraremos por que lidar adequadamente com conversões de data e fuso horário é crucial, como Luxon pode tornar esse processo mais fácil e por que confiar no objeto JavaScript nativo Date pode levar a inconsistências.

O problema: armazenamento UTC versus filtragem de horário local

Quando as datas são armazenadas em UTC, elas representam um padrão global que elimina a ambiguidade causada pelos fusos horários. No entanto, os usuários normalmente pensam em termos de seu fuso horário local. Essa discrepância fica evidente quando os usuários tentam filtrar os registros por data usando entradas de hora local.

Vejamos um exemplo em que as entradas de horário local de um usuário podem levar à perda de registros se não forem tratadas corretamente.

Cenário de exemplo: um usuário no fuso horário GMT-7

Imagine um usuário no fuso horário GMT-7 (horário de verão do Pacífico). Em 5 de setembro de 2024, eles criaram um registro às 22h no horário local. Aqui está o que acontece nos bastidores:

• 5 de setembro de 2024, 22h GMT-7 é convertido em 6 de setembro de 2024, 05h UTC e armazenado no banco de dados como tal.
• O usuário, porém, percebe que criou este registro em 5 de setembro.

A incompatibilidade do filtro

Agora, suponha que o usuário queira consultar todos os registros criados em 5 de setembro. Eles inserem a data 5 de setembro de 2024, esperando recuperar seu registro. No entanto, se o sistema comparar a data de entrada diretamente com a data UTC armazenada sem ajustar as diferenças de fuso horário, o usuário perderá o registro. Por que?

• O registro foi salvo no banco de dados como 6 de setembro (UTC).
• O usuário filtra por 5 de setembro (horário local), mas o sistema compara isso com o UTC, resultando em nenhuma correspondência.

Objeto de data JavaScript: inconsistências entre ambientes

O código de exemplo a seguir demonstra um problema comum ao usar o objeto JavaScript Date nativo para lidar com conversões de data e hora, especialmente em diferentes ambientes, como Node.js e o navegador (por exemplo, console do Chrome).

Código de exemplo:

function convertToUtcStartOfDay(isoString) {
  // Step 1: Parse the ISO string into a Date object
  let localDate = new Date(isoString);

  // Step 2: Set the time to the start of the day (00:00:00) in local time zone
  localDate.setHours(0, 0, 0, 0);

  // Step 3: Get the UTC time using toISOString() – it converts local time to UTC
  let utcStartOfDay = localDate.toISOString();

  return utcStartOfDay; // This will be in UTC
}

// Example usage:
let frontendDate = "2023-08-22T00:00:00 05:30"; // ISO string with timezone offset
let startOfDayUtc = convertToUtcStartOfDay(frontendDate);

console.log(startOfDayUtc); // Expected output: "2023-08-21T18:30:00.000Z"

Neste exemplo, o usuário insere a data "2023-08-22T00:00:00 05:30" (de um fuso horário GMT 5:30). O objeto Date deve convertê-lo para o início do dia em UTC, mas quando executado:

• Em Node.js, a saída é 2023-08-21T00:00:00.000Z - Errado
• No console do Chrome, a saída é 2023-08-21T18:30:00.000Z - Correto

Essa discrepância pode causar resultados imprevisíveis dependendo de onde o código é executado. Esse comportamento torna o objeto Date não confiável para manipulação consistente de datas em diferentes ambientes.

Usando Luxon para tratamento preciso de datas

Para resolver esse problema, é importante usar uma biblioteca como Luxon que fornece comportamento consistente em todos os ambientes. Luxon ajuda você a converter a entrada local do usuário para o início e fim do dia em seu fuso horário e, em seguida, converter esses horários para UTC para consultas precisas ao banco de dados.

Aqui está um exemplo usando Luxon para lidar com isso:

const { DateTime } = require('luxon');

// Example user input date in ISO string with timezone information from the frontend
const userInputDate = "2023-08-22T00:00:00 05:30"; // ISO string sent by frontend

// Step 1: Parse the ISO string to get the user's local time
const userLocalDate = DateTime.fromISO(userInputDate);

// Step 2: Convert this date to start of the day and end of the day in the user's local timezone
const startOfDayLocal = userLocalDate.startOf('day'); // start of the day in the user's timezone
const endOfDayLocal = userLocalDate.endOf('day'); // end of the day in the user's timezone

// Step 3: Convert these local start and end times to UTC
const startOfDayUtc = startOfDayLocal.toUTC().toJSDate(); // start of the day in UTC
const endOfDayUtc = endOfDayLocal.toUTC().toJSDate(); // end of the day in UTC

// Step 4: Query the database using the UTC range
db.records.find({
  createdAt: {
    $gte: startOfDayUtc,
    $lte: endOfDayUtc
  }
});

Por que Luxon é melhor que objetos de data JavaScript

Tratar conversões de data e fuso horário diretamente com o objeto JavaScript Date nativo pode levar a inconsistências como a demonstrada acima. Aqui estão alguns motivos pelos quais Luxon é uma alternativa melhor:

1. Consistência entre ambientes: Luxon fornece comportamento consistente quer o código esteja sendo executado em Node.js ou no navegador (por exemplo, console do Chrome). Isso elimina as discrepâncias que surgem do uso do objeto Date em ambientes diferentes.

2. Suporte integrado de fuso horário: Luxon facilita a conversão entre fusos horários, enquanto o objeto Date não oferece suporte robusto para manipulação de fuso horário.

3. Manipulação Simples de Data: Definir o início ou fim de um dia no fuso horário local do usuário e convertê-lo para UTC é uma tarefa comum em aplicações globais. Luxon simplifica esse processo com sua API intuitiva, enquanto Date requer manuseio manual complexo.

Conclusão

O tratamento adequado das conversões de data e fuso horário é crucial para a construção de aplicativos confiáveis ​​e fáceis de usar. Se os desenvolvedores não levarem em conta as diferenças de fuso horário ao filtrar os registros, os usuários poderão perder dados importantes, causando confusão e erros potencialmente críticos.

Usar Luxon em vez do JavaScript Date object nativo fornece consistência, melhor manipulação de fuso horário e manipulação mais fácil de datas. Isso permite que os desenvolvedores criem uma experiência perfeita para usuários em todos os fusos horários, garantindo que as consultas funcionem conforme o esperado e que nenhum registro seja perdido durante a filtragem.

Em aplicativos globais, o tratamento preciso e confiável de datas é fundamental para oferecer uma experiência de alta qualidade aos usuários, independentemente do fuso horário.

Considerações Finais

Você já encontrou uma situação semelhante em que o tratamento de data e fuso horário causou resultados inesperados em seu aplicativo? Como você abordou isso? Eu adoraria ouvir sobre suas experiências, comentários ou quaisquer dúvidas ou preocupações que você possa ter. Sinta-se à vontade para compartilhá-los na seção de comentários abaixo. Se você achou este artigo útil, curta e compartilhe-o com outras pessoas que possam se beneficiar dele!