Support `Temporal` across Node.js APIs
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 122k
- Forks
- 37.3k
- Avg merge
- 4d 2h
- Merged PRs (30d)
- 283
Description
The Temporal proposal is currently Stage 3, has in progress / experimental implementation in V8 (available in latest releases using --harmony-temporal), and is likely to be unflagged in Node.js once it's stable enough (refs: https://github.com/nodejs/node/issues/57127, https://github.com/nodejs/node/pull/57128).
In light of this, I propose that Node.js begins supporting Temporal in the relevant APIs (mainly those that already work with Dates) after it becomes available by default without runtime flag.
Relevant APIs:
-
fs:StatsandBigIntStats
Only bigint version provides nanosecond precision, and both provide lazy getters forDateinstances. Adding lazy getters forTemporal.Instantwould also make non-bigint version provide nanosecond precision. -
fs:utimes(),lutimes(),futimes(),utimesSync(),lutimesSync(),futimesSync(),promises.utimes(),promises.lutimes(),filehandle.utimes()
Acceptsatimeandmtimeasnumber|string|Date, can supportTemporal.Instantas well.
Note: these functions also don't acceptbigints yet. In the Temporal API,numbers are used forepochTimes in milliseconds whilebigints are used for nanoseconds. Adding direct support ofbigints might result a confusing API: some users might expect it to coerce type and behave exactly the same asnumber|string, some might expect it to be parsed as nanoseconds. AddingTemporalsupport would make it unambiguous.
Maybe there are other APIs that can benefit from this, too?
cc @nodejs/fs since it's only https://github.com/nodejs/node/labels/fs at the moment.
Internal updates (if it happens to be more precise, more fast, or more readable), generic support (primordials, util, assert, etc.) and dependencies (for example, undici.setCookie(, { expires })) are out of scope here.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the listed fs APIs, their existing Date handling, and the linked Temporal proposal and Node.js references. Define the supported API surface and compatibility expectations before changing anything; done means the agreed Temporal support is implemented and covered by the relevant fs tests, though no specific files or tests are named here.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- api, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100