date-fns/date-fns
github.com/date-fns/date-fns ↗ · 2020 files · 10.3 MB
🔥️ NEW: date-fns v4.0 with first-class time zone support is out!
Overview
date-fns is a modular JavaScript and TypeScript date utility library for browser and Node.js developers, with APIs for calendar arithmetic, parsing, formatting, intervals, comparisons, and localization. Its distinctive integration mechanism preserves native Date subclasses and accepts explicit calculation contexts, allowing the companion TZDate and UTCDate packages to control time-zone behavior. This monorepo also contains package generators, compatibility examples, and a separate Firebase-backed documentation publisher. The brief reflects read-only investigation at commit 717ce0a807ea4c6b540d015b5c408723175b2838; inspected tests provide coverage evidence, not passing results.
System map
The repository separates date calculation, date subclasses, documentation publishing, and development tooling into workspace packages. Consumers enter through exported functions and classes rather than a central application startup routine. Core package output supports both ESM and CommonJS, while workspace exports reference source files. Persistent storage appears in the documentation publisher; the inspected calculation paths operate on in-memory dates and options.
- pnpm-workspace.yaml includes pkgs/* and the time-zone engine-test package; root TypeScript references core, docs, utc, tz, and engine tests.
- The core export surface includes independent arithmetic, difference, interval, formatting, parsing, predicate, and boundary functions, plus shared types.
- Published core root imports resolve to index.js/index.d.ts, while require resolves to index.cjs/index.d.cts.
- TZDate extends TZDateMini's target-zone representation; UTCDate extends UTCDateMini's redirected UTC accessors.
- The private dev package exposes date-fns-build-package and date-fns-test-tz; its builder preserves modules, externalizes imports, and rewrites relative import extensions.
- The docs package exposes date-fns-docs and uses Firebase Admin with Typesaurus collections named packages, versions, and pages.
- Auxiliary applications are a React/Vite formatted-date example and a Hono playground serving browser JavaScript on port 3000.
- Temporal-oriented index.tp.ts implementations have a separate Vitest project and are excluded from production source-entry discovery and declaration output.
Feature catalog
The primary user surface is a broad collection of date APIs, with individual imports and functional-programming variants. Formatting and parsing combine Unicode-style tokens with locale-specific behavior. Calendar operations and interval enumeration preserve date-extension context. Companion packages expose UTC and arbitrary-zone dates, while repository examples and documentation tooling support integration and publication.
- Calendar APIs include addition, subtraction, calendar differences, predicates, and start/end boundaries; addMonths clamps dates to the destination month's last day.
- format supports escaped literals, localized P/p expansion, locale preprocessing, and token dispatch; formatDate is an alias.
- parse consumes text against a format and reference date, rejects incompatible token combinations, permits trailing whitespace, and validates setters before returning a date.
- eachDayOfInterval returns cloned midnight dates inclusively, supports reversed intervals and negative steps, and returns an empty array for a zero step.
- formatDistance selects localized second-to-year phrases using elapsed time and offset correction; locale objects also supply relative formats, long formats, localization, and parsing matches.
- The FP surface curries functions with reversed arguments; generated WithOptions variants retain the options argument, while @pure false functions are skipped.
- Time-zone APIs provide tz/utc context factories, zone conversion preserving timestamps, UTC offsets, offset-change scanning, and four zone-name styles.
- Maintainer-facing features include documentation publication and --rollback; integration examples display yyyy-MM-dd in React and log UTC TZDate representations in the playground.
Data flow
Date inputs enter through typed arguments and are normalized into fresh objects before calculation. Context functions and construction hooks determine the date class and time zone used by downstream accessors. Formatting produces strings, parsing builds dates through ordered setters, and enumeration produces arrays of cloned dates. Documentation processing is a separate flow from local files and reflection data into remote collections.
- DateArg accepts a Date subtype, number, or string; toDate forwards the input and optional context to constructFrom.
- constructFrom prioritizes a supplied function, then constructFromSymbol, then a Date instance's constructor, and finally native Date construction.
- normalizeDates binds a constructor context using the explicit context or first object argument, then maps every input through it; normalizeInterval applies this to both endpoints.
- format resolves locale and week defaults, normalizes the date, expands long tokens into parts, optionally preprocesses them, and joins formatter results.
- Parser.run converts a parsed value into a ValueSetter and remaining text; parse retains one setter per priority, validates it against the evolving date, and merges returned flags.
- TZDateMini stores the instant on itself and wall-clock fields on internal; timestamp writes call syncToInternal, while local setters call syncFromInternal and adjustToSystemTZ.
- Global default options live in a module variable; setDefaultOptions copies existing own properties, merges new values, deletes keys set to undefined, and replaces the state object.
- Documentation inputs resolve relative to the imported config; TypeDoc references become serialized function pages and Markdown files become static pages before package metadata, version summaries, and page records are written.
Behavior traces
The inspected flows cover an example startup, primary formatting and parsing actions, date arithmetic, subclass synchronization, and remote documentation persistence. Each trace follows concrete function calls and material branch conditions. Calculation flows end at returned values; the publisher ends at remote writes or deletions. These are source-derived execution traces, not observed runs.
- Example startup: main.tsx calls ReactDOM.createRoot(...).render → StrictMode → App → new Date → format(today, 'yyyy-MM-dd') → paragraph containing the returned string.
- Formatting: format → getDefaultOptions → toDate → constructFrom → isValid → longFormatters → optional localize.preprocessor → protected-token check → formatters[token[0]] → join; invalid dates throw RangeError.
- Parsing: parse expands tokens → looks up parsers → checks incompatibilities → Parser.run creates ValueSetter → rejects leftover non-whitespace → orders setters → validate/set; DateParser checks month/leap-year bounds before setting the day.
- Zoned month addition: tz(zone) → TZDate.tz → addMonths → toDate with options.in → constructFrom(context, input) → destination-month-end calculation → clamp or setFullYear; NaN returns Invalid Date and zero returns the clone.
- Target-zone setter: generated setHours writes internal.setUTCHours → syncFromInternal copies fields through native local setters → adjustToSystemTZ handles offset/DST differences → syncToInternal rebuilds the final wall-clock representation.
- UTC context: utc(value) converts the input to a timestamp → new UTCDate → UTCDateMini constructor sets time; local getter/setter names resolve to UTC methods and getTimezoneOffset returns zero.
- Documentation publication: initializeApp → resolve/import config → getVersion validates package version → getFnPages/getMarkdownPages → concurrently update package versions, add a version summary, and commit a page batch → exit 0; errors exit 1.
- Documentation rollback: after config/version loading, --rollback concurrently filters the package's version list, queries and removes matching version documents, and queries and removes matching page documents.
Testing signals
Tests and CI were inspected, not executed; no passing status or coverage percentage is established. Vitest discovers package projects, with separate core main and Temporal-oriented suites and package-specific isolation settings. Inspected tests exercise mutation guarantees, invalid input, parsing boundaries, context types, DST gaps, and historical offsets. CI describes browser, Node-version, time-zone, smoke, type, lint, and locale checks, but this bounded inspection does not establish exhaustive coverage.
- Root Vitest discovers pkgs/*; core main includes src/**/test.ts, temporarily includes test.tp.ts, and both use forks, disabled isolation, concurrent sequencing, and optional Chromium via Playwright.
- addMonths tests assert timestamp support, input immutability, month-end clamping, pre-100 AD dates, invalid dates/amounts, UTCDate retention, and TZDate context inference.
- Formatting tests cover quote escaping and formatDate alias behavior; parsing tests cover leap-day bounds, mismatches, invalid references, trailing whitespace, and unescaped-letter errors.
- TZ tests include src/**/tests.ts and test/**/*.test.ts; inspected edge cases assert spring-forward normalization and historical second-offset behavior, while UTC configuration enables isolation.
- Push/PR workflows invoke core Node, browser, and time-zone tasks; Node tests name versions 22/24/25/26, and the zone runner launches Vitest with TZ and VITEST_MAX_WORKERS=1.
- Smoke CI delegates to example tasks; quality CI invokes type checking, linting, and locale snapshots, whose renderer covers format/parse, distances, relative dates, and durations under TZ=utc.
- The inspected docs tests assert export/module-node classification and repository-path conversion; its npm test script is a deliberate failure placeholder despite a Vitest tests.ts configuration, so that script is not a reliable docs-suite entrypoint.
- Coverage CI is workflow_dispatch-only with a TODO; addMonths DST cases are conditional on detected transitions, and inspected docs helper tests do not demonstrate Firebase publication/rollback verification. Tests and workflows were read, not run.
Risk map
The strongest source observations concern documentation side effects, snapshot mode selection, date-state synchronization, and build-output paths. These observations are not confirmed security vulnerabilities, and no exploit or runtime failure was reproduced. Library correctness depends on preserving constructor context and handling native Date and Intl edge cases. Potential operational consequences are explicitly labeled as hypotheses where execution would be needed.
- Source-observed snapshot mismatch: test/locales passes --test, but the script compares only when process.argv[2] equals 'test'; the supplied --test therefore selects the writeFile branch.
- The docs CLI dynamically imports a process-argument path and initializes Firebase Admin before dispatch; package, TypeDoc, and Markdown paths are resolved from config without a repository-root containment check in these inspected paths.
- Hypothesis: documentation publication or rollback can leave partial remote state after an individual failure because package, version, and page operations run concurrently without one encompassing transaction. (inferred)
- TZDateMini is a correctness hotspot: separate instant/wall-clock objects require synchronization, historical second corrections, DST-gap detection, and a final small-drift correction bounded below 30 minutes.
- tzOffset caches formatter functions by zone and offsets by strings, catches Intl failures, and falls back to an unanchored numeric-offset regex; cache bounds and stricter fallback input validation are not present in this inspected implementation.
- Module-global defaults affect format and parse, while multi-date normalization uses the first object unless a context is supplied; the time-zone guide explicitly demonstrates order-dependent business-day results.
- Build tooling performs filesystem mutations and shell-outs: package.sh removes package-local dist, the dev builder accepts source/output paths and runs oxfmt, and CDN construction recursively removes an environment-selected output when building a separate CDN package.
- Source-observed subpath mismatch: tz workspace exports reference several paths without src and Date .ts files, while inspected implementations reside under src with Date .js files; utc Date subpaths likewise target .ts instead of the inspected .js implementations. Resolution impact was not tested.
Extension points
Extensions plug into typed date construction, locale objects, token tables, and code-generation inputs. Public function discovery drives export maps and indices rather than requiring every output to be hand-maintained. Parser classes expose explicit compatibility and priority contracts. Documentation has its own configuration interface for additional static pages, categories, and reflection overrides.
- Custom Date subclasses can implement ConstructableDate's constructFromSymbol hook; constructFrom also accepts a context factory directly, and TZDate implements the shared constructDateFrom symbol.
- New public functions enter generator discovery through listFns; indices.ts generates the root index, FP index, locale index, TypeDoc configuration, and workspace/published export maps.
- Parsing tokens plug into the parsers table through Parser subclasses that declare incompatibleTokens, priority, optional subPriority, parse, validate, and set behavior.
- Formatter behavior plugs into the formatters table keyed by token letter; handlers receive date, full token, localize functions, and week/locale options, and format reexports formatter tables for downstream libraries.
- A locale supplies formatDistance, formatLong, formatRelative, localize, match, and week options; the contribution guide recommends copying an existing locale and replacing its data using CLDR as a reference.
- Locale-specific token rewriting can use localize.preprocessor, which receives the normalized date and classified FormatPart array before final formatting.
- FP generation derives arity and options variants from reflection signatures and excludes @pure false functions; generated wrappers delegate to the shared convertToFP implementation.
- DateFnsDocs.Config extends publication inputs through package/json paths, ordered categories, static files, and kindsMap overrides; readRefsFromJSON uses overrides to classify constants and assign categories.
Contributor handoff
Tests and CI were inspected, not executed, and this brief is bounded to the source files read. Begin changes at the owning function or package, then follow construction, locale, and generated-output dependencies. Existing manifests and mise tasks provide more current command evidence than several older contributing examples. Preserve the read-only authority of this investigation; the checks below are future validation guidance when execution is authorized.
- Read AGENTS.md and the owning package's implementation/test/config first; repository instructions identify core, UTC, and TZ boundaries and prohibit unsolicited commits or pushes.
- Preserve the construction contract during date edits: use the existing toDate/constructFrom path so context factories, symbol hooks, subclass constructors, and cloned inputs remain intact.
- For parser changes, read Parser, Setter, the registry, and the specific parser together; compatibility rejection, priority selection, Invalid Date returns, and RangeError branches are distinct contracts.
- Edit generator logic rather than treating generated indices/FP wrappers as independent source; indices.ts rewrites package.json and export indices, and fp.ts labels emitted wrappers as generated.
- Locale work requires the contribution guide and snapshot review; distinguish generation from comparison and address the --test versus test mode mismatch before trusting the existing locale-check task.
- When execution is authorized, start with the relevant Vitest file, then applicable mise type/lint, browser, time-zone, or smoke tasks; this investigation inspected those tests and CI definitions without running them.
- Check documentation commands against current tooling: CONTRIBUTING.md still describes lib output and Prettier/ESLint, while package.sh emits dist/date-fns and root mise uses oxfmt/oxlint.
- Keep verification commands separate from publishing and build mutations: docs CLI writes/deletes remote records, package.sh deletes dist, and Temporal implementations are excluded from production builds despite having their own test project.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 1721 | 95% |
| Markdown | 126 | docs/config |
| JSON | 54 | docs/config |
| JavaScript | 47 | 3% |
| TOML | 26 | 1% |
| Shell | 14 | 1% |
| YAML | 11 | docs/config |
| CSS | 2 | docs/config |
Start reading here
Probable source entrypoint: pkgs/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
pkgs/ (1990 files) codemods/ (1 files)
Source layout — pkgs/
| Path | Files |
|---|---|
pkgs/core/ | 260 |
Repository structure
| Top-level path | Files |
|---|---|
pkgs/ | 1990 |
.github/ | 8 |
.devcontainer/ | 5 |
.agents/ | 1 |
codemods/ | 1 |
.opencode/ | 1 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.md
Package
package.json — @date-fns/root v0.0.0, 5 declared dependencies.
oxfmtoxlintoxlint-tsgolinttypescriptvitest
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionspkgs/core/examples/vite/vite.config.ts— Vite configpkgs/core/examples/vite/src/App.tsx— React rootpkgs/core/examples/vite/src/main.tsx— Vite React entrypointpkgs/core/package.json— npm scripts: lint, locale-snapshots, stats, test, typespkgs/docs/package.json— npm scripts: testpkgs/tz/package.json— npm scripts: testpkgs/utc/package.json— npm scripts: build, test
Structural health signals
Average score 7.7/10 across 96 analyzed source files; 5 hotspots surfaced.
pkgs/tz/src/date/tests.ts— 1347 lines, score 5.5 (Large file, Deep nesting)pkgs/core/src/format/test.ts— 1022 lines, score 5.7 (Large file, Deep nesting)pkgs/docs/src/bin.ts— 216 lines, score 5.9 (Deep nesting, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
717ce0a807ea2026-09-22 — Add Temporal docs, tests and code for `endOfDay`, `endOfDecade`, `endOfHour`, `endOfISOWeek`, `endOfISOWeekYear`, `endOfMinute` and `endOfMonth`bb87ba5de4822026-09-22 — Add Temporal docs, tests and code for `eachWeekendOfInterval`, `eachWeekendOfMonth`, `eachWeekendOfYear`, `eachYearOfInterval`, `setDate`, `setMonth` and `startOfQuarter`766dea98b7042026-09-22 — Fix tpStartOfISOWeekYear to return `Temporal.ZonedDateTime` when possible21006241cf392026-09-22 — Upgrade dev enva2819a71ee222026-09-22 — Add Temporal docs, tests and code for `differenceInISOWeekYears`, `differenceInMilliseconds`, `differenceInMinutes`, `differenceInMonths`, `differenceInQuarters`, `differenceInSeco