Calculate Time Difference

A lightweight JavaScript utility to calculate the remaining time between the current date and a future date.

The function returns the difference in days, hours and minutes.

Installation

Install the package using npm:

npm install calculate-time-difference

Usage

CommonJS

const { CalculateTimeDifference } = require("calculate-time-difference");

const result = CalculateTimeDifference("2026-12-31T23:59:00");

console.log(result);

Output:

{
  days: 121,
  hours: 1,
  minutes: 34
}

ES Modules

import { CalculateTimeDifference } from "calculate-time-difference";

const result = CalculateTimeDifference("2026-12-31T23:59:00");

console.log(result);

Function

CalculateTimeDifference(targetDate)

Parameters

| Parameter | Type | Description | | ------------ | ---------------- | ------------------------------------------------ | | targetDate | string \| Date | The future date to compare with the current date |

The date should be provided in a format supported by JavaScript's Date constructor.

Examples:

"2026-12-31T23:59:00"

or:

new Date("2026-12-31T23:59:00")

Return

When the target date is valid and in the future, the function returns:

{
  days: Number,
  hours: Number,
  minutes: Number
}

Example:

{
  days: 5,
  hours: 8,
  minutes: 32
}

If the provided date is in the past, the function returns:

{
  error: "The date provided is in the past"
}

Example

const { CalculateTimeDifference } = require("calculate-time-difference");

const countdown = CalculateTimeDifference("2027-01-01T00:00:00");

if (countdown.error) {
  console.log(countdown.error);
} else {
  console.log(
    `${countdown.days} days, ${countdown.hours} hours and ${countdown.minutes} minutes remaining`
  );
}

Use Cases

This package can be useful for:

• Countdown timers
• Event countdowns
• Deadline tracking
• Task management applications
• Date-based notifications
• Simple time remaining calculations

Requirements

• Node.js 14 or higher

License

MIT

### Author

Developed as a simple and lightweight utility for JavaScript applications.

**Uma observação importante no seu código:** tem um pequeno bug nessa validação:

```js
if (isNaN(targetDate)) {

O correto seria validar o futureDate:

if (isNaN(futureDate.getTime())) {
    throw new Error("Invalid format date");
}

Porque targetDate pode ser uma string válida, e isNaN(targetDate) não é a forma adequada de verificar se o Date criado é válido.

Também corrigiria diffInMilles para diffInMillis — é só nomenclatura, mas deixa o pacote mais profissional.