ts-datetime

A modern, immutable, and fully-typed TypeScript datetime library inspired by Carbon (PHP) and Day.js.

Features

• 🔄 Immutable API All operations return new instances
• ⛓️ Fluent Interface Chainable, readable, and expressive
• 🌍 Locale Support Global, per-instance, and per-call configuration
• 📅 Robust Parsing ISO, timestamps, relative strings (e.g. "next week", "+2 days")
• ⏱️ Intervals & Periods Built-in support for durations and date ranges
• 💪 TypeScript First Fully typed, with great DX in modern editors
• ✅ Tested Thoroughly tested for edge cases and correctness

Installation

# npm
npm install @stacksjs/ts-datetime

# pnpm
pnpm add @stacksjs/ts-datetime

# yarn
yarn add @stacksjs/ts-datetime

# bun
bun add @stacksjs/ts-datetime

Quick Examples

import { Datetime, DatetimeInterval, DatetimePeriod } from 'ts-datetime'

// Creating dates
const now = Datetime.now()
const tomorrow = Datetime.tomorrow()
const specificDate = new Datetime('2024-01-01T12:00:00Z')

// Manipulation
const nextWeek = now.addDays(7)
const lastMonth = now.subMonths(1)

// Formatting
console.log(specificDate.format('YYYY-MM-DD')) // "2024-01-01"
console.log(now.diffForHumans()) // "just now"

// Intervals
const interval = DatetimeInterval.days(5).add(DatetimeInterval.hours(12))
console.log(interval.forHumans()) // "5 days 12 hours"

// Periods (date ranges)
const period = new DatetimePeriod(
  new Datetime('2024-01-01'),
  new Datetime('2024-01-10'),
  DatetimeInterval.days(2)
)

// Iterate over period
for (const date of period) {
  console.log(date.format('YYYY-MM-DD'))
}
// 2024-01-01, 2024-01-03, 2024-01-05, 2024-01-07, 2024-01-09

Documentation

For full documentation, visit ts-datetime.netlify.app.

• Introduction
• Installation
• Usage
• Configuration

Feature Documentation

• Immutable API
• Formatting
• Intervals
• Periods
• Human Diffs
• Relative Strings

Advanced Topics

• Localization
• Type Safety
• Performance
• Testing

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• Carbon - The inspiration for this library.
• Day.js - A lightweight alternative to Moment.js.

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙