@orafavictor/date-difference-calculator 1.0.0

package/index.js

@@ -0,0 +1,30 @@
+function calculateTimeDifference(targetDate) {
+    const currentDate = new Date();
+    const futureDate = new Date(targetDate);
+
+    if (isNaN(targetDate)){
+        throw new Error("Invalid date format");
+    }
+
+    if (futureDate <= currentDate) {
+        return {error: 'Date provided is in the past'};
+    }
+
+    const differenceInMillis = futureDate - currentDate;
+
+    const differenceInMinutes = Math.floor(differenceInMillis / (1000 * 60));
+    const differenceInHours = Math.floor(differenceInMillis / (1000 * 60 * 60));
+    const days = Math.floor(differenceInMinutes / (60 * 24));
+    const hours = Math.floor(differenceInMinutes % (60 * 24) / 60);
+    const minutes = Math.floor(differenceInMinutes % 60);
+    const seconds = Math.floor((differenceInMillis % (1000 * 60)) / 1000);
+
+    return {
+        days,
+        hours,
+        minutes,
+        seconds
+    }
+}
+
+module.exports = {calculateTimeDifference};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@orafavictor/date-difference-calculator",
+  "version": "1.0.0",
+  "description": "A library to calculate the time difference between the curretn date and a provided date.",
+  "license": "ISC",
+  "author": "Rafael Victor",
+  "type": "commonjs",
+  "main": "index.js",
+  
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+    },
+  "keywords": [
+      "date", 
+      "difference", 
+      "calculator", 
+      "time", 
+      "days", 
+      "hours", 
+      "minutes", 
+      "seconds"
+    ]
+}

package/readme.md

@@ -0,0 +1,116 @@
+# Date Difference Calculator
+
+Uma biblioteca leve e prática para calcular a diferença de tempo exata entre o momento atual e uma data futura. Ideal para criar contagens regressivas (countdowns), verificar prazos ou calcular tempo restante em dias, horas, minutos e segundos.
+
+## 📋 Índice
+
+- [Instalação](#instalação)
+- [Como Usar](#como-usar)
+- [Funcionalidades](#funcionalidades)
+- [API](#api)
+- [Tratamento de Erros](#tratamento-de-erros)
+- [Autor](#autor)
+- [Licença](#licença)
+
+## 🚀 Instalação
+
+Para instalar este pacote no seu projeto, execute o seguinte comando no terminal:
+
+```bash
+npm install date-difference-calculator
+
+💻 Como Usar
+A biblioteca exporta uma função principal chamada calculateTimeDifference. Você deve importar a função e passar a data alvo (futura) como argumento.
+
+Aqui está um exemplo básico de como implementar:
+
+JavaScript
+const { calculateTimeDifference } = require('date-difference-calculator');
+
+// Defina uma data futura (Ex: Ano Novo de 2026)
+// Recomendamos passar um objeto Date ou um timestamp
+const targetDate = new Date('2026-01-01T00:00:00');
+
+try {
+    const timeRemaining = calculateTimeDifference(targetDate);
+    
+    // Verifica se houve erro de data no passado
+    if (timeRemaining.error) {
+        console.log("Atenção:", timeRemaining.error);
+    } else {
+        console.log(`Faltam: 
+        ${timeRemaining.days} dias, 
+        ${timeRemaining.hours} horas, 
+        ${timeRemaining.minutes} minutos e 
+        ${timeRemaining.seconds} segundos.`);
+    }
+} catch (err) {
+    console.error("Erro na data:", err.message);
+}
+✨ Funcionalidades
+Cálculo Preciso: Retorna a diferença quebrada em dias, horas, minutos e segundos.
+
+Validação de Data: Verifica se a data fornecida é válida.
+
+Verificação de Passado: Identifica se a data alvo já passou e retorna uma mensagem amigável ao invés de números negativos.
+
+📚 API
+calculateTimeDifference(targetDate)
+
+Calcula o tempo restante até a targetDate.
+
+Parâmetros
+
+Parâmetro	Tipo	Descrição
+targetDate	Date	Number
+Retorno
+
+Retorna um Objeto contendo os seguintes campos:
+
+JavaScript
+{
+  days: number,    // Dias restantes
+  hours: number,   // Horas restantes (0-23)
+  minutes: number, // Minutos restantes (0-59)
+  seconds: number  // Segundos restantes (0-59)
+}
+Caso a data seja no passado, o retorno será:
+
+JavaScript
+{
+  error: 'Date provided is in the past'
+}
+⚠️ Tratamento de Erros
+A função lançará um erro (throw Error) se o formato da data for inválido (por exemplo, algo que não seja uma data ou número). Recomenda-se envolver a chamada da função em um bloco try...catch ou garantir que o input seja um objeto Date válido.
+
+👤 Autor
+Rafael Victor
+
+Sinta-se à vontade para contribuir ou reportar problemas!
+
+📄 Licença
+Este projeto está sob a licença ISC.
+
+
+---
+
+### 💡 Dica Técnica (Opcional)
+
+Notei um detalhe interessante no seu código no arquivo `index.js`:
+
+```javascript
+if (isNaN(targetDate)){
+    throw new Error("Invalid date format");
+}
+A função isNaN funciona bem para números e objetos Date, mas se o usuário tentar passar uma string diretamente (ex: "2025-12-25"), o isNaN retornará true e vai dar erro, mesmo a string sendo uma data válida.
+
+Sugestão de melhoria para a versão 1.0.1: Se você quiser aceitar strings diretamente no futuro, você pode ajustar a validação para verificar a data depois de convertê-la:
+
+JavaScript
+// Exemplo de ajuste:
+const futureDate = new Date(targetDate);
+
+// Valida se a data criada é válida (Date inválido vira "Invalid Date", que é NaN em valor numérico)
+if (isNaN(futureDate.getTime())) { 
+    throw new Error("Invalid date format");
+}