Home

Welcome to the temporal-fmt wiki!

Roadmap & Known Issues

This page tracks the gaps and open questions in temporal-fmt — the stuff that's honest to call out but doesn't belong in the README. If you're looking for a way to contribute, this is the place to start.

Everything here falls into one of three buckets, and the bucket matters more than the description: it tells you whether there's a PR waiting to happen, a design conversation to have first, or nothing to do at all.

🔴 Blocked upstream — not fixable here

These aren't bugs in temporal-fmt. They're consequences of how Intl and userland Temporal polyfills currently talk to each other. A PR against this repo can't close them; they'd need a spec or engine change somewhere else.

Intl/Temporal interop gap on polyfilled environments

On Node < 26 without native Temporal, locale-aware tokens (MMMM, EEEE, a, etc.) throw Cannot use valueOf instead of working. The cause: Intl.DateTimeFormat reads fields directly off a native Temporal object, and a userland polyfill isn't one, so the read fails.

The documented workaround — swap in the polyfill's own Intl export in place of the global one — stays a workaround, not a fix, until Intl and Temporal interop is resolved upstream. If you hit this and know of movement on the spec side, link it in an issue; that's more useful than a PR here.

🟡 Open design questions — needs discussion before a PR

These are real gaps worth closing, but the fix changes what a function is, not just what it does. Open an issue and propose an approach before sending a PR — otherwise you're guessing at a decision nobody's made yet.

matchesFormat doesn't catch invalid dates

matchesFormat('yyyy-MM-dd', '2026-02-30') currently returns true. It's checking shape and vocabulary — two digits for MM, a real month name for MMMM — not whether the date could actually exist. February never has 30 days, and matchesFormat doesn't know that.

The plan is to have it catch this. But "catch it" means matchesFormat stops being a cheap shape-checker and starts being an actual date validator — it has to know how many days are in a given month, in a given calendar, in a possibly-leap year, before it can say yes or no. That's real scope, not a one-line fix, and it's worth getting the approach right before code gets written:

• Should matchesFormat grow this logic in place, or should validation live in a new, separate export (isValidDate or similar) that matchesFormat calls internally?
• Calendar-awareness matters here too — matchesFormat already has to work across the non-Gregorian calendars Temporal supports, so "days in this month" isn't a fixed lookup table.

If you want to take this on, open an issue with your proposed shape first.

🟢 Intentional — not a bug, won't change

Listed here so nobody spends a PR "fixing" a decision that was made on purpose. If you disagree with the reasoning, that's a fine thing to raise as an issue, but it's a request to revisit a decision, not a bug report.

Numeric fields always render in Western digits

yyyy, MM, dd, HH, mm, ss, SSS come out as 0-9 regardless of locale. Named fields (MMMM, EEEE, a) do localize, since those go through Intl.DateTimeFormat. The split is deliberate: most consumers of formatted output — logs, APIs, filenames — want predictable ASCII digits, and the library's zero-padding logic isn't built to handle non-Latin numeral systems like Arabic-Indic or Devanagari. If you need localized digits, run the numeric pieces through Intl.NumberFormat yourself.

Want to help?

• Blocked-upstream items: track the relevant spec/engine issue, link it here, don't send a PR against this repo.
• Open design questions: start an issue proposing an approach before writing code.
• Found something new? If it's not listed above, it's not a known issue yet — open one.