@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Time.js

@@ -1,114 +1,218 @@
+/**
+ * Time representations, durations, and scheduling utilities.
+ *
+ * @module
+ */
 import { assert } from "./Assert.js";
-import { DateIso, NonNegativeInt } from "./Type.js";
+import { brand, lessThan, NonNegativeInt } from "./Type.js";
 /**
- * Creates a {@link Time} using Date.now().
+ * Creates a {@link Time} using `Date.now()` and `globalThis.setTimeout`.
  *
- * 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.
+ * 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 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.orThrow(globalThis.Date.now());
+    return {
+        now: () => getNowMillis(),
+        nowDateIso: () => millisToDateIso(getNowMillis()),
+        setTimeout: (callback, delay) => globalThis.setTimeout(callback, durationToMillis(delay)),
+        clearTimeout: (id) => {
+            globalThis.clearTimeout(id);
         },
     };
-    return time;
 };
 /**
- * Creates a {@link Time} that returns a monotonically increasing number based on
- * a queueMicrotask.
+ * 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 = () => {
-    let now = 0;
-    const time = {
-        now: () => {
-            const current = now;
+export const testCreateTime = (options) => {
+    let now = options?.startAt ?? minMillis;
+    const autoIncrement = options?.autoIncrement ?? false;
+    let nextId = 1;
+    const pending = new Map();
+    const getNowMillis = () => {
+        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;
+        },
+        clearTimeout: (id) => {
+            pending.delete(id);
+        },
+        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;
 };
+// Literal (not expression like 1 + 2) to preserve type for Brand<"LessThan...">
+const maxMillisWithInfinity = 281474976710655;
+/**
+ * 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 const Millis = /*#__PURE__*/ brand("Millis", 
+/*#__PURE__*/ lessThan(maxMillisWithInfinity)(NonNegativeInt));
+/** Minimum {@link Millis} value. */
+export const minMillis = 0;
+/** Maximum {@link Millis} value. */
+export const maxMillis = (maxMillisWithInfinity - 1);
+/**
+ * Converts {@link Millis} to {@link DateIso}.
+ *
+ * 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();
 /**
  * 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) => {
-    // If it's already a NonNegativeInt (milliseconds), return as-is
-    if (typeof duration === "number") {
+export const 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,
+    m: 60000,
+    h: 3600000,
+    d: 86400000,
+    w: 604800000, // 7 days
+    y: 31536000000, // 365 days
+};
+/**
+ * Frame budget at 60fps (16ms).
+ *
+ * Work exceeding this blocks a frame, causing visible jank in animations.
+ */
+export const ms60fps = 16;
+/**
+ * Frame budget at 120fps (8ms).
+ *
+ * For high refresh rate displays. Work exceeding this blocks a frame.
+ */
+export const ms120fps = 8;
+/**
+ * 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;
+/**
+ * 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) => {
+    const elapsed = millis / 1000;
+    if (elapsed < 60) {
+        return `${elapsed.toFixed(3)}s`;
     }
-    // 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
-    };
-    let total = 0;
-    let i = 0;
-    while (i < duration.length) {
-        // Skip whitespace
-        while (i < duration.length && duration[i] === " ") {
-            i++;
-        }
-        if (i >= duration.length)
-            break;
-        // Parse number
-        let numStr = "";
-        while (i < duration.length && duration[i] >= "0" && duration[i] <= "9") {
-            numStr += duration[i];
-            i++;
-        }
-        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++;
-            }
-        }
-        if (unit === "")
-            break;
-        const value = parseInt(numStr, 10);
-        total += value * units[unit];
+    else if (elapsed < 3600) {
+        const minutes = Math.floor(elapsed / 60);
+        const seconds = (elapsed % 60).toFixed(3);
+        return `${minutes}m${seconds}s`;
     }
-    return NonNegativeInt.orThrow(total);
+    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`;
+    }
+};
+/**
+ * Formats {@link Millis} as `HH:MM:SS.mmm`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * formatMillisAsClockTime(Millis.orThrow(Date.now())); // "14:32:15.234"
+ * ```
+ */
+export const formatMillisAsClockTime = (millis) => {
+    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/dist/src/Tracer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal tracer interface for observability.
+ *
+ * @module
+ */
+import type { Ref } from "./Ref.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;
+}
+//# sourceMappingURL=Tracer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tracer.d.ts","sourceRoot":"","sources":["../../src/Tracer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAEnD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC"}

package/dist/src/Tracer.js

@@ -0,0 +1,6 @@
+/**
+ * Minimal tracer interface for observability.
+ *
+ * @module
+ */
+export {};