ChronoKit

ChronoKit is a lightweight, TypeScript-first date and time library for JavaScript, Node.js, and modern bundlers. Use it to convert between time zones, handle Daylight Saving Time (DST), do date arithmetic (add/subtract days, weeks, months…), calculate the difference between two dates, compare and validate dates, and produce human-friendly output like "3 days ago" — with a simple, consistent, string-first API.

It's a focused convenience layer over Luxon, so timezone and DST math is correct, while ChronoKit gives you a smaller, task-oriented surface. Ships as both ESM and CommonJS with full TypeScript types and JSDoc on every function.

Why ChronoKit?

• 🧩 Simple, consistent API — every function takes a flexible date input and returns a plain string, number, or boolean. No wrapper objects to learn.
• 🌍 Timezone & DST correct — powered by Luxon and the IANA database.
• 🪶 Small & tree-shakeable — import only the functions you use; moment is gone.
• 🧠 TypeScript-first — typed inputs/outputs and inline docs your editor (and AI assistants) can read.
• 📦 ESM + CommonJS — works with import and require.

Table of contents

• Installation
• Quick start
• Common tasks
• API reference
• Migrating from v1

Installation

npm i chronokit

Quick start

import { convertTimeZone, addTime, diff, fromNow } from "chronokit";

convertTimeZone("2026-02-23T14:55:00Z", "UTC", "Australia/Darwin");
// → "2026-02-24 00:25:00"

addTime("2026-01-31", 1, "month"); // clamps month-end
// → "2026-02-28T00:00:00.000+…"

diff("2026-07-14", "2026-07-10", "day"); // → 4

fromNow("2000-01-01"); // → "26 years ago"

Every function accepts a flexible DateInput: an ISO 8601 string, a SQL-style "yyyy-MM-dd HH:mm:ss" string, a JS Date, a millisecond timestamp, or a Luxon DateTime.

Common tasks

Recipes for the things people reach for a date library to do.

Convert a date/time between time zones

import { convertTimeZone } from "chronokit";
convertTimeZone("2026-06-15 09:00", "America/New_York", "Asia/Tokyo");
// → "2026-06-15 22:00:00"

Get the difference between two dates

import { diff } from "chronokit";
diff("2026-12-25", "2026-07-14", "day");   // → 164
diff("2026-07-14T18:00", "2026-07-14T09:00", "hour"); // → 9

Add or subtract time

import { addTime, subtractTime } from "chronokit";
addTime("2026-07-14", 3, "week");       // 3 weeks later
subtractTime("2026-07-14", 6, "month"); // 6 months earlier

Show relative / "time ago" strings

import { fromNow, timeUntil } from "chronokit";
fromNow("2026-07-10");     // → "4 days ago"
timeUntil("2026-12-25");   // → "in 5 months"

Check for Daylight Saving Time

import { isDST } from "chronokit";
isDST("2026-07-01", "America/New_York"); // → true
isDST("2026-01-01", "America/New_York"); // → false

Validate a date or time zone

import { isValidDate, isValidTimeZone } from "chronokit";
isValidDate("2026-02-30");        // → false
isValidTimeZone("Asia/Colombo");  // → true

Calculate an age

import { getAge } from "chronokit";
getAge("2000-07-14", "2026-07-14"); // → 26

API reference

Time zones & DST

| Function | Description | | --- | --- | | convertTimeZone(dateTime, fromZone, toZone, format?) | Convert between IANA zones; returns yyyy-MM-dd HH:mm:ss by default. | | convertDateTime(dateTime, fromZone, toZone) | Convert between zones, keeping the target UTC offset in the output. | | getTimeZoneOffset(zoneA, zoneB) | Absolute offset difference as an ISO 8601 duration (e.g. PT5H30M). | | formatInTimeZone(dateTime, zone, format?) | Format an instant as it appears in a zone. | | isDST(dateTime, zone?) | Whether the instant is in Daylight Saving Time. | | listTimeZones() | All IANA zone names supported by the runtime. | | guessUserTimeZone() | The caller's current IANA zone. | | isValidTimeZone(zone) | Whether a string is a valid IANA zone. |

getTimeZoneOffSet (old spelling) remains as a deprecated alias.

Arithmetic

| Function | Description | | --- | --- | | addTime(dateTime, amount, unit) | Add a duration; returns an ISO 8601 string. | | subtractTime(dateTime, amount, unit) | Subtract a duration. | | performDateArithmetic(dateTime, { duration, unit, operation }) | Add/subtract via an options object. | | diff(a, b, unit?, whole?) | Difference a − b in unit (default "day"). | | startOf(dateTime, unit) / endOf(dateTime, unit) | Snap to the start/end of a unit. |

unit is one of year, month, week, day, hour, minute, second. operation is add or subtract.

Comparison & validation

isBefore(a, b) · isAfter(a, b) · isSame(a, b, unit?) · isBetween(dateTime, start, end, { inclusive? }) · isValidDate(input)

Calendar

isLeapYear(yearOrDate) · daysInMonth(yearOrDate, month?) · getWeekNumber(dateTime) · getDayOfYear(dateTime) · isWeekend(dateTime) · isWeekday(dateTime)

Human-friendly

fromNow(dateTime) · timeUntil(dateTime) · humanizeDuration(msOrObject) · getAge(birthDate, at?) · countdown(target)

Migrating from v1

v2 replaces moment with Luxon. The main breaking change:

• performDateArithmetic no longer takes/returns a Moment object. It now accepts any DateInput and returns an ISO 8601 string:

  // v1
  performDateArithmetic(moment("2026-02-25"), { duration: 2, unit: "week", operation: "add" });
  // v2
  performDateArithmetic("2026-02-25", { duration: 2, unit: "week", operation: "add" });
  // → "2026-03-11T00:00:00.000+…"

Development

npm install     # install dependencies
npm test        # run the Vitest suite
npm run build   # build CJS + ESM + types with tsup

Contributing

Contributions are welcome! Fork the repository, make your changes, and submit a pull request. Please include tests for any new functionality.