Validando Datas Formatadas em ISO em JavaScript - Tutorial

Introdução

Neste laboratório, exploraremos como determinar se uma determinada string é uma string de data válida no formato ISO estendido simplificado (ISO 8601). Usaremos o construtor Date e seus métodos associados para criar um objeto Date a partir da string e verificar sua validade. Ao final do laboratório, você terá uma melhor compreensão de como trabalhar com datas em JavaScript e como validá-las usando o formato ISO.

Compreendendo o Formato de Data ISO e Objetos Date do JavaScript

Antes de começarmos a codificar, vamos entender o que é o formato de data ISO 8601 e como o JavaScript lida com datas.

O Formato de Data ISO 8601

O formato ISO 8601 é um padrão internacional para representar datas e horas. O formato ISO estendido simplificado se parece com isto:

YYYY-MM-DDTHH:mm:ss.sssZ

Onde:

YYYY representa o ano (quatro dígitos)
MM representa o mês (dois dígitos)
DD representa o dia (dois dígitos)
T é um caractere literal que separa a data e a hora
HH representa as horas (dois dígitos)
mm representa os minutos (dois dígitos)
ss representa os segundos (dois dígitos)
sss representa os milissegundos (três dígitos)
Z indica o fuso horário UTC (Tempo Zulu)

Por exemplo, 2023-05-12T14:30:15.123Z representa 12 de maio de 2023, às 14:30:15.123 UTC.

O Objeto Date do JavaScript

O JavaScript fornece um objeto Date embutido para trabalhar com datas e horas. Quando você cria um novo objeto Date, pode passar uma string formatada em ISO para ele:

const date = new Date("2023-05-12T14:30:15.123Z");

Vamos abrir o terminal e praticar o trabalho com objetos Date:

Abra o Terminal clicando no menu Terminal na parte superior do WebIDE
Digite node e pressione Enter para iniciar o shell interativo do Node.js
Crie um novo objeto Date para a hora atual:

const now = new Date();
console.log(now);

Converta este objeto Date em uma string ISO:

const isoString = now.toISOString();
console.log(isoString);

Você deve ver uma saída semelhante a:

2023-05-12T14:30:15.123Z

Crie uma Date a partir de uma string ISO:

const dateFromIso = new Date("2023-05-12T14:30:15.123Z");
console.log(dateFromIso);

Isso demonstra como o JavaScript pode analisar e criar objetos Date a partir de strings formatadas em ISO.

Criando uma Função para Validar Strings de Data Formatadas em ISO

Nesta etapa, criaremos uma função JavaScript que verifica se uma determinada string está em formato ISO 8601 válido.

Criando a Função de Validação

Vamos criar um novo arquivo JavaScript para nosso validador de data ISO:

No WebIDE, clique no ícone Explorer na barra lateral esquerda
Clique com o botão direito no explorador de arquivos e selecione "Novo Arquivo"
Nomeie o arquivo isISODate.js e pressione Enter
Adicione o seguinte código ao arquivo:

/**
 * Checks if a string is a valid ISO 8601 formatted date string
 * @param {string} val - The string to check
 * @return {boolean} - Returns true if the string is in ISO format, false otherwise
 */
const isISOString = (val) => {
  // Create a Date object from the input string
  const d = new Date(val);

  // Check if the date is valid (not NaN) and if the ISO string matches the original
  return !Number.isNaN(d.valueOf()) && d.toISOString() === val;
};

// Export the function so we can use it elsewhere
module.exports = isISOString;

Vamos examinar como esta função funciona:

new Date(val) cria um objeto Date a partir da string de entrada
d.valueOf() retorna o valor numérico do timestamp (milissegundos desde 1º de janeiro de 1970)
Number.isNaN(d.valueOf()) verifica se a data é inválida (NaN significa "Not a Number")
d.toISOString() === val verifica se a conversão da Date de volta para uma string ISO corresponde à entrada original

Testando Nossa Função

Agora, vamos criar um arquivo de teste simples para testar nossa função:

Crie outro arquivo chamado testISO.js
Adicione o seguinte código:

// Import our isISOString function
const isISOString = require("./isISODate");

// Test with a valid ISO formatted date
console.log("Testing a valid ISO date:");
console.log("2020-10-12T10:10:10.000Z");
console.log("Result:", isISOString("2020-10-12T10:10:10.000Z"));
console.log();

// Test with an invalid format
console.log("Testing a non-ISO date:");
console.log("2020-10-12");
console.log("Result:", isISOString("2020-10-12"));

Execute o arquivo de teste usando Node.js:

node testISO.js

Você deve ver uma saída semelhante a:

Testing a valid ISO date:
2020-10-12T10:10:10.000Z
Result: true

Testing a non-ISO date:
2020-10-12
Result: false

Isso mostra que nossa função identifica corretamente que "2020-10-12T10:10:10.000Z" é uma data formatada em ISO válida, enquanto "2020-10-12" não é.

Testando com Vários Formatos de Data

Agora que temos nossa função de validação básica, vamos testá-la com diferentes formatos de data para entender como ela se comporta com várias entradas.

Criando um Conjunto de Testes

Vamos criar um conjunto de testes abrangente para examinar diferentes formatos de data:

Crie um novo arquivo chamado dateTester.js
Adicione o seguinte código:

// Import our isISOString function
const isISOString = require("./isISODate");

// Function to test different date strings
function testDate(description, dateString) {
  console.log(`Testing: ${description}`);
  console.log(`Input: "${dateString}"`);
  console.log(`Is ISO Format: ${isISOString(dateString)}`);
  console.log("-----------------------");
}

// Valid ISO date examples
testDate("Standard ISO date with timezone Z", "2023-05-12T14:30:15.123Z");
testDate("ISO date with zero milliseconds", "2020-10-12T10:10:10.000Z");

// Invalid or non-ISO format examples
testDate("Date only (no time component)", "2023-05-12");
testDate("Date and time without milliseconds", "2023-05-12T14:30:15Z");
testDate(
  "Date with time zone offset instead of Z",
  "2023-05-12T14:30:15+01:00"
);
testDate("Invalid date (month 13 does not exist)", "2023-13-12T14:30:15.123Z");
testDate("Non-date string", "Hello World");

Execute o conjunto de testes no terminal:

node dateTester.js

Você deve ver a saída mostrando quais strings são datas ISO válidas e quais não são.

Compreendendo os Resultados

Vamos analisar o que torna cada caso de teste válido ou inválido:

2023-05-12T14:30:15.123Z - Isso é válido porque segue o formato ISO 8601 completo com o indicador de fuso horário UTC (Z).
2020-10-12T10:10:10.000Z - Isso também é válido, com os milissegundos explicitamente definidos como 000.
2023-05-12 - Esta é uma data válida, mas não no formato ISO porque está faltando o componente de tempo.
2023-05-12T14:30:15Z - Isso parece ser formato ISO, mas está faltando os milissegundos, que são necessários no formato ISO estrito.
2023-05-12T14:30:15+01:00 - Isso usa um deslocamento de fuso horário (+01:00) em vez de 'Z'. Embora isso seja válido de acordo com o ISO 8601, nossa função requer o formato exato produzido por toISOString(), que sempre usa 'Z'.
2023-13-12T14:30:15.123Z - Esta é uma data inválida (o mês 13 não existe), então new Date() criará um objeto Date inválido.
Hello World - Isso não é uma data, então new Date() criará um objeto Date inválido.

Nossa função de validação verifica especificamente duas condições:

A string deve ser analisada para uma data válida (não NaN)
Quando essa data é convertida de volta para uma string ISO, ela deve corresponder exatamente à entrada original

Essa abordagem garante que estamos validando o formato ISO exato produzido pelo método toISOString() do JavaScript.

Lidando com Casos Extremos e Melhorando Nossa Função

Nesta etapa final, melhoraremos nossa função isISOString para lidar com casos extremos e torná-la mais robusta.

Casos Extremos Comuns

Ao validar dados em aplicações reais, você precisa lidar com várias entradas inesperadas. Vamos examinar alguns casos extremos:

Strings vazias
Valores não-string (null, undefined, números, objetos)
Diferentes representações de fuso horário

Aprimorando Nossa Função

Vamos atualizar nosso arquivo isISODate.js para lidar com esses casos extremos:

Abra o arquivo isISODate.js no WebIDE
Substitua o código existente por esta versão aprimorada:

/**
 * Checks if a string is a valid ISO 8601 formatted date string
 * @param {string} val - The string to check
 * @return {boolean} - Returns true if the string is in ISO format, false otherwise
 */
const isISOString = (val) => {
  // Check if input is a string
  if (typeof val !== "string") {
    return false;
  }

  // Check if string is empty
  if (val.trim() === "") {
    return false;
  }

  try {
    // Create a Date object from the input string
    const d = new Date(val);

    // Check if the date is valid and if the ISO string matches the original
    return !Number.isNaN(d.valueOf()) && d.toISOString() === val;
  } catch (error) {
    // If any error occurs during validation, return false
    return false;
  }
};

// Export the function
module.exports = isISOString;

Esta função aprimorada agora:

Verifica se a entrada é uma string antes de processar
Lida com strings vazias
Usa um bloco try-catch para lidar com quaisquer erros que possam ocorrer
Ainda executa nossa lógica de validação principal

Testando Nossa Função Aprimorada

Vamos criar um arquivo de teste final para verificar nossa função aprimorada com casos extremos:

Crie um novo arquivo chamado edgeCaseTester.js
Adicione o seguinte código:

// Import our improved isISOString function
const isISOString = require("./isISODate");

// Function to test and display results
function testCase(description, value) {
  console.log(`Testing: ${description}`);
  console.log(`Input: ${value === "" ? "(empty string)" : value}`);
  console.log(`Type: ${typeof value}`);
  console.log(`Is ISO Format: ${isISOString(value)}`);
  console.log("-----------------------");
}

// Test with various edge cases
testCase("Valid ISO date", "2023-05-12T14:30:15.123Z");
testCase("Empty string", "");
testCase("Null value", null);
testDate("Undefined value", undefined);
testCase("Number value", 12345);
testCase("Object value", {});
testCase("Current date as ISO string", new Date().toISOString());

Execute o arquivo de teste:

node edgeCaseTester.js

Aplicação no Mundo Real

Em uma aplicação real, nossa função isISOString pode ser usada em cenários como:

Validar a entrada do usuário em um campo de data
Verificar datas recebidas de APIs externas
Garantir um formato de data consistente em um banco de dados
Validação de dados antes do processamento

Por exemplo, em uma função de validação de formulário:

function validateForm(formData) {
  // Other validations...

  if (formData.startDate && !isISOString(formData.startDate)) {
    return {
      valid: false,
      error: "Start date must be in ISO format"
    };
  }

  // More validations...

  return { valid: true };
}

A função aprimorada agora é robusta o suficiente para lidar com entradas inesperadas e fornecer validação confiável para strings de data formatadas em ISO.

Resumo

Neste laboratório, você aprendeu como validar se uma string está no formato ISO estendido simplificado (ISO 8601). Aqui está o que você realizou:

Aprendeu sobre o formato de data ISO 8601 e sua estrutura
Entendeu como os objetos Date do JavaScript funcionam com strings formatadas em ISO
Criou uma função para validar se uma string está no formato ISO exato
Testou a função com vários formatos de data
Melhorou a função para lidar com casos extremos e torná-la mais robusta

Essa habilidade é particularmente útil ao trabalhar com APIs, bancos de dados ou qualquer sistema onde a formatação consistente de datas seja importante. O formato ISO 8601 é amplamente utilizado porque evita ambiguidades e fornece uma maneira padronizada de representar datas e horas.

Principais conclusões deste laboratório:

O formato ISO 8601 segue um padrão específico: YYYY-MM-DDTHH:mm:ss.sssZ
O método Date.prototype.toISOString() do JavaScript sempre gera datas nesse formato
Validar datas requer verificar tanto a validade quanto o formato
O tratamento adequado de erros torna as funções de validação mais robustas

Agora você pode aplicar esse conhecimento para construir aplicações mais confiáveis que lidam corretamente com dados de data e hora.

String é Data Formatada em ISO