chronokinesis 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## v8.1.0 - 2026-09-20
+
+- mock native `Temporal.Now` (Node >= 26) alongside `Date`, `Temporal.Now.timeZoneId()` honours timezone travel
+
+## v8.0.1 - 2026-09-13
+
+- use nullish coalescing and optional chaining internally, browser bundle now requires ES2020
+- replace `markdown-toc` script with `@0dep/toc`
+- drop build with node v18 due to dev deps
+
+## v8.0.0 - 2026-04-24
+
+### Breaking
+
+- mocks `process.hrtime([time])` and `process.hrtime.bigint()`
+- mocks `performance.now()`
+
+### Fixes
+
+- fix bug in travel that resulted in consumed milliseconds before returning
+
+## v7.0.1 - 2025-11-13
+
+- proof of provenance release
+
+## v7.0.0 - 2025-07-25
+
+### Breaking
+
+- when declaring "exports" field in package.json it takes prescedence over "main", thus breaking the exports default. Use `import * as ck from 'chronokinesis';`. A simple search & replace should fix this.
+
+### Fixes
+
+- attempt to mitigate issue #4 - multiple module load
+- export FakeDate
+- test faking dates with luxon
+- use prettier for formatting rules
+- use texample to run through README examples
+
+## v6.0.0 - 2023-08-09
+
+### Breaking
+
+- timezone function calls travel by default #3
+- timezone function signature also takes travel arguments
+
+## v5.0.0 - 2023-04-10
+
+- export as module with dist for require and umd
+
+## v4.0.1 - 2022-12-09
+
+- replace lab with mocha and chai
+- default to node v14
+- stop building node v10
+- bump babel and rollup
+- use c8 for coverage

package/README.md

@@ -24,11 +24,12 @@ Mock time and date for traveling and freezing. Inspired and borrowed from [timek
   - [Nodejs require](#nodejs-require)
   - [Browser (UMD)](#browser-umd)
 - [High-resolution clocks](#high-resolution-clocks)
+- [Temporal](#temporal)
 - [chronokinesis vs `node:test` mock timers](#chronokinesis-vs-nodetest-mock-timers)
 - [Caveats when mocking high-resolution clocks](#caveats-when-mocking-high-resolution-clocks)
 - [Acknowledgements](#acknowledgements)
 
-<!-- tocstop -->
+<!-- /toc -->
 
 ## Introduction
 
@@ -132,7 +133,7 @@ setTimeout(function () {
 }, 1500);
 ```
 
-When used in combination with [`freeze`](#freeze) the time is still frozen but at the travelled time().
+When used in combination with [`freeze`](#freezeargs) the time is still frozen but at the travelled time().
 
 ```javascript
 import * as ck from 'chronokinesis';
@@ -293,9 +294,27 @@ console.log(performance.now() - basePerf); //                    ≈ 1000 (ms)
 ck.reset();
 ```
 
+## Temporal
+
+When the runtime ships a native `Temporal` global (Node ≥ 26), the methods on `Temporal.Now` are patched in place while timekeeping is active, so `Temporal.Now.instant()` and friends follow the same frozen or travelled clock as `Date.now()`. `Temporal.Now.timeZoneId()` returns the travelled IANA zone while a [timezone traveller](#timezonetimezone-args) is active, so the zone-less variants (`zonedDateTimeISO()`, `plainDateTimeISO()`, `plainDateISO()`, `plainTimeISO()`) resolve in that zone. `reset()` restores the native methods by identity.
+
+Temporal polyfills that build `Temporal.Now` on top of `Date.now()` need no patching and keep working on older Node versions. Polyfills that prefer the native global when present pick up the mock automatically.
+
+```js
+import * as ck from 'chronokinesis';
+
+ck.timezone('Asia/Tokyo').freeze(1980, 0, 1, 12, 0);
+
+console.log(Temporal.Now.timeZoneId()); //                 Asia/Tokyo
+console.log(Temporal.Now.plainDateTimeISO().toString()); // 1980-01-01T12:00:00
+console.log(Temporal.Now.instant().epochMilliseconds === Date.now()); // true
+
+ck.reset();
+```
+
 ## chronokinesis vs `node:test` mock timers
 
-chronokinesis mocks **clocks only** — `Date`, `process.hrtime`, `performance.now`. Timers (`setTimeout`, `setInterval`, `setImmediate`) still run on the real wall clock; a `setTimeout(fn, 10)` under `freeze()` still fires ~10ms later in real time.
+chronokinesis mocks **clocks only** — `Date`, `process.hrtime`, `performance.now`, and native `Temporal.Now`. Timers (`setTimeout`, `setInterval`, `setImmediate`) still run on the real wall clock; a `setTimeout(fn, 10)` under `freeze()` still fires ~10ms later in real time.
 
 Node's built-in `node:test` provides `mock.timers` which is different: it mocks both the clock **and** the timer queue, and `mock.timers.tick(ms)` synchronously advances time and fires any timers scheduled within that window — no real waiting required.
 

package/dist/chronokinesis.cjs

@@ -12,7 +12,7 @@
    */
   const kNativeDate = Symbol.for('chronokinesis native date');
 
-  const NativeDate = Date[kNativeDate] || Date;
+  const NativeDate = Date[kNativeDate] ?? Date;
   const nativeGetTimezoneOffset = NativeDate.prototype.getTimezoneOffset;
 
   /* c8 ignore start -- environment-capability guards; false branches only hit in browser (isomorphic test) */
@@ -21,12 +21,16 @@
   const nativeHrtimeBigint = nativeHrtime && typeof nativeHrtime.bigint === 'function' ? nativeHrtime.bigint : null;
   const nativePerformance = typeof performance !== 'undefined' ? performance : null;
   const nativePerformanceNow = nativePerformance && typeof nativePerformance.now === 'function' ? nativePerformance.now : null;
+  // Native Temporal (Node >= 26) reads the OS clock directly in Temporal.Now, so any Temporal global
+  // present at load is patched in place alongside Date. Polyfills built on Date.now() would work unpatched.
+  const nativeTemporal = typeof Temporal !== 'undefined' && typeof Temporal.Now === 'object' ? Temporal : null;
+  const nativeTemporalNow = nativeTemporal && snapshotTemporalNow(nativeTemporal.Now);
 
   // Anchor native perf.now against native hrtime at module load so that later reads
   // can reconstruct real native perf.now even when process.hrtime has been swapped
   // (Node <22 wires performance.now to process.hrtime internally).
-  const perfAnchorMs = nativePerformanceNow ? nativePerformanceNow.call(nativePerformance) : 0;
-  const hrtimeAnchorNs = nativeHrtimeBigint ? nativeHrtimeBigint.call(nativeProcess) : 0n;
+  const perfAnchorMs = nativePerformanceNow?.call(nativePerformance) ?? 0;
+  const hrtimeAnchorNs = nativeHrtimeBigint?.call(nativeProcess) ?? 0n;
   /* c8 ignore stop */
 
   let freezedAt = null;
@@ -190,6 +194,7 @@
     if (nativePerformanceNow) {
       Object.defineProperty(nativePerformance, 'now', { value: fakePerformanceNow, configurable: true, writable: true });
     }
+    if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, fakeTemporalNow());
   }
 
   function useNativeDate() {
@@ -198,6 +203,7 @@
     if (nativePerformanceNow) {
       Object.defineProperty(nativePerformance, 'now', { value: nativePerformanceNow, configurable: true, writable: true });
     }
+    if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, {});
   }
 
   function time() {
@@ -231,8 +237,7 @@
   }
 
   function fakeHrtimeNs() {
-    if (freezedHrtimeNs !== null) return freezedHrtimeNs;
-    return nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
+    return freezedHrtimeNs ?? nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
   }
 
   function fakeHrtime(prev) {
@@ -254,8 +259,44 @@
   };
 
   function fakePerformanceNow() {
-    if (freezedPerformanceNow !== null) return freezedPerformanceNow;
-    return nativePerformanceNowFromHrtime() + performanceNowOffset;
+    return freezedPerformanceNow ?? nativePerformanceNowFromHrtime() + performanceNowOffset;
+  }
+
+  function snapshotTemporalNow(Now) {
+    const snapshot = {};
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(Now))) {
+      if (typeof descriptor.value === 'function') snapshot[key] = descriptor;
+    }
+    return snapshot;
+  }
+
+  function assignTemporalNow(Now, methods) {
+    for (const [key, descriptor] of Object.entries(nativeTemporalNow)) {
+      Object.defineProperty(Now, key, { ...descriptor, value: methods[key] ?? descriptor.value });
+    }
+  }
+
+  function fakeTemporalNow() {
+    return {
+      instant: fakeTemporalInstant,
+      timeZoneId: fakeTemporalTimeZoneId,
+      zonedDateTimeISO: fakeTemporalZonedDateTimeISO,
+      plainDateTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDateTime(),
+      plainDateISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDate(),
+      plainTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainTime(),
+    };
+  }
+
+  function fakeTemporalInstant() {
+    return nativeTemporal.Instant.fromEpochMilliseconds(currentMockedMs());
+  }
+
+  function fakeTemporalTimeZoneId() {
+    return iana ?? nativeTemporalNow.timeZoneId.value.call(nativeTemporal.Now);
+  }
+
+  function fakeTemporalZonedDateTimeISO(timeZone) {
+    return fakeTemporalInstant().toZonedDateTimeISO(timeZone ?? fakeTemporalTimeZoneId());
   }
 
   function instantiate(type, args) {

package/dist/index.cjs

@@ -8,7 +8,7 @@
  */
 const kNativeDate = Symbol.for('chronokinesis native date');
 
-const NativeDate = Date[kNativeDate] || Date;
+const NativeDate = Date[kNativeDate] ?? Date;
 const nativeGetTimezoneOffset = NativeDate.prototype.getTimezoneOffset;
 
 /* c8 ignore start -- environment-capability guards; false branches only hit in browser (isomorphic test) */
@@ -17,12 +17,16 @@ const nativeHrtime = nativeProcess && typeof nativeProcess.hrtime === 'function'
 const nativeHrtimeBigint = nativeHrtime && typeof nativeHrtime.bigint === 'function' ? nativeHrtime.bigint : null;
 const nativePerformance = typeof performance !== 'undefined' ? performance : null;
 const nativePerformanceNow = nativePerformance && typeof nativePerformance.now === 'function' ? nativePerformance.now : null;
+// Native Temporal (Node >= 26) reads the OS clock directly in Temporal.Now, so any Temporal global
+// present at load is patched in place alongside Date. Polyfills built on Date.now() would work unpatched.
+const nativeTemporal = typeof Temporal !== 'undefined' && typeof Temporal.Now === 'object' ? Temporal : null;
+const nativeTemporalNow = nativeTemporal && snapshotTemporalNow(nativeTemporal.Now);
 
 // Anchor native perf.now against native hrtime at module load so that later reads
 // can reconstruct real native perf.now even when process.hrtime has been swapped
 // (Node <22 wires performance.now to process.hrtime internally).
-const perfAnchorMs = nativePerformanceNow ? nativePerformanceNow.call(nativePerformance) : 0;
-const hrtimeAnchorNs = nativeHrtimeBigint ? nativeHrtimeBigint.call(nativeProcess) : 0n;
+const perfAnchorMs = nativePerformanceNow?.call(nativePerformance) ?? 0;
+const hrtimeAnchorNs = nativeHrtimeBigint?.call(nativeProcess) ?? 0n;
 /* c8 ignore stop */
 
 let freezedAt = null;
@@ -186,6 +190,7 @@ function useFakeDate() {
   if (nativePerformanceNow) {
     Object.defineProperty(nativePerformance, 'now', { value: fakePerformanceNow, configurable: true, writable: true });
   }
+  if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, fakeTemporalNow());
 }
 
 function useNativeDate() {
@@ -194,6 +199,7 @@ function useNativeDate() {
   if (nativePerformanceNow) {
     Object.defineProperty(nativePerformance, 'now', { value: nativePerformanceNow, configurable: true, writable: true });
   }
+  if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, {});
 }
 
 function time() {
@@ -227,8 +233,7 @@ function shiftAndLockFakeClocks(deltaMs) {
 }
 
 function fakeHrtimeNs() {
-  if (freezedHrtimeNs !== null) return freezedHrtimeNs;
-  return nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
+  return freezedHrtimeNs ?? nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
 }
 
 function fakeHrtime(prev) {
@@ -250,8 +255,44 @@ fakeHrtime.bigint = function fakeHrtimeBigint() {
 };
 
 function fakePerformanceNow() {
-  if (freezedPerformanceNow !== null) return freezedPerformanceNow;
-  return nativePerformanceNowFromHrtime() + performanceNowOffset;
+  return freezedPerformanceNow ?? nativePerformanceNowFromHrtime() + performanceNowOffset;
+}
+
+function snapshotTemporalNow(Now) {
+  const snapshot = {};
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(Now))) {
+    if (typeof descriptor.value === 'function') snapshot[key] = descriptor;
+  }
+  return snapshot;
+}
+
+function assignTemporalNow(Now, methods) {
+  for (const [key, descriptor] of Object.entries(nativeTemporalNow)) {
+    Object.defineProperty(Now, key, { ...descriptor, value: methods[key] ?? descriptor.value });
+  }
+}
+
+function fakeTemporalNow() {
+  return {
+    instant: fakeTemporalInstant,
+    timeZoneId: fakeTemporalTimeZoneId,
+    zonedDateTimeISO: fakeTemporalZonedDateTimeISO,
+    plainDateTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDateTime(),
+    plainDateISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDate(),
+    plainTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainTime(),
+  };
+}
+
+function fakeTemporalInstant() {
+  return nativeTemporal.Instant.fromEpochMilliseconds(currentMockedMs());
+}
+
+function fakeTemporalTimeZoneId() {
+  return iana ?? nativeTemporalNow.timeZoneId.value.call(nativeTemporal.Now);
+}
+
+function fakeTemporalZonedDateTimeISO(timeZone) {
+  return fakeTemporalInstant().toZonedDateTimeISO(timeZone ?? fakeTemporalTimeZoneId());
 }
 
 function instantiate(type, args) {

package/index.js

@@ -6,7 +6,7 @@
  */
 const kNativeDate = Symbol.for('chronokinesis native date');
 
-const NativeDate = Date[kNativeDate] || Date;
+const NativeDate = Date[kNativeDate] ?? Date;
 const nativeGetTimezoneOffset = NativeDate.prototype.getTimezoneOffset;
 
 /* c8 ignore start -- environment-capability guards; false branches only hit in browser (isomorphic test) */
@@ -15,12 +15,16 @@ const nativeHrtime = nativeProcess && typeof nativeProcess.hrtime === 'function'
 const nativeHrtimeBigint = nativeHrtime && typeof nativeHrtime.bigint === 'function' ? nativeHrtime.bigint : null;
 const nativePerformance = typeof performance !== 'undefined' ? performance : null;
 const nativePerformanceNow = nativePerformance && typeof nativePerformance.now === 'function' ? nativePerformance.now : null;
+// Native Temporal (Node >= 26) reads the OS clock directly in Temporal.Now, so any Temporal global
+// present at load is patched in place alongside Date. Polyfills built on Date.now() would work unpatched.
+const nativeTemporal = typeof Temporal !== 'undefined' && typeof Temporal.Now === 'object' ? Temporal : null;
+const nativeTemporalNow = nativeTemporal && snapshotTemporalNow(nativeTemporal.Now);
 
 // Anchor native perf.now against native hrtime at module load so that later reads
 // can reconstruct real native perf.now even when process.hrtime has been swapped
 // (Node <22 wires performance.now to process.hrtime internally).
-const perfAnchorMs = nativePerformanceNow ? nativePerformanceNow.call(nativePerformance) : 0;
-const hrtimeAnchorNs = nativeHrtimeBigint ? nativeHrtimeBigint.call(nativeProcess) : 0n;
+const perfAnchorMs = nativePerformanceNow?.call(nativePerformance) ?? 0;
+const hrtimeAnchorNs = nativeHrtimeBigint?.call(nativeProcess) ?? 0n;
 /* c8 ignore stop */
 
 let freezedAt = null;
@@ -184,6 +188,7 @@ function useFakeDate() {
   if (nativePerformanceNow) {
     Object.defineProperty(nativePerformance, 'now', { value: fakePerformanceNow, configurable: true, writable: true });
   }
+  if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, fakeTemporalNow());
 }
 
 function useNativeDate() {
@@ -192,6 +197,7 @@ function useNativeDate() {
   if (nativePerformanceNow) {
     Object.defineProperty(nativePerformance, 'now', { value: nativePerformanceNow, configurable: true, writable: true });
   }
+  if (nativeTemporalNow) assignTemporalNow(nativeTemporal.Now, {});
 }
 
 function time() {
@@ -225,8 +231,7 @@ function shiftAndLockFakeClocks(deltaMs) {
 }
 
 function fakeHrtimeNs() {
-  if (freezedHrtimeNs !== null) return freezedHrtimeNs;
-  return nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
+  return freezedHrtimeNs ?? nativeHrtimeBigint.call(nativeProcess) + hrtimeOffset;
 }
 
 function fakeHrtime(prev) {
@@ -248,8 +253,44 @@ fakeHrtime.bigint = function fakeHrtimeBigint() {
 };
 
 function fakePerformanceNow() {
-  if (freezedPerformanceNow !== null) return freezedPerformanceNow;
-  return nativePerformanceNowFromHrtime() + performanceNowOffset;
+  return freezedPerformanceNow ?? nativePerformanceNowFromHrtime() + performanceNowOffset;
+}
+
+function snapshotTemporalNow(Now) {
+  const snapshot = {};
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(Now))) {
+    if (typeof descriptor.value === 'function') snapshot[key] = descriptor;
+  }
+  return snapshot;
+}
+
+function assignTemporalNow(Now, methods) {
+  for (const [key, descriptor] of Object.entries(nativeTemporalNow)) {
+    Object.defineProperty(Now, key, { ...descriptor, value: methods[key] ?? descriptor.value });
+  }
+}
+
+function fakeTemporalNow() {
+  return {
+    instant: fakeTemporalInstant,
+    timeZoneId: fakeTemporalTimeZoneId,
+    zonedDateTimeISO: fakeTemporalZonedDateTimeISO,
+    plainDateTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDateTime(),
+    plainDateISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainDate(),
+    plainTimeISO: (timeZone) => fakeTemporalZonedDateTimeISO(timeZone).toPlainTime(),
+  };
+}
+
+function fakeTemporalInstant() {
+  return nativeTemporal.Instant.fromEpochMilliseconds(currentMockedMs());
+}
+
+function fakeTemporalTimeZoneId() {
+  return iana ?? nativeTemporalNow.timeZoneId.value.call(nativeTemporal.Now);
+}
+
+function fakeTemporalZonedDateTimeISO(timeZone) {
+  return fakeTemporalInstant().toZonedDateTimeISO(timeZone ?? fakeTemporalTimeZoneId());
 }
 
 function instantiate(type, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chronokinesis",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Module for testing time-dependent code",
   "author": {
     "name": "Pål Edman",
@@ -23,20 +23,21 @@
     "types": "./index.d.ts"
   },
   "scripts": {
-    "toc": "node generate-api-toc.cjs",
     "test": "mocha",
+    "posttest": "npm run lint && npm run dist && texample -g",
     "lint": "eslint . --cache && prettier . --check --cache",
     "test:lcov": "c8 -r lcov -r text mocha && npm run lint",
     "cov:html": "c8 mocha -R dot && c8 report --reporter html",
-    "posttest": "npm run lint && npm run dist && texample -g",
     "prepack": "npm run dist",
+    "toc": "toc -c README.md",
     "dist": "npm run toc && rollup -c"
   },
   "files": [
     "index.js",
     "index.d.ts",
     "dist/chronokinesis.cjs",
-    "dist/index.cjs"
+    "dist/index.cjs",
+    "CHANGELOG.md"
   ],
   "bugs": {
     "url": "https://github.com/paed01/chronokinesis/issues"
@@ -46,6 +47,7 @@
     "time",
     "hrtime",
     "performance",
+    "temporal",
     "timezone",
     "fake",
     "mock",
@@ -56,18 +58,21 @@
     "fake now"
   ],
   "devDependencies": {
+    "@0dep/toc": "^2.1.0",
+    "@eslint/js": "^10.0.1",
+    "@js-temporal/polyfill": "^0.5.1",
     "@rollup/plugin-commonjs": "^29.0.0",
-    "c8": "^10.1.2",
+    "c8": "^12.0.0",
     "chai": "^6.2.0",
-    "eslint": "^9.3.0",
-    "happy-dom": "^17.6.1",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "happy-dom": "^20.14.5",
     "lodash.clonedeep": "^4.5.0",
     "luxon": "^3.7.1",
-    "markdown-toc": "^1.2.0",
-    "mocha": "^11.0.1",
+    "mocha": "^12.0.1",
     "moment": "^2.30.1",
     "prettier": "^3.2.5",
     "rollup": "^4.12.1",
-    "texample": "^0.1.0"
+    "texample": "^1.0.2"
   }
 }