@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Time.js

@@ -4,24 +4,86 @@
  * @module
  */
 import { assert } from "./Assert.js";
-import { brand, lessThan, NonNegativeInt } from "./Type.js";
+import { brand, lessThan, NonNegativeInt, positive, } from "./Type.js";
 /**
- * Creates a {@link Time} using `Date.now()` and `globalThis.setTimeout`.
+ * Creates a {@link Time} using `Date.now()`, `performance`, and
+ * `globalThis.setTimeout`.
+ *
+ * Long timeouts are split into native timer chunks and tracked against an
+ * absolute wall-clock deadline so late callback execution and system suspension
+ * do not extend the requested delay. System clock adjustments can therefore
+ * shorten or lengthen long timeouts.
  *
  * Throws if the system clock returns an out-of-range value. This is intentional
  * — there's no reasonable fallback for a misconfigured clock.
  */
 export const createTime = () => {
-    const getNowMillis = () => Millis.orThrow(globalThis.Date.now());
+    const timeoutOwner = Symbol("Time");
+    function now(type) {
+        const millis = getSystemNowMillis();
+        return type === "DateIso" ? millisToDateIso(millis) : millis;
+    }
     return {
-        now: () => getNowMillis(),
-        nowDateIso: () => millisToDateIso(getNowMillis()),
-        setTimeout: (callback, delay) => globalThis.setTimeout(callback, durationToMillis(delay)),
+        now,
+        performance: {
+            timeOrigin: globalThis.performance.timeOrigin,
+            now: () => globalThis.performance.now(),
+        },
+        setTimeout: (callback, duration) => scheduleNativeTimeout(timeoutOwner, callback, duration),
         clearTimeout: (id) => {
-            globalThis.clearTimeout(id);
+            clearTimeoutId(timeoutOwner, id);
+        },
+    };
+};
+const scheduleNativeTimeout = (owner, callback, duration) => {
+    const delay = durationToMillis(duration);
+    let cancelled = false;
+    let nativeId;
+    if (delay <= maxNativeTimeoutMillis) {
+        nativeId = globalThis.setTimeout(() => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            callback();
+        }, delay);
+    }
+    else {
+        // Recompute each chunk from one absolute deadline so time elapsed while the
+        // event loop is suspended, for example during system sleep, is not added again.
+        const deadline = getSystemNowMillis() + delay;
+        const onTimeout = () => {
+            if (cancelled)
+                return;
+            const remaining = deadline - getSystemNowMillis();
+            if (remaining > 0) {
+                nativeId = globalThis.setTimeout(onTimeout, Math.min(remaining, maxNativeTimeoutMillis));
+                return;
+            }
+            cancelled = true;
+            callback();
+        };
+        nativeId = globalThis.setTimeout(onTimeout, maxNativeTimeoutMillis);
+    }
+    return {
+        owner,
+        clear: () => {
+            cancelled = true;
+            globalThis.clearTimeout(nativeId);
         },
     };
 };
+/**
+ * Maximum delay supported reliably by native timers: the largest positive
+ * signed 32-bit integer, approximately 24.9 days in milliseconds. Longer
+ * logical delays are scheduled in chunks to avoid native timer overflow.
+ */
+const maxNativeTimeoutMillis = 2 ** 31 - 1;
+const getSystemNowMillis = () => Millis.orThrow(globalThis.Date.now());
+const clearTimeoutId = (owner, id) => {
+    const internal = id;
+    assert(internal.owner === owner, "TimeoutId was created by another Time instance");
+    internal.clear();
+};
 /**
  * Creates a {@link TestTime} with controllable timers for testing.
  *
@@ -29,15 +91,18 @@ export const createTime = () => {
  * called. Timeouts scheduled via `setTimeout` fire when time is advanced past
  * their deadline.
  *
- * Set `autoIncrement` to automatically increment time by 1ms after each `now()`
- * call. `"microtask"` increments after the current turn, while `"sync"`
- * increments immediately after each read. Omit it to keep time fixed until
- * `advance()` is called.
+ * Set `autoIncrement` to automatically increment time by 1ms after each
+ * wall-clock or performance `now()` call. `"microtask"` increments after the
+ * current turn, while `"sync"` increments immediately after each read. Omit it
+ * to keep time fixed until `advance()` is called.
  */
 export const testCreateTime = (options) => {
-    let now = options?.startAt ?? minMillis;
+    const startAt = options?.startAt ?? minMillis;
     const autoIncrement = options?.autoIncrement;
+    const timeoutOwner = Symbol("TestTime");
+    let now = startAt;
     let nextId = 1;
+    let advancing = false;
     const pending = new Map();
     const incrementNow = () => {
         now = Millis.orThrow(now + 1);
@@ -54,24 +119,55 @@ export const testCreateTime = (options) => {
         }
         return result;
     };
+    function getNow(type) {
+        const millis = getNowMillis();
+        return type === "DateIso" ? millisToDateIso(millis) : millis;
+    }
     return {
-        now: () => getNowMillis(),
-        nowDateIso: () => millisToDateIso(getNowMillis()),
+        now: getNow,
+        performance: {
+            timeOrigin: Number(startAt),
+            now: () => (getNowMillis() - startAt),
+        },
         setTimeout: (callback, delay) => {
+            const runAt = Millis.orThrow(now + durationToMillis(delay));
             const id = nextId++;
-            pending.set(id, { callback, runAt: now + durationToMillis(delay) });
-            return id;
+            pending.set(id, { callback, runAt });
+            return {
+                owner: timeoutOwner,
+                clear: () => {
+                    pending.delete(id);
+                },
+            };
         },
         clearTimeout: (id) => {
-            pending.delete(id);
+            clearTimeoutId(timeoutOwner, id);
         },
         advance: (duration) => {
-            now = Millis.orThrow(now + durationToMillis(duration));
-            for (const [id, timeout] of pending) {
-                if (timeout.runAt <= now) {
-                    pending.delete(id);
+            assert(!advancing, "TestTime.advance cannot be called while advancing");
+            const target = Millis.orThrow(now + durationToMillis(duration));
+            advancing = true;
+            try {
+                while (pending.size > 0) {
+                    let earliestId = null;
+                    let nextRunAt = Number.POSITIVE_INFINITY;
+                    for (const [id, timeout] of pending) {
+                        if (timeout.runAt <= target && timeout.runAt < nextRunAt) {
+                            earliestId = id;
+                            nextRunAt = timeout.runAt;
+                        }
+                    }
+                    if (earliestId === null)
+                        break;
+                    const timeout = pending.get(earliestId);
+                    pending.delete(earliestId);
+                    now = Millis.orThrow(Math.max(now, nextRunAt));
                     timeout.callback();
                 }
+                now = Millis.orThrow(Math.max(now, target));
+            }
+            finally {
+                advancing = false;
             }
         },
     };
@@ -79,7 +175,7 @@ export const testCreateTime = (options) => {
 // Literal (not expression like 1 + 2) to preserve type for Brand<"LessThan...">
 const maxMillisWithInfinity = 281474976710655;
 /**
- * Milliseconds timestamp, like `Date.now()`.
+ * Non-negative integer milliseconds used for timestamps and durations.
  *
  * The maximum value is 281474976710654 (281474976710655 - 1, reserved for
  * infinity). This enables efficient binary serialization, saving 2 bytes
@@ -92,6 +188,8 @@ const maxMillisWithInfinity = 281474976710655;
  */
 export const Millis = /*#__PURE__*/ brand("Millis", 
 /*#__PURE__*/ lessThan(maxMillisWithInfinity)(NonNegativeInt));
+/** Positive {@link Millis} value. */
+export const PositiveMillis = /*#__PURE__*/ positive(Millis);
 /** Minimum {@link Millis} value. */
 export const minMillis = 0;
 /** Maximum {@link Millis} value. */
@@ -109,46 +207,22 @@ export const saturateMillis = (value) => Millis.orNull(Math.max(0, Math.round(va
  */
 export const millisToDateIso = (value) => new globalThis.Date(value).toISOString();
 /**
- * Converts a duration to milliseconds.
+ * Returns the elapsed fractional milliseconds between two performance times.
  *
- * Accepts either a {@link DurationLiteral} (e.g., "5m", "1.5s") or
- * {@link Millis}.
- *
- * ### Example
- *
- * ```ts
- * durationToMillis("1ms"); // 1
- * durationToMillis("500ms"); // 500
- * durationToMillis("1.5s"); // 1500
- * durationToMillis("30s"); // 30000
- * durationToMillis("5m"); // 300000
- * durationToMillis("12h"); // 43200000
- * durationToMillis("7d"); // 604800000
- * durationToMillis(Millis.orThrow(5000)); // 5000 (already Millis)
- * ```
+ * Throws if `end` precedes `start`.
  */
-export const durationToMillis = (duration) => {
+export const performanceDurationBetween = (start, end) => {
+    assert(end >= start, "Performance end time must not precede start time");
+    return (end - start);
+};
+export function durationToMillis(duration) {
     if (typeof duration === "number")
         return duration;
     const num = parseFloat(duration);
     const unit = duration.endsWith("ms") ? "ms" : duration.at(-1);
     assert(unit in durationUnits, `Unknown duration unit: ${unit}`);
     return Millis.orThrow(Math.round(num * durationUnits[unit]));
-};
-/**
- * Returns a Promise that resolves after the specified duration.
- *
- * Uses {@link Duration} parsing and `globalThis.setTimeout`.
- *
- * ### Example
- *
- * ```ts
- * await setTimeout("1ms");
- * ```
- */
-export const setTimeout = (duration) => new Promise((resolve) => {
-    globalThis.setTimeout(resolve, durationToMillis(duration));
-});
+}
 const durationUnits = {
     ms: 1,
     s: 1000,
@@ -184,40 +258,65 @@ export const msLongTask = 50;
  *
  * - Under 1 minute: `1.234s`
  * - Under 1 hour: `1m30.000s`
- * - 1 hour or more: `1h30m45.000s`
+ * - Under 1 day: `1h30m45.000s`
+ * - Under 1 week: `1d2h30m45.000s`
+ * - Under 1 year: `1w2d3h30m45.000s`
+ * - 1 year or more: `1y2w3d4h30m45.000s`
+ *
+ * Weeks are 7 days and years are 365 days.
  *
  * ### Example
  *
  * ```ts
- * formatMillisAsDuration(1234 as Millis); // "1.234s"
- * formatMillisAsDuration(90000 as Millis); // "1m30.000s"
- * formatMillisAsDuration(3661000 as Millis); // "1h1m1.000s"
+ * import { formatMillisAsDuration, Millis } from "@evolu/common";
+ *
+ * expect(formatMillisAsDuration(Millis.orThrow(1234))).toBe("1.234s");
+ * expect(formatMillisAsDuration(Millis.orThrow(90000))).toBe("1m30.000s");
+ * expect(formatMillisAsDuration(Millis.orThrow(90061000))).toBe(
+ *   "1d1h1m1.000s",
+ * );
  * ```
  */
 export const formatMillisAsDuration = (millis) => {
-    const elapsed = millis / 1000;
-    if (elapsed < 60) {
-        return `${elapsed.toFixed(3)}s`;
-    }
-    else if (elapsed < 3600) {
-        const minutes = Math.floor(elapsed / 60);
-        const seconds = (elapsed % 60).toFixed(3);
+    const seconds = ((millis % durationUnits.m) / durationUnits.s).toFixed(3);
+    if (millis < durationUnits.m)
+        return `${seconds}s`;
+    const minutes = Math.floor(millis / durationUnits.m) % 60;
+    if (millis < durationUnits.h)
         return `${minutes}m${seconds}s`;
-    }
-    else {
-        const hours = Math.floor(elapsed / 3600);
-        const minutes = Math.floor((elapsed % 3600) / 60);
-        const seconds = ((elapsed % 3600) % 60).toFixed(3);
+    const hours = Math.floor(millis / durationUnits.h) % 24;
+    if (millis < durationUnits.d)
         return `${hours}h${minutes}m${seconds}s`;
-    }
+    const daysAfterYears = Math.floor((millis % durationUnits.y) / durationUnits.d);
+    const days = daysAfterYears % 7;
+    if (millis < durationUnits.w)
+        return `${days}d${hours}h${minutes}m${seconds}s`;
+    const weeks = Math.floor(daysAfterYears / 7);
+    if (millis < durationUnits.y)
+        return `${weeks}w${days}d${hours}h${minutes}m${seconds}s`;
+    const years = Math.floor(millis / durationUnits.y);
+    return `${years}y${weeks}w${days}d${hours}h${minutes}m${seconds}s`;
 };
 /**
- * Formats {@link Millis} as `HH:MM:SS.mmm`.
+ * Formats {@link Millis} as local time in `HH:MM:SS.mmm` format.
  *
  * ### Example
  *
  * ```ts
- * formatMillisAsClockTime(Millis.orThrow(Date.now())); // "14:32:15.234"
+ * import { formatMillisAsClockTime, Millis } from "@evolu/common";
+ *
+ * const timestamp = new globalThis.Date(
+ *   2026,
+ *   0,
+ *   28,
+ *   14,
+ *   32,
+ *   15,
+ *   234,
+ * ).getTime();
+ * expect(formatMillisAsClockTime(Millis.orThrow(timestamp))).toBe(
+ *   "14:32:15.234",
+ * );
  * ```
  */
 export const formatMillisAsClockTime = (millis) => {