@evolu/common 6.0.1-preview.8 → 7.0.0

package/dist/src/Task.js

@@ -0,0 +1,469 @@
+/**
+ * ⚡ Lazy, cancellable Promise that returns Result instead of throwing
+ *
+ * @module
+ */
+import { isNonEmptyArray, shiftArray } from "./Array.js";
+import { err, ok } from "./Result.js";
+import { durationToNonNegativeInt } from "./Time.js";
+import { NonNegativeInt, PositiveInt } from "./Type.js";
+/** Narrower check to detect AbortError objects at runtime. */
+const isAbortError = (error) => typeof error === "object" &&
+    error !== null &&
+    error.type === "AbortError";
+// For React Native
+if (typeof AbortSignal.any !== "function") {
+    AbortSignal.any = function (signals) {
+        const controller = new AbortController();
+        const onAbort = (event) => {
+            controller.abort(event.target.reason);
+            cleanup();
+        };
+        const cleanup = () => {
+            for (const s of signals)
+                s.removeEventListener("abort", onAbort);
+        };
+        for (const s of signals) {
+            if (s.aborted) {
+                controller.abort(s.reason);
+                return controller.signal;
+            }
+            s.addEventListener("abort", onAbort);
+        }
+        return controller.signal;
+    };
+}
+/**
+ * Combines user signal from context with an internal signal.
+ *
+ * If the context has a signal, combines both signals using AbortSignal.any().
+ * Otherwise, returns just the internal signal.
+ */
+const combineSignal = (context, internalSignal) => context?.signal
+    ? AbortSignal.any([context.signal, internalSignal])
+    : internalSignal;
+/**
+ * Converts async function returning {@link Result} to a {@link Task}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface FetchError {
+ *   readonly type: "FetchError";
+ *   readonly error: unknown;
+ * }
+ *
+ * // Task version of fetch with proper error handling and cancellation support.
+ * const fetch = (url: string) =>
+ *   toTask((context) =>
+ *     tryAsync(
+ *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
+ *       (error): FetchError => ({ type: "FetchError", error }),
+ *     ),
+ *   );
+ *
+ * // `satisfies` shows the expected type signature.
+ * fetch satisfies (url: string) => Task<Response, FetchError>;
+ *
+ * const result1 = await fetch("https://api.example.com/data")();
+ * result1 satisfies Result<Response, FetchError>;
+ *
+ * // With AbortController
+ * const controller = new AbortController();
+ * const result2 = await fetch("https://api.example.com/data")(controller);
+ * result2 satisfies Result<Response, FetchError | AbortError>;
+ * ```
+ */
+export const toTask = (fn) => 
+// Note: Not using async to avoid Promise wrapper overhead in fast path
+((context) => {
+    const signal = context?.signal;
+    // Fast path when no signal – return promise directly
+    if (!signal) {
+        // Preserve future context fields (e.g., tracing) even without a signal
+        return fn(context);
+    }
+    if (signal.aborted) {
+        return Promise.resolve(err({ type: "AbortError", reason: signal.reason }));
+    }
+    // Use Promise.withResolvers for clean abort handling and cleanup
+    const { promise: abortPromise, resolve: resolveAbort } = Promise.withResolvers();
+    const handleAbort = () => {
+        resolveAbort(err({ type: "AbortError", reason: signal.reason }));
+    };
+    signal.addEventListener("abort", handleAbort, { once: true });
+    // No finally: we expect no throws in normal flow; Result path removes listener.
+    // Unexpected throws indicate a bug and are allowed to crash (no recovery here).
+    return Promise.race([
+        abortPromise,
+        fn(context).then((result) => {
+            signal.removeEventListener("abort", handleAbort);
+            return result;
+        }),
+    ]);
+});
+// For React Native
+if (typeof AbortSignal.timeout !== "function") {
+    AbortSignal.timeout = function (ms) {
+        const controller = new AbortController();
+        const id = setTimeout(() => {
+            controller.abort();
+        }, ms);
+        // clear timeout if aborted early
+        controller.signal.addEventListener("abort", () => {
+            clearTimeout(id);
+        });
+        return controller.signal;
+    };
+}
+/**
+ * Creates a {@link Task} that waits for the specified duration.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result1 = await wait("10ms")();
+ * result1 satisfies Result<void, never>;
+ *
+ * // With AbortController
+ * const controller = new AbortController();
+ * const result2 = await wait("10ms")(controller);
+ * result2 satisfies Result<void, AbortError>;
+ * ```
+ */
+export const wait = (duration) => toTask((context) => new Promise((resolve) => {
+    const ms = durationToNonNegativeInt(duration);
+    const timeoutSignal = AbortSignal.timeout(ms);
+    const signal = combineSignal(context, timeoutSignal);
+    // Listen for abort - either from timeout completion or external abort
+    signal.addEventListener("abort", () => {
+        resolve(ok());
+    }, { once: true });
+}));
+/**
+ * Adds timeout behavior to a {@link Task}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface FetchError {
+ *   readonly type: "FetchError";
+ *   readonly error: unknown;
+ * }
+ *
+ * // Task version of fetch with proper error handling and cancellation support.
+ * const fetch = (url: string) =>
+ *   toTask((context) =>
+ *     tryAsync(
+ *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
+ *       (error): FetchError => ({ type: "FetchError", error }),
+ *     ),
+ *   );
+ *
+ * // `satisfies` shows the expected type signature.
+ * fetch satisfies (url: string) => Task<Response, FetchError>;
+ *
+ * const fetchWithTimeout = (url: string) => timeout("2m", fetch(url));
+ *
+ * const result1 = await fetchWithTimeout("https://api.example.com/data")();
+ * result1 satisfies Result<Response, FetchError | TimeoutError>;
+ *
+ * // With AbortController
+ * const controller = new AbortController();
+ * const result2 = await fetchWithTimeout("https://api.example.com/data")(
+ *   controller,
+ * );
+ * result2 satisfies Result<
+ *   Response,
+ *   FetchError | TimeoutError | AbortError
+ * >;
+ * ```
+ */
+export const timeout = (duration, task) => toTask(async (context) => {
+    const timeoutMs = durationToNonNegativeInt(duration);
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = combineSignal(context, timeoutSignal);
+    const result = await task({ signal });
+    if (timeoutSignal.aborted) {
+        return err({ type: "TimeoutError", timeoutMs });
+    }
+    return result;
+});
+/**
+ * Adds retry logic with exponential backoff and jitter to a {@link Task}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface FetchError {
+ *   readonly type: "FetchError";
+ *   readonly error: unknown;
+ * }
+ *
+ * // Task version of fetch with proper error handling and cancellation support.
+ * const fetch = (url: string) =>
+ *   toTask((context) =>
+ *     tryAsync(
+ *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
+ *       (error): FetchError => ({ type: "FetchError", error }),
+ *     ),
+ *   );
+ *
+ * // `satisfies` shows the expected type signature.
+ * fetch satisfies (url: string) => Task<Response, FetchError>;
+ *
+ * const fetchWithRetry = (url: string) =>
+ *   retry({ retries: PositiveInt.orThrow(3) }, fetch(url));
+ *
+ * const result1 = await fetchWithRetry("https://api.example.com/data")();
+ * result1 satisfies Result<Response, FetchError | RetryError<FetchError>>;
+ *
+ * // With AbortController
+ * const controller = new AbortController();
+ * const result2 = await fetchWithRetry("https://api.example.com/data")(
+ *   controller,
+ * );
+ * result2 satisfies Result<
+ *   Response,
+ *   FetchError | RetryError<FetchError> | AbortError
+ * >;
+ * ```
+ */
+export const retry = ({ retries, initialDelay = "1s", maxDelay = "30s", factor = 2, jitter = 0.5, retryable = (error) => !isAbortError(error), onRetry, }, task) => toTask(async (context) => {
+    const initialDelayMs = durationToNonNegativeInt(initialDelay);
+    const maxDelayMs = durationToNonNegativeInt(maxDelay);
+    const maxRetries = PositiveInt.orThrow(retries);
+    let attempt = 0;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        const result = await task(context);
+        if (result.ok) {
+            return result;
+        }
+        // Never retry on AbortError; propagate it directly
+        if (isAbortError(result.error)) {
+            return err(result.error);
+        }
+        attempt += 1;
+        if (attempt > maxRetries || !retryable(result.error)) {
+            return err({
+                type: "RetryError",
+                cause: result.error,
+                attempts: attempt,
+            });
+        }
+        // Calculate delay with exponential backoff
+        const exponentialDelay = initialDelayMs * Math.pow(factor, attempt - 1);
+        const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+        // Apply jitter to prevent thundering herd problem
+        const randomFactor = 1 - jitter + Math.random() * jitter * 2;
+        const delay = Math.floor(cappedDelay * randomFactor);
+        if (onRetry) {
+            onRetry(result.error, attempt, delay);
+        }
+        // Wait before retry
+        const delayResult = await wait(NonNegativeInt.orThrow(delay))(context);
+        if (!delayResult.ok) {
+            // If delay was aborted, return AbortError (will be handled by toTask)
+            return delayResult;
+        }
+    }
+});
+/**
+ * Creates a semaphore that limits concurrent async Tasks to the specified
+ * count.
+ *
+ * A semaphore controls access to a resource by maintaining a count of available
+ * permits. Tasks acquire a permit before executing and release it when
+ * complete.
+ *
+ * For mutual exclusion (exactly one Task at a time), consider using
+ * {@link createMutex} instead.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Allow maximum 3 concurrent Tasks
+ * const semaphore = createSemaphore(PositiveInt.orThrow(3));
+ *
+ * let currentConcurrent = 0;
+ * const events: Array<string> = [];
+ *
+ * const fetchData = (id: number) =>
+ *   toTask<number, never>(async (context) => {
+ *     currentConcurrent++;
+ *     events.push(`start ${id} (concurrent: ${currentConcurrent})`);
+ *
+ *     await wait("10ms")(context);
+ *
+ *     currentConcurrent--;
+ *     events.push(`end ${id} (concurrent: ${currentConcurrent})`);
+ *     return ok(id * 10);
+ *   });
+ *
+ * // These will execute with at most 3 running concurrently
+ * const results = await Promise.all([
+ *   semaphore.withPermit(fetchData(1))(),
+ *   semaphore.withPermit(fetchData(2))(),
+ *   semaphore.withPermit(fetchData(3))(),
+ *   semaphore.withPermit(fetchData(4))(), // waits for one above to complete
+ *   semaphore.withPermit(fetchData(5))(), // waits for permit
+ * ]);
+ *
+ * expect(results.map(getOrThrow)).toEqual([10, 20, 30, 40, 50]);
+ * expect(events).toMatchInlineSnapshot(`
+ *   [
+ *     "start 1 (concurrent: 1)",
+ *     "start 2 (concurrent: 2)",
+ *     "start 3 (concurrent: 3)",
+ *     "end 1 (concurrent: 2)",
+ *     "start 4 (concurrent: 3)",
+ *     "end 2 (concurrent: 2)",
+ *     "start 5 (concurrent: 3)",
+ *     "end 3 (concurrent: 2)",
+ *     "end 4 (concurrent: 1)",
+ *     "end 5 (concurrent: 0)",
+ *   ]
+ * `);
+ * ```
+ */
+export const createSemaphore = (maxConcurrent) => {
+    let isDisposed = false;
+    let availablePermits = maxConcurrent;
+    const waitingQueue = [];
+    const semaphoreController = new AbortController();
+    const acquire = () => {
+        if (availablePermits > 0) {
+            availablePermits--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            waitingQueue.push(resolve);
+        });
+    };
+    const release = () => {
+        if (isNonEmptyArray(waitingQueue)) {
+            shiftArray(waitingQueue)();
+        }
+        else {
+            availablePermits++;
+        }
+    };
+    return {
+        withPermit: (task) => toTask(async (context) => {
+            await acquire();
+            // Check if semaphore was disposed while waiting
+            if (isDisposed) {
+                return err({
+                    type: "AbortError",
+                    reason: "Semaphore disposed",
+                });
+            }
+            const signal = combineSignal(context, semaphoreController.signal);
+            const result = await task({ signal });
+            release();
+            return result;
+        }),
+        [Symbol.dispose]: () => {
+            if (isDisposed)
+                return;
+            isDisposed = true;
+            // Cancel all running and waiting tasks
+            semaphoreController.abort("Semaphore disposed");
+            // Release all waiting tasks so they can continue and check isDisposed
+            while (isNonEmptyArray(waitingQueue)) {
+                shiftArray(waitingQueue)();
+            }
+        },
+    };
+};
+/**
+ * Creates a new mutex for ensuring mutual exclusion.
+ *
+ * A mutex is a {@link createSemaphore} with exactly one permit, ensuring that
+ * only one Task can execute at a time.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const mutex = createMutex();
+ *
+ * const updateTask = (id: number) =>
+ *   toTask((context) =>
+ *     tryAsync(
+ *       () => updateSharedResource(id, context),
+ *       (error): UpdateError => ({ type: "UpdateError", error }),
+ *     ),
+ *   );
+ *
+ * // These Tasks will execute one at a time
+ * const results = await Promise.all([
+ *   mutex.withLock(updateTask(1))(),
+ *   mutex.withLock(updateTask(2))(),
+ *   mutex.withLock(updateTask(3))(),
+ * ]);
+ * ```
+ */
+export const createMutex = () => {
+    const mutex = createSemaphore(PositiveInt.orThrow(1));
+    return {
+        withLock: mutex.withPermit,
+        [Symbol.dispose]: mutex[Symbol.dispose],
+    };
+};
+/**
+ * Schedule a task to run after all interactions (animations, gestures,
+ * navigation) have completed.
+ *
+ * This uses `requestIdleCallback` when available, otherwise falls back to
+ * `setTimeout(0)` for cross-platform compatibility.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const processDataTask: Task<void, ProcessError> = toTask(async () => {
+ *   // Heavy processing work
+ *   return ok();
+ * });
+ *
+ * // Schedule the task to run when idle
+ * void requestIdleTask(processDataTask)();
+ * ```
+ */
+export const requestIdleTask = (task) => toTask(async (context) => new Promise((resolve) => {
+    idleCallback(() => {
+        void task(context).then(resolve);
+    });
+}));
+const idleCallback = typeof globalThis.requestIdleCallback === "function"
+    ? globalThis.requestIdleCallback
+    : (callback) => setTimeout(callback, 0);
+/**
+ * Type guard to check if a {@link MaybeAsync} value is async (a promise).
+ *
+ * This function narrows the type of a {@link MaybeAsync} value, allowing you to
+ * conditionally `await` only when necessary.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const getData = (id: string): MaybeAsync<Data> => {
+ *   const cached = cache.get(id);
+ *   if (cached) return cached; // Sync path
+ *   return fetchData(id); // Async path
+ * };
+ *
+ * const result = getData(id);
+ * const data = isAsync(result) ? await result : result;
+ * // No microtask overhead when cached!
+ * ```
+ */
+export const isAsync = (value) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+typeof value?.then === "function";
+// TODO: Add tracing support
+// - Extend TaskContext with optional tracing field
+// - Add traced(name, task) helper that wraps Task execution
+// - Collect span data (name, timing, parent-child relationships, status)
+// - Support OpenTelemetry export format with proper traceId/spanId generation
+// - Automatic parent-child span relationships through context propagation

package/dist/src/Time.d.ts

@@ -3,18 +3,83 @@
  *
  * @module
  */
+import { DateIso, NonNegativeInt } from "./Type.js";
 /** Retrieves the current time in milliseconds, similar to `Date.now()`. */
 export interface Time {
     readonly now: () => number;
+    readonly nowIso: () => DateIso;
 }
 export interface TimeDep {
     readonly time: Time;
 }
-/** Creates a {@link Time} using Date.now(). */
+/**
+ * Creates a {@link Time} using Date.now().
+ *
+ * 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.
+ */
 export declare const createTime: () => Time;
 /**
  * Creates a {@link Time} that returns a monotonically increasing number based on
  * a queueMicrotask.
  */
 export declare const createTestTime: () => Time;
+/** Single digit 0-9. Used internally for {@link DurationString} validation. */
+export type D = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * Minutes and seconds 1-59. Used internally for {@link DurationString}
+ * validation. Uses single digits for 1-9, full numbers for 10-59.
+ */
+export type MmSs = Exclude<D, "0"> | `1${D}` | `2${D}` | `3${D}` | `4${D}` | `5${D}`;
+/** Hours 1-23. Used internally for {@link DurationString} validation. */
+export type Hours = Exclude<D, "0"> | `1${D}` | `2${"0" | "1" | "2" | "3"}`;
+/** Days 1-99. Used internally for {@link DurationString} validation. */
+export type Days = Exclude<D, "0"> | `${Exclude<D, "0">}${D}`;
+/**
+ * Template literal type for compile-time validated duration strings.
+ *
+ * Allowed patterns: basic units (ms, s, m, h, d) and logical combinations
+ * (s+ms, m+s, h+m, d+h).
+ *
+ * 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`
+ *
+ * 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.
+ */
+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`;
+/**
+ * Duration can be either a {@link DurationString} or milliseconds as
+ * {@link NonNegativeInt}.
+ */
+export type Duration = DurationString | NonNegativeInt;
+/**
+ * Converts a duration to milliseconds.
+ *
+ * Accepts either a {@link DurationString} (e.g., "5m", "1h 30m") or milliseconds
+ * as {@link NonNegativeInt}.
+ *
+ * ### 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)
+ * ```
+ */
+export declare const durationToNonNegativeInt: (duration: Duration) => NonNegativeInt;
 //# sourceMappingURL=Time.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,+CAA+C;AAC/C,eAAO,MAAM,UAAU,QAAO,IAE5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAO,IAWjC,CAAC"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAO,IAa7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAO,IAcjC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE1E;;;GAGG;AACH,MAAM,MAAM,IAAI,GACZ,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,GACf,IAAI,CAAC,EAAE,GACP,IAAI,CAAC,EAAE,GACP,IAAI,CAAC,EAAE,GACP,IAAI,CAAC,EAAE,GACP,IAAI,CAAC,EAAE,CAAC;AAEZ,yEAAyE;AACzE,MAAM,MAAM,KAAK,GACb,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,GACf,IAAI,CAAC,EAAE,GACP,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAEhC,wEAAwE;AACxE,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,GACtB,GAAG,CAAC,IAAI,GACR,GAAG,CAAC,GAAG,CAAC,IAAI,GACZ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAChB,GAAG,IAAI,GAAG,GACV,GAAG,IAAI,GAAG,GACV,GAAG,KAAK,GAAG,GACX,GAAG,IAAI,GAAG,GACV,GAAG,IAAI,KAAK,CAAC,IAAI,GACjB,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,GACrB,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GACzB,GAAG,IAAI,KAAK,IAAI,GAAG,GACnB,GAAG,KAAK,KAAK,IAAI,GAAG,GACpB,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,QAAQ,KACjB,cA+DF,CAAC"}

package/dist/src/Time.js

@@ -3,17 +3,36 @@
  *
  * @module
  */
-/** Creates a {@link Time} using Date.now(). */
-export const createTime = () => ({
-    now: () => Date.now(),
-});
+import { assert } from "./Assert.js";
+import { DateIso, NonNegativeInt } from "./Type.js";
+/**
+ * Creates a {@link Time} using Date.now().
+ *
+ * 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.
+ */
+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;
+        },
+    };
+    return time;
+};
 /**
  * Creates a {@link Time} that returns a monotonically increasing number based on
  * a queueMicrotask.
  */
 export const createTestTime = () => {
     let now = 0;
-    return {
+    const time = {
         now: () => {
             const current = now;
             queueMicrotask(() => {
@@ -21,5 +40,80 @@ export const createTestTime = () => {
             });
             return current;
         },
+        nowIso: () => DateIso.orThrow(new globalThis.Date(time.now()).toISOString()),
+    };
+    return time;
+};
+/**
+ * Converts a duration to milliseconds.
+ *
+ * Accepts either a {@link DurationString} (e.g., "5m", "1h 30m") or milliseconds
+ * as {@link NonNegativeInt}.
+ *
+ * ### 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)
+ * ```
+ */
+export const durationToNonNegativeInt = (duration) => {
+    // If it's already a NonNegativeInt (milliseconds), return as-is
+    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
     };
+    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];
+    }
+    return NonNegativeInt.orThrow(total);
 };