@evolu/common 6.0.1-preview.8 → 7.0.0

package/dist/src/Number.d.ts

@@ -1,7 +1,8 @@
 import { NonEmptyReadonlyArray } from "./Array.js";
 import { Result } from "./Result.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
-import { IsBranded, Predicate, WidenLiteral } from "./Types.js";
+import { Predicate, WidenLiteral } from "./Types.js";
+import { IsBranded } from "./Brand.js";
 export declare const increment: (n: number) => number;
 export declare const decrement: (n: number) => number;
 /** Clamps a number within a given range. */
@@ -36,7 +37,7 @@ export declare const max: <T extends number>(...values: [T, ...ReadonlyArray<T>]
  */
 export declare const computeBalancedBuckets: (numberOfItems: NonNegativeInt, 
 /** Default: 16 */
-numberOfBuckets?: PositiveInt, 
+numberOfBuckets?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">, 
 /** Default: 2 */
-minNumberOfItemsPerBucket?: PositiveInt) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
+minNumberOfItemsPerBucket?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
 //# sourceMappingURL=Number.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAEL,SAAS,EACT,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,kBAAwB,WAAW;AAEnC,iBAAiB;AACjB,4BAAiC,WAAW,KAC3C,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC"}
+{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAoB,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,iJAAyC;AAEzC,iBAAiB;AACjB,2JAAkD,KACjD,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC"}

package/dist/src/Number.js

@@ -1,5 +1,6 @@
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok } from "./Result.js";
+import { PositiveInt } from "./Type.js";
 export const increment = (n) => n + 1;
 export const decrement = (n) => n - 1;
 /** Clamps a number within a given range. */
@@ -34,12 +35,12 @@ export const max = (...values) => values.reduce((a, b) => (a > b ? a : b));
  */
 export const computeBalancedBuckets = (numberOfItems, 
 /** Default: 16 */
-numberOfBuckets = 16, 
+numberOfBuckets = PositiveInt.orThrow(16), 
 /** Default: 2 */
-minNumberOfItemsPerBucket = 2) => {
+minNumberOfItemsPerBucket = PositiveInt.orThrow(2)) => {
     const minRequiredItems = numberOfBuckets * minNumberOfItemsPerBucket;
     if (numberOfItems < minRequiredItems)
-        return err(minRequiredItems);
+        return err(PositiveInt.orThrow(minRequiredItems));
     const indexes = [];
     const itemsPerBucket = Math.floor(numberOfItems / numberOfBuckets);
     const extraItems = numberOfItems % numberOfBuckets;
@@ -48,7 +49,7 @@ minNumberOfItemsPerBucket = 2) => {
         const hasExtraItem = i < extraItems;
         const itemsInThisBucket = itemsPerBucket + (hasExtraItem ? 1 : 0);
         bucketBoundary += itemsInThisBucket;
-        indexes.push(bucketBoundary);
+        indexes.push(PositiveInt.orThrow(bucketBoundary));
     }
     assertNonEmptyReadonlyArray(indexes);
     return ok(indexes);

package/dist/src/Object.d.ts

@@ -18,11 +18,17 @@ export declare const isPlainObject: (value: unknown) => value is Record<string,
 export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
 type StringKeyOf<T> = Extract<keyof T, string>;
 /**
- * Converts a record to entries, preserving branded string key types (e.g.,
- * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
- * which widens keys to `string`.
+ * Like `Object.entries` but preserves branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const users: Record<UserId, string> = {};
+ * const entries = objectToEntries(users); // [UserId, string][]
+ * ```
  */
-export declare const objectToEntries: <T extends Record<string, any>>(record: T) => Array<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+export declare const objectToEntries: <T extends Record<string, any>>(record: T) => ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
  * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.

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

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAC2B,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAG5E,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3D,QAAQ,CAAC,KACR,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAC0B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC9C,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAMK,CAAC;AAE5B,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC7D,KAAK,CAAC,EACN,MAAM,CAAC,EACP,YAAY,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAC2B,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAG5E,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3D,QAAQ,CAAC,KACR,aAAa,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAGK,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC9C,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAMK,CAAC;AAE5B,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC7D,KAAK,CAAC,EACN,MAAM,CAAC,EACP,YAAY,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC"}

package/dist/src/Object.js

@@ -12,9 +12,15 @@
  */
 export const isPlainObject = (value) => Object.prototype.toString.call(value) === "[object Object]";
 /**
- * Converts a record to entries, preserving branded string key types (e.g.,
- * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
- * which widens keys to `string`.
+ * Like `Object.entries` but preserves branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const users: Record<UserId, string> = {};
+ * const entries = objectToEntries(users); // [UserId, string][]
+ * ```
  */
 export const objectToEntries = (record) => Object.entries(record);
 /**

package/dist/src/Platform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform detection utilities for Evolu.
+ *
+ * @module
+ */
+/** Detects if the code is running in React Native environment. */
+export declare const isReactNative: boolean;
+/**
+ * Detects if Node.js Buffer is available and should be used.
+ *
+ * React Native apps often polyfill Node.js APIs like Buffer, but we want to use
+ * native methods when available for better performance.
+ *
+ * Returns false in React Native even if Buffer is polyfilled, as we prefer
+ * native methods in that environment.
+ *
+ * @see https://github.com/craftzdog/react-native-quick-base64#installation
+ */
+export declare const hasNodeBuffer: boolean;
+//# sourceMappingURL=Platform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,eAAO,MAAM,aAAa,SAIoB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SACkC,CAAC"}

package/dist/src/Platform.js

@@ -0,0 +1,22 @@
+/**
+ * Platform detection utilities for Evolu.
+ *
+ * @module
+ */
+/** Detects if the code is running in React Native environment. */
+export const isReactNative = typeof navigator !== "undefined" &&
+    "product" in navigator &&
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    navigator.product === "ReactNative";
+/**
+ * Detects if Node.js Buffer is available and should be used.
+ *
+ * React Native apps often polyfill Node.js APIs like Buffer, but we want to use
+ * native methods when available for better performance.
+ *
+ * Returns false in React Native even if Buffer is polyfilled, as we prefer
+ * native methods in that environment.
+ *
+ * @see https://github.com/craftzdog/react-native-quick-base64#installation
+ */
+export const hasNodeBuffer = !isReactNative && typeof globalThis.Buffer !== "undefined";

package/dist/src/Random.d.ts

@@ -5,8 +5,9 @@
  */
 import { Random as RandomLib } from "random";
 /**
- * A simple wrapper around Math.random(). Most apps need only this. For more
- * complex needs check {@link RandomLibDep}.
+ * A simple wrapper around Math.random().
+ *
+ * For more complex needs check {@link RandomLibDep}.
  *
  * ### Example
  *

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

@@ -1 +1 @@
-{"version":3,"file":"Random.d.ts","sourceRoot":"","sources":["../../src/Random.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAKnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,YAErD,CAAC"}
+{"version":3,"file":"Random.d.ts","sourceRoot":"","sources":["../../src/Random.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAKnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,YAErD,CAAC"}

package/dist/src/Relation.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Object identity:
+ *
+ * - 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.
+ */
+export interface Relation<A, B> {
+    /**
+     * Adds a pair to the relation. Returns true if the pair was newly added,
+     * false if it already existed.
+     */
+    readonly add: (a: A, b: B) => boolean;
+    /**
+     * Removes a specific pair from the relation. Returns true if the pair existed
+     * 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;
+    /**
+     * Iterates over each pair in the relation (in insertion order of A elements,
+     * then B elements per A).
+     */
+    readonly forEach: (callback: (a: A, b: B) => void) => void;
+    /**
+     * Iterator over all pairs enabling for..of and spread. Yields readonly [a, b]
+     * tuples.
+     */
+    readonly [Symbol.iterator]: () => IterableIterator<readonly [A, B]>;
+    /** Checks if a specific pair exists in the relation. */
+    readonly has: (a: A, b: B) => boolean;
+    /** Checks if an A element exists in the relation. */
+    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 pairs currently stored in the relation. */
+    readonly size: () => number;
+}
+/** Creates a {@link Relation}. */
+export declare const createRelation: <A, B>() => Relation<A, B>;
+//# sourceMappingURL=Relation.d.ts.map

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

@@ -0,0 +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"}

package/dist/src/Relation.js

@@ -0,0 +1,127 @@
+import { assert } from "./Assert.js";
+/** Creates a {@link Relation}. */
+export const createRelation = () => {
+    const aToB = new Map();
+    const bToA = new Map();
+    let sizeInternal = 0;
+    const relation = {
+        add(a, b) {
+            let bSet = aToB.get(a);
+            if (bSet?.has(b))
+                return false;
+            if (!bSet) {
+                bSet = new Set();
+                aToB.set(a, bSet);
+            }
+            bSet.add(b);
+            let aSet = bToA.get(b);
+            if (!aSet) {
+                aSet = new Set();
+                bToA.set(b, aSet);
+            }
+            aSet.add(a);
+            sizeInternal++;
+            return true;
+        },
+        remove(a, b) {
+            const bSet = aToB.get(a);
+            if (!bSet?.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--;
+            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)
+                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;
+            return true;
+        },
+        deleteB(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;
+        },
+        clear() {
+            aToB.clear();
+            bToA.clear();
+            sizeInternal = 0;
+        },
+        aCount() {
+            return aToB.size;
+        },
+        bCount() {
+            return bToA.size;
+        },
+        size() {
+            return sizeInternal;
+        },
+    };
+    return relation;
+};

package/dist/src/Resources.d.ts

@@ -0,0 +1,118 @@
+import { Result } from "./Result.js";
+/**
+ * A generic resource manager that handles reference counting and delayed
+ * disposal of shared resources. Useful for managing expensive resources like
+ * WebSocket connections that need to be shared among multiple consumers.
+ */
+export interface Resources<TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string> extends Disposable {
+    /**
+     * Adds a consumer to resources, creating them if necessary. Increments
+     * reference counts for existing consumer-resource pairs.
+     */
+    readonly addConsumer: (consumer: TConsumer, resourceConfigs: ReadonlyArray<TResourceConfig>) => void;
+    /**
+     * Removes a consumer from resources. Decrements reference counts and
+     * schedules disposal when no consumers remain.
+     *
+     * Returns an error if the resource doesn't exist or if the consumer wasn't
+     * added to the resource.
+     */
+    readonly removeConsumer: (consumer: TConsumer, resourceConfigs: ReadonlyArray<TResourceConfig>) => Result<void, ResourceNotFoundError<TResourceKey> | ConsumerNotFoundError<TConsumerId, TResourceKey>>;
+    /** Gets the resource for the specified key, or null if it doesn't exist. */
+    readonly getResource: (key: TResourceKey) => TResource | null;
+    /** Gets all consumer IDs currently using the specified resource key. */
+    readonly getConsumersForResource: (key: TResourceKey) => ReadonlyArray<TConsumerId>;
+    /** Checks if a consumer is currently using any resources. */
+    readonly hasConsumerAnyResource: (consumer: TConsumer) => boolean;
+    /**
+     * Gets the consumer for the specified consumer ID, or null if not found or
+     * not using any resources.
+     */
+    readonly getConsumer: (consumerId: TConsumerId) => TConsumer | null;
+}
+/** Error when trying to remove a consumer from a resource that doesn't exist. */
+export interface ResourceNotFoundError<TResourceKey extends string = string> {
+    readonly type: "ResourceNotFoundError";
+    readonly resourceKey: TResourceKey;
+}
+/** Error when trying to remove a consumer that wasn't added to a resource. */
+export interface ConsumerNotFoundError<TConsumerId extends string = string, TResourceKey extends string = string> {
+    readonly type: "ConsumerNotFoundError";
+    readonly consumerId: TConsumerId;
+    readonly resourceKey: TResourceKey;
+}
+export interface ResourcesConfig<TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string> {
+    /** Creates a new resource for the given config. */
+    readonly createResource: (config: TResourceConfig) => TResource;
+    /** Extracts a unique key from a resource config for deduplication. */
+    readonly getResourceKey: (config: TResourceConfig) => TResourceKey;
+    /** Extracts a unique identifier from a consumer for reference counting. */
+    readonly getConsumerId: (consumer: TConsumer) => TConsumerId;
+    /**
+     * Delay in milliseconds before disposing unused resources. Helps avoid
+     * resource churn during rapid add/remove cycles. Defaults to 100ms.
+     */
+    readonly disposalDelay?: number;
+    /**
+     * Called when a consumer is added to a resource for the first time. This
+     * happens when the consumer's reference count goes from 0 to 1 for this
+     * resource.
+     */
+    readonly onConsumerAdded?: (consumer: TConsumer, resource: TResource, resourceKey: TResourceKey) => void;
+    /**
+     * Called when a consumer is completely removed from a resource. This happens
+     * when the consumer's reference count goes from 1 to 0 for this resource.
+     */
+    readonly onConsumerRemoved?: (consumer: TConsumer, resource: TResource, resourceKey: TResourceKey) => void;
+}
+/**
+ * Creates {@link Resources}.
+ *
+ * This tracks which consumers are using which resources and maintains reference
+ * counts to know when it's safe to dispose resources. Resources are created
+ * on-demand and disposed with a configurable delay to avoid churn.
+ *
+ * ### Example Usage
+ *
+ * ```ts
+ * // WebSocket connections
+ * interface WebSocketConfig {
+ *   readonly url: WebSocketUrl;
+ * }
+ *
+ * type WebSocketUrl = string & Brand<"WebSocketUrl">;
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const webSockets = createResources<
+ *   WebSocket,
+ *   WebSocketUrl,
+ *   WebSocketConfig,
+ *   User,
+ *   UserId
+ * >({
+ *   createResource: (config) => new WebSocket(config.url),
+ *   getResourceKey: (config) => config.url,
+ *   getConsumerId: (user) => user.id,
+ *   disposalDelay: 1000,
+ * });
+ *
+ * // Add users to WebSocket connections
+ * webSockets.addConsumer(user1, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ *   { url: "ws://server2.com" as WebSocketUrl },
+ * ]);
+ * webSockets.addConsumer(user2, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ * ]);
+ *
+ * // Remove users - server1 stays alive (user2 still using it)
+ * webSockets.removeConsumer(user1, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ *   { url: "ws://server2.com" as WebSocketUrl },
+ * ]);
+ *
+ * // server2 gets disposed after delay, server1 stays alive
+ * ```
+ */
+export declare const createResources: <TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string>(config: ResourcesConfig<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>) => Resources<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>;
+//# sourceMappingURL=Resources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Resources.d.ts","sourceRoot":"","sources":["../../src/Resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAG9C;;;;GAIG;AACH,MAAM,WAAW,SAAS,CACxB,SAAS,SAAS,UAAU,EAC5B,YAAY,SAAS,MAAM,EAC3B,eAAe,EACf,SAAS,EACT,WAAW,SAAS,MAAM,CAC1B,SAAQ,UAAU;IAClB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CACpB,QAAQ,EAAE,SAAS,EACnB,eAAe,EAAE,aAAa,CAAC,eAAe,CAAC,KAC5C,IAAI,CAAC;IAEV;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,CACvB,QAAQ,EAAE,SAAS,EACnB,eAAe,EAAE,aAAa,CAAC,eAAe,CAAC,KAC5C,MAAM,CACT,IAAI,EACF,qBAAqB,CAAC,YAAY,CAAC,GACnC,qBAAqB,CAAC,WAAW,EAAE,YAAY,CAAC,CACnD,CAAC;IAEF,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,SAAS,GAAG,IAAI,CAAC;IAE9D,wEAAwE;IACxE,QAAQ,CAAC,uBAAuB,EAAE,CAChC,GAAG,EAAE,YAAY,KACd,aAAa,CAAC,WAAW,CAAC,CAAC;IAEhC,6DAA6D;IAC7D,QAAQ,CAAC,sBAAsB,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC;IAElE;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,IAAI,CAAC;CACrE;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB,CAAC,YAAY,SAAS,MAAM,GAAG,MAAM;IACzE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACpC;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB,CACpC,WAAW,SAAS,MAAM,GAAG,MAAM,EACnC,YAAY,SAAS,MAAM,GAAG,MAAM;IAEpC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACpC;AAED,MAAM,WAAW,eAAe,CAC9B,SAAS,SAAS,UAAU,EAC5B,YAAY,SAAS,MAAM,EAC3B,eAAe,EACf,SAAS,EACT,WAAW,SAAS,MAAM;IAE1B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,SAAS,CAAC;IAEhE,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,YAAY,CAAC;IAEnE,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,WAAW,CAAC;IAE7D;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,SAAS,EACnB,WAAW,EAAE,YAAY,KACtB,IAAI,CAAC;IAEV;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAC3B,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,SAAS,EACnB,WAAW,EAAE,YAAY,KACtB,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,SAAS,UAAU,EAC5B,YAAY,SAAS,MAAM,EAC3B,eAAe,EACf,SAAS,EACT,WAAW,SAAS,MAAM,EAE1B,QAAQ,eAAe,CACrB,SAAS,EACT,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,CACZ,KACA,SAAS,CACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,CAoLZ,CAAC"}