@evolu/common 8.9.0 → 8.11.0

package/src/Time.ts

@@ -1,15 +1,31 @@
 /**
  * Time representations, durations, and scheduling utilities.
  *
+ * Durations follow a pattern that other quantities in Evolu repeat, such as
+ * sizes in Bytes.ts:
+ *
+ * - {@link Millis} is the canonical unit, a validated number of milliseconds.
+ * - {@link DurationLiteral} is the human-readable form, such as `"1.5s"`,
+ *   validated at compile time and runtime.
+ * - {@link Duration} is what APIs accept: `DurationLiteral | Millis`.
+ * - {@link durationToMillis} normalizes a `Duration` to `Millis`.
+ *
  * @module
  */
 
+import { safelyStringifyUnknownValue } from "./String.ts";
 import { assert } from "./Assert.ts";
 import type { Brand } from "./Brand.ts";
 import { exhaustiveCheck } from "./Function.ts";
 import type { yieldNow } from "./Task.ts";
 import {
   brand,
+  createTypeWithError,
+  type Type,
+  type TypeError,
+  type UnionError,
+  type UnionType,
+  type TemplateLiteralType,
   type DateIso,
   Digit,
   Digit1To23,
@@ -26,7 +42,11 @@ import {
   union,
 } from "./Type.ts";
 
-/** Time and timer operations. */
+/**
+ * Time and timer operations.
+ *
+ * @group Core
+ */
 export interface Time {
   readonly now: {
     /** Returns current time as Unix epoch milliseconds. */
@@ -64,6 +84,11 @@ export interface Time {
   readonly clearTimeout: (id: TimeoutId) => void;
 }
 
+/**
+ * Dependency wrapper for {@link Time}.
+ *
+ * @group Core
+ */
 export interface TimeDep {
   readonly time: Time;
 }
@@ -72,6 +97,8 @@ export interface TimeDep {
  * Opaque type for timeout handles.
  *
  * Use with {@link Time.clearTimeout} to cancel a pending timeout.
+ *
+ * @group Core
  */
 export type TimeoutId = Brand<"TimeoutId">;
 
@@ -91,6 +118,8 @@ interface TimeoutIdInternal {
  *
  * Throws if the system clock returns an out-of-range value. This is intentional
  * — there's no reasonable fallback for a misconfigured clock.
+ *
+ * @group Core
  */
 export const createTime = (): Time => {
   const timeoutOwner = Symbol("Time");
@@ -188,6 +217,8 @@ const clearTimeoutId = (owner: symbol, id: TimeoutId): void => {
  * Test {@link Time} with controllable timers.
  *
  * Call `advance(ms)` to move time forward and trigger any pending timeouts.
+ *
+ * @group Testing
  */
 export interface TestTime extends Time {
   /**
@@ -199,6 +230,11 @@ export interface TestTime extends Time {
   readonly advance: (duration: Duration) => void;
 }
 
+/**
+ * Dependency wrapper for {@link TestTime}.
+ *
+ * @group Testing
+ */
 export interface TestTimeDep {
   readonly time: TestTime;
 }
@@ -214,6 +250,8 @@ export interface TestTimeDep {
  * 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.
+ *
+ * @group Testing
  */
 export const testCreateTime = (options?: {
   readonly startAt?: Millis;
@@ -325,6 +363,8 @@ const maxMillisWithInfinity = 281474976710655;
  *
  * If a system clock exceeds this range, operations will throw. This is
  * intentional — there's no reasonable fallback for a misconfigured clock.
+ *
+ * @group Millis
  */
 export const Millis = /*#__PURE__*/ brand(
   "Millis",
@@ -332,19 +372,33 @@ export const Millis = /*#__PURE__*/ brand(
 );
 export type Millis = typeof Millis.Output;
 
-/** Positive {@link Millis} value. */
+/**
+ * Positive {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const PositiveMillis = /*#__PURE__*/ positive(Millis);
 export type PositiveMillis = typeof PositiveMillis.Output;
 
-/** Minimum {@link Millis} value. */
+/**
+ * Minimum {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const minMillis = 0 as Millis;
 
-/** Maximum {@link Millis} value. */
+/**
+ * Maximum {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const maxMillis = (maxMillisWithInfinity - 1) as Millis;
 
 /**
  * Converts a number to {@link Millis}, rounding to the nearest millisecond and
  * saturating overflow at {@link maxMillis}.
+ *
+ * @group Millis
  */
 export const saturateMillis = (value: NonNaNNumber): Millis =>
   Millis.orNull(Math.max(0, Math.round(value))) ?? maxMillis;
@@ -354,23 +408,39 @@ export const saturateMillis = (value: NonNaNNumber): Millis =>
  *
  * This is a safe cast because {@link Millis} guarantees a valid timestamp range
  * that always produces a valid ISO string.
+ *
+ * @group Millis
  */
 export const millisToDateIso = (value: Millis): DateIso =>
   new Date(value).toISOString() as DateIso;
 
-/** Unix epoch milliseconds used as the origin for {@link PerformanceTime}. */
+/**
+ * Unix epoch milliseconds used as the origin for {@link PerformanceTime}.
+ *
+ * @group Performance
+ */
 export type PerformanceTimeOrigin = number & Brand<"PerformanceTimeOrigin">;
 
-/** High-resolution milliseconds elapsed since {@link PerformanceTimeOrigin}. */
+/**
+ * High-resolution milliseconds elapsed since {@link PerformanceTimeOrigin}.
+ *
+ * @group Performance
+ */
 export type PerformanceTime = number & Brand<"PerformanceTime">;
 
-/** Elapsed fractional milliseconds measured using {@link PerformanceTime}. */
+/**
+ * Elapsed fractional milliseconds measured using {@link PerformanceTime}.
+ *
+ * @group Performance
+ */
 export type PerformanceDuration = number & Brand<"PerformanceDuration">;
 
 /**
  * Returns the elapsed fractional milliseconds between two performance times.
  *
  * Throws if `end` precedes `start`.
+ *
+ * @group Performance
  */
 export const performanceDurationBetween = (
   start: PerformanceTime,
@@ -396,6 +466,8 @@ export const performanceDurationBetween = (
  *
  * assertType<typeof readableSchedule, typeof validatedSchedule>();
  * ```
+ *
+ * @group Durations
  */
 export type Duration = DurationLiteral | Millis;
 
@@ -415,11 +487,27 @@ export type Duration = DurationLiteral | Millis;
  *
  * assertType<typeof readableSleep, typeof validatedSleep>();
  * ```
+ *
+ * @group Durations
  */
 export type PositiveDuration = DurationLiteral | PositiveMillis;
 
-/** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
-export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
+// Keep these annotations concrete. Generic unit wrappers add thousands of
+// compiler instantiations to pnpm bench:type.
+/**
+ * Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}.
+ *
+ * @group Durations
+ */
+export const DurationLiteralMilliseconds: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To9, "ms"]>,
+    TemplateLiteralType<readonly [typeof Digit1To9, typeof Digit, "ms"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To9, typeof Digit, typeof Digit, "ms"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To9, "ms"),
   /*#__PURE__*/ templateLiteral(Digit1To9, Digit, "ms"),
   /*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "ms"),
@@ -430,8 +518,17 @@ export type DurationLiteralMilliseconds =
 /**
  * Seconds duration: `"1s"` to `"59s"` or `"1.1s"` to `"59.9s"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralSeconds = /*#__PURE__*/ union(
+export const DurationLiteralSeconds: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To59, "s"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To59, ".", typeof Digit1To9, "s"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To59, "s"),
   /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "s"),
 );
@@ -440,8 +537,17 @@ export type DurationLiteralSeconds = typeof DurationLiteralSeconds.Output;
 /**
  * Minutes duration: `"1m"` to `"59m"` or `"1.1m"` to `"59.9m"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralMinutes = /*#__PURE__*/ union(
+export const DurationLiteralMinutes: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To59, "m"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To59, ".", typeof Digit1To9, "m"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To59, "m"),
   /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "m"),
 );
@@ -450,8 +556,17 @@ export type DurationLiteralMinutes = typeof DurationLiteralMinutes.Output;
 /**
  * Hours duration: `"1h"` to `"23h"` or `"1.1h"` to `"23.9h"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralHours = /*#__PURE__*/ union(
+export const DurationLiteralHours: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To23, "h"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To23, ".", typeof Digit1To9, "h"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To23, "h"),
   /*#__PURE__*/ templateLiteral(Digit1To23, ".", Digit1To9, "h"),
 );
@@ -460,8 +575,17 @@ export type DurationLiteralHours = typeof DurationLiteralHours.Output;
 /**
  * Days duration: `"1d"` to `"6d"` or `"1.1d"` to `"6.9d"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralDays = /*#__PURE__*/ union(
+export const DurationLiteralDays: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To6, "d"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To6, ".", typeof Digit1To9, "d"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To6, "d"),
   /*#__PURE__*/ templateLiteral(Digit1To6, ".", Digit1To9, "d"),
 );
@@ -470,8 +594,17 @@ export type DurationLiteralDays = typeof DurationLiteralDays.Output;
 /**
  * Weeks duration: `"1w"` to `"51w"` or `"1.1w"` to `"51.9w"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralWeeks = /*#__PURE__*/ union(
+export const DurationLiteralWeeks: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To51, "w"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To51, ".", typeof Digit1To9, "w"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To51, "w"),
   /*#__PURE__*/ templateLiteral(Digit1To51, ".", Digit1To9, "w"),
 );
@@ -480,13 +613,47 @@ export type DurationLiteralWeeks = typeof DurationLiteralWeeks.Output;
 /**
  * Years duration: `"1y"` to `"99y"` or `"1.1y"` to `"99.9y"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
-export const DurationLiteralYears = /*#__PURE__*/ union(
+export const DurationLiteralYears: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To99, "y"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To99, ".", typeof Digit1To9, "y"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To99, "y"),
   /*#__PURE__*/ templateLiteral(Digit1To99, ".", Digit1To9, "y"),
 );
 export type DurationLiteralYears = typeof DurationLiteralYears.Output;
 
+/**
+ * Duration literal string, from {@link DurationLiteralMilliseconds} to
+ * {@link DurationLiteralYears}.
+ *
+ * @group Durations
+ */
+export type DurationLiteral =
+  | DurationLiteralMilliseconds
+  | DurationLiteralSeconds
+  | DurationLiteralMinutes
+  | DurationLiteralHours
+  | DurationLiteralDays
+  | DurationLiteralWeeks
+  | DurationLiteralYears;
+
+const durationLiteralSyntax = /*#__PURE__*/ union(
+  DurationLiteralMilliseconds,
+  DurationLiteralSeconds,
+  DurationLiteralMinutes,
+  DurationLiteralHours,
+  DurationLiteralDays,
+  DurationLiteralWeeks,
+  DurationLiteralYears,
+);
+
 /**
  * Duration literal Type with compile-time and runtime validation.
  *
@@ -514,17 +681,61 @@ export type DurationLiteralYears = typeof DurationLiteralYears.Output;
  *
  * See {@link Duration} for a type that also accepts {@link Millis}. Use
  * {@link durationToMillis} to convert to milliseconds.
+ *
+ * Invalid values produce a {@link DurationLiteralError}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   DurationLiteral,
+ * } from "@evolu/common";
+ *
+ * // The TypeScript type accepts valid spellings and rejects the rest.
+ * const literal: DurationLiteral = "1.5s";
+ * assertType<Extract<DurationLiteral, "1000ms" | "60s" | "0s">, never>();
+ *
+ * // The runtime Type validates the same grammar.
+ * assertOk(DurationLiteral.fromUnknown(literal), "1.5s");
+ * assertFalse(DurationLiteral.is("1000ms"));
+ * ```
+ *
+ * @group Durations
  */
-export const DurationLiteral = /*#__PURE__*/ union(
-  DurationLiteralMilliseconds,
-  DurationLiteralSeconds,
-  DurationLiteralMinutes,
-  DurationLiteralHours,
-  DurationLiteralDays,
-  DurationLiteralWeeks,
-  DurationLiteralYears,
+export const DurationLiteral: Type<
+  "DurationLiteral",
+  DurationLiteral,
+  DurationLiteral,
+  DurationLiteralError
+> = /*#__PURE__*/ createTypeWithError(
+  "DurationLiteral",
+  durationLiteralSyntax,
+  (cause, value): DurationLiteralError => ({
+    type: "DurationLiteral",
+    value,
+    cause,
+  }),
+  (error) =>
+    `The value ${safelyStringifyUnknownValue(error.value)} is not a duration literal. Use a value such as "500ms" or "1.5s".`,
 );
-export type DurationLiteral = typeof DurationLiteral.Output;
+
+/**
+ * Error returned when {@link DurationLiteral} rejects a value.
+ *
+ * @group Durations
+ */
+export interface DurationLiteralError extends TypeError<"DurationLiteral"> {
+  readonly value: unknown;
+  /**
+   * The underlying union failure, retained for diagnostics.
+   *
+   * With `{ errors: "all" }`, includes every failed alternative.
+   */
+  readonly cause: UnionError;
+}
 
 /**
  * Converts a duration to milliseconds.
@@ -543,6 +754,8 @@ export type DurationLiteral = typeof DurationLiteral.Output;
  * assertEqual(durationToMillis("1w"), 604800000);
  * assertEqual(durationToMillis(Millis.orThrow(5000)), 5000);
  * ```
+ *
+ * @group Durations
  */
 export function durationToMillis(
   duration: DurationLiteral | PositiveMillis,
@@ -579,6 +792,8 @@ const durationUnits = {
  * Frame budget at 60fps (16ms).
  *
  * Work exceeding this blocks a frame, causing visible jank in animations.
+ *
+ * @group Millis
  */
 export const ms60fps = 16 as Millis;
 
@@ -586,6 +801,8 @@ export const ms60fps = 16 as Millis;
  * Frame budget at 120fps (8ms).
  *
  * For high refresh rate displays. Work exceeding this blocks a frame.
+ *
+ * @group Millis
  */
 export const ms120fps = 8 as Millis;
 
@@ -595,6 +812,7 @@ export const ms120fps = 8 as Millis;
  * Tasks exceeding this are "long tasks" per web standards. Use with
  * {@link yieldNow} to yield periodically and keep UI responsive.
  *
+ * @group Millis
  * @see https://web.dev/articles/optimize-long-tasks
  */
 export const msLongTask = 50 as Millis;
@@ -627,6 +845,8 @@ export const msLongTask = 50 as Millis;
  *   "1d1h1m1.000s",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsDuration = (millis: Millis): string => {
   const seconds = ((millis % durationUnits.m) / durationUnits.s).toFixed(3);
@@ -671,6 +891,8 @@ export const formatMillisAsDuration = (millis: Millis): string => {
  *   "14:32:15.234",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsClockTime = (millis: Millis): string => {
   const date = new Date(millis);