@evolu/common 7.4.1 → 8.0.0-next.0

package/src/Time.ts

@@ -1,10 +1,36 @@
+/**
+ * Time representations, durations, and scheduling utilities.
+ *
+ * @module
+ */
+
 import { assert } from "./Assert.js";
-import { DateIso, NonNegativeInt } from "./Type.js";
+import type { Brand } from "./Brand.js";
+import type { yieldNow } from "./Task.js";
+import { brand, type DateIso, lessThan, NonNegativeInt } from "./Type.js";
+import type {
+  Digit,
+  Digit1To23,
+  Digit1To51,
+  Digit1To59,
+  Digit1To6,
+  Digit1To9,
+  Digit1To99,
+} from "./Types.js";
 
-/** Retrieves the current time in milliseconds, similar to `Date.now()`. */
+/** Time and timer operations. */
 export interface Time {
-  readonly now: () => number;
-  readonly nowIso: () => DateIso;
+  /** Returns current time as Unix epoch milliseconds. */
+  readonly now: () => Millis;
+
+  /** Returns current time as an ISO 8601 UTC string. */
+  readonly nowDateIso: () => DateIso;
+
+  /** Schedules a callback after the specified delay. */
+  readonly setTimeout: (fn: () => void, delay: Duration) => TimeoutId;
+
+  /** Cancels a timeout scheduled with {@link Time.setTimeout}. */
+  readonly clearTimeout: (id: TimeoutId) => void;
 }
 
 export interface TimeDep {
@@ -12,194 +38,371 @@ export interface TimeDep {
 }
 
 /**
- * Creates a {@link Time} using Date.now().
+ * Opaque type for timeout handles.
  *
- * If the system clock is misconfigured (out of allowed range), the application
- * will fail with an assertion error. This is intentional - there's no
- * reasonable fallback when the system clock is fundamentally wrong.
+ * Use with {@link Time.clearTimeout} to cancel a pending timeout.
+ */
+export type TimeoutId = Brand<"TimeoutId">;
+
+/**
+ * Creates a {@link Time} using `Date.now()` and `globalThis.setTimeout`.
+ *
+ * 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 time: Time = {
-    now: () => {
-      const iso = time.nowIso();
-      return new globalThis.Date(iso).getTime();
-    },
-    nowIso: () => {
-      const iso = new globalThis.Date().toISOString();
-      assert(DateIso.is(iso), "System clock returned invalid ISO date");
-      return iso;
+  const getNowMillis = (): Millis => Millis.orThrow(globalThis.Date.now());
+
+  return {
+    now: () => getNowMillis(),
+
+    nowDateIso: () => millisToDateIso(getNowMillis()),
+
+    setTimeout: (callback, delay) =>
+      globalThis.setTimeout(
+        callback,
+        durationToMillis(delay),
+      ) as unknown as TimeoutId,
+
+    clearTimeout: (id) => {
+      globalThis.clearTimeout(id as unknown as number);
     },
   };
-  return time;
 };
 
 /**
- * Creates a {@link Time} that returns a monotonically increasing number based on
- * a queueMicrotask.
+ * 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. */
+  readonly advance: (duration: Duration) => void;
+}
+
+export interface TestTimeDep {
+  readonly time: TestTime;
+}
+
+/**
+ * Creates a {@link TestTime} with controllable timers for testing.
+ *
+ * Time starts at `startAt` (default 0) and only advances when `advance()` is
+ * 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 via microtask (useful for tests that need monotonically increasing
+ * values without explicit `advance()` calls).
  */
-export const createTestTime = (): Time => {
-  let now = 0;
-  const time: Time = {
-    now: () => {
-      const current = now;
+export const testCreateTime = (options?: {
+  readonly startAt?: Millis;
+  readonly autoIncrement?: boolean;
+}): TestTime => {
+  let now = options?.startAt ?? minMillis;
+  const autoIncrement = options?.autoIncrement ?? false;
+  let nextId = 1;
+
+  const pending = new Map<number, { callback: () => void; runAt: number }>();
+
+  const getNowMillis = (): Millis => {
+    const result = now;
+    if (autoIncrement) {
       queueMicrotask(() => {
-        now++;
+        now = Millis.orThrow(now + 1);
       });
-      return current;
+    }
+    return result;
+  };
+
+  return {
+    now: () => getNowMillis(),
+
+    nowDateIso: () => millisToDateIso(getNowMillis()),
+
+    setTimeout: (callback, delay) => {
+      const id = nextId++;
+      pending.set(id, { callback, runAt: now + durationToMillis(delay) });
+      return id as unknown as TimeoutId;
+    },
+
+    clearTimeout: (id) => {
+      pending.delete(id as unknown as number);
+    },
+
+    advance: (duration) => {
+      now = Millis.orThrow(now + durationToMillis(duration));
+
+      for (const [id, timeout] of pending) {
+        if (timeout.runAt <= now) {
+          pending.delete(id);
+          timeout.callback();
+        }
+      }
     },
-    nowIso: () =>
-      DateIso.orThrow(new globalThis.Date(time.now()).toISOString()),
   };
-  return time;
 };
 
-/** Single digit 0-9. Used internally for {@link DurationString} validation. */
-export type D = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+// Literal (not expression like 1 + 2) to preserve type for Brand<"LessThan...">
+const maxMillisWithInfinity = 281474976710655;
 
 /**
- * Minutes and seconds 1-59. Used internally for {@link DurationString}
- * validation. Uses single digits for 1-9, full numbers for 10-59.
+ * Milliseconds timestamp, like `Date.now()`.
+ *
+ * The maximum value is 281474976710654 (281474976710655 - 1, reserved for
+ * infinity). This enables efficient binary serialization, saving 2 bytes
+ * compared to typical 8-byte (64-bit) timestamps.
+ *
+ * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
+ *
+ * If a system clock exceeds this range, operations will throw. This is
+ * intentional — there's no reasonable fallback for a misconfigured clock.
  */
-export type MmSs =
-  | Exclude<D, "0"> // 1..9 (single digit)
-  | `1${D}` // 10..19
-  | `2${D}` // 20..29
-  | `3${D}` // 30..39
-  | `4${D}` // 40..49
-  | `5${D}`; // 50..59
+export const Millis = /*#__PURE__*/ brand(
+  "Millis",
+  /*#__PURE__*/ lessThan(maxMillisWithInfinity)(NonNegativeInt),
+);
+export type Millis = typeof Millis.Type;
 
-/** Hours 1-23. Used internally for {@link DurationString} validation. */
-export type Hours =
-  | Exclude<D, "0"> // 1-9
-  | `1${D}` // 10-19
-  | `2${"0" | "1" | "2" | "3"}`; // 20-23
+/** Minimum {@link Millis} value. */
+export const minMillis = 0 as Millis;
 
-/** Days 1-99. Used internally for {@link DurationString} validation. */
-export type Days = Exclude<D, "0"> | `${Exclude<D, "0">}${D}`;
+/** Maximum {@link Millis} value. */
+export const maxMillis = (maxMillisWithInfinity - 1) as Millis;
 
 /**
- * Template literal type for compile-time validated duration strings.
+ * Converts {@link Millis} to {@link DateIso}.
  *
- * Allowed patterns: basic units (ms, s, m, h, d) and logical combinations
- * (s+ms, m+s, h+m, d+h).
+ * This is a safe cast because {@link Millis} guarantees a valid timestamp range
+ * that always produces a valid ISO string.
+ */
+export const millisToDateIso = (value: Millis): DateIso =>
+  new globalThis.Date(value).toISOString() as DateIso;
+
+/**
+ * Duration can be either a {@link DurationLiteral} or milliseconds as
+ * {@link Millis}.
+ */
+export type Duration = DurationLiteral | Millis;
+
+/**
+ * Duration literal with compile-time validation.
  *
  * Supported formats:
  *
- * - Milliseconds: `0ms`, `1ms`, `500ms`, `999ms`
- * - Seconds: `5s`, `30s` (1-59, single digit for 1-9)
- * - Minutes: `5m`, `30m` (1-59, single digit for 1-9)
- * - Hours: `1h`, `12h`, `23h` (1-23)
- * - Days: `1d`, `30d`, `99d` (1-99)
- * - Combinations: `1s 250ms`, `30m 15s`, `2h 45m`, `7d 12h`
+ * - Milliseconds: `1ms`, `500ms`, `999ms` (1-999)
+ * - Seconds: `1s`, `59s`, `12.5s` (1-59, 1.1-59.9)
+ * - Minutes: `1m`, `59m`, `12.5m` (1-59, 1.1-59.9)
+ * - Hours: `1h`, `23h`, `12.5h` (1-23, 1.1-23.9)
+ * - Days: `1d`, `6d`, `1.5d` (1-6, 1.1-6.9)
+ * - Weeks: `1w`, `51w`, `1.5w` (1-51, 1.1-51.9)
+ * - 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"`).
+ *
+ * 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),
+ * use {@link Millis} directly.
  *
- * Note: Duration strings are for developer experience only - they provide
- * readable, compile-time validated expressions but should never be persisted or
- * parsed from users as they are not localized. Always convert to NonNegativeInt
- * (milliseconds) for storage and APIs.
+ * Zero duration (0ms) is not supported. For yielding without delay, use `await
+ * Promise.resolve()` for microtasks or the {@link yieldNow} for macrotasks.
+ *
+ * See {@link Duration} for a type that also accepts {@link Millis}. Use
+ * {@link durationToMillis} to convert to milliseconds.
+ */
+export type DurationLiteral =
+  | DurationLiteralMilliseconds
+  | DurationLiteralSeconds
+  | DurationLiteralMinutes
+  | DurationLiteralHours
+  | DurationLiteralDays
+  | DurationLiteralWeeks
+  | DurationLiteralYears;
+
+/** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
+export type DurationLiteralMilliseconds =
+  | `${Digit1To9}ms` // 1-9
+  | `${Digit1To9}${Digit}ms` // 10-99
+  | `${Digit1To9}${Digit}${Digit}ms`; // 100-999
+
+/**
+ * Seconds duration: `"1s"` to `"59s"` or `"1.1s"` to `"59.9s"`. See
+ * {@link DurationLiteral}.
  */
-export type DurationString =
-  | `${D}ms`
-  | `${D}${D}ms`
-  | `${D}${D}${D}ms`
-  | `${MmSs}s`
-  | `${MmSs}m`
-  | `${Hours}h`
-  | `${Days}d`
-  | `${MmSs}s ${D}ms`
-  | `${MmSs}s ${D}${D}ms`
-  | `${MmSs}s ${D}${D}${D}ms`
-  | `${MmSs}m ${MmSs}s`
-  | `${Hours}h ${MmSs}m`
-  | `${Days}d ${Hours}h`;
+export type DurationLiteralSeconds =
+  | `${Digit1To59}s` // 1-59
+  | `${Digit1To59}.${Digit1To9}s`; // 1.1-59.9
 
 /**
- * Duration can be either a {@link DurationString} or milliseconds as
- * {@link NonNegativeInt}.
+ * Minutes duration: `"1m"` to `"59m"` or `"1.1m"` to `"59.9m"`. See
+ * {@link DurationLiteral}.
  */
-export type Duration = DurationString | NonNegativeInt;
+export type DurationLiteralMinutes =
+  | `${Digit1To59}m` // 1-59
+  | `${Digit1To59}.${Digit1To9}m`; // 1.1-59.9
+
+/**
+ * Hours duration: `"1h"` to `"23h"` or `"1.1h"` to `"23.9h"`. See
+ * {@link DurationLiteral}.
+ */
+export type DurationLiteralHours =
+  | `${Digit1To23}h` // 1-23
+  | `${Digit1To23}.${Digit1To9}h`; // 1.1-23.9
+
+/**
+ * Days duration: `"1d"` to `"6d"` or `"1.1d"` to `"6.9d"`. See
+ * {@link DurationLiteral}.
+ */
+export type DurationLiteralDays =
+  | `${Digit1To6}d` // 1-6
+  | `${Digit1To6}.${Digit1To9}d`; // 1.1-6.9
+
+/**
+ * Weeks duration: `"1w"` to `"51w"` or `"1.1w"` to `"51.9w"`. See
+ * {@link DurationLiteral}.
+ */
+export type DurationLiteralWeeks =
+  | `${Digit1To51}w` // 1-51
+  | `${Digit1To51}.${Digit1To9}w`; // 1.1-51.9
+
+/**
+ * Years duration: `"1y"` to `"99y"` or `"1.1y"` to `"99.9y"`. See
+ * {@link DurationLiteral}.
+ */
+export type DurationLiteralYears =
+  | `${Digit1To99}y` // 1-99
+  | `${Digit1To99}.${Digit1To9}y`; // 1.1-99.9
 
 /**
  * Converts a duration to milliseconds.
  *
- * Accepts either a {@link DurationString} (e.g., "5m", "1h 30m") or milliseconds
- * as {@link NonNegativeInt}.
+ * Accepts either a {@link DurationLiteral} (e.g., "5m", "1.5s") or
+ * {@link Millis}.
  *
  * ### Example
  *
  * ```ts
- * durationToNonNegativeInt("0ms"); // 0 ✅
- * durationToNonNegativeInt("500ms"); // 500 ✅
- * durationToNonNegativeInt("30s"); // 30000 ✅
- * durationToNonNegativeInt("5m"); // 300000 ✅
- * durationToNonNegativeInt("12h"); // 43200000 ✅
- * durationToNonNegativeInt("7d"); // 604800000 ✅
- * durationToNonNegativeInt("2h 45m"); // 9900000 ✅
- * durationToNonNegativeInt(5000); // 5000 ✅ (already milliseconds)
+ * 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)
  * ```
  */
-export const durationToNonNegativeInt = (
-  duration: Duration,
-): NonNegativeInt => {
-  // If it's already a NonNegativeInt (milliseconds), return as-is
-  if (typeof duration === "number") {
-    return duration;
-  }
+export const durationToMillis = (duration: Duration): Millis => {
+  if (typeof duration === "number") return duration;
 
-  // Parse duration string without regex to avoid ReDoS vulnerabilities
-  const units = {
-    ms: 1,
-    s: 1000,
-    m: 60000,
-    h: 3600000,
-    d: 86400000, // 24 * 60 * 60 * 1000
-  } as const;
-
-  let total = 0;
-  let i = 0;
-
-  while (i < duration.length) {
-    // Skip whitespace
-    while (i < duration.length && duration[i] === " ") {
-      i++;
-    }
+  const num = parseFloat(duration);
+  const unit = duration.endsWith("ms") ? "ms" : duration.at(-1)!;
 
-    if (i >= duration.length) break;
+  assert(unit in durationUnits, `Unknown duration unit: ${unit}`);
 
-    // Parse number
-    let numStr = "";
-    while (i < duration.length && duration[i] >= "0" && duration[i] <= "9") {
-      numStr += duration[i];
-      i++;
-    }
+  return Millis.orThrow(
+    Math.round(num * durationUnits[unit as keyof typeof durationUnits]),
+  );
+};
 
-    if (numStr === "") break;
-
-    // Parse unit (ms or single char s/m/h/d)
-    let unit = "";
-    if (i < duration.length) {
-      if (
-        duration[i] === "m" &&
-        i + 1 < duration.length &&
-        duration[i + 1] === "s"
-      ) {
-        unit = "ms";
-        i += 2;
-      } else if (
-        duration[i] === "s" ||
-        duration[i] === "m" ||
-        duration[i] === "h" ||
-        duration[i] === "d"
-      ) {
-        unit = duration[i];
-        i++;
-      }
-    }
+/**
+ * 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,
+  s: 1000,
+  m: 60000,
+  h: 3600000,
+  d: 86400000,
+  w: 604800000, // 7 days
+  y: 31536000000, // 365 days
+} as const;
+
+/**
+ * Frame budget at 60fps (16ms).
+ *
+ * Work exceeding this blocks a frame, causing visible jank in animations.
+ */
+export const ms60fps = 16 as Millis;
+
+/**
+ * Frame budget at 120fps (8ms).
+ *
+ * For high refresh rate displays. Work exceeding this blocks a frame.
+ */
+export const ms120fps = 8 as Millis;
 
-    if (unit === "") break;
+/**
+ * Long task threshold (50ms).
+ *
+ * Tasks exceeding this are "long tasks" per web standards. Use with
+ * {@link yieldNow} to yield periodically and keep UI responsive.
+ *
+ * @see https://web.dev/articles/optimize-long-tasks
+ */
+export const msLongTask = 50 as Millis;
 
-    const value = parseInt(numStr, 10);
-    total += value * units[unit as keyof typeof units];
+/**
+ * Formats {@link Millis} as a human-readable duration string.
+ *
+ * - Under 1 minute: `1.234s`
+ * - Under 1 hour: `1m30.000s`
+ * - 1 hour or more: `1h30m45.000s`
+ *
+ * ### Example
+ *
+ * ```ts
+ * formatMillisAsDuration(1234 as Millis); // "1.234s"
+ * formatMillisAsDuration(90000 as Millis); // "1m30.000s"
+ * formatMillisAsDuration(3661000 as Millis); // "1h1m1.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`;
   }
+};
 
-  return NonNegativeInt.orThrow(total);
+/**
+ * Formats {@link Millis} as `HH:MM:SS.mmm`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * formatMillisAsClockTime(Millis.orThrow(Date.now())); // "14:32:15.234"
+ * ```
+ */
+export const formatMillisAsClockTime = (millis: Millis): string => {
+  const date = new globalThis.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");
+  const ms = date.getMilliseconds().toString().padStart(3, "0");
+  return `${hours}:${minutes}:${seconds}.${ms}`;
 };

package/src/Tracer.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal tracer interface for observability.
+ *
+ * @module
+ */
+
+import type { Ref } from "./Ref.js";
+import type { Run } from "./Task.js";
+
+/**
+ * Minimal tracer interface for observability.
+ *
+ * Tracer provides unified observability for both sync and async code. Use it
+ * directly for sync operations, or let {@link Run} use it automatically for
+ * async tasks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Sync code — use tracer directly
+ * const result = deps.tracer?.span("parseData", () => parseData(input));
+ *
+ * // Async code — Run traces automatically
+ * await using run = createRun(deps);
+ * const result = await run(fetchUser(id)); // Traced if tracer provided
+ * ```
+ *
+ * TODO: Complete implementation with OpenTelemetry adapter.
+ */
+export interface Tracer {
+  /**
+   * Wraps a sync function in a traced span.
+   *
+   * Records start time, end time, and success/failure status.
+   */
+  readonly span: <T>(name: string, fn: () => T) => T;
+
+  /** Records an event/fact (e.g., "user.purchased", "sync.completed"). */
+  readonly event: (name: string, data?: unknown) => void;
+}
+
+export interface TracerDep {
+  readonly tracer: Tracer;
+}
+
+/** Configuration for tracing. */
+export interface TracerConfig {
+  /** When `true`, enables trace data collection. Can be toggled at runtime. */
+  readonly tracing?: Ref<boolean>;
+}
+
+export interface TracerConfigDep {
+  readonly tracerConfig: TracerConfig;
+}