Date Difference Calculator

A lightweight and easy-to-use JavaScript library for calculating the difference between dates, supporting multiple time units and customizable output formats.

Features

• Calculate time differences in various units (years, months, days, hours, minutes, seconds)
• Support for custom date formats
• Zero dependencies
• TypeScript support
• Handles timezone differences
• Lightweight (~2KB minified)

Installation

npm install date-difference-calculator
# or
yarn add date-difference-calculator

Usage

import { calculateDateDifference } from 'date-difference-calculator';

// Basic usage
const difference = calculateDateDifference('2024-01-01', '2024-02-15');
console.log(difference.days); // Output: 45

// With specific units
const customDifference = calculateDateDifference('2024-01-01', '2025-06-15', {
  units: ['years', 'months', 'days']
});
console.log(customDifference);
// Output: { years: 1, months: 5, days: 14 }

// Using Date objects
const date1 = new Date('2024-01-01');
const date2 = new Date('2024-12-31');
const result = calculateDateDifference(date1, date2);

API Reference

calculateDateDifference(startDate, endDate, options?)

Returns the difference between two dates.

Parameters

• startDate (Date | string): The starting date
• endDate (Date | string): The ending date
• options (object, optional): Configuration options
  • units (array): Array of desired units ['years', 'months', 'days', 'hours', 'minutes', 'seconds']
  • format (string): Output format ('object' | 'string')
  • timezone (string): Specific timezone for calculations

Returns

Returns either an object with time units or a formatted string, depending on options.

Examples

// Get difference in multiple units
const diff = calculateDateDifference('2023-01-01', '2024-06-15', {
  units: ['years', 'months', 'days']
});
// Output: { years: 1, months: 5, days: 14 }

// Get formatted string output
const formatted = calculateDateDifference('2023-01-01', '2024-06-15', {
  format: 'string'
});
// Output: "1 year, 5 months, 14 days"

// Working with specific timezones
const tzDiff = calculateDateDifference('2024-01-01T00:00:00', '2024-01-02T00:00:00', {
  timezone: 'America/New_York'
});

Error Handling

The library throws clear error messages for invalid inputs:

try {
  const diff = calculateDateDifference('invalid-date', '2024-01-01');
} catch (error) {
  console.error(error.message); // "Invalid date format provided"
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.