@evolu/common 8.6.2 → 8.8.0

package/dist/src/Test.js

@@ -1,14 +1,57 @@
 /**
  * Cross-module test utilities for deterministic testing.
  *
- * Test helpers are usually colocated with the code they test. Helpers that
- * cannot be colocated because they would create dependency cycles belong here.
+ * Test helpers are usually colocated with the code they test. General helpers
+ * shared across unrelated modules, or helpers whose colocation would create
+ * dependency cycles, belong here.
  *
  * @module
  */
 import { testCreateRandomBytes } from "./Crypto.js";
 import { testCreateRandomLib } from "./Random.js";
 import { createId } from "./Type.js";
+/**
+ * Temporarily replaces a global property for a test scope.
+ *
+ * Node.js can mock existing globals with `t.mock.property`, but it rejects a
+ * property that does not exist. That catches misspelled mock targets, but it
+ * cannot model optional platform globals whose presence varies. Use this helper
+ * to provide such a global, for example `scheduler`, or replace a global with
+ * `undefined` to exercise a fallback.
+ *
+ * The original property descriptor is restored on disposal. A property that did
+ * not exist is deleted. Prefer dependency injection when available because
+ * global properties are shared by concurrently running tests.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertFalse, testStubGlobal } from "@evolu/common";
+ *
+ * const key = Symbol("test global");
+ * {
+ *   using _stub = testStubGlobal(key, 42);
+ *   assertEqual(Reflect.get(globalThis, key), 42);
+ * }
+ * assertFalse(Reflect.has(globalThis, key));
+ * ```
+ */
+export const testStubGlobal = (key, value) => {
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+    Object.defineProperty(globalThis, key, {
+        configurable: true,
+        value,
+        writable: true,
+    });
+    const disposer = new DisposableStack();
+    disposer.defer(() => {
+        if (descriptor === undefined)
+            Reflect.deleteProperty(globalThis, key);
+        else
+            Object.defineProperty(globalThis, key, descriptor);
+    });
+    return disposer;
+};
 /**
  * Creates a deterministic `createId` helper.
  *
@@ -41,7 +84,7 @@ import { createId } from "./Type.js";
  *
  * const replayCreateId = testCreateId();
  * assertEqual(replayCreateId(), callbackId);
- * assertType<Id & Brand<"Todo">, typeof todoId>();
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
  * ```
  */
 export const testCreateId = () => {

package/dist/src/Time.d.ts

@@ -151,7 +151,7 @@ export declare const performanceDurationBetween: (start: PerformanceTime, end: P
  * const readableSchedule = spaced("1s");
  * const validatedSchedule = spaced(Millis.orThrow(1000));
  *
- * assertType<typeof validatedSchedule, typeof readableSchedule>();
+ * assertType<typeof readableSchedule, typeof validatedSchedule>();
  * ```
  */
 export type Duration = DurationLiteral | Millis;
@@ -169,7 +169,7 @@ export type Duration = DurationLiteral | Millis;
  * const readableSleep = sleep("1s");
  * const validatedSleep = sleep(PositiveMillis.orThrow(1000));
  *
- * assertType<typeof validatedSleep, typeof readableSleep>();
+ * assertType<typeof readableSleep, typeof validatedSleep>();
  * ```
  */
 export type PositiveDuration = DurationLiteral | PositiveMillis;
@@ -326,15 +326,7 @@ export declare const formatMillisAsDuration: (millis: Millis) => string;
  *   Millis,
  * } from "@evolu/common";
  *
- * const timestamp = new globalThis.Date(
- *   2026,
- *   0,
- *   28,
- *   14,
- *   32,
- *   15,
- *   234,
- * ).getTime();
+ * const timestamp = new Date(2026, 0, 28, 14, 32, 15, 234).getTime();
  * assertEqual(
  *   formatMillisAsClockTime(Millis.orThrow(timestamp)),
  *   "14:32:15.234",

package/dist/src/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}

package/dist/src/Time.js

@@ -27,8 +27,8 @@ export const createTime = () => {
     return {
         now,
         performance: {
-            timeOrigin: globalThis.performance.timeOrigin,
-            now: () => globalThis.performance.now(),
+            timeOrigin: performance.timeOrigin,
+            now: () => performance.now(),
         },
         setTimeout: (callback, duration) => scheduleNativeTimeout(timeoutOwner, callback, duration),
         clearTimeout: (id) => {
@@ -41,7 +41,7 @@ const scheduleNativeTimeout = (owner, callback, duration) => {
     let cancelled = false;
     let nativeId;
     if (delay <= maxNativeTimeoutMillis) {
-        nativeId = globalThis.setTimeout(() => {
+        nativeId = setTimeout(() => {
             if (cancelled)
                 return;
             cancelled = true;
@@ -57,19 +57,19 @@ const scheduleNativeTimeout = (owner, callback, duration) => {
                 return;
             const remaining = deadline - getSystemNowMillis();
             if (remaining > 0) {
-                nativeId = globalThis.setTimeout(onTimeout, Math.min(remaining, maxNativeTimeoutMillis));
+                nativeId = setTimeout(onTimeout, Math.min(remaining, maxNativeTimeoutMillis));
                 return;
             }
             cancelled = true;
             callback();
         };
-        nativeId = globalThis.setTimeout(onTimeout, maxNativeTimeoutMillis);
+        nativeId = setTimeout(onTimeout, maxNativeTimeoutMillis);
     }
     return {
         owner,
         clear: () => {
             cancelled = true;
-            globalThis.clearTimeout(nativeId);
+            clearTimeout(nativeId);
         },
     };
 };
@@ -79,7 +79,7 @@ const scheduleNativeTimeout = (owner, callback, duration) => {
  * logical delays are scheduled in chunks to avoid native timer overflow.
  */
 const maxNativeTimeoutMillis = 2 ** 31 - 1;
-const getSystemNowMillis = () => Millis.orThrow(globalThis.Date.now());
+const getSystemNowMillis = () => Millis.orThrow(Date.now());
 const clearTimeoutId = (owner, id) => {
     const internal = id;
     assert(internal.owner === owner, "TimeoutId was created by another Time instance");
@@ -210,7 +210,7 @@ export const saturateMillis = (value) => Millis.orNull(Math.max(0, Math.round(va
  * This is a safe cast because {@link Millis} guarantees a valid timestamp range
  * that always produces a valid ISO string.
  */
-export const millisToDateIso = (value) => new globalThis.Date(value).toISOString();
+export const millisToDateIso = (value) => new Date(value).toISOString();
 /**
  * Returns the elapsed fractional milliseconds between two performance times.
  *
@@ -397,15 +397,7 @@ export const formatMillisAsDuration = (millis) => {
  *   Millis,
  * } from "@evolu/common";
  *
- * const timestamp = new globalThis.Date(
- *   2026,
- *   0,
- *   28,
- *   14,
- *   32,
- *   15,
- *   234,
- * ).getTime();
+ * const timestamp = new Date(2026, 0, 28, 14, 32, 15, 234).getTime();
  * assertEqual(
  *   formatMillisAsClockTime(Millis.orThrow(timestamp)),
  *   "14:32:15.234",
@@ -413,7 +405,7 @@ export const formatMillisAsDuration = (millis) => {
  * ```
  */
 export const formatMillisAsClockTime = (millis) => {
-    const date = new globalThis.Date(millis);
+    const date = new Date(millis);
     const hours = date.getHours().toString().padStart(2, "0");
     const minutes = date.getMinutes().toString().padStart(2, "0");
     const seconds = date.getSeconds().toString().padStart(2, "0");