@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Test.d.ts

@@ -1,127 +1,14 @@
 /**
- * Test utilities for deterministic testing.
+ * Cross-module test utilities for deterministic testing.
+ *
+ * Test helpers are usually colocated with the code they test. Helpers that
+ * cannot be colocated because they would create dependency cycles belong here.
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
-import { type TestConsoleDep } from "./Console.js";
-import { type RandomLibDep } from "./Random.js";
-import { type Run, type RunDeps } from "./Task.js";
-import { type Duration, type TestTimeDep } from "./Time.js";
-import { type Id } from "./Type.js";
+import type { Brand } from "./Brand.ts";
+import { type Id } from "./Type.ts";
 export type TestCreateId = <B extends string = never>() => [B] extends [never] ? Id : Id & Brand<B>;
-/**
- * Cheap deterministic baseline deps for tests.
- *
- * `TestDeps` includes test-friendly replacements for {@link RunDeps}, such as
- * {@link TestConsole} and {@link TestTime}, plus extra helpers commonly useful in
- * tests and fixtures, such as `randomLib` (only that for now).
- *
- * Use it directly for synchronous test setup, fixtures, and helpers. It is also
- * intentionally the base deps used by {@link testCreateRun}.
- */
-export type TestDeps = Omit<RunDeps, "console" | "time"> & TestConsoleDep & TestTimeDep & RandomLibDep;
-/**
- * Creates deterministic {@link TestDeps}.
- *
- * Each call creates fresh instances, so tests don't share state.
- *
- * Includes these deps:
- *
- * - `console`: {@link TestConsole}
- * - `random`: {@link Random}
- * - `randomLib`: seeded `random` package instance
- * - `randomBytes`: {@link RandomBytes}
- * - `time`: {@link TestTime}
- *
- * Use this for synchronous code that accepts deps directly. For tests that run
- * Tasks, use {@link testCreateRun}.
- *
- * ### Example
- *
- * ```ts
- * test("Callbacks with no argument", () => {
- *   const deps = testCreateDeps();
- *   const callbacks = createCallbacks(deps);
- *
- *   let called = false;
- *   const id = callbacks.register(() => {
- *     called = true;
- *   });
- *
- *   callbacks.execute(id);
- *   expect(called).toBe(true);
- * });
- * ```
- */
-export declare const testCreateDeps: (options?: {
-    readonly seed?: string;
-}) => TestDeps;
-/**
- * Creates a test {@link Run} with deterministic default deps or optional custom
- * deps.
- *
- * Use this as the default composition root in tests. Each call creates fresh
- * {@link TestDeps} via {@link testCreateDeps}, then merges any provided custom
- * deps.
- *
- * ### Example
- *
- * ```ts
- * // Built-in TestTime
- * await using run = testCreateRun();
- * const fiber = run(sleep("1s"));
- * run.deps.time.advance("1s");
- * await fiber;
- *
- * // For a single test, create the dependency using the Run.
- * await using run = testCreateRun();
- * await using foo = await run.orThrow(createFoo());
- * const runWithFoo = run.addDeps({ foo });
- *
- * expect(runWithFoo.deps.foo).toBe(foo);
- *
- * // If multiple tests need the same setup, create a disposable helper.
- * // Then `await using setup` disposes everything the helper owns.
- * const setupFoo = async () => {
- *   await using disposer = new AsyncDisposableStack();
- *   const run = disposer.use(testCreateRun());
- *   const foo = disposer.use(await run.orThrow(createFoo()));
- *   const disposables = disposer.move();
- *
- *   // Return whatever the tests need: a Run with the dependency,
- *   // the dependency itself, or both.
- *   return {
- *     run: run.addDeps({ foo }),
- *     foo,
- *     [Symbol.asyncDispose]: () => moved.disposeAsync(),
- *   };
- * };
- *
- * await using setup = await setupFoo();
- * const { run, foo } = setup;
- * expect(run.deps.foo).toBe(foo);
- * ```
- *
- * Name reusable setup helpers after what they set up:
- *
- * - `setupFoo` for reusable test setup for `Foo`
- * - `testSetupFoo` when a library module exports the helper as part of its public
- *   test API, e.g. `testSetupSqlite`.
- */
-export declare function testCreateRun(): Run<TestDeps>;
-/** With custom dependencies merged into {@link TestDeps}. */
-export declare function testCreateRun<D>(deps: D): Run<TestDeps & D>;
-/**
- * Returns a Promise that resolves after a macrotask delay.
- *
- * Use this to model a real async boundary in a test double, for example an
- * async disposer that should not complete in the same turn.
- *
- * Avoid using it to coordinate assertions. Waiting for a macrotask tends to
- * make tests indirect and brittle.
- */
-export declare const testWaitForMacrotask: (duration?: Duration) => Promise<void>;
 /**
  * Creates a deterministic `createId` helper.
  *
@@ -137,13 +24,18 @@ export declare const testWaitForMacrotask: (duration?: Duration) => Promise<void
  * ### Example
  *
  * ```ts
- * test("creates stable ids", () => {
- *   const createId = testCreateId();
+ * import { testCreateId, type Brand, type Id } from "@evolu/common";
+ *
+ * const createId = testCreateId();
+ *
+ * const callbackId = createId();
+ * const secondCallbackId = createId();
+ * const todoId = createId<"Todo">();
+ * expect(new Set([callbackId, secondCallbackId, todoId]).size).toBe(3);
  *
- *   const callbackId = createId();
- *   const secondCallbackId = createId();
- *   const todoId = createId<"Todo">();
- * });
+ * const replayCreateId = testCreateId();
+ * expect(replayCreateId()).toBe(callbackId);
+ * expectTypeOf(todoId).toEqualTypeOf<Id & Brand<"Todo">>();
  * ```
  */
 export declare const testCreateId: () => TestCreateId;

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

@@ -1 +1 @@
-{"version":3,"file":"Test.d.ts","sourceRoot":"","sources":["../../src/Test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAa,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAIL,KAAK,QAAQ,EAEb,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1E,EAAE,GACF,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAElB;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,GACtD,cAAc,GACd,WAAW,GACX,YAAY,CAAC;AAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,KAAG,QAQH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;AAE/C,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;AAO7D;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WAAU,QAAoB,KAC7B,OAAO,CAAC,IAAI,CAAyB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,YAAY,QAAO,YAQ/B,CAAC"}
+{"version":3,"file":"Test.d.ts","sourceRoot":"","sources":["../../src/Test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1E,EAAE,GACF,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,QAAO,YAM/B,CAAC"}

package/dist/src/Test.js

@@ -1,70 +1,14 @@
 /**
- * Test utilities for deterministic testing.
+ * Cross-module test utilities for deterministic testing.
+ *
+ * Test helpers are usually colocated with the code they test. Helpers that
+ * cannot be colocated because they would create dependency cycles belong here.
  *
  * @module
  */
-import { testCreateConsole, } from "./Console.js";
 import { testCreateRandomBytes } from "./Crypto.js";
-import { testCreateRandom, testCreateRandomLib, } from "./Random.js";
-import { createRun } from "./Task.js";
-import { minMillis, setTimeout, testCreateTime, } from "./Time.js";
+import { testCreateRandomLib } from "./Random.js";
 import { createId } from "./Type.js";
-/**
- * Creates deterministic {@link TestDeps}.
- *
- * Each call creates fresh instances, so tests don't share state.
- *
- * Includes these deps:
- *
- * - `console`: {@link TestConsole}
- * - `random`: {@link Random}
- * - `randomLib`: seeded `random` package instance
- * - `randomBytes`: {@link RandomBytes}
- * - `time`: {@link TestTime}
- *
- * Use this for synchronous code that accepts deps directly. For tests that run
- * Tasks, use {@link testCreateRun}.
- *
- * ### Example
- *
- * ```ts
- * test("Callbacks with no argument", () => {
- *   const deps = testCreateDeps();
- *   const callbacks = createCallbacks(deps);
- *
- *   let called = false;
- *   const id = callbacks.register(() => {
- *     called = true;
- *   });
- *
- *   callbacks.execute(id);
- *   expect(called).toBe(true);
- * });
- * ```
- */
-export const testCreateDeps = (options) => {
-    const seed = options?.seed ?? "evolu";
-    const console = testCreateConsole();
-    const random = testCreateRandom(seed);
-    const randomLib = testCreateRandomLib(seed);
-    const randomBytes = testCreateRandomBytes({ randomLib });
-    const time = testCreateTime();
-    return { console, randomBytes, random, randomLib, time };
-};
-export function testCreateRun(deps) {
-    const defaults = testCreateDeps();
-    return createRun({ ...defaults, ...deps });
-}
-/**
- * Returns a Promise that resolves after a macrotask delay.
- *
- * Use this to model a real async boundary in a test double, for example an
- * async disposer that should not complete in the same turn.
- *
- * Avoid using it to coordinate assertions. Waiting for a macrotask tends to
- * make tests indirect and brittle.
- */
-export const testWaitForMacrotask = (duration = minMillis) => setTimeout(duration);
 /**
  * Creates a deterministic `createId` helper.
  *
@@ -80,18 +24,23 @@ export const testWaitForMacrotask = (duration = minMillis) => setTimeout(duratio
  * ### Example
  *
  * ```ts
- * test("creates stable ids", () => {
- *   const createId = testCreateId();
+ * import { testCreateId, type Brand, type Id } from "@evolu/common";
+ *
+ * const createId = testCreateId();
+ *
+ * const callbackId = createId();
+ * const secondCallbackId = createId();
+ * const todoId = createId<"Todo">();
+ * expect(new Set([callbackId, secondCallbackId, todoId]).size).toBe(3);
  *
- *   const callbackId = createId();
- *   const secondCallbackId = createId();
- *   const todoId = createId<"Todo">();
- * });
+ * const replayCreateId = testCreateId();
+ * expect(replayCreateId()).toBe(callbackId);
+ * expectTypeOf(todoId).toEqualTypeOf<Id & Brand<"Todo">>();
  * ```
  */
 export const testCreateId = () => {
     const randomBytes = testCreateRandomBytes({
         randomLib: testCreateRandomLib(),
     });
-    return () => createId({ randomBytes });
+    return (() => createId({ randomBytes }));
 };

package/dist/src/Time.d.ts

@@ -3,18 +3,39 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
-import { type DateIso } from "./Type.js";
-import type { Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9, Digit1To99 } from "./Types.js";
+import type { Brand } from "./Brand.ts";
+import { type DateIso, type NonNaNNumber } from "./Type.ts";
+import type { Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9, Digit1To99 } from "./Types.ts";
 /** Time and timer operations. */
 export interface Time {
-    /** 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 now: {
+        /** Returns current time as Unix epoch milliseconds. */
+        (): Millis;
+        /** 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 positive delay. */
+    readonly setTimeout: (fn: () => void, delay: PositiveDuration) => TimeoutId;
+    /**
+     * 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;
 }
 export interface TimeDep {
@@ -27,7 +48,13 @@ export interface TimeDep {
  */
 export type TimeoutId = Brand<"TimeoutId">;
 /**
- * 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.
@@ -39,7 +66,12 @@ export declare const createTime: () => Time;
  * 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;
 }
 export interface TestTimeDep {
@@ -52,17 +84,17 @@ 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 declare const testCreateTime: (options?: {
     readonly startAt?: Millis;
     readonly autoIncrement?: "microtask" | "sync";
 }) => TestTime;
 /**
- * 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
@@ -73,8 +105,11 @@ export declare const testCreateTime: (options?: {
  * If a system clock exceeds this range, operations will throw. This is
  * intentional — there's no reasonable fallback for a misconfigured clock.
  */
-export declare const Millis: import("./Type.js").BrandType<import("./Type.js").BrandType<import("./Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("./Type.js").NonNegativeError, number & Brand<"Int">, import("./Type.js").NumberError | import("./Type.js").IntError>, "LessThan281474976710655", import("./Type.js").LessThanError<281474976710655>, import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError>, "Millis", import("./Type.js").BrandWithoutRefineError<"Millis", import("./Type.js").NumberError | import("./Type.js").LessThanError<281474976710655> | import("./Type.js").NonNegativeError | import("./Type.js").IntError>, never>;
-export type Millis = typeof Millis.Type;
+export declare const Millis: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").Type<"Number", number, number, import("./Type.ts").TypeOfError<"Number">, null, import("./Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("./Type.ts").NonNaNError>, "Finite", import("./Type.ts").FiniteError>, "Int", import("./Type.ts").IntError>, "NonNegative", import("./Type.ts").NonNegativeError>, "LessThan281474976710655", import("./Type.ts").LessThanError<281474976710655>>, "Millis", never>;
+export type Millis = typeof Millis.Output;
+/** Positive {@link Millis} value. */
+export declare const PositiveMillis: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").Type<"Number", number, number, import("./Type.ts").TypeOfError<"Number">, null, import("./Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("./Type.ts").NonNaNError>, "Finite", import("./Type.ts").FiniteError>, "Int", import("./Type.ts").IntError>, "NonNegative", import("./Type.ts").NonNegativeError>, "LessThan281474976710655", import("./Type.ts").LessThanError<281474976710655>>, "Millis", never>, "Positive", import("./Type.ts").PositiveError>;
+export type PositiveMillis = typeof PositiveMillis.Output;
 /** Minimum {@link Millis} value. */
 export declare const minMillis: Millis;
 /** Maximum {@link Millis} value. */
@@ -83,7 +118,7 @@ export declare const maxMillis: Millis;
  * Converts a number to {@link Millis}, rounding to the nearest millisecond and
  * saturating overflow at {@link maxMillis}.
  */
-export declare const saturateMillis: (value: number) => Millis;
+export declare const saturateMillis: (value: NonNaNNumber) => Millis;
 /**
  * Converts {@link Millis} to {@link DateIso}.
  *
@@ -91,11 +126,25 @@ export declare const saturateMillis: (value: number) => Millis;
  * that always produces a valid ISO string.
  */
 export declare const millisToDateIso: (value: Millis) => 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 declare const performanceDurationBetween: (start: PerformanceTime, end: PerformanceTime) => 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.
  *
@@ -110,9 +159,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),
@@ -166,29 +215,17 @@ export type DurationLiteralYears = `${Digit1To99}y` | `${Digit1To99}.${Digit1To9
  * ### 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)
- * ```
- */
-export declare const durationToMillis: (duration: Duration) => Millis;
-/**
- * Returns a Promise that resolves after the specified duration.
+ * import { durationToMillis, Millis } from "@evolu/common";
  *
- * Uses {@link Duration} parsing and `globalThis.setTimeout`.
- *
- * ### Example
- *
- * ```ts
- * await setTimeout("1ms");
+ * 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 declare const setTimeout: (duration: Duration) => Promise<void>;
+export declare function durationToMillis(duration: DurationLiteral | PositiveMillis): PositiveMillis;
+export declare function durationToMillis(duration: Duration): Millis;
 /**
  * Frame budget at 60fps (16ms).
  *
@@ -215,24 +252,46 @@ export declare const msLongTask: 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 declare const formatMillisAsDuration: (millis: Millis) => string;
 /**
- * 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 declare const formatMillisAsClockTime: (millis: Millis) => string;

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

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}