@evolu/common 8.0.0-next.5 → 8.0.0

package/dist/src/Http.js

@@ -0,0 +1,102 @@
+/**
+ * Task-aware HTTP helpers.
+ *
+ * @module
+ */
+import { err, ok, tryAsync } from "./Result.js";
+export function fetch(input, modeOrConsume, init) {
+    return async (run) => {
+        const { signal } = run;
+        // Abort control flow wins over step errors, normalizing host abort errors
+        // from native fetch, body reads, body cancel, and consumers.
+        const orAbort = (error) => {
+            signal.throwIfAborted();
+            return error;
+        };
+        const fetched = await tryAsync(() => run.deps.nativeFetch(input, { ...init, signal }), orAbort);
+        let result;
+        if (!fetched.ok) {
+            result = err({ type: "FetchTransportError", error: fetched.error });
+        }
+        else {
+            const response = fetched.value;
+            // A response that arrives after abort is not processed: cancel its body
+            // best-effort, then let abort win before any mode or consumer runs.
+            if (signal.aborted) {
+                await tryAsync(() => response.body?.cancel());
+                signal.throwIfAborted();
+            }
+            if (typeof modeOrConsume === "function") {
+                const consumed = await tryAsync(() => modeOrConsume(response), orAbort);
+                // A consumer throw is a defect once orAbort has ruled out abort.
+                if (!consumed.ok)
+                    throw consumed.error;
+                result = consumed.value;
+            }
+            else if (modeOrConsume === "headers") {
+                // The head is already a value; body cancel failures are irrelevant.
+                await tryAsync(() => response.body?.cancel(), orAbort);
+                result = ok(response);
+            }
+            else if (!response.ok) {
+                result = err({
+                    type: "FetchStatusError",
+                    response,
+                    // Error bodies are diagnostics; text preserves proxy/HTML/plain responses across modes.
+                    body: await tryAsync(() => response.text(), orAbort),
+                });
+            }
+            else {
+                const body = await tryAsync(() => {
+                    switch (modeOrConsume) {
+                        case "text":
+                            return response.text();
+                        case "json":
+                            return response.json();
+                        case "bytes":
+                            return response.bytes();
+                    }
+                }, orAbort);
+                result = body.ok
+                    ? body
+                    : err({ type: "FetchBodyError", response, error: body.error });
+            }
+        }
+        // An Err produced after abort is treated as abort control flow.
+        if (!result.ok)
+            signal.throwIfAborted();
+        return result;
+    };
+}
+/**
+ * Creates {@link TestNativeFetch}.
+ *
+ * @group Testing
+ */
+export const testCreateNativeFetch = (...handlers) => {
+    const calls = [];
+    const handlerQueue = [...handlers];
+    return Object.assign((input, init) => {
+        calls.push({ input, init });
+        const handler = handlerQueue.shift();
+        if (!handler)
+            throw new Error("Unexpected NativeFetch call");
+        return Promise.resolve(handler(input, init));
+    }, {
+        calls,
+        handle: (handler) => {
+            handlerQueue.push(handler);
+        },
+    });
+};
+/**
+ * Creates a Response body for {@link NativeFetch} tests that errors on first
+ * read.
+ *
+ * @group Testing
+ */
+export const testCreateNativeFetchErroringBody = (error = new Error("stream failed")) => new ReadableStream({
+    pull: (controller) => {
+        controller.error(error);
+    },
+});

package/dist/src/Identicon.d.ts

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
-import { Id } from "./Type.js";
+import type { Brand } from "./Brand.ts";
+import { Id } from "./Type.ts";
 /**
  * SVG string representing a visual identicon for an {@link Id}, created with
  * {@link createIdenticon}.
@@ -27,13 +27,22 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * ### Example
  *
  * ```ts
+ * import { createIdFromString, createIdenticon } from "@evolu/common";
+ *
+ * const id = createIdFromString("identicon-example");
  * const svg = createIdenticon(id);
- * const quadrantStyle = createIdenticon(id, "quadrant");
- * const gradientStyle = createIdenticon(id, "gradient");
- * const sutnarStyle = createIdenticon(id, "sutnar");
+ * const styles = ["quadrant", "gradient", "sutnar"] as const;
+ * const alternativeSvgs = styles.map((style) =>
+ *   createIdenticon(id, style),
+ * );
+ *
+ * // Branded IDs work too.
+ * const todoId = createIdFromString<"Todo">("todo-1");
+ * const todoSvg = createIdenticon(todoId);
  *
- * // Works with branded IDs
- * const ownerSvg = createIdenticon(ownerId);
+ * expect(svg.startsWith("<svg")).toBe(true);
+ * expect(new Set([svg, ...alternativeSvgs]).size).toBe(4);
+ * expect(todoSvg.startsWith("<svg")).toBe(true);
  * ```
  */
 export declare const createIdenticon: (id: Id, style?: IdenticonStyle) => Identicon;

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

@@ -1 +1 @@
-{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,QAAO,cAAyB,KAC/B,SA4JF,CAAC"}
+{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,OACtB,EAAE,UACC,cAAc,KACpB,SA4JF,CAAC"}

package/dist/src/Identicon.js

@@ -20,13 +20,22 @@ import { Id, idToIdBytes } from "./Type.js";
  * ### Example
  *
  * ```ts
+ * import { createIdFromString, createIdenticon } from "@evolu/common";
+ *
+ * const id = createIdFromString("identicon-example");
  * const svg = createIdenticon(id);
- * const quadrantStyle = createIdenticon(id, "quadrant");
- * const gradientStyle = createIdenticon(id, "gradient");
- * const sutnarStyle = createIdenticon(id, "sutnar");
+ * const styles = ["quadrant", "gradient", "sutnar"] as const;
+ * const alternativeSvgs = styles.map((style) =>
+ *   createIdenticon(id, style),
+ * );
+ *
+ * // Branded IDs work too.
+ * const todoId = createIdFromString<"Todo">("todo-1");
+ * const todoSvg = createIdenticon(todoId);
  *
- * // Works with branded IDs
- * const ownerSvg = createIdenticon(ownerId);
+ * expect(svg.startsWith("<svg")).toBe(true);
+ * expect(new Set([svg, ...alternativeSvgs]).size).toBe(4);
+ * expect(todoSvg.startsWith("<svg")).toBe(true);
  * ```
  */
 export const createIdenticon = (id, style = "github") => {

package/dist/src/LeakDetector.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Development-time detection of leaked handles via garbage collection.
+ *
+ * @module
+ */
+import { type ConsoleDep } from "./Console.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 declare const createLeakDetector: (deps: ConsoleDep) => LeakDetector;
+/** No-op {@link LeakDetector} for production. */
+export declare const noopLeakDetector: LeakDetector;
+/**
+ * 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 declare const testCreateLeakDetector: (deps: ConsoleDep) => TestLeakDetector;
+//# sourceMappingURL=LeakDetector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LeakDetector.d.ts","sourceRoot":"","sources":["../../src/LeakDetector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9E,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,iEAAiE;AACjE,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,UAAU,KAAG,YAoBrD,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,EAAE,YAG9B,CAAC;AAyBF;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAE/B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,SAAU,UAAU,KAAG,gBAsCzD,CAAC"}

package/dist/src/LeakDetector.js

@@ -0,0 +1,86 @@
+/**
+ * Development-time detection of leaked handles via garbage collection.
+ *
+ * @module
+ */
+import {} from "./Console.js";
+import { constVoid } from "./Function.js";
+/**
+ * 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) => {
+    if (typeof globalThis.FinalizationRegistry !== "function")
+        return noopLeakDetector;
+    const registry = new globalThis.FinalizationRegistry(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 = {
+    track: constVoid,
+    untrack: constVoid,
+};
+/**
+ * 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) => (leak) => {
+    if (!leak.isLeaked())
+        return false;
+    deps.console.warn(`${leak.name} was garbage-collected without cleanup. Tracked at:`, leak.stack);
+    return true;
+};
+/** Creates {@link TestLeakDetector}. */
+export const testCreateLeakDetector = (deps) => {
+    const trackedLeaksByToken = new Map();
+    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/dist/src/LockManager.d.ts

@@ -3,32 +3,41 @@
  *
  * @module
  */
-import { AbortError, type Task } from "./Task.js";
-import type { Callback } from "./Types.js";
+import type { Task } from "./Task.ts";
+import type { Callback } from "./Types.ts";
 /**
  * Dependency wrapper for {@link LockManager}.
  *
  * 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");
  * ```
  */
 export interface LockManagerDep {
@@ -58,7 +67,7 @@ export declare const testCreateLockManager: (nativeLockManager?: LockManager) =>
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
  */
-export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable, AbortError, LockManagerDep>;
+export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable, never, LockManagerDep>;
 /**
  * Competes to become the current leader for `name` using {@link LockManager}.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAChC,oBAAmB,WAAwC,KAC1D,WAwCF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC3B,MAAM,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,UAAU,EAAE,cAAc,CA4B7D,CAAC;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACnC,MAAM,cAAc,MACpB,MAAM,MAAM,EAAE,UAAU,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}
+{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,uBACb,WAAW,KAC7B,WAwCF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,SACrB,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,CAuB1D,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,SAC7B,cAAc,YACd,MAAM,YAAY,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}

package/dist/src/LockManager.js

@@ -4,9 +4,8 @@
  * @module
  */
 import { createRandomBytes } from "./Crypto.js";
-import { lazyVoid } from "./Function.js";
-import { tryAsync } from "./Result.js";
-import { AbortError } from "./Task.js";
+import { constVoid } from "./Function.js";
+import { ok } from "./Result.js";
 import { createId } from "./Type.js";
 /**
  * Creates a test {@link LockManager} backed by the native platform
@@ -56,7 +55,7 @@ export const testCreateLockManager = (nativeLockManager = globalThis.navigator.l
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
  */
-export const acquireLeaderLock = (name) => (run) => tryAsync(async () => {
+export const acquireLeaderLock = (name) => async (run) => {
     const acquisition = Promise.withResolvers();
     const released = Promise.withResolvers();
     const request = run.deps.lockManager.request(createLeaderLockName(name), { mode: "exclusive", signal: run.signal }, async () => {
@@ -65,13 +64,13 @@ export const acquireLeaderLock = (name) => (run) => tryAsync(async () => {
     });
     void request.catch(acquisition.reject);
     await acquisition.promise;
-    return {
+    return ok({
         [Symbol.asyncDispose]: async () => {
             released.resolve();
             await request;
         },
-    };
-}, (error) => AbortError.is(error) ? error : { type: "AbortError", reason: error });
+    });
+};
 /**
  * Competes to become the current leader for `name` using {@link LockManager}.
  *
@@ -92,7 +91,7 @@ export const acquireLeaderLockCallback = (deps) => (name, callback) => {
         callback();
         await released.promise;
     });
-    void request.catch(lazyVoid);
+    void request.catch(constVoid);
     return {
         [Symbol.dispose]: () => {
             abortController.abort();

package/dist/src/Lookup.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
+import type { Brand } from "./Brand.ts";
 /**
  * Derives the native lookup key used by lookup-based collections.
  *
@@ -18,6 +18,16 @@ import type { Brand } from "./Brand.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}
  */
@@ -113,17 +123,19 @@ export type StructuralKey = StructuralScalar | ReadonlyArray<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}
  * @see {@link structuralLookup}
  */
 export type Structural<T> = T extends StructuralScalar ? T : T extends ReadonlyArray<infer Item> ? ReadonlyArray<Structural<Item>> : T extends StructuralFunction ? 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;
 /** Function branch excluded by {@link Structural}. */
 export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
@@ -132,7 +144,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.
@@ -143,16 +156,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}

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

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

package/dist/src/Lookup.js

@@ -113,7 +113,8 @@ export const createLookupSet = ({ lookup, values, }) => {
  *
  * 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.
@@ -124,16 +125,33 @@ export const createLookupSet = ({ lookup, values, }) => {
  * ### 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}
@@ -180,6 +198,8 @@ const structuralLookupInternal = (value, path = new Set()) => {
             else {
                 assert(false, "Structural lookup keys must be JSON-like values or Uint8Array.");
             }
+            // Cache only after traversal succeeds so cyclic values never leave a
+            // partial lookup key in the memo.
             structuralLookupKeyByValue.set(value, lookupKey);
             return lookupKey;
         }

package/dist/src/Microtask.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { type NonEmptyReadonlyArray } from "./Array.js";
+import { type NonEmptyReadonlyArray } from "./Array.ts";
 /**
  * Batches values and flushes them in a single microtask.
  *