@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Random.ts

@@ -1,11 +1,11 @@
 /**
- * Seeded random number generation.
+ * Random number generation.
  *
  * @module
  */
 
 import { Random as RandomLib } from "random";
-import type { Brand } from "./Brand.js";
+import type { Brand } from "./Brand.ts";
 
 /**
  * A random floating point number in [0, 1).
@@ -22,22 +22,32 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * ### Example
  *
  * ```ts
- * // For apps
+ * import {
+ *   createRandom,
+ *   testCreateRandom,
+ *   type RandomNumber,
+ * } from "@evolu/common";
+ *
+ * // For apps, use the Math.random-backed implementation.
  * const random = createRandom();
- * random.next();
+ * const value = random.next();
+ * expectTypeOf(value).toEqualTypeOf<RandomNumber>();
+ * expect(value).toBeGreaterThanOrEqual(0);
+ * expect(value).toBeLessThan(1);
  *
- * // For tests
- * const random = createRandomWithSeed("test");
- * random.next();
+ * // For tests, use a seed.
+ * const firstTestRandom = testCreateRandom("test");
+ * const secondTestRandom = testCreateRandom("test");
+ * expect(firstTestRandom.next()).toBe(secondTestRandom.next());
  * ```
  */
 export interface Random {
   /** Returns a floating point number in [0, 1). Just like Math.random(). */
-  next: () => RandomNumber;
+  readonly next: () => RandomNumber;
 }
 
 export interface RandomDep {
-  random: Random;
+  readonly random: Random;
 }
 
 /** Creates a {@link Random} using Math.random(). */
@@ -45,15 +55,12 @@ export const createRandom = (): Random => ({
   next: () => Math.random() as RandomNumber,
 });
 
-/** Creates a seeded {@link Random} for deterministic tests. Default seed "evolu". */
-export const testCreateRandom = (seed = "evolu"): Random =>
-  createRandomWithSeed(seed);
-
 /**
- * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
- * for tests.
+ * Creates a seeded {@link Random} for deterministic tests.
+ *
+ * Default seed "evolu".
  */
-export const createRandomWithSeed = (seed: string): Random => {
+export const testCreateRandom = (seed = "evolu"): Random => {
   const random = new RandomLib(seed);
   return {
     next: () => random.next() as RandomNumber,
@@ -61,7 +68,8 @@ export const createRandomWithSeed = (seed: string): Random => {
 };
 
 /**
- * A random number generator using the NPM `random` package dependency.
+ * Seedable random number generator supporting many common distributions,
+ * provided by the NPM `random` package.
  *
  * https://github.com/transitive-bullshit/random
  */
@@ -69,9 +77,14 @@ export interface RandomLibDep {
   readonly randomLib: RandomLib;
 }
 
-/** Creates a `RandomLib` using the NPM `random` package. */
+/** Creates a random number generator from the NPM `random` package. */
 export const createRandomLib = (): RandomLib => new RandomLib();
 
-/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+/**
+ * Creates a seeded random number generator from the NPM `random` package for
+ * deterministic tests.
+ *
+ * Default seed "evolu".
+ */
 export const testCreateRandomLib = (seed = "evolu"): RandomLib =>
   new RandomLib(seed);

package/src/Redacted.ts

@@ -4,9 +4,9 @@
  * @module
  */
 
-import { assert } from "./Assert.js";
-import type { Brand } from "./Brand.js";
-import type { Eq } from "./Eq.js";
+import { assert } from "./Assert.ts";
+import type { Brand } from "./Brand.ts";
+import type { Eq } from "./Eq.ts";
 
 /**
  * A wrapper type that prevents sensitive values from being accidentally exposed
@@ -29,35 +29,38 @@ import type { Eq } from "./Eq.js";
  * ### Example
  *
  * ```ts
- * // Define branded types for your secrets
+ * import {
+ *   createRedacted,
+ *   revealRedacted,
+ *   type Brand,
+ *   type Redacted,
+ * } from "@evolu/common";
+ *
  * type ApiKey = string & Brand<"ApiKey">;
  * type DbPassword = string & Brand<"DbPassword">;
- *
- * // Wrap them with Redacted for safe passing
  * type RedactedApiKey = Redacted<ApiKey>;
- * type RedactedDbPassword = Redacted<DbPassword>;
  *
- * // Create a redacted secret
+ * // Apply brands only after validation or at another trusted boundary.
  * const apiKey: ApiKey = "secret-123" as ApiKey;
- * const redactedKey: RedactedApiKey = createRedacted(apiKey);
- *
- * console.log(redactedKey); // <redacted>
- * console.log(revealRedacted(redactedKey)); // secret-123
- *
- * // Type safety: RedactedApiKey ≠ RedactedDbPassword
- * const fetchUser = (key: RedactedApiKey) => {
- *   const value: ApiKey = revealRedacted(key);
- *   // use value...
- * };
- *
- * fetchUser(redactedKey); // ok
- * // fetchUser(createRedacted("x" as DbPassword)); // type error
- *
- * // Automatic cleanup with `using`
- * {
- *   using secret = createRedacted("sensitive" as ApiKey);
- *   // ... use secret ...
- * } // automatically wiped from memory
+ * using redactedKey: RedactedApiKey = createRedacted(apiKey);
+ * const fetchUser = (key: RedactedApiKey): ApiKey => revealRedacted(key);
+ *
+ * expect(redactedKey.toString()).toBe("<redacted>");
+ * expect(JSON.stringify({ apiKey: redactedKey })).toBe(
+ *   '{"apiKey":"<redacted>"}',
+ * );
+ * expect(fetchUser(redactedKey)).toBe(apiKey);
+ *
+ * using password = createRedacted("password" as DbPassword);
+ * // @ts-expect-error Redacted secrets retain their distinct branded types.
+ * fetchUser(password);
+ *
+ * const disposedKey = (() => {
+ *   using key = createRedacted(apiKey);
+ *   return key;
+ * })();
+ * // Leaving the `using` scope removes the value from memory.
+ * expect(() => revealRedacted(disposedKey)).toThrow();
  * ```
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
@@ -108,12 +111,23 @@ export const isRedacted = (value: unknown): value is Redacted<unknown> =>
  * ### Example
  *
  * ```ts
+ * import {
+ *   createEqRedacted,
+ *   createRedacted,
+ *   eqString,
+ *   type Brand,
+ * } from "@evolu/common";
+ *
  * type ApiKey = string & Brand<"ApiKey">;
  * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
  *
- * const a = createRedacted("x" as ApiKey);
- * const b = createRedacted("x" as ApiKey);
- * eqRedactedApiKey(a, b); // true
+ * // Apply brands only after validation or at another trusted boundary.
+ * using a = createRedacted("x" as ApiKey);
+ * using b = createRedacted("x" as ApiKey);
+ * using c = createRedacted("y" as ApiKey);
+ *
+ * expect(eqRedactedApiKey(a, b)).toBe(true);
+ * expect(eqRedactedApiKey(a, c)).toBe(false);
  * ```
  */
 export const createEqRedacted =

package/src/Ref.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import type { Store } from "./Store.js";
+import type { Store } from "./Store.ts";
 
 /**
  * Mutable reference to an immutable value.
@@ -21,18 +21,26 @@ import type { Store } from "./Store.js";
  * ### Example
  *
  * ```ts
+ * import { createRef } from "@evolu/common";
+ *
  * const count = createRef(0);
  * count.set(1);
  * count.update((n) => n + 1);
- * console.log(count.get()); // 2
+ * expect(count.get()).toBe(2);
  * ```
  *
- * ### Example of using Ref as a dependency
+ * ### As a dependency
  *
  * ```ts
+ * import { createRef, type Ref } from "@evolu/common";
+ *
  * interface CounterRefDep {
  *   readonly counterRef: Ref<number>;
  * }
+ *
+ * const deps: CounterRefDep = { counterRef: createRef(0) };
+ * deps.counterRef.update((count) => count + 1);
+ * expect(deps.counterRef.get()).toBe(1);
  * ```
  */
 export interface Ref<T> {
@@ -59,7 +67,7 @@ export interface Ref<T> {
 
   /** Modifies the current value and returns a computed result. */
   readonly modify: <R>(
-    updater: (current: T) => readonly [result: R, nextValue: T],
+    modifier: (current: T) => readonly [result: R, nextValue: T],
   ) => R;
 }
 
@@ -100,8 +108,8 @@ export const createRef = <T>(initialValue: T): Ref<T> => {
       return currentValue;
     },
 
-    modify: (updater) => {
-      const [result, nextValue] = updater(currentValue);
+    modify: (modifier) => {
+      const [result, nextValue] = modifier(currentValue);
       currentValue = nextValue;
       return result;
     },

package/src/RefCount.ts

@@ -4,10 +4,10 @@
  * @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";
+import { assert } from "./Assert.ts";
+import { disposable, identity } from "./Function.ts";
+import { createLookupMap, type Lookup, type LookupOption } from "./Lookup.ts";
+import { NonNegativeInt, PositiveInt, zeroNonNegativeInt } from "./Type.ts";
 
 /**
  * Reference count for one retained value.
@@ -27,40 +27,27 @@ export interface RefCount extends Disposable {
 
   /** 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 => {
-  // We use DisposableStack only because of assertNotDisposed.
-  using disposer = new DisposableStack();
   let count = zeroNonNegativeInt;
-  const disposables = disposer.move();
 
-  return {
+  return disposable<RefCount>({
     increment: () => {
-      assertNotDisposed(disposables);
       const nextCount = PositiveInt.orThrow(count + 1);
       count = nextCount;
       return nextCount;
     },
 
     decrement: () => {
-      assertNotDisposed(disposables);
       assert(count > 0, "RefCount must not be decremented below zero.");
       count = NonNegativeInt.orThrow(count - 1);
       return count;
     },
 
-    getCount: () => {
-      assertNotDisposed(disposables);
-      return count;
-    },
-
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
+    getCount: () => count,
+  });
 };
 
 /**
@@ -91,9 +78,6 @@ export interface RefCountByKey<TKey> extends Disposable {
 
   /** 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}. */
@@ -110,65 +94,39 @@ export function createRefCountByKey<TKey, L>(
 export function createRefCountByKey<TKey, L = TKey>({
   lookup = identity as Lookup<TKey, L>,
 }: CreateRefCountByKeyOptions<TKey, L> = {}): RefCountByKey<TKey> {
-  // We use DisposableStack only because of assertNotDisposed.
   using disposer = new DisposableStack();
 
-  const refCountByKey = disposer.adopt(
-    createLookupMap<TKey, RefCount, L>({ lookup }),
-    (refCountByKey) => {
-      using disposer = new DisposableStack();
-      disposer.defer(() => {
-        refCountByKey.clear();
-      });
-      for (const refCount of refCountByKey.values()) {
-        disposer.use(refCount);
-      }
+  const refCountByKey = createLookupMap<TKey, RefCount, L>({ lookup });
+  disposer.defer(() => {
+    refCountByKey.clear();
+  });
+
+  return disposable<RefCountByKey<TKey>>(
+    {
+      increment: (key) =>
+        refCountByKey.getOrInsertComputed(key, createRefCount).increment(),
+
+      decrement: (key) => {
+        const refCount = refCountByKey.get(key);
+        assert(
+          refCount,
+          "RefCount must not be decremented for an untracked key.",
+        );
+        const nextCount = refCount.decrement();
+        if (nextCount === 0) {
+          refCountByKey.delete(key);
+          refCount[Symbol.dispose]();
+        }
+        return nextCount;
+      },
+
+      getCount: (key) =>
+        refCountByKey.get(key)?.getCount() ?? zeroNonNegativeInt,
+
+      has: (key) => refCountByKey.has(key),
+
+      keys: () => new Set(refCountByKey.keys()),
     },
+    disposer,
   );
-
-  const disposables = disposer.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(disposables);
-      return getRefCount(key).increment();
-    },
-
-    decrement: (key) => {
-      assertNotDisposed(disposables);
-      const refCount = getRefCount(key);
-      const nextCount = refCount.decrement();
-      if (nextCount === 0) {
-        refCountByKey.delete(key);
-        refCount[Symbol.dispose]();
-      }
-      return nextCount;
-    },
-
-    getCount: (key) => {
-      assertNotDisposed(disposables);
-      return refCountByKey.get(key)?.getCount() ?? zeroNonNegativeInt;
-    },
-
-    has: (key) => {
-      assertNotDisposed(disposables);
-      return refCountByKey.has(key);
-    },
-
-    keys: () => {
-      assertNotDisposed(disposables);
-      return new Set(refCountByKey.keys());
-    },
-
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
 }

package/src/Relation.ts

@@ -4,15 +4,22 @@
  * @module
  */
 
-import { emptyArray } from "./Array.js";
-import { assert } from "./Assert.js";
-import { identity } from "./Function.js";
+import { emptyArray } from "./Array.ts";
+import { assert } from "./Assert.ts";
+import { identity } from "./Function.ts";
 import {
   createLookupMap,
   createLookupSet,
   type Lookup,
+  type LookupMap,
   type LookupSet,
-} from "./Lookup.js";
+} from "./Lookup.ts";
+import {
+  NonNegativeInt,
+  onePositiveInt,
+  PositiveInt,
+  zeroNonNegativeInt,
+} from "./Type.ts";
 
 /**
  * Bidirectional relation between two types.
@@ -44,20 +51,33 @@ import {
  * The input parameter types of `lookupA` and `lookupB` determine which values
  * the returned relation accepts on each side.
  *
- * ### Example
+ * ### Reference identity
  *
  * Use the default identity semantics.
  *
  * ```ts
- * const relation = createRelation<WebSocket, string>();
+ * import { createRelation } from "@evolu/common";
+ *
+ * interface Socket {
+ *   readonly id: string;
+ * }
+ *
+ * const relation = createRelation<Socket, string>();
+ * const socket = { id: "socket-1" };
+ *
  * relation.add(socket, "owner-1");
+ *
+ * expect(relation.has(socket, "owner-1")).toBe(true);
+ * expect(relation.has({ id: "socket-1" }, "owner-1")).toBe(false);
  * ```
  *
- * ### Example
+ * ### Lookup-derived equality
  *
  * Use lookup-derived equality.
  *
  * ```ts
+ * import { createRelation } from "@evolu/common";
+ *
  * interface Person {
  *   readonly id: string;
  *   readonly name: string;
@@ -69,7 +89,10 @@ import {
  * });
  *
  * relation.add({ id: "1", name: "Ada" }, { id: "admins" });
- * relation.has({ id: "1", name: "Grace" }, { id: "admins" }); // true
+ *
+ * expect(relation.has({ id: "1", name: "Grace" }, { id: "admins" })).toBe(
+ *   true,
+ * );
  * ```
  *
  * @see {@link createRelation}
@@ -171,7 +194,6 @@ export function createRelation<A, B, LA = A, LB = 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));
 
@@ -181,7 +203,6 @@ export function createRelation<A, B, LA = A, LB = B>({
     }
 
     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));
 
@@ -279,8 +300,179 @@ export function createRelation<A, B, LA = A, LB = B>({
   };
 }
 
+// This can fail if a lookup function violates its pure and stable contract.
 const assertRelationMappingConsistency: (
   condition: unknown,
 ) => asserts condition = (condition) => {
   assert(condition, "Relation mapping inconsistency");
 };
+
+/**
+ * Bidirectional relation with a positive retain count for every active pair.
+ *
+ * Logical equality and canonical representatives follow the same lookup rules
+ * as {@link Relation}. The first active representative on each side remains
+ * canonical until that value has no active pairs. Increment and decrement
+ * return those representatives so callers can reliably handle pair transitions
+ * without repeating lookup or canonicalization logic.
+ *
+ * Unlike {@link Relation}'s live iterators, directional and entry reads return
+ * snapshots so callers can mutate this relation while iterating. Their order
+ * follows first insertion of the current canonical representatives and pairs.
+ */
+export interface RefCountedRelation<A, B> {
+  /** Increments a pair count and returns its canonical values and new count. */
+  readonly increment: (
+    a: A,
+    b: B,
+  ) => {
+    readonly a: A;
+    readonly b: B;
+    readonly count: PositiveInt;
+  };
+
+  /**
+   * Decrements a pair count and returns its canonical values and new count.
+   * Decrementing a missing pair is a programmer error checked with
+   * {@link assert}.
+   */
+  readonly decrement: (
+    a: A,
+    b: B,
+  ) => {
+    readonly a: A;
+    readonly b: B;
+    readonly count: NonNegativeInt;
+  };
+
+  /** Returns the pair count, or zero when the pair is absent. */
+  readonly getCount: (a: A, b: B) => NonNegativeInt;
+
+  /** Returns a snapshot of canonical A values related to `b`. */
+  readonly getAs: (b: B) => ReadonlyArray<A>;
+
+  /** Returns a snapshot of canonical B values related to `a`. */
+  readonly getBs: (a: A) => ReadonlyArray<B>;
+
+  /** Returns whether an A value has at least one active pair. */
+  readonly hasA: (a: A) => boolean;
+
+  /** Returns whether a B value has at least one active pair. */
+  readonly hasB: (b: B) => boolean;
+
+  /** Returns a snapshot of every canonical pair and its positive count. */
+  readonly getEntries: () => ReadonlyArray<
+    readonly [a: A, b: B, count: PositiveInt]
+  >;
+
+  /** Removes all pair counts and both directional indexes. */
+  readonly clear: () => void;
+}
+
+/** Creates a {@link RefCountedRelation}. */
+export function createRefCountedRelation<A, B>(): RefCountedRelation<A, B>;
+export function createRefCountedRelation<A, B, LA, LB>(
+  options: CreateRelationOptions<A, B, LA, LB>,
+): RefCountedRelation<A, B>;
+export function createRefCountedRelation<A, B, LA = A, LB = B>({
+  lookupA = identity as Lookup<A, LA>,
+  lookupB = identity as Lookup<B, LB>,
+}: CreateRelationOptions<A, B, LA, LB> = {}): RefCountedRelation<A, B> {
+  interface RelatedBs {
+    readonly a: A;
+    readonly countsByB: LookupMap<B, PositiveInt>;
+  }
+
+  interface RelatedAs {
+    readonly b: B;
+    readonly as: LookupSet<A>;
+  }
+
+  const relatedBsByA = createLookupMap<A, RelatedBs, LA>({ lookup: lookupA });
+  const relatedAsByB = createLookupMap<B, RelatedAs, LB>({ lookup: lookupB });
+
+  return {
+    increment: (a, b) => {
+      let relatedBs = relatedBsByA.get(a);
+      const canonicalA = relatedBs ? relatedBs.a : a;
+      const relatedAs = relatedAsByB.get(b);
+      const canonicalB = relatedAs ? relatedAs.b : b;
+
+      if (!relatedBs) {
+        relatedBs = {
+          a: canonicalA,
+          countsByB: createLookupMap<B, PositiveInt, LB>({ lookup: lookupB }),
+        };
+        relatedBsByA.set(canonicalA, relatedBs);
+      }
+
+      const count = relatedBs.countsByB.get(canonicalB);
+      if (count) {
+        const nextCount = PositiveInt.orThrow(count + 1);
+        relatedBs.countsByB.set(canonicalB, nextCount);
+        return { a: canonicalA, b: canonicalB, count: nextCount };
+      }
+
+      relatedBs.countsByB.set(canonicalB, onePositiveInt);
+      if (relatedAs) {
+        relatedAs.as.add(canonicalA);
+      } else {
+        relatedAsByB.set(canonicalB, {
+          b: canonicalB,
+          as: createLookupSet<A, LA>({
+            lookup: lookupA,
+            values: [canonicalA],
+          }),
+        });
+      }
+      return { a: canonicalA, b: canonicalB, count: onePositiveInt };
+    },
+
+    decrement: (a, b) => {
+      const relatedBs = relatedBsByA.get(a);
+      const relatedAs = relatedAsByB.get(b);
+      const count = relatedBs?.countsByB.get(b);
+      assert(
+        relatedBs && relatedAs && count,
+        "RefCountedRelation pair must exist before decrement.",
+      );
+
+      const nextCount = NonNegativeInt.orThrow(count - 1);
+      if (nextCount > 0) {
+        relatedBs.countsByB.set(relatedAs.b, PositiveInt.orThrow(nextCount));
+      } else {
+        relatedBs.countsByB.delete(relatedAs.b);
+        if (relatedBs.countsByB.size === 0) relatedBsByA.delete(relatedBs.a);
+
+        relatedAs.as.delete(relatedBs.a);
+        if (relatedAs.as.size === 0) relatedAsByB.delete(relatedAs.b);
+      }
+
+      return { a: relatedBs.a, b: relatedAs.b, count: nextCount };
+    },
+
+    getCount: (a, b) =>
+      relatedBsByA.get(a)?.countsByB.get(b) ?? zeroNonNegativeInt,
+
+    getAs: (b) => [...(relatedAsByB.get(b)?.as ?? emptyArray)],
+
+    getBs: (a) => [...(relatedBsByA.get(a)?.countsByB.keys() ?? emptyArray)],
+
+    hasA: (a) => relatedBsByA.has(a),
+
+    hasB: (b) => relatedAsByB.has(b),
+
+    getEntries: () => {
+      const entries: Array<readonly [A, B, PositiveInt]> = [];
+      for (const { a, countsByB } of relatedBsByA.values()) {
+        for (const [b, count] of countsByB) entries.push([a, b, count]);
+      }
+      return entries;
+    },
+
+    clear: () => {
+      relatedBsByA.clear();
+      relatedAsByB.clear();
+    },
+  };
+}