https://github.com/nazmul-nhb/chronos-date
A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.
https://github.com/nazmul-nhb/chronos-date
bangla-date bangla-date-time calendar chronos date date-time immutable timezone
Last synced: about 1 month ago
JSON representation
A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.
- Host: GitHub
- URL: https://github.com/nazmul-nhb/chronos-date
- Owner: nazmul-nhb
- License: apache-2.0
- Created: 2026-05-10T15:54:10.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-17T19:09:38.000Z (about 2 months ago)
- Last Synced: 2026-05-17T20:52:47.813Z (about 2 months ago)
- Topics: bangla-date, bangla-date-time, calendar, chronos, date, date-time, immutable, timezone
- Language: TypeScript
- Homepage: https://chronos.nazmul-nhb.dev
- Size: 1.49 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [Chronos Date](https://chronos.nazmul-nhb.dev/)
> A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.
[](https://chronos.nazmul-nhb.dev/)
## 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
```sh
npm install chronos-date
# or
yarn add chronos-date
# or
pnpm add chronos-date
```
---
## Quick Start
```ts
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
```
---
## Modular Imports
You can import specific submodules for better tree-shaking:
```ts
// 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**](https://chronos.nazmul-nhb.dev/).
---
## 🔗 Related Packages
---
## License
This project is licensed under the [Apache License 2.0](LICENSE) with the following additional requirement:
**Additional Requirement:**
> Any fork, derivative work, or redistribution of this project must include clear attribution to [**Nazmul Hassan**](https://github.com/nazmul-nhb) 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**](https://nazmul-nhb.dev)