nodejs / nodejs/node

Support `Temporal` across Node.js APIs

Open
#57,891 6 comments 53 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature request never-stale
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: Stats and BigIntStats
    Only bigint version provides nanosecond precision, and both provide lazy getters for Date instances. Adding lazy getters for Temporal.Instant would also make non-bigint version provide nanosecond precision.
  • fs: utimes(), lutimes(), futimes(), utimesSync(), lutimesSync(), futimesSync(), promises.utimes(), promises.lutimes(), filehandle.utimes()
    Accepts atime and mtime as number|string|Date, can support Temporal.Instant as well.
    Note: these functions also don't accept bigints yet. In the Temporal API, numbers are used for epochTimes in milliseconds while bigints are used for nanoseconds. Adding direct support of bigints might result a confusing API: some users might expect it to coerce type and behave exactly the same as number|string, some might expect it to be parsed as nanoseconds. Adding Temporal support 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.