datetime-toolkit

Lightweight datetime utilities for Node.js — zero dependencies.

Installation

npm install datetime-toolkit

Quick start

const {
  now, format, relative, countdown,
  addDays, diffDays, businessDays,
  startOfWeek, endOfMonth, isWeekend,
  age, weekNumber, configure,
} = require('datetime-toolkit');

configure({ locale: 'en-GB', timezone: 'Europe/London' });

console.log(now());                          // "2025-06-03T14:00:00.000Z"
console.log(format(new Date()));             // "3 Jun 2025, 14:00"
console.log(relative('2025-01-01'));         // "5 months ago"
console.log(countdown('2026-01-01'));        // { days: 212, hours: 10, ... }
console.log(businessDays('2025-06-01', '2025-06-30')); // 21

Configuration

configure(opts)

Set defaults used by format(), relative(), and other locale-aware functions.

configure({
  locale:   'fr-FR',           // any BCP 47 locale tag
  timezone: 'Europe/Paris',    // any IANA timezone name
});

API

Core

| Function | Returns | Description | |---|---|---| | now() | string | Current datetime as ISO 8601 | | timestamp() | number | Current Unix time in ms | | parse(str) | Date \| null | Safe parse — null on invalid input |

Formatting

format(date, options?, locale?)

Formats a date using Intl.DateTimeFormat. Respects configure() defaults.

format(new Date())
// "Jun 3, 2025, 2:00 PM"

format(new Date(), { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
// "Tuesday, June 3, 2025"

format(new Date(), { dateStyle: 'full' }, 'ja-JP')
// "2025年6月3日火曜日"

relative(date, locale?)

Human-readable relative time using Intl.RelativeTimeFormat.

relative('2025-01-01')          // "5 months ago"
relative('2027-06-01')          // "in 2 years"
relative(new Date())            // "now"
relative('2025-01-01', 'de-DE') // "vor 5 Monaten"

formatDuration(ms)

Format a duration in milliseconds as a readable string.

formatDuration(3_661_000)  // "1h 1m 1s"
formatDuration(90_000)     // "1m 30s"
formatDuration(500)        // "0s"

elapsed(from)

Milliseconds since a given date.

elapsed('2025-01-01') // 13219320000

countdown(date)

Countdown object to a future date. All values are 0 if the date is past.

countdown('2026-01-01')
// { total: 18345600000, days: 212, hours: 10, minutes: 40, seconds: 0 }

Arithmetic

addSeconds(date, n)   // ± seconds
addMinutes(date, n)   // ± minutes
addHours(date, n)     // ± hours
addDays(date, n)      // ± days
addWeeks(date, n)     // ± weeks
addMonths(date, n)    // ± months (clamps to end of month)
addYears(date, n)     // ± years

addDays(new Date(), 7)     // one week from now
addMonths(new Date(), -1)  // one month ago
addYears('2020-02-29', 1)  // 2021-02-28  ← clamps correctly

Boundaries

startOfDay(date)             // 00:00:00.000
endOfDay(date)               // 23:59:59.999
startOfWeek(date, startDay?) // defaults to Sunday (0); pass 1 for Monday
endOfWeek(date, startDay?)
startOfMonth(date)           // 1st of the month, midnight
endOfMonth(date)             // last day of the month, 23:59:59.999
startOfYear(date)            // Jan 1, midnight
endOfYear(date)              // Dec 31, 23:59:59.999

Comparison

isBefore(a, b)              // a < b
isAfter(a, b)               // a > b
isBetween(date, start, end) // start ≤ date ≤ end
isSameDay(a, b)             // same calendar day
isWeekend(date)             // Saturday or Sunday
isWeekday(date)             // Monday – Friday

Difference

diffDays(a, b?)

Whole-day difference between two dates (a − b). Defaults b to today.

diffDays('2025-12-31')          // days until New Year's Eve
diffDays('2025-06-10', '2025-06-01') // 9

businessDays(from, to)

Count Monday–Friday days between two dates (inclusive).

businessDays('2025-06-01', '2025-06-30') // 21

Calendar helpers

| Function | Description | |---|---| | daysInMonth(date) | Number of days in the month | | isLeapYear(yearOrDate) | Leap year check | | weekNumber(date?) | ISO week number (1–53) | | age(birthdate) | Age in whole years | | nextWeekday(date, weekday) | Next occurrence of a weekday (0=Sun … 6=Sat) |

daysInMonth('2024-02-01')      // 29
isLeapYear(2024)               // true
weekNumber()                   // 23
age('1990-06-03')              // 35
nextWeekday(new Date(), 1)     // next Monday

License

ISC