Luxon

Luxon is a modern JavaScript library for working with dates, times, durations, and intervals. Built by a Moment.js maintainer, it offers an immutable, chainable API and relies on the platform’s native Intl support for time zones and localization, so there are no locale or time-zone data files to bundle.

It models the domain with distinct DateTime, Duration, Interval, and Info types, handles invalid values gracefully through a sentinel pattern rather than exceptions, and covers parsing and formatting for ISO, RFC 2822, HTTP, SQL, and custom token formats.

What You Get

• Immutable DateTime, Duration, and Interval types with a fluent, chainable API
• Native IANA time-zone support via the Intl API, with no bundled tz data
• Parsing and formatting for ISO 8601, RFC 2822, HTTP, SQL, and custom token formats
• Locale-aware formatting and human-readable relative time using Intl
• A graceful invalid-value model that avoids throwing on bad input

Common Use Cases

• Parsing and reformatting API timestamps across time zones
• Displaying localized, human-friendly dates and relative times in UIs
• Computing durations, differences, and calendar math between events
• Scheduling logic that must respect a specific IANA time zone
• Migrating away from the legacy, mutable Moment.js API

Under The Hood

Architecture Luxon centers on four public types exported from src/luxon.js: DateTime (src/datetime.js), Duration (src/duration.js), Interval (src/interval.js), and the Info metadata facade (src/info.js). A Zone abstraction (src/zone.js) has concrete implementations for fixed offsets, IANA zones, the system zone, and an invalid zone under src/zones/. The heavy lifting lives in src/impl/, which separates concerns into a formatter, regexParser and tokenParser, calendar conversions (gregorian/week/ordinal), diff, locale, and shared util helpers, keeping the public types thin over well-isolated internals.

Tech Stack The library is written in plain ES-module JavaScript with no runtime dependencies, leaning entirely on the platform Intl object for time-zone resolution and localization. It is transpiled with Babel and bundled with Rollup into ES6 (build/es6/luxon.mjs) and CommonJS (build/node/luxon.js) outputs via the tasks in tasks/. Testing uses Jest with coverage, and formatting is enforced with Prettier through lint-staged and Husky hooks.

Code Quality The repository carries a substantial test suite of roughly 60 spec files under test/, mirroring the source layout (datetime, duration, interval, zones, impl). Error handling is deliberate: rather than throwing on bad input, operations produce ‘invalid’ sentinel values, with a small hierarchy of LuxonError subclasses in src/errors.js reserved for genuine misuse. Naming is consistent and the immutable design keeps functions pure and easy to reason about.

API Design The public API is a strong point: it is immutable and chainable, so expressions like DateTime.now().setZone('America/New_York').minus({ weeks: 1 }).endOf('day').toISO() read naturally. Method names are consistent and unambiguous, getting started requires almost no boilerplate, and the project ships extensive guides and generated API docs. TypeScript users consume separately published @types/luxon definitions rather than bundled types.