Support Temporal across Node.js APIs

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 file-system APIs and the fs module. 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.

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).

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 requesting new Node.js features. 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.

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.

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

https://bsky.app/profile/tc39.es/post/3mgsa4jzers2x

fs: add `Temporal.Instant` support to `Stats` and `BigIntStats`

Navigation Menu

Repository navigation

Support `Temporal` across Node.js APIs #57891

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Support Temporal across Node.js APIs #57891

Description

Activity

joyeecheung commented on Apr 16, 2025

LiviaMedeiros commented on Apr 16, 2025

jasnell commented on Apr 27, 2025

github-actions commented on Oct 25, 2025

Manishearth commented on Oct 25, 2025

ctcpip commented on Mar 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Support `Temporal` across Node.js APIs #57891