@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/RefCount.js

@@ -0,0 +1,83 @@
+/**
+ * Reference counting helpers.
+ *
+ * @module
+ */
+import { assert, assertNotDisposed } from "./Assert.js";
+import { identity } from "./Function.js";
+import { createLookupMap } from "./Lookup.js";
+import { NonNegativeInt, PositiveInt, zeroNonNegativeInt } from "./Type.js";
+/** Creates {@link RefCount}. */
+export const createRefCount = () => {
+    let count = zeroNonNegativeInt;
+    const stack = new DisposableStack();
+    stack.defer(() => {
+        count = zeroNonNegativeInt;
+    });
+    const moved = stack.move();
+    return {
+        increment: () => {
+            assertNotDisposed(moved);
+            const nextCount = PositiveInt.orThrow(count + 1);
+            count = nextCount;
+            return nextCount;
+        },
+        decrement: () => {
+            assertNotDisposed(moved);
+            assert(count > 0, "RefCount must not be decremented below zero.");
+            count = NonNegativeInt.orThrow(count - 1);
+            return count;
+        },
+        getCount: () => {
+            assertNotDisposed(moved);
+            return count;
+        },
+        [Symbol.dispose]: () => moved.dispose(),
+    };
+};
+export function createRefCountByKey({ lookup = identity, } = {}) {
+    const stack = new DisposableStack();
+    const refCountByKey = stack.adopt(createLookupMap({ lookup }), (refCountByKey) => {
+        for (const refCount of refCountByKey.values())
+            refCount[Symbol.dispose]();
+        refCountByKey.clear();
+    });
+    const moved = stack.move();
+    const getRefCount = (key) => {
+        let refCount = refCountByKey.get(key);
+        if (!refCount) {
+            refCount = createRefCount();
+            refCountByKey.set(key, refCount);
+        }
+        return refCount;
+    };
+    return {
+        increment: (key) => {
+            assertNotDisposed(moved);
+            return getRefCount(key).increment();
+        },
+        decrement: (key) => {
+            assertNotDisposed(moved);
+            const refCount = getRefCount(key);
+            const nextCount = refCount.decrement();
+            if (nextCount === 0) {
+                refCount[Symbol.dispose]();
+                refCountByKey.delete(key);
+            }
+            return nextCount;
+        },
+        getCount: (key) => {
+            assertNotDisposed(moved);
+            return refCountByKey.get(key)?.getCount() ?? zeroNonNegativeInt;
+        },
+        has: (key) => {
+            assertNotDisposed(moved);
+            return refCountByKey.has(key);
+        },
+        keys: () => {
+            assertNotDisposed(moved);
+            return new Set(refCountByKey.keys());
+        },
+        [Symbol.dispose]: () => moved.dispose(),
+    };
+}

package/dist/src/Relation.d.ts

@@ -1,7 +1,11 @@
 /**
- * Bidirectional relation between two types.
+ * Bidirectional relations with O(1) lookup in both directions.
  *
- * Why useful:
+ * @module
+ */
+import { type Lookup } from "./Lookup.js";
+/**
+ * Bidirectional relation between two types.
  *
  * - Provides O(1) (amortized) lookup in both directions (A → B and B → A) without
  *   maintaining two maps manually and risking them diverging.
@@ -9,26 +13,56 @@
  *   item, user ↔ role, entity ↔ subscription where both directions are
  *   frequently queried.
  * - Supports fast membership tests via `has`, `hasA`, and `hasB`.
- * - Iteration helpers (`forEach`, iterator) allow treating the structure as a set
- *   of pairs when needed.
+ * - Exposes directional iterators for imperative `for...of` traversal.
+ * - The relation itself is iterable, allowing it to be treated as a set of pairs
+ *   when needed.
  *
  * Complexity:
  *
- * - `add` / `remove` / `has*` / `get*` each perform a constant number of Map/Set
- *   operations (O(1) expected).
- * - `deleteA` and `deleteB` are O(d) where d is the number of associated elements
- *   (the degree). This is optimal because every associated pair must be touched
- *   once.
+ * - `add` / `remove` / `has*` / `*Count*` each perform a constant number of
+ *   Map/Set operations (O(1) expected).
+ * - `iterateA` and `iterateB` create iterators in O(1); consuming them is O(d)
+ *   where d is the number of associated elements.
+ * - `removeByA` and `removeByB` are O(d) where d is the number of associated
+ *   elements, because every associated pair must be touched once.
+ *
+ * By default, {@link createRelation} uses reference identity for both sides,
+ * matching native `Map` and `Set`. Callers may instead provide
+ * {@link Lookup lookup} functions so logical equality is based on a derived
+ * stable key.
+ *
+ * The input parameter types of `lookupA` and `lookupB` determine which values
+ * the returned relation accepts on each side.
+ *
+ * ### Example
+ *
+ * Use the default identity semantics.
  *
- * Object identity:
+ * ```ts
+ * const relation = createRelation<WebSocket, string>();
+ * relation.add(socket, "owner-1");
+ * ```
  *
- * - Elements are compared by reference (standard Map / Set semantics). Structural
- *   hashing of objects in JavaScript is non-trivial, can be expensive, and
- *   collision-prone if done naively. Prefer using stable primitive identifiers
- *   (ids, strings) instead of attempting to hash full object structures.
- * - If structural equivalence is truly required, wrap objects in an adapter that
- *   supplies a canonical hash/id and stores/retrieves the original objects
- *   separately. This is a rare need; avoid unless you have clear requirements.
+ * ### Example
+ *
+ * Use lookup-derived equality.
+ *
+ * ```ts
+ * interface Person {
+ *   readonly id: string;
+ *   readonly name: string;
+ * }
+ *
+ * const relation = createRelation({
+ *   lookupA: (person: Person) => person.id,
+ *   lookupB: (group: { readonly id: string }) => group.id,
+ * });
+ *
+ * relation.add({ id: "1", name: "Ada" }, { id: "admins" });
+ * relation.has({ id: "1", name: "Grace" }, { id: "admins" }); // true
+ * ```
+ *
+ * @see {@link createRelation}
  */
 export interface Relation<A, B> {
     /**
@@ -41,15 +75,28 @@ export interface Relation<A, B> {
      * and was removed, false if it was not present.
      */
     readonly remove: (a: A, b: B) => boolean;
-    /** Gets all B elements related to an A element. */
-    readonly getB: (a: A) => ReadonlySet<B> | undefined;
-    /** Gets all A elements related to a B element. */
-    readonly getA: (b: B) => ReadonlySet<A> | undefined;
+    /** Removes all pairs containing the given A element. */
+    readonly removeByA: (a: A) => boolean;
+    /** Removes all pairs containing the given B element. */
+    readonly removeByB: (b: B) => boolean;
+    /**
+     * Iterates over all A elements related to a B element.
+     *
+     * Returns a live iterator over the current relation state rather than a
+     * snapshot copy.
+     *
+     * Returns an empty iterator when the B element has no related values.
+     */
+    readonly iterateA: (b: B) => IterableIterator<A>;
     /**
-     * Iterates over each pair in the relation (in insertion order of A elements,
-     * then B elements per A).
+     * Iterates over all B elements related to an A element.
+     *
+     * Returns a live iterator over the current relation state rather than a
+     * snapshot copy.
+     *
+     * Returns an empty iterator when the A element has no related values.
      */
-    readonly forEach: (callback: (a: A, b: B) => void) => void;
+    readonly iterateB: (a: A) => IterableIterator<B>;
     /**
      * Iterator over all pairs enabling for..of and spread. Yields readonly [a, b]
      * tuples.
@@ -61,19 +108,27 @@ export interface Relation<A, B> {
     readonly hasA: (a: A) => boolean;
     /** Checks if a B element exists in the relation. */
     readonly hasB: (b: B) => boolean;
-    /** Deletes all pairs containing the given A element. */
-    readonly deleteA: (a: A) => boolean;
-    /** Deletes all pairs containing the given B element. */
-    readonly deleteB: (b: B) => boolean;
     /** Clears all pairs from the relation. */
     readonly clear: () => void;
     /** Number of distinct A elements currently present. */
     readonly aCount: () => number;
     /** Number of distinct B elements currently present. */
     readonly bCount: () => number;
+    /** Number of B elements related to the given A element. */
+    readonly bCountForA: (a: A) => number;
+    /** Number of A elements related to the given B element. */
+    readonly aCountForB: (b: B) => number;
     /** Number of pairs currently stored in the relation. */
     readonly size: () => number;
 }
+/** Options for {@link createRelation}. */
+export interface CreateRelationOptions<A, B, LA = A, LB = B> {
+    /** Derives logical identity for A values. Defaults to {@link identity}. */
+    readonly lookupA?: Lookup<A, LA>;
+    /** Derives logical identity for B values. Defaults to {@link identity}. */
+    readonly lookupB?: Lookup<B, LB>;
+}
 /** Creates a {@link Relation}. */
-export declare const createRelation: <A, B>() => Relation<A, B>;
+export declare function createRelation<A, B>(): Relation<A, B>;
+export declare function createRelation<A, B, LA, LB>(options: CreateRelationOptions<A, B, LA, LB>): Relation<A, B>;
 //# sourceMappingURL=Relation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../src/Relation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEzC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpD,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;IAE3D;;;OAGG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpE,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEjC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEjC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEpC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEpC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAE3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAE9B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAE9B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,kCAAkC;AAClC,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,OAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,CA2IpD,CAAC"}
+{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../src/Relation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAGL,KAAK,MAAM,EAEZ,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEzC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEjD;;;OAGG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpE,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEjC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEjC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAE3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAE9B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAE9B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAEtC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAEtC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEjC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;CAClC;AAED,kCAAkC;AAClC,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACvD,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACzC,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC3C,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/src/Relation.js

@@ -1,127 +1,105 @@
+/**
+ * Bidirectional relations with O(1) lookup in both directions.
+ *
+ * @module
+ */
+import { emptyArray } from "./Array.js";
 import { assert } from "./Assert.js";
-/** Creates a {@link Relation}. */
-export const createRelation = () => {
-    const aToB = new Map();
-    const bToA = new Map();
+import { identity } from "./Function.js";
+import { createLookupMap, createLookupSet, } from "./Lookup.js";
+export function createRelation({ lookupA = identity, lookupB = identity, } = {}) {
+    const bByA = createLookupMap({ lookup: lookupA });
+    const aByB = createLookupMap({ lookup: lookupB });
     let sizeInternal = 0;
-    const relation = {
-        add(a, b) {
-            let bSet = aToB.get(a);
-            if (bSet?.has(b))
+    const removePair = (a, b) => {
+        const relatedB = bByA.get(a);
+        // This should only fail if a leaked view was mutated via an unsafe cast.
+        assertRelationMappingConsistency(relatedB);
+        assertRelationMappingConsistency(relatedB.has(b));
+        relatedB.delete(b);
+        if (relatedB.size === 0) {
+            bByA.delete(a);
+        }
+        const relatedA = aByB.get(b);
+        // This should only fail if a leaked view was mutated via an unsafe cast.
+        assertRelationMappingConsistency(relatedA);
+        assertRelationMappingConsistency(relatedA.has(a));
+        relatedA.delete(a);
+        if (relatedA.size === 0) {
+            aByB.delete(b);
+        }
+        sizeInternal--;
+    };
+    return {
+        add: (a, b) => {
+            const canonicalA = bByA.getKey(a) ?? a;
+            const canonicalB = aByB.getKey(b) ?? b;
+            let relatedB = bByA.get(canonicalA);
+            if (relatedB?.has(canonicalB))
                 return false;
-            if (!bSet) {
-                bSet = new Set();
-                aToB.set(a, bSet);
+            if (!relatedB) {
+                relatedB = createLookupSet({ lookup: lookupB });
+                bByA.set(canonicalA, relatedB);
             }
-            bSet.add(b);
-            let aSet = bToA.get(b);
-            if (!aSet) {
-                aSet = new Set();
-                bToA.set(b, aSet);
+            relatedB.add(canonicalB);
+            let relatedA = aByB.get(canonicalB);
+            if (!relatedA) {
+                relatedA = createLookupSet({ lookup: lookupA });
+                aByB.set(canonicalB, relatedA);
             }
-            aSet.add(a);
+            relatedA.add(canonicalA);
             sizeInternal++;
             return true;
         },
-        remove(a, b) {
-            const bSet = aToB.get(a);
-            if (!bSet?.has(b))
+        remove: (a, b) => {
+            if (!bByA.get(a)?.has(b))
                 return false;
-            bSet.delete(b);
-            if (bSet.size === 0) {
-                aToB.delete(a);
-            }
-            const aSet = bToA.get(b);
-            assert(aSet, "Relation mapping inconsistency");
-            aSet.delete(a);
-            if (aSet.size === 0) {
-                bToA.delete(b);
-            }
-            sizeInternal--;
+            removePair(a, b);
             return true;
         },
-        getB(a) {
-            return aToB.get(a);
-        },
-        getA(b) {
-            return bToA.get(b);
-        },
-        forEach(callback) {
-            for (const [a, bSet] of aToB) {
-                for (const b of bSet)
-                    callback(a, b);
-            }
-        },
-        [Symbol.iterator]() {
-            const iterator = function* () {
-                for (const [a, bSet] of aToB) {
-                    for (const b of bSet) {
-                        yield [a, b];
-                    }
-                }
-            };
-            return iterator();
-        },
-        has(a, b) {
-            const bSet = aToB.get(a);
-            return bSet?.has(b) ?? false;
-        },
-        hasA(a) {
-            return aToB.has(a);
-        },
-        hasB(b) {
-            return bToA.has(b);
-        },
-        deleteA(a) {
-            const bSet = aToB.get(a);
-            if (!bSet)
+        removeByA: (a) => {
+            const relatedB = bByA.get(a);
+            if (!relatedB)
                 return false;
-            const removed = bSet.size;
-            for (const b of bSet) {
-                const aSet = bToA.get(b);
-                if (aSet) {
-                    aSet.delete(a);
-                    if (aSet.size === 0) {
-                        bToA.delete(b);
-                    }
-                }
-            }
-            aToB.delete(a);
-            sizeInternal -= removed;
+            for (const b of [...relatedB.keys()])
+                removePair(a, b);
             return true;
         },
-        deleteB(b) {
-            const aSet = bToA.get(b);
-            if (!aSet)
+        removeByB: (b) => {
+            const relatedA = aByB.get(b);
+            if (!relatedA)
                 return false;
-            const removed = aSet.size;
-            for (const a of aSet) {
-                const bSet = aToB.get(a);
-                if (bSet) {
-                    bSet.delete(b);
-                    if (bSet.size === 0) {
-                        aToB.delete(a);
-                    }
-                }
-            }
-            bToA.delete(b);
-            sizeInternal -= removed;
+            for (const a of [...relatedA.keys()])
+                removePair(a, b);
             return true;
         },
-        clear() {
-            aToB.clear();
-            bToA.clear();
-            sizeInternal = 0;
-        },
-        aCount() {
-            return aToB.size;
+        iterateA: (b) => aByB.get(b)?.keys() ?? emptyArray.values(),
+        iterateB: (a) => bByA.get(a)?.keys() ?? emptyArray.values(),
+        *[Symbol.iterator]() {
+            for (const [a, relatedB] of bByA) {
+                for (const b of relatedB.keys()) {
+                    yield [a, b];
+                }
+            }
         },
-        bCount() {
-            return bToA.size;
+        has: (a, b) => {
+            const relatedB = bByA.get(a);
+            return relatedB?.has(b) ?? false;
         },
-        size() {
-            return sizeInternal;
+        hasA: (a) => bByA.has(a),
+        hasB: (b) => aByB.has(b),
+        clear: () => {
+            bByA.clear();
+            aByB.clear();
+            sizeInternal = 0;
         },
+        aCount: () => bByA.size,
+        bCount: () => aByB.size,
+        bCountForA: (a) => bByA.get(a)?.size ?? 0,
+        aCountForB: (b) => aByB.get(b)?.size ?? 0,
+        size: () => sizeInternal,
     };
-    return relation;
+}
+const assertRelationMappingConsistency = (condition) => {
+    assert(condition, "Relation mapping inconsistency");
 };