@evolu/common 8.0.0-next.4 → 8.0.0

package/src/LeakDetector.ts

@@ -0,0 +1,182 @@
+/**
+ * Development-time detection of leaked handles via garbage collection.
+ *
+ * @module
+ */
+
+import { type ConsoleDep } from "./Console.ts";
+import { constVoid } from "./Function.ts";
+
+/**
+ * Detects handles that are garbage-collected while still considered held.
+ *
+ * A handle such as a Lease must be explicitly cleaned up. Nothing in JavaScript
+ * enforces that, so a handle whose last reference is dropped without cleanup
+ * leaks silently. Garbage collection proves the leak: once the handle is
+ * unreachable, no code can ever clean it up. A LeakDetector observes collection
+ * with `FinalizationRegistry` and warns when the collected handle was still
+ * held — a proven leak with zero false positives, pointing at the tracking
+ * site.
+ *
+ * Detection is best-effort: garbage collection timing is not deterministic, so
+ * a warning may come late or, in short-lived processes, never. It is a
+ * development canary, not a guarantee. Production uses
+ * {@link noopLeakDetector}.
+ */
+export interface LeakDetector {
+  /**
+   * Starts tracking `target` until {@link LeakDetector.untrack | untrack} or
+   * garbage collection.
+   *
+   * When `target` is garbage-collected and {@link Leak.isLeaked} returns `true`,
+   * the leak is reported with the stack captured at this call. The leak must
+   * not reference `target`, or the target would never become unreachable.
+   */
+  readonly track: (target: object, leak: Leak, unregisterToken: object) => void;
+
+  /** Stops tracking the target registered with `unregisterToken`. */
+  readonly untrack: (unregisterToken: object) => void;
+}
+
+/** Describes a tracked handle for {@link LeakDetector.track}. */
+export interface Leak {
+  /** Handle name used in the warning, for example `"Lease"`. */
+  readonly name: string;
+
+  /** Returns whether the collected handle was still considered held. */
+  readonly isLeaked: () => boolean;
+}
+
+/**
+ * Dependency wrapper for {@link LeakDetector}.
+ *
+ * @see {@link LeakDetector}
+ */
+export interface LeakDetectorDep {
+  readonly leakDetector: LeakDetector;
+}
+
+/**
+ * Creates {@link LeakDetector} backed by `FinalizationRegistry`.
+ *
+ * Capturing a stack per track call is too expensive for production; use
+ * {@link noopLeakDetector} there.
+ */
+export const createLeakDetector = (deps: ConsoleDep): LeakDetector => {
+  if (typeof globalThis.FinalizationRegistry !== "function")
+    return noopLeakDetector;
+
+  const registry = new globalThis.FinalizationRegistry<TrackedLeak>(
+    reportLeak(deps),
+  );
+
+  return {
+    track: (target, leak, unregisterToken) => {
+      registry.register(
+        target,
+        { ...leak, stack: new Error().stack },
+        unregisterToken,
+      );
+    },
+    untrack: (unregisterToken) => {
+      registry.unregister(unregisterToken);
+    },
+  };
+};
+
+/** No-op {@link LeakDetector} for production. */
+export const noopLeakDetector: LeakDetector = {
+  track: constVoid,
+  untrack: constVoid,
+};
+
+interface TrackedLeak extends Leak {
+  readonly stack: string | undefined;
+}
+
+/**
+ * Reports a collected handle that was still held.
+ *
+ * Shared by {@link createLeakDetector} as the `FinalizationRegistry` callback
+ * and by {@link testCreateLeakDetector.collect | collect}, so tests cover the
+ * same reporting path without forcing garbage collection. Returns whether the
+ * leak was reported.
+ */
+const reportLeak =
+  (deps: ConsoleDep) =>
+  (leak: TrackedLeak): boolean => {
+    if (!leak.isLeaked()) return false;
+    deps.console.warn(
+      `${leak.name} was garbage-collected without cleanup. Tracked at:`,
+      leak.stack,
+    );
+    return true;
+  };
+
+/**
+ * Test {@link LeakDetector} with deterministic collection.
+ *
+ * @see {@link testCreateLeakDetector}
+ */
+export interface TestLeakDetector extends LeakDetector {
+  /**
+   * Simulates garbage collection of all tracked targets.
+   *
+   * Reports every tracked handle that is still held and clears tracking.
+   * Returns the number of reported leaks.
+   */
+  readonly collect: () => number;
+
+  /** Returns the number of currently tracked targets. */
+  readonly getTrackedCount: (options?: { name?: string }) => number;
+}
+
+/**
+ * Dependency wrapper for {@link TestLeakDetector}.
+ *
+ * @see {@link TestLeakDetector}
+ */
+export interface TestLeakDetectorDep extends LeakDetectorDep {
+  readonly leakDetector: TestLeakDetector;
+}
+
+/** Creates {@link TestLeakDetector}. */
+export const testCreateLeakDetector = (deps: ConsoleDep): TestLeakDetector => {
+  const trackedLeaksByToken = new Map<object, ReadonlyArray<TrackedLeak>>();
+  const report = reportLeak(deps);
+
+  return {
+    track: (_target, leak, unregisterToken) => {
+      const trackedLeaks = trackedLeaksByToken.get(unregisterToken) ?? [];
+      trackedLeaksByToken.set(unregisterToken, [
+        ...trackedLeaks,
+        {
+          ...leak,
+          stack: new Error().stack,
+        },
+      ]);
+    },
+    untrack: (unregisterToken) => {
+      trackedLeaksByToken.delete(unregisterToken);
+    },
+    collect: () => {
+      let leakCount = 0;
+      for (const trackedLeaks of trackedLeaksByToken.values()) {
+        for (const leak of trackedLeaks) {
+          if (report(leak)) leakCount++;
+        }
+      }
+      trackedLeaksByToken.clear();
+      return leakCount;
+    },
+    getTrackedCount: ({ name } = {}) => {
+      let count = 0;
+      for (const trackedLeaks of trackedLeaksByToken.values()) {
+        for (const leak of trackedLeaks) {
+          if (name === undefined || leak.name === name) count++;
+        }
+      }
+      return count;
+    },
+  };
+};

package/src/LockManager.ts

@@ -4,12 +4,12 @@
  * @module
  */
 
-import { createRandomBytes } from "./Crypto.js";
-import { lazyVoid } from "./Function.js";
-import { tryAsync } from "./Result.js";
-import { AbortError, type Task } from "./Task.js";
-import { createId } from "./Type.js";
-import type { Callback } from "./Types.js";
+import { createRandomBytes } from "./Crypto.ts";
+import { constVoid } from "./Function.ts";
+import { ok } from "./Result.ts";
+import type { Task } from "./Task.ts";
+import { createId } from "./Type.ts";
+import type { Callback } from "./Types.ts";
 
 /**
  * Dependency wrapper for {@link LockManager}.
@@ -17,24 +17,33 @@ import type { Callback } from "./Types.js";
  * For React Native, use the `lockManager` ponyfill from `@evolu/react-native`.
  * For tests, use {@link testCreateLockManager}.
  *
- * ### Example
+ * ### Web and Node.js 24+
  *
  * ```ts
- * // Web or Node.js 24+
- * import { testCreateLockManager } from "@evolu/common";
+ * import type { LockManagerDep } from "@evolu/common";
  *
  * const deps: LockManagerDep = {
- *   lockManager: testCreateLockManager(),
+ *   lockManager: globalThis.navigator.locks,
  * };
+ *
+ * const result = await deps.lockManager.request("example", (lock) => {
+ *   return lock?.name;
+ * });
+ * expect(result).toBe("example");
  * ```
  *
- * ### Example
+ * ### React Native
  *
  * ```ts
- * // React Native
+ * import type { LockManagerDep } from "@evolu/common";
  * import { lockManager } from "@evolu/react-native";
  *
  * const deps: LockManagerDep = { lockManager };
+ *
+ * const result = await deps.lockManager.request("example", (lock) => {
+ *   return lock?.name;
+ * });
+ * expect(result).toBe("example");
  * ```
  */
 
@@ -110,35 +119,30 @@ export const testCreateLockManager = (
  * abortable via the calling {@link Task}'s signal.
  */
 export const acquireLeaderLock =
-  (name: string): Task<AsyncDisposable, AbortError, LockManagerDep> =>
-  (run) =>
-    tryAsync(
-      async () => {
-        const acquisition = Promise.withResolvers<void>();
-        const released = Promise.withResolvers<void>();
+  (name: string): Task<AsyncDisposable, never, LockManagerDep> =>
+  async (run) => {
+    const acquisition = Promise.withResolvers<void>();
+    const released = Promise.withResolvers<void>();
 
-        const request = run.deps.lockManager.request(
-          createLeaderLockName(name),
-          { mode: "exclusive", signal: run.signal },
-          async () => {
-            acquisition.resolve();
-            await released.promise;
-          },
-        );
-        void request.catch(acquisition.reject);
-
-        await acquisition.promise;
-
-        return {
-          [Symbol.asyncDispose]: async () => {
-            released.resolve();
-            await request;
-          },
-        };
+    const request = run.deps.lockManager.request(
+      createLeaderLockName(name),
+      { mode: "exclusive", signal: run.signal },
+      async () => {
+        acquisition.resolve();
+        await released.promise;
       },
-      (error): AbortError =>
-        AbortError.is(error) ? error : { type: "AbortError", reason: error },
     );
+    void request.catch(acquisition.reject);
+
+    await acquisition.promise;
+
+    return ok({
+      [Symbol.asyncDispose]: async () => {
+        released.resolve();
+        await request;
+      },
+    });
+  };
 
 /**
  * Competes to become the current leader for `name` using {@link LockManager}.
@@ -167,7 +171,7 @@ export const acquireLeaderLockCallback =
         await released.promise;
       },
     );
-    void request.catch(lazyVoid);
+    void request.catch(constVoid);
 
     return {
       [Symbol.dispose]: () => {

package/src/Lookup.ts

@@ -4,10 +4,10 @@
  * @module
  */
 
-import { assert } from "./Assert.js";
-import type { Brand } from "./Brand.js";
-import { isPlainObject } from "./Object.js";
-import { Uint8Array, uint8ArrayToBase64Url } from "./Type.js";
+import { assert } from "./Assert.ts";
+import type { Brand } from "./Brand.ts";
+import { isPlainObject } from "./Object.ts";
+import { Uint8Array, uint8ArrayToBase64Url } from "./Type.ts";
 
 /**
  * Derives the native lookup key used by lookup-based collections.
@@ -23,6 +23,16 @@ import { Uint8Array, uint8ArrayToBase64Url } from "./Type.js";
  * Use this when callers provide keys in one form but logical identity should be
  * based on another stable key, such as a natural id or {@link StructuralKey}.
  *
+ * Lookup functions must be pure and stable. The same logical key must derive
+ * the same native `Map` key while an entry is stored, so use lookup-based
+ * collections with immutable key data, preferably readonly values. Mutating key
+ * data after insertion can make later `get`, `has`, and `delete` calls disagree
+ * with the inserted entry.
+ *
+ * The returned lookup key uses native `Map` equality. Return primitives or
+ * stable object references; returning a new object for each call prevents equal
+ * logical keys from matching.
+ *
  * @see {@link createLookupMap}
  * @see {@link createLookupSet}
  */
@@ -74,12 +84,12 @@ export const createLookupMap = <K, V, L>({
   lookup,
   entries,
 }: CreateLookupMapOptions<K, V, L>): LookupMap<K, V> => {
-  interface LookupEntry<K, V> {
+  interface LookupEntry {
     readonly key: K;
     readonly value: V;
   }
 
-  const entriesByLookupKey = new Map<L, LookupEntry<K, V>>();
+  const entriesByLookupKey = new Map<L, LookupEntry>();
 
   const map: LookupMap<K, V> = {
     get size() {
@@ -278,8 +288,10 @@ export type StructuralKey =
  *
  * `Structural<T>` checks a concrete type recursively at compile time instead:
  * scalars pass through, arrays recurse, object properties recurse, and
- * function-valued properties are rejected. This keeps public structural APIs
- * ergonomic for interface-based inputs while preserving the same runtime
+ * function-valued and symbol-keyed properties are rejected. Symbol-keyed
+ * properties are rejected because runtime serialization reads only enumerable
+ * string keys, so they would be silently ignored. This keeps public structural
+ * APIs ergonomic for interface-based inputs while preserving the same runtime
  * constraints as structural lookup serialization.
  *
  * @see {@link StructuralKey}
@@ -293,19 +305,21 @@ export type Structural<T> = T extends StructuralScalar
       ? never
       : T extends object
         ? {
-            readonly [K in keyof T as Extract<
-              T[K],
-              StructuralFunction
-            > extends never
-              ? K
-              : never]: Structural<Exclude<T[K], StructuralFunction>>;
+            readonly [
+              K in keyof T as K extends symbol
+                ? never
+                : Extract<T[K], StructuralFunction> extends never
+                  ? K
+                  : never
+            ]: Structural<Exclude<T[K], StructuralFunction>>;
           } & {
-            readonly [K in keyof T as Extract<
-              T[K],
-              StructuralFunction
-            > extends never
-              ? never
-              : K]?: never;
+            readonly [
+              K in keyof T as K extends symbol
+                ? K
+                : Extract<T[K], StructuralFunction> extends never
+                  ? never
+                  : K
+            ]?: never;
           }
         : never;
 
@@ -317,7 +331,8 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  *
  * Structural lookup keys are derived from JSON-like values plus `Uint8Array`.
  * Equal structures produce the same lookup key even when they are different
- * JavaScript instances.
+ * JavaScript instances. `undefined` values and sparse array holes are rejected
+ * rather than skipped.
  *
  * The derived key is memoized by non-null object identity in a module-scoped
  * `WeakMap` shared by all callers, so keys must be immutable.
@@ -328,16 +343,33 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  * ### Example
  *
  * ```ts
- * const byFilter = createLookupMap<
- *   { readonly table: string; readonly where: readonly [string, string] },
- *   string,
- *   StructuralLookupKey
- * >({
+ * import {
+ *   createLookupMap,
+ *   structuralLookup,
+ *   type StructuralLookupKey,
+ * } from "@evolu/common";
+ *
+ * interface Filter {
+ *   readonly table: string;
+ *   readonly where: readonly [string, string];
+ * }
+ *
+ * const byFilter = createLookupMap<Filter, string, StructuralLookupKey>({
  *   lookup: structuralLookup,
  * });
  *
- * byFilter.set({ table: "todo", where: ["owner", "ada"] }, "cached");
- * byFilter.get({ table: "todo", where: ["owner", "ada"] }); // "cached"
+ * const cachedFilter: Filter = {
+ *   table: "todo",
+ *   where: ["owner", "ada"],
+ * };
+ * const equivalentFilter: Filter = {
+ *   where: ["owner", "ada"],
+ *   table: "todo",
+ * };
+ * byFilter.set(cachedFilter, "cached");
+ *
+ * expect(byFilter.get(equivalentFilter)).toBe("cached");
+ * expect(byFilter.getKey(equivalentFilter)).toBe(cachedFilter);
  * ```
  *
  * @see {@link StructuralKey}
@@ -395,6 +427,8 @@ const structuralLookupInternal = (
         );
       }
 
+      // Cache only after traversal succeeds so cyclic values never leave a
+      // partial lookup key in the memo.
       structuralLookupKeyByValue.set(value, lookupKey);
       return lookupKey;
     }

package/src/Microtask.ts

@@ -4,8 +4,8 @@
  * @module
  */
 
-import { appendToArray, type NonEmptyReadonlyArray } from "./Array.js";
-import { assertNotDisposed } from "./Assert.js";
+import { appendToArray, type NonEmptyReadonlyArray } from "./Array.ts";
+import { disposable } from "./Function.ts";
 
 /**
  * Batches values and flushes them in a single microtask.
@@ -32,8 +32,6 @@ export const createMicrotaskBatch = <T>(
     queue = null;
   });
 
-  const disposables = disposer.move();
-
   const flushQueuedItems = () => {
     if (queue == null) return;
     const queuedItems = queue;
@@ -41,24 +39,22 @@ export const createMicrotaskBatch = <T>(
     onFlush(queuedItems);
   };
 
-  return {
-    push: (item) => {
-      assertNotDisposed(disposables);
-
-      if (queue == null) {
-        queue = [item];
-        queueMicrotask(flushQueuedItems);
-        return;
-      }
-
-      queue = appendToArray(queue, item);
+  return disposable<MicrotaskBatch<T>>(
+    {
+      push: (item) => {
+        if (queue == null) {
+          queue = [item];
+          queueMicrotask(flushQueuedItems);
+          return;
+        }
+
+        queue = appendToArray(queue, item);
+      },
+
+      flushNow: () => {
+        flushQueuedItems();
+      },
     },
-
-    flushNow: () => {
-      assertNotDisposed(disposables);
-      flushQueuedItems();
-    },
-
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
+    disposer,
+  );
 };

package/src/Number.ts

@@ -4,22 +4,51 @@
  * @module
  */
 
-import type { NonEmptyReadonlyArray } from "./Array.js";
-import { assertNonEmptyReadonlyArray } from "./Assert.js";
-import type { IsBranded } from "./Brand.js";
-import type { Result } from "./Result.js";
-import { err, ok } from "./Result.js";
+import type { NonEmptyReadonlyArray } from "./Array.ts";
+import { assertNonEmptyReadonlyArray } from "./Assert.ts";
+import type { IsBranded } from "./Brand.ts";
+import type { Result } from "./Result.ts";
+import { err, ok } from "./Result.ts";
 import {
   brand,
   lessThanOrEqualTo,
   onePositiveInt,
   NonNegativeInt,
   PositiveInt,
-} from "./Type.js";
-import type { Predicate, WidenLiteral } from "./Types.js";
+  Ratio,
+} from "./Type.ts";
+import type {
+  Digit,
+  Digit1To9,
+  Digit1To99,
+  Predicate,
+  WidenLiteral,
+} from "./Types.ts";
+
+/** Percentage represented as a readable literal or a validated ratio. */
+export type Percentage = PercentageLiteral | Ratio;
+
+/**
+ * Percentage literal from `"0%"` to `"100%"`.
+ *
+ * Decimal literals support one decimal place. Use {@link Ratio} for computed
+ * values or greater precision.
+ */
+export type PercentageLiteral =
+  "0%" | "100%" | `${Digit1To99}%` | `${Digit | Digit1To99}.${Digit1To9}%`;
+
+/** Converts a {@link Percentage} to its numeric {@link Ratio}. */
+export const percentageToRatio = (percentage: Percentage): Ratio =>
+  typeof percentage === "number"
+    ? percentage
+    : Ratio.orThrow(globalThis.Number.parseFloat(percentage) / 100);
 
 export const increment = (n: number): number => n + 1;
 
+/** Increments a positive integer, saturating at the maximum safe integer. */
+export const incrementPositiveInt = (n: PositiveInt): PositiveInt =>
+  PositiveInt.orNull(increment(n)) ?? n;
+
 export const decrement = (n: number): number => n - 1;
 
 /** Clamps a number within a given range. */
@@ -34,9 +63,12 @@ export const clamp =
  * ### Example
  *
  * ```ts
+ * import { isBetween } from "@evolu/common";
+ *
  * const isBetween10And20 = isBetween(10, 20);
- * console.log(isBetween10And20(15)); // true
- * console.log(isBetween10And20(25)); // false
+ *
+ * expect(isBetween10And20(20)).toBe(true);
+ * expect(isBetween10And20(25)).toBe(false);
  * ```
  */
 export const isBetween =
@@ -64,8 +96,28 @@ export const max = <T extends number>(
  * ### Example
  *
  * ```ts
- * computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
- * computeBalancedBuckets(5, 3, 2); // Returns err(6)
+ * import {
+ *   computeBalancedBuckets,
+ *   NonNegativeInt,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * expectOk(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(10),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   [4, 7, 10],
+ * );
+ * expectErr(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(5),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   6,
+ * );
  * ```
  */
 export const computeBalancedBuckets = (
@@ -107,7 +159,7 @@ export const FibonacciIndex = /*#__PURE__*/ brand(
   "FibonacciIndex",
   /*#__PURE__*/ lessThanOrEqualTo(78)(PositiveInt),
 );
-export type FibonacciIndex = typeof FibonacciIndex.Type;
+export type FibonacciIndex = typeof FibonacciIndex.Output;
 
 /** Returns the Fibonacci number at the given index (1-indexed: 1,1,2,3,5,8,...). */
 export const fibonacciAt = (index: FibonacciIndex): PositiveInt => {