moment/luxon
github.com/moment/luxon ↗ · 150 files · 850 KB
Luxon [![MIT License][license-image]][license] [![Build Status][github-action-image]][github-action-url] [![NPM version][npm-version-image]][npm-url] [![Coverage Status][test-coverage-image]][test-coverage-url] [![PRs welcome][contributing-image]][contributing
Overview
Luxon 3.7.2 is a JavaScript library for developers who need explicit, immutable APIs for dates, durations, and time intervals. It combines standard and token-based parsing, calendar-aware arithmetic, serialization, and localized formatting with time-zone and locale data supplied by the host's Date and Intl implementations. This brief examines commit f427515a38f6a671f8de663e6bcc040ed81f114e through public source reads; tests, builds, and CI were inspected, not executed.
System map
The main product is an embeddable library whose public entrypoint exports temporal types and configuration APIs. Implementation modules separate parsing, calendar conversion, formatting, locale handling, and zone behavior. Runtime state consists of object fields, global defaults, and caches; serialization returns values to the caller. Build tooling produces several JavaScript distributions, while a separate static site supplies documentation and examples.
- src/luxon.js exports VERSION 3.7.2, DateTime, Duration, Interval, Info, Settings, Zone, and four concrete zone classes.
- The package routes imports to build/es6/luxon.mjs and require calls to build/node/luxon.js; src/package.json independently marks source files as ES modules.
- DateTime coordinates Zone and Locale state, Duration stores unit values and a conversion matrix, and Interval stores two DateTime endpoints.
- Standard parsing uses regex/extractor pairs; custom parsing uses TokenParser; Formatter delegates localized date output through Locale formatter factories.
- The host supplies time-zone behavior: SystemZone reads Date.getTimezoneOffset, while IANAZone validates names and computes offsets using Intl.DateTimeFormat.
- The inspected state boundary is in memory: Settings owns module-level defaults, Locale caches Intl instances, and DateTime exposes JSON/BSON conversion hooks rather than a storage adapter.
- npm build invokes tasks/buildAll.js; buildAll concurrently generates Node, browser CommonJS, ES module, AMD, global, and global-es6 bundles with source maps.
- The static documentation build combines generated API documentation with docs/site copies; benchmarks run ES-module suites, and CI declares build, formatting, coverage-test, and site-generation steps.
Feature catalog
Luxon's user-facing surface is primarily its JavaScript API. DateTime handles construction, parsing, transformations, formatting, and interoperability; Duration models quantities, and Interval models bounded spans. Info exposes locale and zone metadata, while Settings controls defaults and invalid-value policy. The companion site provides searchable guides, API documentation, runnable examples, and a persistent theme preference.
- DateTime.now reads the configured clock; fromObject accepts Gregorian, ordinal, ISO-week, and locale-week fields, rejecting conflicting representations and out-of-range values.
- DateTime supports ISO, RFC 2822, HTTP, SQL, and explicit custom-format parsing; custom parsing also has explain and reusable-parser APIs.
- DateTime formats tokens, localized strings, and localized parts; ISO output supports precision and offset options, while JSON, BSON, numeric timestamps, and native Date provide interoperability.
- DateTime offers zone conversion with optional wall-time preservation, calendar-aware plus/minus, endOf, diff, and relative or relative-calendar descriptions.
- Duration parses ISO quantities and ISO times, performs unit conversion with casual/longterm/custom matrices, and emits human-readable, object, ISO, JSON, or millisecond representations.
- Interval represents half-open spans, accepts endpoint or duration-based construction, supports containment and splitting, and exposes intersection, union, merge, xor, difference, and duration conversion.
- Info exposes localized date labels, IANA-zone validation, DST detection, week-start/weekend metadata, and relative/localeWeek feature detection; Settings supplies defaults and throwOnInvalid.
- The documentation site enables search and sidebar guides, the demo renders API examples, and its dark-theme plugin remembers the selected theme in localStorage.
Data flow
Inputs enter through explicit factories and are normalized into calendar fields, unit quantities, or endpoints. Parsing carries extracted zones separately from date fields before construction resolves defaults, validates data, and computes a timestamp. Transformations create new temporal objects, with calendar arithmetic distinguished from elapsed-time arithmetic. Output methods emit strings, numbers, objects, or native Dates; durable storage remains the caller's responsibility.
- normalizeObject processes own properties, skips null/undefined values, canonicalizes unit names, and coerces numbers; asNumber rejects booleans, empty strings, and non-finite results.
- ISO parsing tries anchored Gregorian, week, ordinal, and time patterns, returning fields and a Zone; parseDataToDateTime interprets in the parsed zone and converts to the requested/default zone unless setZone is true.
- Custom-format input becomes parsed tokens, macro expansions, regex handlers, and matched fields; parseFromTokens forwards result, zone, specificOffset, and invalidReason into DateTime construction.
- fromObject fills omitted higher-order fields from the current/reference date and lower-order fields from defaults, validates the selected calendar, then converts week/ordinal values to Gregorian fields and resolves timestamp/offset.
- DateTime owns ts, zone, locale, calendar fields, offset, validity, and wasHole; clone carries these forward into a new instance and the constructor reuses derived fields when timestamp and zone are unchanged.
- plus/minus normalize duration-like inputs; adjustTime changes calendar fields first, resolves DST, adds residual elapsed milliseconds, and recalculates the offset after that addition.
- Localized output flows through Formatter, Locale.dtFormatter, and cached Intl.DateTimeFormat instances; unsupported fixed/custom zones are represented via shifted UTC Dates and substituted zone-name parts.
- DateTime.toJSON emits ISO text and toBSON emits a native Date; Duration.toJSON emits ISO duration text, while Interval.toISO emits start/end strings, so these paths transfer values without writing application storage.
Behavior traces
These traces follow implementation order from public calls to outputs. Construction and parsing resolve zone, locale, validity, and timestamp before later operations run. Arithmetic revisits zone offsets after calendar and elapsed-time changes, while formatting crosses into native Intl. Serialization supplies a caller-owned persistence boundary; the documentation theme is a separate concrete browser-storage flow.
- Current-time flow: DateTime.now → new DateTime({}) → Settings.defaultZone/normalizeZone → Settings.now → zone.offset → tsToObj → Locale.create, producing an instance with derived calendar fields.
- ISO flow: DateTime.fromISO → parseISODate → parse and its matching extractor → parseDataToDateTime → DateTime.fromObject → objToTS/fixOffset → optional setZone; unmatched input becomes an unparsable DateTime.
- Custom-format flow: fromFormat → Locale.fromOpts(defaultToEN) → parseFromTokens → TokenParser construction → explainFromTokens → parseDataToDateTime; missing arguments throw, while parser-invalid results create an invalid DateTime.
- Calendar-addition flow: plus({days: 1}) → Duration.fromDurationLike → Duration.fromObject → adjustTime → objToLocalTS → fixOffset → clone; adding hours instead contributes elapsed milliseconds after calendar resolution.
- Localized-format flow: toLocaleString → loc.clone → Formatter.create → formatDateTime → Locale.dtFormatter → PolyDateFormatter → getCachedDTF → format; substituted zones use formatToParts and zone.offsetName.
- Interval flow: fromISO splits start/end text → parses start with setZone:true → parseISOIntervalEnd → parseDataToDateTime with start timestamp/zone as context → restores requested zones → fromDateTimes/validateStartEnd; duration alternatives use after or before.
- Serialization flow: DateTime.toJSON → toISO → validity check → precision normalization → toISODate/toISOTime; invalid dates emit null, and restoring ISO text uses fromISO without restoring the original Locale configuration.
- Theme-persistence flow: the Docsify plugin initializes the localStorage preference from matchMedia if absent → hook.init applies it → hook.doneEach installs controls → click invokes applyTheme(true), writes the preference, and changes stylesheet/body state.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. Jest runs in Node with Babel transformation and coverage collection from source files. Inspected suites cover parsing, DST, localization, duration conversion, interval semantics, and selected fallback behavior. This inventory is bounded: browser rendering, published bundle loading, and release behavior are outside the configured source-test scope.
- Jest searches test/, uses the Node environment and babel-jest, loads setupTests.js, and collects src/**/*.js coverage except src/zone.js; these settings were inspected, not run.
- CI declares Ubuntu jobs on Node 20.20.1, 22.22.1, 24.14.0, and 25.8.1 with LANG=en_US.utf8 and TZ=America/New_York, followed by install, build, format-check, coverage tests, and site generation; execution status was not inspected.
- DST tests distinguish fromObject's current-offset overlap choice from local's cached-offset choice and assert gap bumping, wasHole, and arithmetic across transitions.
- Parsing tests assert ISO offset interpretation versus setZone retention, custom token fields and incompatible-input reasons, reusable-parser equivalence, and locale mismatch errors.
- Formatting tests cover output calendars, numbering-system overrides, IANA/fixed/custom zones, and invalid output; locale-week tests assert differing week starts and year-boundary behavior.
- Duration tests distinguish casual and longterm conversion factors and exercise a custom business-time matrix, including fractional-week conversion into days, hours, and minutes.
- Interval tests cover duration/end alternatives under throwOnInvalid, abbreviated-end inheritance, intersection/merge boundaries, positive-duration splitting, and varying month lengths; two invalid/zero-duration tests also use an already-invalid reversed interval.
- Helpers simulate missing RelativeTimeFormat and locale-week APIs and restore globals; however, Jest's configured roots and coverage targets do not exercise site scripts or build tasks as coverage subjects, and the inspected CI declares no browser test step.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. The main runtime sensitivities are host Intl behavior, shared caches/defaults, DST ambiguity, and inputs that drive interval iteration. Security-relevant execution boundaries appear in the demonstration site and CI/deployment tooling. Compatibility claims and operational scripts require separate verification before relying on them.
- CI executes a remotely fetched Codecov shell script via bash process substitution; the inspected workflow supplies no content hash for that fetched script.
- deploy-site sources .env or a supplied configuration file as shell code, accepts configurable deployment directories/remotes, rewrites Git branch/index state, and commits/pushes; it is an operational execution boundary, not a read-only helper.
- The demo evaluates code and interpolates results into innerHTML, but the inspected callers supply hard-coded example strings; user-controlled execution or injection is not established by this source.
- Runtime behavior depends on host Intl support and data: IANA offsets contain formatToParts/legacy-format branches, while interval localization directly calls Intl.DateTimeFormat.formatRange without a fallback in that method.
- Locale's list-formatter cache is populated separately, but Locale.resetCache clears its other listed caches without clearing intlLFCache; resetCaches therefore does not reset every formatter cache shown here.
- Hypothesis: splitBy with a negative duration may fail to advance toward the interval end because its guard checks invalidity and zero length, while the loop keeps moving from the original start using increasing multiples; inspected split tests do not establish negative-input handling. (inferred)
- Ambiguous local-time resolution is coupled to constructor choice and shared offset-cache history; the DST suite explicitly expects fromObject to use the current offset and local to retain a cached choice until reset.
- Compatibility guidance has drift: package.json declares Node >=12, the install guide still says Node 6+, CONTRIBUTING says tests require Node 18, Docker uses Node 15, and CI starts at Node 20.
Extension points
Extension primarily happens through configuration, factories, callback transformations, and explicit implementation tables. Zone is the clearest public behavioral interface, while Duration accepts custom conversion matrices and DateTime offers reusable token parsers. Parsing and formatting additions require coordinated changes rather than a dynamic registration API. Build targets and documentation plugins have separate, concrete integration points.
- Custom zones can implement Zone's behavioral interface; normalizeZone accepts Zone instances and also duck-types objects with an offset function, while localized formatting adapts custom zones through shifted UTC values.
- Settings.now is an injectable epoch-millisecond clock callback; defaultZone, locale, numbering system, output calendar, and week settings customize newly constructed instances.
- Duration.fromObject accepts opts.matrix, its constructor gives a supplied matrix precedence over casual/longterm presets, and reconfigure can replace conversion configuration.
- DateTime.buildFormatParser constructs a reusable TokenParser; fromFormatParser checks Locale equality before consuming its explanation result and passing fields into normal construction.
- New standard date grammars fit the regex/extractor composition in regexParser.js: combineRegexes anchors patterns, combineExtractors merges fields/zones, and parse tries explicit alternatives in order.
- Custom token additions must coordinate unitForToken's parsing switch, Formatter's output switch, and macroTokenToFormatOpts when presets are involved.
- Duration.mapUnits validates callback results numerically and clones the quantity; Interval.mapEndpoints applies a callback to both endpoints and reconstructs through endpoint validation.
- Distribution targets plug into buildLibrary options and buildAll's target list; documentation plugins append to $docsify.plugins, and new guide navigation belongs in the sidebar list.
Contributor handoff
Begin with the public exports and actual package/test/build configuration, then follow the relevant factory through implementation helpers and its matching tests. Preserve explicit parsing, immutable transformations, half-open interval semantics, and calendar-versus-elapsed arithmetic. Tests and CI were inspected, not executed; this bounded brief supplies no passing status or exhaustive coverage guarantee. Under this task's authority, continue read-only investigation and reserve implementation or execution for a separately authorized task.
- Read src/luxon.js and package.json first to distinguish source APIs from distributed entrypoints; src/package.json and tasks/build.js explain source-module and generated-bundle boundaries.
- Preserve the documented scope: use host-native internationalization, keep APIs explicit, avoid convenience bloat, and address module-loader compatibility in build tooling rather than runtime source.
- For parsing work, read regexParser/tokenParser together with parseDataToDateTime and fromObject; interpretation-zone, setZone, specificOffset, missing-field defaults, and representation conflicts are separate contracts.
- For arithmetic work, retain higher-order calendar adjustment before elapsed-millisecond addition and protect DST gaps/overlaps; docs/math.md and dst.test.js provide the relevant semantic examples.
- Restore Settings and mocked Intl APIs around tests; helpers provide try/finally patterns, and cache resets matter when testing constructor-specific overlap choices.
- If later authorized to execute checks, start with npm run jest -- --runInBand plus the relevant test file, then use npm run test for coverage and npm run format-check; this investigation inspected those scripts and CI without executing them.
- Use manifest/CI evidence to resolve setup uncertainty: historical contributor instructions mention npm commands absent from the current scripts, while the declared Node minimum and CI matrix differ from older installation text.
- Keep operational boundaries explicit: release invokes npm publish, tagging, and site deployment; deploy-site sources configuration and commits/pushes, while API/site generation writes generated files under build.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 96 | 100% |
| Markdown | 24 | docs/config |
| HTML | 3 | docs/config |
| JSON | 3 | docs/config |
| CSS | 2 | docs/config |
| YAML | 2 | docs/config |
Start reading here
Probable source entrypoint: src/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (25 files)
Source layout — src/
| Path | Files |
|---|---|
src/impl/ | 12 |
src/zones/ | 4 |
src/datetime.js | 1 |
src/duration.js | 1 |
src/errors.js | 1 |
src/info.js | 1 |
src/interval.js | 1 |
src/luxon.js | 1 |
src/package.json | 1 |
src/settings.js | 1 |
src/zone.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
test/ | 60 |
src/ | 25 |
docs/ | 14 |
site/ | 11 |
scripts/ | 9 |
tasks/ | 4 |
docker/ | 4 |
benchmarks/ | 4 |
Docs found: CONTRIBUTING.mdLICENSE.mdREADME.mddocs/calendars.mddocs/formatting.mddocs/home.mddocs/install.mddocs/intl.mddocs/math.mddocs/matrix.md
Package
package.json — luxon v3.7.2, 20 declared dependencies.
@babel/core@babel/node@babel/plugin-external-helpers@babel/preset-env@rollup/plugin-babel@rollup/plugin-commonjs@rollup/plugin-node-resolvebabel-jestbenchmarkcodecovdocumentationfs-extra
CI & config entrypoints
README.md— Repository readme.github/workflows/test.yml— GitHub Actions workflowpackage.json— npm scripts: api-docs, benchmark, build, build-global, build-node, codecov, copy-site, format
Structural health signals
Average score 8.7/10 across 96 analyzed source files; 4 hotspots surfaced.
src/duration.js— 1073 lines, score 5 (Large file, Deep nesting)test/datetime/tokenParse.test.js— 1264 lines, score 5.5 (Large file, Deep nesting)src/interval.js— 694 lines, score 6 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
f427515a38f62026-08-09 — Rewrite Duration#shiftTo and normalize to do less "unintuitive" conversions.aeb7427a8d272026-08-06 — fix(interval): respect endpoint zones in hasSame for empty intervals (#1790)f2e767dbc74f2026-08-05 — Fix a typo in toRelative JSDoc exampleaeb07e37399b2026-08-06 — Reject out-of-range 12-hour values with a meridiem in fromFormat (#1787)8a798d11be622026-08-06 — Fix lost negative sign in Duration#toFormat when largest unit is zero (#1786)