feat!: parse dates to native Date instead of Moment

[joris974]

Summary

date() was the only thing in this repo importing moment-timezone, and it used none of the timezone functionality — just moment(x) followed by isValid(). That pulled the whole IANA timezone database into every consumer's bundle to do a string parse.

	bundled, minified
moment-timezone	782,814 bytes
date-fns (parseISO + isValid)	3,062 bytes

date() now returns a native Date. The library's public API carries no date-library opinion, so consumers pick whatever they use downstream. moment is now entirely absent from pnpm-lock.yaml — it was the only path to it.

Upstream status

Moment is also a dead end for us going forward. Its own README says so:

⚠️ Moment.js is a legacy project, now in maintenance mode. New features are not being accepted.

Moment core's last release was 2.30.1, in December 2023 — over two and a half years ago. moment-timezone still publishes (0.6.3 landed 2026-07-19), but those releases are IANA timezone database refreshes rather than library work, which is exactly what maintenance mode looks like. The upstream project also recommends migrating to a modern alternative, date-fns among them.

So the 764KB we were shipping bought us a dependency that is explicitly not being developed.

Why date-fns rather than bare new Date()

new Date() is unsafe for a validation library. Measured against the current behavior:

input	moment (before)	new Date()	parseISO (after)
'2016-03-12 13:00:00'	21:00Z	21:00Z	21:00Z ✅
'2016-03-12' (date-only)	local midnight	UTC midnight ⚠️	local midnight ✅
'2016-02-30'	rejected	rolls to Mar 1 ⚠️	rejected ✅
'2015-02-29'	rejected	rolls to Mar 1 ⚠️	rejected ✅

parseISO matches the previous moment behavior on every case that matters. date-fns is also already used in megarepo, so this doesn't introduce a new library to the stack.

Temporal would be the longer-term answer, but it's unavailable on Node 22 (typeof Temporal === 'undefined') and would need a polyfill.

Release

This is a major version bump: 3.0.1 -> 4.0.0.

The commit is feat!: with a BREAKING CHANGE: footer, so semantic-release cuts the major automatically on merge. Note that package.json in the repo reads "version": "2.0.0" — that value is stale and unmanaged, because @semantic-release/npm sets the version at publish time and does not commit it back. The published latest is 3.0.1 (tag v3.0.1), so don't read the 2.0.0 in the diff as the current version, and there's no manual version edit in this PR.

Worth knowing for anyone tracking the v3 references below: v3.0.0 was the semantic-release adoption, not an API change. date() still returns ParserT<Moment> in the published v3.0.1, so the console comment predicting nativeDate() "in v3" was overtaken by events — that change is landing here, in v4.

Breaking changes

1. date() returns ParserT<Date>, not ParserT<Moment>.
2. Only ISO-8601 is accepted. '03/12/2016' and 'March 12, 2016' previously worked via moment's deprecated Date fallback (it logged a deprecation warning) and are now rejected. '03/12/2016' is genuinely ambiguous between March 12 and December 3.

date() returned a Moment through v3. To keep Moment values, convert at the boundary:

mapStatic(date(), d => moment(d))

Downstream impact

megarepo is the only consumer. frontend/platform/console already has a Moment→Date adapter used across ~15 model files, carrying this note:

REMOVE when @freckle/parser v3 adds nativeDate().

That adapter collapses to date(). frontend/educator (PremiumCutoff = Moment) and frontend/student's test mock need the inverse wrapper above; megarepo has 409 files importing moment-timezone, so it stays moment-based regardless. A companion megarepo PR is required before this is consumed — not included here.

Notes for the reviewer

• parseISO accepts the ISO century form, so '12' parses as year 1200 (moment gave 2001-12-01). Both are nonsense; I kept parseISO's standard-conformant behavior rather than adding custom length rules. Flagging in case you'd rather guard it.
• New tests use for...of rather than lodash forEach to avoid conflicting with refactor: remove lodash dependency #273, which removes lodash from this file.
• Verified under TZ=UTC, Asia/Tokyo, America/Los_Angeles, Pacific/Kiritimati — the date assertions are timezone-independent.

Test plan

• pnpm test — 82 tests pass (76 before, +6 pinning the new contract)
• pnpm build — typechecks clean; dist/index.d.ts emits date(): ParserT<Date>; no Moment reference left in dist/
• pnpm check-git-clean — committed dist/ in sync
• prettier --check 'src/**/*.ts' — clean
• grep -c moment pnpm-lock.yaml → 0

🤖 Generated with Claude Code

[github-actions]

PR checklist

• Version in package.json is updated according to semver policy.
• Built dist/ reflects all changes in PR prior to merge.