A robust, type-safe utility for calculating and formatting time differences. timeSince provides a flexible solution for determining elapsed time with support for multiple output formats, internationalization, and precise handling of edge cases like future dates and timezone differences.
- Type-Safe: Written in TypeScript with full type definitions
- Multiple Output Formats: Return elapsed time as:
- Complete breakdown object with years, months, days, etc.
- Single unit values (milliseconds, seconds, days, etc.)
- Human-readable relative strings ("2 days ago", "last year", etc.)
- Internationalization Support: Format relative times in any locale
- Edge Case Handling:
- Future dates with correct time until representation
- Accurate leap year calculations
- Proper timezone handling
- Zero time difference ("now")
- Zero Dependencies: Lightweight with no external dependencies
- 100% Test Coverage: Comprehensive test suite ensures reliability
npm install @risadams/time-sinceyarn add @risadams/time-sincepnpm add @risadams/time-sinceThe library supports both ESM and CommonJS imports.
import { timeSince } from '@risadams/time-since';const { timeSince } = require('@risadams/time-since');The package includes TypeScript type declarations:
import { timeSince } from '@risadams/time-since';
// Types are automatically availableimport { timeSince } from '@risadams/time-since';
// As of May 1, 2025
const result = timeSince('2020-01-01');
console.log(result);
/* Output:
{
date: Date("2020-01-01T00:00:00.000Z"),
asOf: Date("2025-05-01T00:00:00.000Z"),
years: 5,
months: 4,
days: 0,
hours: 0,
minutes: 0,
seconds: 0,
milliseconds: 0
}
*/// Get total milliseconds elapsed
const ms = timeSince('2025-04-30', { format: 'milliseconds' });
console.log(ms); // Output: 86400000 (1 day in milliseconds)
// Get total days elapsed
const days = timeSince('2025-04-01', { format: 'days' });
console.log(days); // Output: 30 (30 days)
// Get total months elapsed
const months = timeSince('2024-05-01', { format: 'months' });
console.log(months); // Output: 12 (12 months)
// Get total years elapsed
const years = timeSince('2020-05-01', { format: 'years' });
console.log(years); // Output: 5 (5 years)// Default locale (English)
const relative = timeSince('2025-04-30', { format: 'relative' });
console.log(relative); // Output: "yesterday"
// Different locales
const french = timeSince('2024-05-01', { format: 'relative', locale: 'fr' });
console.log(french); // Output: "il y a 1 an" (1 year ago)
const spanish = timeSince('2025-04-29', { format: 'relative', locale: 'es' });
console.log(spanish); // Output: "hace 2 días" (2 days ago)
const german = timeSince('2025-03-01', { format: 'relative', locale: 'de' });
console.log(german); // Output: "vor 2 Monaten" (2 months ago)// Future date (June 1, 2025 - 1 month in the future from May 1, 2025)
const futureResult = timeSince('2025-06-01');
console.log(futureResult.months); // Output: 1 (1 month until this date)
// Relative format automatically handles future dates
const futureRelative = timeSince('2025-06-01', { format: 'relative' });
console.log(futureRelative); // Output: "in 1 month"// ISO format
const isoDate = timeSince('2025-04-01T12:00:00Z');
// Short date format
const shortDate = timeSince('4/1/2025');
// Long date format
const longDate = timeSince('April 1, 2025');
// Unix timestamp
const timestamp = timeSince(new Date('2025-04-01').getTime());
// Date object
const dateObj = timeSince(new Date('2025-04-01'));date(Date | string): The starting date from which to calculate elapsed timeoptions(Object, optional): Configuration optionsformat(string, optional): Output format'object'(default): Returns a detailed breakdown object'milliseconds','seconds','minutes','hours','days','months','years': Returns elapsed time in the specified unit'relative': Returns a human-readable string using Intl.RelativeTimeFormat
locale(string, optional): BCP 47 language tag for relative formatting (default: 'en')
- With format='object': A TimeSinceResult object containing date breakdown
- With format='milliseconds', 'seconds', etc.: A number representing elapsed time in that unit
- With format='relative': A localized string representing the relative time
The project includes a comprehensive test suite with 100% code coverage:
# Run tests
npm test
# Run tests with coverage report
npm run test:coverageIf you think this could be better, please open an issue!
Please note that all interactions in this organization fall under our Code of Conduct.
MIT © 1996+ Ris Adams