Chronos Date

A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.

Quick Start

import { Chronos, chronos } from 'chronos-date';

// Using the constructor
const now = new Chronos();
console.log(now.format('dd, mmm DD, YYYY')); 

// Using the function wrapper
const tomorrow = chronos().addDays(1);
console.log(tomorrow.formatSafe('YYYY-MM-DD'));

// Calculate differences
const eventDate = new Chronos('2025-12-31');
console.log(now.diff(eventDate, 'day')); // Days until event

// Using utils
import { addDate, getDaysInMonth } from 'chronos-date/utils';

const final = addDate(new Date(), { day: 1, hour: '7' });

console.log(final);

console.log(getDaysInMonth('2024-02')); // 29

Why Chronos?

In ancient Greek mythology, Chronos is the primordial embodiment of time — not merely tracking moments, but defining their very existence. Like its mythological namesake, the Chronos class offers precise, immutable, and expressive control over time within your application.

Designed to go beyond the native Date object, it empowers you to manipulate, format, compare, and traverse time with clarity, reliability, and confidence — all while staying immutable and framework-agnostic.

Key Features

• Immutability: Every modification returns a new Chronos instance. Your original dates remain intact.
• Rich API: From formatting to comparison, calculation, and detailed part extraction.
• Plugin System: Extend core capabilities seamlessly using Chronos.use(plugin). Over a dozen official plugins exist for advanced operations like business hours, seasons, zodiacs, relative times, and more.
• Time Zone Support: Advanced formatting and tracking of UTC offsets and Native time zone properties.
• Date Utilities: Extra utilities, type guards, types and constants for light weight date operations without the need of core class.
• TypeScript IntelliSense: Built with first-class TypeScript types and TSDoc documentation for better IDE support and autocompletion.
• Cross-environment compatibility: Works anywhere JS runs (Node.js, Browser, Deno, Bun).

Installation

npm install chronos-date
# or
yarn add chronos-date
# or
pnpm add chronos-date

Modular Imports

You can import specific submodules for better tree-shaking:

// Guards
import { isValidDateInput } from "chronos-date/guards";

// Utility functions
import { formatDate } from "chronos-date/utils";

// Type definitions
import type { ChronosInput } from "chronos-date/types";

// Constants
import { MONTHS } from "chronos-date/constants";

// Plugins (imported individually)
import { timeZonePlugin } from "chronos-date/plugins/timeZonePlugin";
import { seasonPlugin } from "chronos-date/plugins/seasonPlugin";
// All plugin imports share the same pattern
import { pluginName } from "chronos-date/plugins/pluginName";

Documentation

For full documentation, API reference, and interactive playgrounds, visit the Documentation Site.

🔗 Related Packages

License

This project is licensed under the Apache License 2.0 with the following additional requirement:

Additional Requirement:

Any fork, derivative work, or redistribution of this project must include clear attribution to Nazmul Hassan in both the source code and any publicly available documentation.

You are free to use, modify, and distribute this project under the terms of the Apache 2.0 License, provided that appropriate credit is given.

Built with ❤️ by Nazmul Hassan