@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Time.ts

@@ -4,10 +4,17 @@
  * @module
  */
 
-import { assert } from "./Assert.js";
-import type { Brand } from "./Brand.js";
-import type { yieldNow } from "./Task.js";
-import { brand, type DateIso, lessThan, NonNegativeInt } from "./Type.js";
+import { assert } from "./Assert.ts";
+import type { Brand } from "./Brand.ts";
+import type { yieldNow } from "./Task.ts";
+import {
+  brand,
+  type DateIso,
+  lessThan,
+  type NonNaNNumber,
+  NonNegativeInt,
+  positive,
+} from "./Type.ts";
 import type {
   Digit,
   Digit1To23,
@@ -16,20 +23,43 @@ import type {
   Digit1To6,
   Digit1To9,
   Digit1To99,
-} from "./Types.js";
+} from "./Types.ts";
 
 /** Time and timer operations. */
 export interface Time {
-  /** Returns current time as Unix epoch milliseconds. */
-  readonly now: () => Millis;
+  readonly now: {
+    /** Returns current time as Unix epoch milliseconds. */
+    (): Millis;
 
-  /** Returns current time as an ISO 8601 UTC string. */
-  readonly nowDateIso: () => DateIso;
+    /** Returns current time as an ISO 8601 UTC string. */
+    (type: "DateIso"): DateIso;
+  };
+
+  readonly performance: {
+    /** Unix epoch timestamp used as the origin for `performance.now()`. */
+    readonly timeOrigin: PerformanceTimeOrigin;
+
+    /**
+     * Returns a high-resolution timestamp in milliseconds relative to
+     * `performance.timeOrigin`.
+     *
+     * Unlike {@link Time.now}, this value is not Unix epoch time and is
+     * unaffected by system clock adjustments. Like Node.js
+     * `process.hrtime.bigint()`, it is suitable for measuring elapsed time, but
+     * it uses the Web Performance API's number representation rather than
+     * nanoseconds as a bigint.
+     */
+    readonly now: () => PerformanceTime;
+  };
 
-  /** Schedules a callback after the specified delay. */
-  readonly setTimeout: (fn: () => void, delay: Duration) => TimeoutId;
+  /** Schedules a callback after the specified positive delay. */
+  readonly setTimeout: (fn: () => void, delay: PositiveDuration) => TimeoutId;
 
-  /** Cancels a timeout scheduled with {@link Time.setTimeout}. */
+  /**
+   * Cancels a timeout scheduled with this instance's {@link Time.setTimeout}.
+   *
+   * Throws if the timeout was scheduled by another {@link Time} instance.
+   */
   readonly clearTimeout: (id: TimeoutId) => void;
 }
 
@@ -44,39 +74,127 @@ export interface TimeDep {
  */
 export type TimeoutId = Brand<"TimeoutId">;
 
+interface TimeoutIdInternal {
+  readonly owner: symbol;
+  readonly clear: () => void;
+}
+
 /**
- * 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 = (): Time => {
-  const getNowMillis = (): Millis => Millis.orThrow(globalThis.Date.now());
+  const timeoutOwner = Symbol("Time");
+  function now(): Millis;
+  function now(type: "DateIso"): DateIso;
+  function now(type?: "DateIso"): Millis | DateIso {
+    const millis = getSystemNowMillis();
+    return type === "DateIso" ? millisToDateIso(millis) : millis;
+  }
 
   return {
-    now: () => getNowMillis(),
+    now,
 
-    nowDateIso: () => millisToDateIso(getNowMillis()),
+    performance: {
+      timeOrigin: globalThis.performance.timeOrigin as PerformanceTimeOrigin,
+      now: () => globalThis.performance.now() as PerformanceTime,
+    },
 
-    setTimeout: (callback, delay) =>
-      globalThis.setTimeout(
-        callback,
-        durationToMillis(delay),
-      ) as unknown as TimeoutId,
+    setTimeout: (callback, duration) =>
+      scheduleNativeTimeout(timeoutOwner, callback, duration),
 
     clearTimeout: (id) => {
-      globalThis.clearTimeout(id as unknown as number);
+      clearTimeoutId(timeoutOwner, id);
     },
   };
 };
 
+const scheduleNativeTimeout = (
+  owner: symbol,
+  callback: () => void,
+  duration: PositiveDuration,
+): TimeoutId => {
+  const delay = durationToMillis(duration);
+  let cancelled = false;
+  let nativeId: ReturnType<typeof globalThis.setTimeout>;
+
+  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 = (): void => {
+      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);
+    },
+  } as unknown as TimeoutId;
+};
+
+/**
+ * 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 => Millis.orThrow(globalThis.Date.now());
+
+const clearTimeoutId = (owner: symbol, id: TimeoutId): void => {
+  const internal = id as unknown as TimeoutIdInternal;
+  assert(
+    internal.owner === owner,
+    "TimeoutId was created by another Time instance",
+  );
+  internal.clear();
+};
+
 /**
  * Test {@link Time} with controllable timers.
  *
  * Call `advance(ms)` to move time forward and trigger any pending timeouts.
  */
 export interface TestTime extends Time {
-  /** Advances time by the specified duration, triggering pending timeouts. */
+  /**
+   * Advances time by the specified duration, triggering pending timeouts.
+   *
+   * Timeout callback errors propagate and leave time at the callback's
+   * deadline. Throws if called while another advance is in progress.
+   */
   readonly advance: (duration: Duration) => void;
 }
 
@@ -91,20 +209,23 @@ export interface TestTimeDep {
  * 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?: {
   readonly startAt?: Millis;
   readonly autoIncrement?: "microtask" | "sync";
 }): TestTime => {
-  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<number, { callback: () => void; runAt: number }>();
+  const pending = new Map<number, { callback: () => void; runAt: Millis }>();
   const incrementNow = (): void => {
     now = Millis.orThrow(now + 1);
   };
@@ -121,30 +242,65 @@ export const testCreateTime = (options?: {
     }
     return result;
   };
+  function getNow(): Millis;
+  function getNow(type: "DateIso"): DateIso;
+  function getNow(type?: "DateIso"): Millis | DateIso {
+    const millis = getNowMillis();
+    return type === "DateIso" ? millisToDateIso(millis) : millis;
+  }
 
   return {
-    now: () => getNowMillis(),
+    now: getNow,
 
-    nowDateIso: () => millisToDateIso(getNowMillis()),
+    performance: {
+      timeOrigin: Number(startAt) as PerformanceTimeOrigin,
+      now: () => (getNowMillis() - startAt) as PerformanceTime,
+    },
 
     setTimeout: (callback, delay) => {
+      const runAt = Millis.orThrow(now + durationToMillis(delay));
       const id = nextId++;
-      pending.set(id, { callback, runAt: now + durationToMillis(delay) });
-      return id as unknown as TimeoutId;
+      pending.set(id, { callback, runAt });
+      return {
+        owner: timeoutOwner,
+        clear: () => {
+          pending.delete(id);
+        },
+      } as unknown as TimeoutId;
     },
 
     clearTimeout: (id) => {
-      pending.delete(id as unknown as number);
+      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: number | null = 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;
       }
     },
   };
@@ -154,7 +310,7 @@ export const testCreateTime = (options?: {
 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
@@ -169,7 +325,11 @@ export const Millis = /*#__PURE__*/ brand(
   "Millis",
   /*#__PURE__*/ lessThan(maxMillisWithInfinity)(NonNegativeInt),
 );
-export type Millis = typeof Millis.Type;
+export type Millis = typeof Millis.Output;
+
+/** Positive {@link Millis} value. */
+export const PositiveMillis = /*#__PURE__*/ positive(Millis);
+export type PositiveMillis = typeof PositiveMillis.Output;
 
 /** Minimum {@link Millis} value. */
 export const minMillis = 0 as Millis;
@@ -181,7 +341,7 @@ export const maxMillis = (maxMillisWithInfinity - 1) as Millis;
  * Converts a number to {@link Millis}, rounding to the nearest millisecond and
  * saturating overflow at {@link maxMillis}.
  */
-export const saturateMillis = (value: number): Millis =>
+export const saturateMillis = (value: NonNaNNumber): Millis =>
   Millis.orNull(Math.max(0, Math.round(value))) ?? maxMillis;
 
 /**
@@ -193,12 +353,37 @@ export const saturateMillis = (value: number): Millis =>
 export const millisToDateIso = (value: Millis): DateIso =>
   new globalThis.Date(value).toISOString() as DateIso;
 
+/** Unix epoch milliseconds used as the origin for {@link PerformanceTime}. */
+export type PerformanceTimeOrigin = number & Brand<"PerformanceTimeOrigin">;
+
+/** High-resolution milliseconds elapsed since {@link PerformanceTimeOrigin}. */
+export type PerformanceTime = number & Brand<"PerformanceTime">;
+
+/** Elapsed fractional milliseconds measured using {@link PerformanceTime}. */
+export type PerformanceDuration = number & Brand<"PerformanceDuration">;
+
+/**
+ * Returns the elapsed fractional milliseconds between two performance times.
+ *
+ * Throws if `end` precedes `start`.
+ */
+export const performanceDurationBetween = (
+  start: PerformanceTime,
+  end: PerformanceTime,
+): PerformanceDuration => {
+  assert(end >= start, "Performance end time must not precede start time");
+  return (end - start) as PerformanceDuration;
+};
+
 /**
  * Duration can be either a {@link DurationLiteral} or milliseconds as
  * {@link Millis}.
  */
 export type Duration = DurationLiteral | Millis;
 
+/** Positive duration accepted by timer-based APIs. */
+export type PositiveDuration = DurationLiteral | PositiveMillis;
+
 /**
  * Duration literal with compile-time validation.
  *
@@ -213,9 +398,9 @@ export type Duration = DurationLiteral | Millis;
  * - Months: not supported (variable length)
  * - Years: `1y`, `99y`, `1.5y` (1-99, 1.1-99.9)
  *
- * Each unit is limited to values that can't be expressed in the next larger
- * unit, ensuring every duration has exactly one canonical representation (e.g.,
- * 1000ms must be written as `"1s"`, not `"1000ms"`).
+ * Each unit uses a bounded range. Where units convert exactly, this avoids
+ * equivalent representations (e.g., 1000ms must be written as `"1s"`, not
+ * `"1000ms"`).
  *
  * Decimal values cover cases like 1.5s (1500ms) or 1.5h (90 minutes) without
  * allowing redundant forms. For precise values that don't fit (e.g., 1050ms),
@@ -299,17 +484,20 @@ export type DurationLiteralYears =
  * ### 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)
+ * import { durationToMillis, Millis } from "@evolu/common";
+ *
+ * expect(durationToMillis("1.5s")).toBe(1500);
+ * expect(durationToMillis("5m")).toBe(300000);
+ * expect(durationToMillis("12h")).toBe(43200000);
+ * expect(durationToMillis("1w")).toBe(604800000);
+ * expect(durationToMillis(Millis.orThrow(5000))).toBe(5000);
  * ```
  */
-export const durationToMillis = (duration: Duration): Millis => {
+export function durationToMillis(
+  duration: DurationLiteral | PositiveMillis,
+): PositiveMillis;
+export function durationToMillis(duration: Duration): Millis;
+export function durationToMillis(duration: Duration): Millis {
   if (typeof duration === "number") return duration;
 
   const num = parseFloat(duration);
@@ -320,23 +508,7 @@ export const durationToMillis = (duration: Duration): Millis => {
   return Millis.orThrow(
     Math.round(num * durationUnits[unit as keyof typeof durationUnits]),
   );
-};
-
-/**
- * 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: Duration): Promise<void> =>
-  new Promise((resolve) => {
-    globalThis.setTimeout(resolve, durationToMillis(duration));
-  });
+}
 
 const durationUnits = {
   ms: 1,
@@ -377,39 +549,70 @@ export const msLongTask = 50 as Millis;
  *
  * - 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: Millis): string => {
-  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);
-    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);
-    return `${hours}h${minutes}m${seconds}s`;
-  }
+  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`;
+
+  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: Millis): string => {