From 9eb700c6348c0eddc2f3594be3460c31626a112b Mon Sep 17 00:00:00 2001
From: LiviaMedeiros <livia@cirno.name>
Date: Thu, 20 Nov 2025 12:30:49 +0800
Subject: [PATCH 1/2] fs: add `Temporal.Instant` support to `Stats` and
 `BigIntStats`

---
 doc/api/fs.md                      |  37 +++++++-
 lib/internal/fs/utils.js           | 130 +++++++++++++++++++++++++++--
 test/parallel/test-fs-watchfile.js |  12 ++-
 3 files changed, 162 insertions(+), 17 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index f09395cb123150..3f246210de04e0 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -4494,7 +4494,11 @@ Stats {
   atime: 2019-06-22T03:37:33.072Z,
   mtime: 2019-06-22T03:36:54.583Z,
   ctime: 2019-06-22T03:37:06.624Z,
-  birthtime: 2019-06-22T03:28:46.937Z
+  birthtime: 2019-06-22T03:28:46.937Z,
+  atimeInstant: 2019-06-22T03:37:33.071963Z,
+  mtimeInstant: 2019-06-22T03:36:54.5833518Z,
+  ctimeInstant: 2019-06-22T03:37:06.6235366Z,
+  birthtimeInstant: 2019-06-22T03:28:46.9372893Z
 }
 false
 Stats {
@@ -4515,7 +4519,11 @@ Stats {
   atime: 2019-06-22T03:36:56.619Z,
   mtime: 2019-06-22T03:36:54.584Z,
   ctime: 2019-06-22T03:36:54.584Z,
-  birthtime: 2019-06-22T03:26:47.711Z
+  birthtime: 2019-06-22T03:26:47.711Z,
+  atimeInstant: 2019-06-22T03:36:56.6188555Z,
+  mtimeInstant: 2019-06-22T03:36:54.584Z,
+  ctimeInstant: 2019-06-22T03:36:54.5838145Z,
+  birthtimeInstant: 2019-06-22T03:26:47.7107478Z
 }
 ```
 
@@ -7203,6 +7211,9 @@ i.e. before the `'ready'` event is emitted.
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/00000
+    description: Added Temporal.Instant support.
   - version:
     - v22.0.0
     - v20.13.0
@@ -7238,10 +7249,19 @@ Stats {
   mtimeMs: 1318289051000.1,
   ctimeMs: 1318289051000.1,
   birthtimeMs: 1318289051000.1,
+
+  // Instances of Date
   atime: Mon, 10 Oct 2011 23:24:11 GMT,
   mtime: Mon, 10 Oct 2011 23:24:11 GMT,
   ctime: Mon, 10 Oct 2011 23:24:11 GMT,
-  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
+  birthtime: Mon, 10 Oct 2011 23:24:11 GMT,
+
+  // Instances of Temporal.Instant
+  atimeInstant: 2011-10-10T23:24:11.0001Z,
+  mtimeInstant: 2011-10-10T23:24:11.0001Z,
+  ctimeInstant: 2011-10-10T23:24:11.0001Z,
+  birthtimeInstant: 2011-10-10T23:24:11.0001Z
+}
 ```
 
 `bigint` version:
@@ -7266,10 +7286,19 @@ BigIntStats {
   mtimeNs: 1318289051000000000n,
   ctimeNs: 1318289051000000000n,
   birthtimeNs: 1318289051000000000n,
+
+  // Instances of Date
   atime: Mon, 10 Oct 2011 23:24:11 GMT,
   mtime: Mon, 10 Oct 2011 23:24:11 GMT,
   ctime: Mon, 10 Oct 2011 23:24:11 GMT,
-  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
+  birthtime: Mon, 10 Oct 2011 23:24:11 GMT,
+
+  // Instances of Temporal.Instant
+  atimeInstant: 2011-10-10T23:24:11Z,
+  mtimeInstant: 2011-10-10T23:24:11Z,
+  ctimeInstant: 2011-10-10T23:24:11Z,
+  birthtimeInstant: 2011-10-10T23:24:11Z
+}
 ```
 
 #### `stats.isBlockDevice()`
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 0f788ce4dbc3a3..c1f14548f76b2a 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -8,6 +8,7 @@ const {
   DatePrototypeGetTime,
   ErrorCaptureStackTrace,
   FunctionPrototypeCall,
+  MathFloor,
   MathMin,
   MathRound,
   Number,
@@ -63,6 +64,10 @@ const {
 const pathModule = require('path');
 const kType = Symbol('type');
 const kStats = Symbol('stats');
+const kPartialAtimeNs = Symbol('partialAtimeNs');
+const kPartialMtimeNs = Symbol('partialMtimeNs');
+const kPartialCtimeNs = Symbol('partialCtimeNs');
+const kPartialBirthtimeNs = Symbol('kPartialBirthtimeNs');
 const assert = require('internal/assert');
 
 const {
@@ -431,6 +436,11 @@ function nsFromTimeSpecBigInt(sec, nsec) {
   return sec * kNsPerSecBigInt + nsec;
 }
 
+function instantFromTimeSpecMs(msec, nsec) {
+  // TODO(LiviaMedeiros): TemporalInstant primordial
+  return new Temporal.Instant(BigInt(MathFloor(msec / kMsPerSec)) * kNsPerSecBigInt + BigInt(nsec));
+}
+
 // The Date constructor performs Math.floor() on the absolute value
 // of the timestamp: https://tc39.es/ecma262/#sec-timeclip
 // Since there may be a precision loss when the timestamp is
@@ -491,6 +501,102 @@ const lazyDateFields = {
   },
 };
 
+const lazyTemporalFields = {
+  __proto__: null,
+  atimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.atimeInstant = instantFromTimeSpecMs(this.atimeMs, this[kPartialAtimeNs]);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'atimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  mtimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.mtimeInstant = instantFromTimeSpecMs(this.mtimeMs, this[kPartialMtimeNs]);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'mtimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  ctimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.ctimeInstant = instantFromTimeSpecMs(this.ctimeMs, this[kPartialCtimeNs]);;
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'ctimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  birthtimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.birthtimeInstant = instantFromTimeSpecMs(this.birthtimeMs, this[kPartialBirthtimeNs]);;
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'birthtimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+};
+
+const lazyTemporalBigIntFields = {
+  __proto__: null,
+  atimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.atimeInstant = new Temporal.Instant(this.atimeNs);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'atimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  mtimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.mtimeInstant = new Temporal.Instant(this.mtimeNs);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'mtimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  ctimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.ctimeInstant = new Temporal.Instant(this.ctimeNs);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'ctimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+  birthtimeInstant: {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() {
+      return this.birthtimeInstant = new Temporal.Instant(this.birthtimeNs);
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'birthtimeInstant', { __proto__: null, value, writable: true });
+    },
+  },
+};
+
 function BigIntStats(dev, mode, nlink, uid, gid, rdev, blksize,
                      ino, size, blocks,
                      atimeNs, mtimeNs, ctimeNs, birthtimeNs) {
@@ -510,6 +616,7 @@ function BigIntStats(dev, mode, nlink, uid, gid, rdev, blksize,
 ObjectSetPrototypeOf(BigIntStats.prototype, StatsBase.prototype);
 ObjectSetPrototypeOf(BigIntStats, StatsBase);
 ObjectDefineProperties(BigIntStats.prototype, lazyDateFields);
+ObjectDefineProperties(BigIntStats.prototype, lazyTemporalBigIntFields);
 
 BigIntStats.prototype._checkModeProperty = function(property) {
   if (isWindows && (property === S_IFIFO || property === S_IFBLK ||
@@ -521,18 +628,23 @@ BigIntStats.prototype._checkModeProperty = function(property) {
 
 function Stats(dev, mode, nlink, uid, gid, rdev, blksize,
                ino, size, blocks,
-               atimeMs, mtimeMs, ctimeMs, birthtimeMs) {
+               atimeS, atimeNs, mtimeS, mtimeNs, ctimeS, ctimeNs, birthtimeS, birthtimeNs) {
   FunctionPrototypeCall(StatsBase, this, dev, mode, nlink, uid, gid, rdev,
                         blksize, ino, size, blocks);
-  this.atimeMs = atimeMs;
-  this.mtimeMs = mtimeMs;
-  this.ctimeMs = ctimeMs;
-  this.birthtimeMs = birthtimeMs;
+  this.atimeMs = msFromTimeSpec(atimeS, atimeNs);
+  this.mtimeMs = msFromTimeSpec(mtimeS, mtimeNs);
+  this.ctimeMs = msFromTimeSpec(ctimeS, ctimeNs);
+  this.birthtimeMs = msFromTimeSpec(birthtimeS, birthtimeNs);
+  this[kPartialAtimeNs] = atimeNs;
+  this[kPartialMtimeNs] = mtimeNs;
+  this[kPartialCtimeNs] = ctimeNs;
+  this[kPartialBirthtimeNs] = birthtimeNs;
 }
 
 ObjectSetPrototypeOf(Stats.prototype, StatsBase.prototype);
 ObjectSetPrototypeOf(Stats, StatsBase);
 ObjectDefineProperties(Stats.prototype, lazyDateFields);
+ObjectDefineProperties(Stats.prototype, lazyTemporalFields);
 
 Stats.prototype._checkModeProperty = function(property) {
   if (isWindows && (property === S_IFIFO || property === S_IFBLK ||
@@ -565,10 +677,10 @@ function getStatsFromBinding(stats, offset = 0) {
     stats[3 + offset], stats[4 + offset], stats[5 + offset],
     stats[6 + offset], stats[7 + offset], stats[8 + offset],
     stats[9 + offset],
-    msFromTimeSpec(stats[10 + offset], stats[11 + offset]),
-    msFromTimeSpec(stats[12 + offset], stats[13 + offset]),
-    msFromTimeSpec(stats[14 + offset], stats[15 + offset]),
-    msFromTimeSpec(stats[16 + offset], stats[17 + offset]),
+    stats[10 + offset], stats[11 + offset], // atime
+    stats[12 + offset], stats[13 + offset], // mtime
+    stats[14 + offset], stats[15 + offset], // ctime
+    stats[16 + offset], stats[17 + offset], // birthtime
   );
 }
 
diff --git a/test/parallel/test-fs-watchfile.js b/test/parallel/test-fs-watchfile.js
index bd86835d9ff758..e1fd3f4c3433d3 100644
--- a/test/parallel/test-fs-watchfile.js
+++ b/test/parallel/test-fs-watchfile.js
@@ -42,10 +42,14 @@ const expectedStatObject = new fs.Stats(
   0,                                        // ino
   0,                                        // size
   0,                                        // blocks
-  Date.UTC(1970, 0, 1, 0, 0, 0),            // atime
-  Date.UTC(1970, 0, 1, 0, 0, 0),            // mtime
-  Date.UTC(1970, 0, 1, 0, 0, 0),            // ctime
-  Date.UTC(1970, 0, 1, 0, 0, 0)             // birthtime
+  0,                                        // atimeS
+  0,                                        // atimeNs
+  0,                                        // mtimeS
+  0,                                        // mtimeNs
+  0,                                        // ctime
+  0,                                        // ctimeNs
+  0,                                        // birthtime
+  0,                                        // birthtimeNs
 );
 
 tmpdir.refresh();

From 22dc64f09ff3b5a95293ca177b350fea1f825696 Mon Sep 17 00:00:00 2001
From: LiviaMedeiros <livia@cirno.name>
Date: Fri, 21 Nov 2025 15:23:33 +0800
Subject: [PATCH 2/2] squash: add `ERR_NO_TEMPORAL` error

---
 lib/internal/errors.js   |  2 ++
 lib/internal/fs/utils.js | 20 ++++++++++++++++----
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/lib/internal/errors.js b/lib/internal/errors.js
index 5fa4437b09e556..0b334ad642437c 100644
--- a/lib/internal/errors.js
+++ b/lib/internal/errors.js
@@ -1634,6 +1634,8 @@ E('ERR_NO_CRYPTO',
   'Node.js is not compiled with OpenSSL crypto support', Error);
 E('ERR_NO_ICU',
   '%s is not supported on Node.js compiled without ICU', TypeError);
+E('ERR_NO_TEMPORAL',
+  'Node.js is not compiled with Temporal support', Error);
 E('ERR_NO_TYPESCRIPT',
   'Node.js is not compiled with TypeScript support', Error);
 E('ERR_OPERATION_FAILED', 'Operation failed: %s', Error, TypeError);
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index c1f14548f76b2a..97314342841fa8 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -35,6 +35,7 @@ const {
     ERR_INCOMPATIBLE_OPTION_PAIR,
     ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
+    ERR_NO_TEMPORAL,
     ERR_OUT_OF_RANGE,
   },
   hideStackFrames,
@@ -436,7 +437,18 @@ function nsFromTimeSpecBigInt(sec, nsec) {
   return sec * kNsPerSecBigInt + nsec;
 }
 
+function instantFromNs(nsec) {
+  if (Temporal === undefined) {
+    throw new ERR_NO_TEMPORAL();
+  }
+  // TODO(LiviaMedeiros): TemporalInstant primordial
+  return new Temporal.Instant(nsec);
+}
+
 function instantFromTimeSpecMs(msec, nsec) {
+  if (Temporal === undefined) {
+    throw new ERR_NO_TEMPORAL();
+  }
   // TODO(LiviaMedeiros): TemporalInstant primordial
   return new Temporal.Instant(BigInt(MathFloor(msec / kMsPerSec)) * kNsPerSecBigInt + BigInt(nsec));
 }
@@ -556,7 +568,7 @@ const lazyTemporalBigIntFields = {
     enumerable: true,
     configurable: true,
     get() {
-      return this.atimeInstant = new Temporal.Instant(this.atimeNs);
+      return this.atimeInstant = instantFromNs(this.atimeNs);
     },
     set(value) {
       ObjectDefineProperty(this, 'atimeInstant', { __proto__: null, value, writable: true });
@@ -567,7 +579,7 @@ const lazyTemporalBigIntFields = {
     enumerable: true,
     configurable: true,
     get() {
-      return this.mtimeInstant = new Temporal.Instant(this.mtimeNs);
+      return this.mtimeInstant = instantFromNs(this.mtimeNs);
     },
     set(value) {
       ObjectDefineProperty(this, 'mtimeInstant', { __proto__: null, value, writable: true });
@@ -578,7 +590,7 @@ const lazyTemporalBigIntFields = {
     enumerable: true,
     configurable: true,
     get() {
-      return this.ctimeInstant = new Temporal.Instant(this.ctimeNs);
+      return this.ctimeInstant = instantFromNs(this.ctimeNs);
     },
     set(value) {
       ObjectDefineProperty(this, 'ctimeInstant', { __proto__: null, value, writable: true });
@@ -589,7 +601,7 @@ const lazyTemporalBigIntFields = {
     enumerable: true,
     configurable: true,
     get() {
-      return this.birthtimeInstant = new Temporal.Instant(this.birthtimeNs);
+      return this.birthtimeInstant = instantFromNs(this.birthtimeNs);
     },
     set(value) {
       ObjectDefineProperty(this, 'birthtimeInstant', { __proto__: null, value, writable: true });