@evolu/common 7.4.0 → 8.0.0-next.0

package/src/RefCount.ts

@@ -0,0 +1,170 @@
+/**
+ * Reference counting helpers.
+ *
+ * @module
+ */
+
+import { assert, assertNotDisposed } from "./Assert.js";
+import { identity } from "./Function.js";
+import { createLookupMap, type Lookup, type LookupOption } from "./Lookup.js";
+import { NonNegativeInt, PositiveInt, zeroNonNegativeInt } from "./Type.js";
+
+/**
+ * Reference count for one retained value.
+ *
+ * Decrementing below zero is a programmer error checked with {@link assert}.
+ */
+export interface RefCount extends Disposable {
+  /** Increments the count and returns the new count. */
+  readonly increment: () => PositiveInt;
+
+  /**
+   * Decrements the count and returns the new count.
+   *
+   * Decrementing below zero is a programmer error checked with {@link assert}.
+   */
+  readonly decrement: () => NonNegativeInt;
+
+  /** Returns the current count. */
+  readonly getCount: () => NonNegativeInt;
+
+  /** Disposes and invalidates the helper. Further method calls throw. */
+  readonly [Symbol.dispose]: () => void;
+}
+
+/** Creates {@link RefCount}. */
+export const createRefCount = (): RefCount => {
+  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(),
+  };
+};
+
+/**
+ * Reference counts keyed by logical identity.
+ *
+ * By default, {@link createRefCountByKey} uses reference identity, the same as
+ * `Map` keys. Callers may instead provide a {@link Lookup lookup} so logical
+ * equality is based on a derived stable key. Decrementing a missing key is a
+ * programmer error checked with {@link assert}.
+ */
+export interface RefCountByKey<TKey> extends Disposable {
+  /** Increments key count and returns the new count. */
+  readonly increment: (key: TKey) => PositiveInt;
+
+  /**
+   * Decrements key count and returns the new count.
+   *
+   * Decrementing a missing key is a programmer error checked with
+   * {@link assert}.
+   */
+  readonly decrement: (key: TKey) => NonNegativeInt;
+
+  /** Gets current count for key. Returns `0` when the key is not tracked. */
+  readonly getCount: (key: TKey) => NonNegativeInt;
+
+  /** Returns `true` when the key is tracked with count greater than zero. */
+  readonly has: (key: TKey) => boolean;
+
+  /** Returns all currently tracked keys. */
+  readonly keys: () => ReadonlySet<TKey>;
+
+  /** Disposes and invalidates the helper. Further method calls throw. */
+  readonly [Symbol.dispose]: () => void;
+}
+
+/** Options for {@link createRefCountByKey}. */
+export interface CreateRefCountByKeyOptions<
+  TKey,
+  L = TKey,
+> extends LookupOption<TKey, L> {}
+
+/** Creates {@link RefCountByKey}. */
+export function createRefCountByKey<TKey = unknown>(): RefCountByKey<TKey>;
+export function createRefCountByKey<TKey, L>(
+  options: CreateRefCountByKeyOptions<TKey, L>,
+): RefCountByKey<TKey>;
+export function createRefCountByKey<TKey, L = TKey>({
+  lookup = identity as Lookup<TKey, L>,
+}: CreateRefCountByKeyOptions<TKey, L> = {}): RefCountByKey<TKey> {
+  const stack = new DisposableStack();
+
+  const refCountByKey = stack.adopt(
+    createLookupMap<TKey, RefCount, L>({ lookup }),
+    (refCountByKey) => {
+      for (const refCount of refCountByKey.values()) refCount[Symbol.dispose]();
+      refCountByKey.clear();
+    },
+  );
+
+  const moved = stack.move();
+
+  const getRefCount = (key: TKey): RefCount => {
+    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/src/Relation.ts

@@ -1,36 +1,78 @@
+/**
+ * Bidirectional relations with O(1) lookup in both directions.
+ *
+ * @module
+ */
+
+import { emptyArray } from "./Array.js";
 import { assert } from "./Assert.js";
+import { identity } from "./Function.js";
+import {
+  createLookupMap,
+  createLookupSet,
+  type Lookup,
+  type LookupSet,
+} from "./Lookup.js";
 
 /**
  * Bidirectional relation between two types.
  *
- * Why useful:
- *
  * - Provides O(1) (amortized) lookup in both directions (A → B and B → A) without
  *   maintaining two maps manually and risking them diverging.
  * - Natural fit for symmetric associations such as ownerId ↔ WebSocket, tag ↔
  *   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
  *
- * Object identity:
+ * Use the default identity semantics.
  *
- * - 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.
+ * ```ts
+ * const relation = createRelation<WebSocket, string>();
+ * relation.add(socket, "owner-1");
+ * ```
+ *
+ * ### 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> {
   /**
@@ -45,17 +87,31 @@ export interface Relation<A, B> {
    */
   readonly remove: (a: A, b: B) => boolean;
 
-  /** Gets all B elements related to an A element. */
-  readonly getB: (a: A) => ReadonlySet<B> | undefined;
+  /** Removes all pairs containing the given A element. */
+  readonly removeByA: (a: A) => boolean;
 
-  /** Gets all A elements related to a B element. */
-  readonly getA: (b: B) => ReadonlySet<A> | undefined;
+  /** Removes all pairs containing the given B element. */
+  readonly removeByB: (b: B) => boolean;
 
   /**
-   * Iterates over each pair in the relation (in insertion order of A elements,
-   * then B elements per A).
+   * 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 forEach: (callback: (a: A, b: B) => void) => void;
+  readonly iterateA: (b: B) => IterableIterator<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 iterateB: (a: A) => IterableIterator<B>;
 
   /**
    * Iterator over all pairs enabling for..of and spread. Yields readonly [a, b]
@@ -72,12 +128,6 @@ export interface Relation<A, B> {
   /** 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;
 
@@ -87,148 +137,150 @@ export interface Relation<A, B> {
   /** 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 const createRelation = <A, B>(): Relation<A, B> => {
-  const aToB = new Map<A, Set<B>>();
-  const bToA = new Map<B, Set<A>>();
+export function createRelation<A, B>(): Relation<A, B>;
+export function createRelation<A, B, LA, LB>(
+  options: CreateRelationOptions<A, B, LA, LB>,
+): Relation<A, B>;
+export function createRelation<A, B, LA = A, LB = B>({
+  lookupA = identity as Lookup<A, LA>,
+  lookupB = identity as Lookup<B, LB>,
+}: CreateRelationOptions<A, B, LA, LB> = {}): Relation<A, B> {
+  const bByA = createLookupMap<A, LookupSet<B>, LA>({ lookup: lookupA });
+  const aByB = createLookupMap<B, LookupSet<A>, LB>({ lookup: lookupB });
   let sizeInternal = 0;
 
-  const relation: Relation<A, B> = {
-    add(a: A, b: B) {
-      let bSet = aToB.get(a);
-      if (bSet?.has(b)) return false;
-      if (!bSet) {
-        bSet = new Set<B>();
-        aToB.set(a, bSet);
-      }
-      bSet.add(b);
+  const removePair = (a: A, b: B): void => {
+    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));
 
-      let aSet = bToA.get(b);
-      if (!aSet) {
-        aSet = new Set<A>();
-        bToA.set(b, aSet);
-      }
-      aSet.add(a);
-      sizeInternal++;
-      return true;
-    },
+    relatedB.delete(b);
+    if (relatedB.size === 0) {
+      bByA.delete(a);
+    }
 
-    remove(a: A, b: B) {
-      const bSet = aToB.get(a);
-      if (!bSet?.has(b)) return false;
+    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));
 
-      bSet.delete(b);
-      if (bSet.size === 0) {
-        aToB.delete(a);
-      }
+    relatedA.delete(a);
+    if (relatedA.size === 0) {
+      aByB.delete(b);
+    }
+
+    sizeInternal--;
+  };
 
-      const aSet = bToA.get(b);
-      assert(aSet, "Relation mapping inconsistency");
+  return {
+    add: (a, b) => {
+      const canonicalA = bByA.getKey(a) ?? a;
+      const canonicalB = aByB.getKey(b) ?? b;
 
-      aSet.delete(a);
-      if (aSet.size === 0) {
-        bToA.delete(b);
+      let relatedB = bByA.get(canonicalA);
+      if (relatedB?.has(canonicalB)) return false;
+      if (!relatedB) {
+        relatedB = createLookupSet<B, LB>({ lookup: lookupB });
+        bByA.set(canonicalA, relatedB);
       }
-      sizeInternal--;
-      return true;
-    },
+      relatedB.add(canonicalB);
 
-    getB(a: A): ReadonlySet<B> | undefined {
-      return aToB.get(a);
-    },
+      let relatedA = aByB.get(canonicalB);
+      if (!relatedA) {
+        relatedA = createLookupSet<A, LA>({ lookup: lookupA });
+        aByB.set(canonicalB, relatedA);
+      }
+      relatedA.add(canonicalA);
 
-    getA(b: B): ReadonlySet<A> | undefined {
-      return bToA.get(b);
+      sizeInternal++;
+      return true;
     },
 
-    forEach(callback: (a: A, b: B) => void) {
-      for (const [a, bSet] of aToB) {
-        for (const b of bSet) callback(a, b);
-      }
-    },
+    remove: (a, b) => {
+      if (!bByA.get(a)?.has(b)) return false;
 
-    [Symbol.iterator](): IterableIterator<readonly [A, B]> {
-      const iterator = function* () {
-        for (const [a, bSet] of aToB) {
-          for (const b of bSet) {
-            yield [a, b] as const;
-          }
-        }
-      };
-      return iterator();
+      removePair(a, b);
+      return true;
     },
 
-    has(a: A, b: B) {
-      const bSet = aToB.get(a);
-      return bSet?.has(b) ?? false;
+    removeByA: (a) => {
+      const relatedB = bByA.get(a);
+      if (!relatedB) return false;
+      for (const b of [...relatedB.keys()]) removePair(a, b);
+      return true;
     },
 
-    hasA(a: A) {
-      return aToB.has(a);
+    removeByB: (b) => {
+      const relatedA = aByB.get(b);
+      if (!relatedA) return false;
+      for (const a of [...relatedA.keys()]) removePair(a, b);
+      return true;
     },
 
-    hasB(b: B) {
-      return bToA.has(b);
-    },
+    iterateA: (b) =>
+      aByB.get(b)?.keys() ?? (emptyArray.values() as IterableIterator<A>),
+
+    iterateB: (a) =>
+      bByA.get(a)?.keys() ?? (emptyArray.values() as IterableIterator<B>),
 
-    deleteA(a: A) {
-      const bSet = aToB.get(a);
-      if (!bSet) 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);
-          }
+    *[Symbol.iterator](): IterableIterator<readonly [A, B]> {
+      for (const [a, relatedB] of bByA) {
+        for (const b of relatedB.keys()) {
+          yield [a, b] as const;
         }
       }
-      aToB.delete(a);
-      sizeInternal -= removed;
-      return true;
     },
 
-    deleteB(b: B) {
-      const aSet = bToA.get(b);
-      if (!aSet) 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;
-      return true;
+    has: (a, b) => {
+      const relatedB = bByA.get(a);
+      return relatedB?.has(b) ?? false;
     },
 
-    clear() {
-      aToB.clear();
-      bToA.clear();
+    hasA: (a) => bByA.has(a),
+
+    hasB: (b) => aByB.has(b),
+
+    clear: () => {
+      bByA.clear();
+      aByB.clear();
       sizeInternal = 0;
     },
 
-    aCount() {
-      return aToB.size;
-    },
+    aCount: () => bByA.size,
 
-    bCount() {
-      return bToA.size;
-    },
+    bCount: () => aByB.size,
 
-    size() {
-      return sizeInternal;
-    },
+    bCountForA: (a) => bByA.get(a)?.size ?? 0,
+
+    aCountForB: (b) => aByB.get(b)?.size ?? 0,
+
+    size: () => sizeInternal,
   };
+}
 
-  return relation;
+const assertRelationMappingConsistency: (
+  condition: unknown,
+) => asserts condition = (condition) => {
+  assert(condition, "Relation mapping inconsistency");
 };