Support `Temporal` across Node.js APIs

[LiviaMedeiros]

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: #57127, #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 fs Issues and PRs related to the fs subsystem / file system. 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.

[joyeecheung]

I wonder why util (inspect) and assert support are excluded here. IMO these seem more necessary (have to be implemented by Node.js and are essential for debugging) compared to fs support (which can be worked around by wrapping timestamps).

[LiviaMedeiros]

Generic support from util/assert is out of scope of this issue exactly because there's no questioning that this is necessary and essential. Things like "assert.deepStrictEqual() passes for completely different Temporal.Instants" (which is currently the case with --harmony-temporal) or "util.inspect(instantInstance) doesn't really inspect its internal datetime value" would be more of a bug once Temporal graduates from experimental state.

Specific details that are facing userspace, for example:

assert.deepStrictEqual( // should this pass or throw?
  Temporal.ZonedDateTime.from('2025-04-16T20:00+09:00[Asia/Tokyo]'),
  Temporal.ZonedDateTime.from('2025-04-16T12:00+01:00[Europe/Berlin]')
);
assert.deepEqual( // should this pass or throw?
  Temporal.ZonedDateTime.from('2025-04-16T20:00+09:00[Asia/Tokyo]'),
  Temporal.ZonedDateTime.from('2025-04-16T12:00+01:00[Europe/Berlin]')
);
assert.deepEqual( // or maybe even this is somehow a good idea?
  Temporal.Instant.fromEpochMilliseconds(1234567890e3),
  new Date(1234567890e3)
);

...can be discussed, of course.

But this issue is feature request Issues that request new features to be added to Node.js. and mainly I'd like to hear the arguments for or against further adoption of Temporal APIs before implementing.

Also it's not limited to fs subsystem and Instant instances. Maybe someone would like to have something idiomatic like:

await require('node:timers').promises.setTimeout(Temporal.Duration.from({ hours: 2 }), 'two hours later');

Or

import { Resolver } from 'node:dns';
const resolver = new Resolver({ timeout: Temporal.Duration.from('PT99S') });

Without prior converting it to ms in userspace.

[jasnell]

A couple of things here to add to the TODO... Currently there is no C++ API for Temporal in V8. So operations like IsTemporal...() do not exist. We use c++ level apis to back util/types which are used internally by the inspect logic. I suspect that we will need that plus something like a v8::Temporal::NewInstant(...), etc set of APIs for creating and working with Temporal objects at the native layer.

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Mark issue so that it is never considered stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.

[Manishearth]

This is still being worked on in other venues: Milad has an upstream CL that should hopefully unblock node.