A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.
npm install chronos-ts




Chronos-ts โ named after the Greek god of time โ is a comprehensive TypeScript library for date and time manipulation. Version 2.0 is a complete rewrite inspired by Carbon PHP, bringing modern, intuitive date handling to TypeScript and JavaScript.
> [!WARNING]
> This is a major rewrite (v2.0) and is not backward compatible with v1.x. Please refer to the migration guide for details.
- ๐ฏ Intuitive API โ Fluent, chainable methods for all date operations
- ๐
Immutable by Default โ All operations return new instances
- ๐ Timezone Support โ Built-in timezone handling with DST awareness
- ๐ Internationalization โ Extensible locale system with human-readable output
- โฑ๏ธ Intervals โ Powerful duration/interval handling (like CarbonInterval)
- ๐ Periods โ Date range iteration with filtering and transformations
- ๐ Period Collections โ Manage and analyze multiple date periods easily
- ๐ Type-Safe โ Full TypeScript support with comprehensive types
- ๐ชถ Zero Dependencies โ No external runtime dependencies
``bash
npm install chronos-ts
๐ Quick Start
`typescript
import { Chronos, ChronosInterval, ChronosPeriod } from 'chronos-ts';// Create dates
const now = Chronos.now();
const birthday = Chronos.create(1990, 6, 15);
const parsed = Chronos.parse('2024-03-15T10:30:00');
// Manipulate dates
const nextWeek = now.addWeeks(1);
const lastMonth = now.subtractMonths(1);
const startOfDay = now.startOf('day');
// Format dates
console.log(now.format('YYYY-MM-DD HH:mm:ss')); // "2024-03-15 14:30:45"
console.log(now.diffForHumans(birthday)); // "33 years ago"
// Work with intervals
const interval = ChronosInterval.create({ hours: 2, minutes: 30 });
console.log(interval.forHumans()); // "2 hours 30 minutes"
// Iterate over periods
const thisMonth = ChronosPeriod.thisMonth();
for (const day of thisMonth) {
console.log(day.format('YYYY-MM-DD'));
}
`๐ API Reference
For detailed documentation on all classes and methods, please refer to the API Reference.
$3
- Chronos: The main class for date/time manipulation.
- ChronosInterval: Represents a duration of time.
- ChronosPeriod: Represents a date range or schedule.
- ChronosPeriodCollection: Manages collections of periods.
- ChronosTimezone: Timezone utilities.
---
๐ Localization
Chronos-ts includes built-in support for English and Spanish, with an extensible locale system.
`typescript
import { Chronos, registerLocale, getLocale } from 'chronos-ts';// Use built-in locale
const date = Chronos.now().locale('es');
date.format('dddd, D [de] MMMM [de] YYYY');
// "viernes, 15 de marzo de 2024"
// Human-readable in Spanish
date.diffForHumans(Chronos.yesterday());
// "hace 1 dรญa"
// Register custom locale
registerLocale({
code: 'de',
months: ['Januar', 'Februar', 'Mรคrz', 'April', 'Mai', 'Juni',
'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'],
monthsShort: ['Jan', 'Feb', 'Mรคr', 'Apr', 'Mai', 'Jun',
'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez'],
weekdays: ['Sonntag', 'Montag', 'Dienstag', 'Mittwoch',
'Donnerstag', 'Freitag', 'Samstag'],
weekdaysShort: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
weekdaysMin: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
relativeTime: {
future: 'in %s',
past: 'vor %s',
s: 'wenigen Sekunden',
ss: '%d Sekunden',
m: 'einer Minute',
mm: '%d Minuten',
h: 'einer Stunde',
hh: '%d Stunden',
d: 'einem Tag',
dd: '%d Tagen',
M: 'einem Monat',
MM: '%d Monaten',
y: 'einem Jahr',
yy: '%d Jahren',
},
});
`---
๐ง Configuration
`typescript
import { Chronos } from 'chronos-ts';// Set global configuration
Chronos.configure({
defaultTimezone: 'America/New_York',
defaultLocale: 'en',
});
// Set test/mock time (useful for testing)
Chronos.setTestNow(Chronos.create(2024, 1, 1));
const now = Chronos.now(); // Returns 2024-01-01
// Reset test time
Chronos.setTestNow(null);
`---
๐ Real-World Examples
$3
`typescript
import { Chronos, ChronosPeriod, ChronosInterval } from 'chronos-ts';// Conference dates
const conference = {
start: Chronos.create(2024, 6, 15, 9, 0),
end: Chronos.create(2024, 6, 17, 18, 0),
};
// Check if a session conflicts
const session = Chronos.create(2024, 6, 16, 14, 0);
const isDuringConference = session.isBetween(conference.start, conference.end);
// Create weekly recurring meeting
const meetings = ChronosPeriod
.create(
Chronos.now(),
Chronos.now().addMonths(3),
{ weeks: 1 }
)
.filter(date => date.dayOfWeek === 1) // Mondays only
.toArray();
`$3
`typescript
import { Chronos, ChronosInterval } from 'chronos-ts';class Subscription {
constructor(
public startDate: Chronos,
public interval: ChronosInterval
) {}
get nextBillingDate(): Chronos {
return this.startDate.add(this.interval);
}
isActive(): boolean {
return Chronos.now().isBefore(this.nextBillingDate);
}
daysUntilRenewal(): number {
return this.nextBillingDate.diffInDays(Chronos.now());
}
}
const monthly = new Subscription(
Chronos.now(),
ChronosInterval.months(1)
);
console.log(
Days until renewal: ${monthly.daysUntilRenewal()});
`$3
`typescript
import { Chronos, ChronosPeriod } from 'chronos-ts';// Get working days this month
const workingDays = ChronosPeriod
.thisMonth()
.filterWeekdays()
.toArray();
console.log(
Working days this month: ${workingDays.length});// Calculate hours worked
const clockIn = Chronos.create(2024, 3, 15, 9, 0);
const clockOut = Chronos.create(2024, 3, 15, 17, 30);
const hoursWorked = clockOut.diffInHours(clockIn);
const overtime = Math.max(0, hoursWorked - 8);
console.log(
Hours worked: ${hoursWorked});
console.log(Overtime: ${overtime});
`$3
`typescript
import { Chronos } from 'chronos-ts';function getAge(birthDate: Chronos): { years: number; months: number; days: number } {
const now = Chronos.now();
return {
years: now.diffInYears(birthDate),
months: now.diffInMonths(birthDate) % 12,
days: now.diffInDays(birthDate.addYears(now.diffInYears(birthDate))) % 30,
};
}
const birthday = Chronos.create(1990, 6, 15);
const age = getAge(birthday);
console.log(
Age: ${age.years} years, ${age.months} months, ${age.days} days);
`---
๐งช Testing
`typescript
import { Chronos } from 'chronos-ts';describe('MyFeature', () => {
beforeEach(() => {
// Freeze time for consistent tests
Chronos.setTestNow(Chronos.create(2024, 1, 15, 12, 0, 0));
});
afterEach(() => {
// Reset to real time
Chronos.setTestNow(null);
});
it('should calculate correct deadline', () => {
const deadline = Chronos.now().addDays(30);
expect(deadline.format('YYYY-MM-DD')).toBe('2024-02-14');
});
});
`---
๐ Comparison with Other Libraries
| Feature | Chronos-ts | Day.js | Moment.js | date-fns |
|---------|-----------|--------|-----------|----------|
| Immutable | โ
| โ
| โ | โ
|
| TypeScript | โ
Native | Plugin | Plugin | โ
Native |
| Tree-shakeable | โ
| โ
| โ | โ
|
| Intervals | โ
| Plugin | โ
| โ |
| Periods | โ
| โ | โ | โ |
| Timezones | โ
| Plugin | Plugin | โ
|
| Zero deps | โ
| โ
| โ | โ
|
| API Style | Fluent | Fluent | Fluent | Functional |
---
๐ค Contributing
Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md for guidelines.
`bash
Clone the repository
git clone https://github.com/hendurhance/chronos-ts.gitInstall dependencies
npm installRun tests
npm testBuild
npm run build
``---
This project is licensed under the MIT License โ see the LICENSE file for details.
---
- Carbon PHP โ Primary API inspiration
- Day.js โ Immutability patterns
- Moment.js โ Format string patterns
- Period - Complex period comparisons
---
Made with โค๏ธ by the Chronos-ts team