@evolu/common 6.0.1-preview.2 → 6.0.1-preview.20

package/dist/src/Evolu/Timestamp.d.ts

@@ -1,8 +1,9 @@
-import { NanoIdLibDep } from "../NanoId.js";
+import { Brand } from "../Brand.js";
+import { RandomBytesDep } from "../Crypto.js";
 import { Order } from "../Order.js";
 import { Result } from "../Result.js";
 import { TimeDep } from "../Time.js";
-import { Brand } from "../Types.js";
+import { InferType } from "../Type.js";
 export interface TimestampConfig {
     /**
      * Maximum physical clock drift allowed in ms.
@@ -14,7 +15,7 @@ export interface TimestampConfig {
 export interface TimestampConfigDep {
     readonly timestampConfig: TimestampConfig;
 }
-export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError;
+export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError;
 export interface TimestampDriftError {
     readonly type: "TimestampDriftError";
     readonly next: Millis;
@@ -23,10 +24,6 @@ export interface TimestampDriftError {
 export interface TimestampCounterOverflowError {
     readonly type: "TimestampCounterOverflowError";
 }
-export interface TimestampDuplicateNodeError {
-    readonly type: "TimestampDuplicateNodeError";
-    readonly nodeId: NodeId;
-}
 export interface TimestampTimeOutOfRangeError {
     readonly type: "TimestampTimeOutOfRangeError";
 }
@@ -42,11 +39,11 @@ export interface TimestampTimeOutOfRangeError {
  *
  * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
  */
-export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
 export type Millis = typeof Millis.Type;
 export declare const minMillis: Millis;
 export declare const maxMillis: Millis;
-export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
 export type Counter = typeof Counter.Type;
 export declare const minCounter: Counter;
 export declare const maxCounter: Counter;
@@ -63,14 +60,17 @@ export declare const maxCounter: Counter;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * yet they will think they are synced. This is extremely rare and can be
+ * resolved by resetting one device to generate a new NodeId.
  */
 export declare const NodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 export type NodeId = typeof NodeId.Type;
@@ -84,23 +84,31 @@ export declare const maxNodeId: NodeId;
  * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
  */
 export declare const Timestamp: import("../Type.js").ObjectType<{
-    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
-    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
     nodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 }>;
-export type Timestamp = typeof Timestamp.Type;
+export interface Timestamp extends InferType<typeof Timestamp> {
+}
+/** Equality function for comparing {@link Timestamp}. */
+export declare const eqTimestamp: import("../Eq.js").Eq<{
+    readonly millis: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<`LessThanOrEqualTo${number}`> & Brand<"Millis">;
+    readonly counter: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"LessThanOrEqualTo65535"> & Brand<"Counter">;
+    readonly nodeId: string & Brand<"NodeId">;
+}>;
 export declare const createTimestamp: ({ millis, counter, nodeId, }?: Partial<Timestamp>) => Timestamp;
-export declare const createInitialTimestamp: (deps: NanoIdLibDep) => Timestamp;
-/** TimestampString is a sortable string version of {@link Timestamp}. */
+export declare const createInitialTimestamp: (deps: RandomBytesDep) => Timestamp;
+/** Sortable string representation of {@link Timestamp}. */
 export type TimestampString = string & Brand<"TimestampString">;
 export declare const timestampToTimestampString: (t: Timestamp) => TimestampString;
 export declare const timestampStringToTimestamp: (timestampString: TimestampString) => Timestamp;
 export declare const sendTimestamp: (deps: TimeDep & TimestampConfigDep) => (timestamp: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
-export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError>;
-/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
-export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
-export declare const binaryTimestampLength: number & Brand<"Int"> & Brand<"NonNegative">;
-export declare const timestampToBinaryTimestamp: (timestamp: Timestamp) => BinaryTimestamp;
-export declare const binaryTimestampToTimestamp: (timestamp: BinaryTimestamp) => Timestamp;
-export declare const orderBinaryTimestamp: Order<BinaryTimestamp>;
+export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
+/** Sortable bytes representation of {@link Timestamp}. */
+export declare const TimestampBytes: import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "TimestampBytes", import("../Type.js").BrandWithoutRefineError<"TimestampBytes", import("../Type.js").Uint8ArrayError>, never>;
+export type TimestampBytes = typeof TimestampBytes.Type;
+export declare const timestampBytesLength: number & Brand<"Int"> & Brand<"NonNegative">;
+export declare const timestampToTimestampBytes: (timestamp: Timestamp) => TimestampBytes;
+export declare const timestampBytesToTimestamp: (timestamp: TimestampBytes) => Timestamp;
+export declare const orderTimestampBytes: Order<TimestampBytes>;
 //# sourceMappingURL=Timestamp.d.ts.map

package/dist/src/Evolu/Timestamp.d.ts.map

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

package/dist/src/Evolu/Timestamp.js

@@ -1,8 +1,10 @@
 import { assert } from "../Assert.js";
+import { bytesToHex } from "../Buffer.js";
+import { createEqObject, eqNumber, eqString } from "../Eq.js";
 import { increment } from "../Number.js";
 import { orderUint8Array } from "../Order.js";
-import { err, getOrThrow, ok } from "../Result.js";
-import { brand, lessThanOrEqualTo, NonNegativeInt, object, regex, String, } from "../Type.js";
+import { err, ok } from "../Result.js";
+import { brand, lessThanOrEqualTo, NonNegativeInt, object, regex, String, Uint8Array, } from "../Type.js";
 /**
  * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
  * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
@@ -34,14 +36,17 @@ export const maxCounter = 65535;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * yet they will think they are synced. This is extremely rare and can be
+ * resolved by resetting one device to generate a new NodeId.
  */
 export const NodeId = regex("NodeId", /^[a-f0-9]{16}$/)(String);
 export const minNodeId = "0000000000000000";
@@ -58,10 +63,15 @@ export const Timestamp = object({
     counter: Counter,
     nodeId: NodeId,
 });
+/** Equality function for comparing {@link Timestamp}. */
+export const eqTimestamp = createEqObject({
+    millis: eqNumber,
+    counter: eqNumber,
+    nodeId: eqString,
+});
 export const createTimestamp = ({ millis = minMillis, counter = minCounter, nodeId = minNodeId, } = {}) => ({ millis, counter, nodeId });
-const hexAlphabet = "0123456789abcdef";
 export const createInitialTimestamp = (deps) => {
-    const nodeId = deps.nanoIdLib.customAlphabet(hexAlphabet, 16)();
+    const nodeId = bytesToHex(deps.randomBytes.create(8));
     return createTimestamp({ nodeId });
 };
 export const timestampToTimestampString = (t) => [
@@ -115,9 +125,6 @@ export const sendTimestamp = (deps) => (timestamp) => {
     });
 };
 export const receiveTimestamp = (deps) => (local, remote) => {
-    if (local.nodeId === remote.nodeId) {
-        return err({ type: "TimestampDuplicateNodeError", nodeId: local.nodeId });
-    }
     const millis = getNextMillis(deps)([local.millis, remote.millis]);
     if (!millis.ok)
         return millis;
@@ -136,11 +143,13 @@ export const receiveTimestamp = (deps) => (local, remote) => {
         nodeId: local.nodeId,
     });
 };
-export const binaryTimestampLength = getOrThrow(NonNegativeInt.from(16));
-export const timestampToBinaryTimestamp = (timestamp) => {
+/** Sortable bytes representation of {@link Timestamp}. */
+export const TimestampBytes = brand("TimestampBytes", Uint8Array);
+export const timestampBytesLength = NonNegativeInt.orThrow(16);
+export const timestampToTimestampBytes = (timestamp) => {
     const { millis, counter, nodeId } = timestamp;
     // 6 bytes for millis, 2 bytes for counter, 8 bytes for nodeId.
-    const value = new Uint8Array(16);
+    const value = new globalThis.Uint8Array(16);
     // Encode `millis` into the first 6 bytes.
     const millisBigInt = BigInt(millis);
     value[0] = Number((millisBigInt >> 40n) & 0xffn);
@@ -159,7 +168,7 @@ export const timestampToBinaryTimestamp = (timestamp) => {
     }
     return value;
 };
-export const binaryTimestampToTimestamp = (timestamp) => {
+export const timestampBytesToTimestamp = (timestamp) => {
     // Decode `millis` from the first 6 bytes.
     const millis = (BigInt(timestamp[0]) << 40n) |
         (BigInt(timestamp[1]) << 32n) |
@@ -176,4 +185,4 @@ export const binaryTimestampToTimestamp = (timestamp) => {
     }
     return { millis: Number(millis), counter, nodeId };
 };
-export const orderBinaryTimestamp = orderUint8Array;
+export const orderTimestampBytes = orderUint8Array;

package/dist/src/ManyToManyMap.d.ts

@@ -1,17 +1,75 @@
-/** Represents a many-to-many mapping between keys and values. */
+/**
+ * Bidirectional many-to-many map between keys and values.
+ *
+ * Why useful:
+ *
+ * - Provides O(1) (amortized) forward lookup (key -> values) and reverse lookup
+ *   (value -> keys) without maintaining two maps manually and risking them
+ *   diverging.
+ * - Natural fit for pub/sub style relations such as ownerId ↔ WebSocket, tag ↔
+ *   item, user ↔ role, entity ↔ subscription where both directions are
+ *   frequently queried.
+ * - Supports fast membership tests via `hasPair`, `hasKey`, and `hasValue`.
+ * - Iteration helpers (`forEach`, iterator) allow treating the structure as an
+ *   edge list when needed.
+ *
+ * Complexity:
+ *
+ * - `add` / `remove` / `has*` / `get*` each perform a constant number of Map/Set
+ *   operations (O(1) expected).
+ * - `deleteKey` and `deleteValue` are O(d) where d is the number of associated
+ *   values / keys (the degree). This is optimal because every associated pair
+ *   must be touched once.
+ * - In the Relay use case a socket (value) typically has only dozens of owners
+ *   (degree small), and connection closes (triggering deleteValue) are
+ *   relatively infrequent, so O(d) is acceptable.
+ *
+ * Object identity:
+ *
+ * - Keys and values 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 ManyToManyMap<K, V> {
-    /** Adds a key-value association to the map. */
-    add: (key: K, value: V) => ManyToManyMap<K, V>;
-    /** Removes a specific key-value association. */
+    /**
+     * Adds a key-value association to the map. Returns true if the pair was newly
+     * added, false if it already existed.
+     */
+    add: (key: K, value: V) => boolean;
+    /**
+     * Removes a specific key-value association. Returns true if the pair existed
+     * and was removed, false if it was not present.
+     */
     remove: (key: K, value: V) => boolean;
-    /** Gets all values associated with a key. */
-    getValues: (key: K) => Set<V> | undefined;
-    /** Gets all keys associated with a value. */
-    getKeys: (value: V) => Set<K> | undefined;
+    /**
+     * Gets all values associated with a key. Returned set is the internal Set
+     * instance typed as ReadonlySet. Do not mutate.
+     */
+    getValues: (key: K) => ReadonlySet<V> | undefined;
+    /**
+     * Gets all keys associated with a value. Returned set is the internal Set
+     * instance typed as ReadonlySet. Do not mutate.
+     */
+    getKeys: (value: V) => ReadonlySet<K> | undefined;
+    /**
+     * Iterates over each key-value pair (in insertion order of keys, then values
+     * per key).
+     */
+    forEach: (callback: (key: K, value: V) => void) => void;
+    /**
+     * Iterator over all key-value pairs enabling for..of and spread. Yields
+     * readonly [key, value] tuples.
+     */
+    readonly [Symbol.iterator]: () => IterableIterator<readonly [K, V]>;
     /** Checks if a specific key-value pair exists. */
     hasPair: (key: K, value: V) => boolean;
     /** Checks if a key exists in the map. */
-    hasKey(key: K): boolean;
+    hasKey: (key: K) => boolean;
     /** Checks if a value exists in the map. */
     hasValue: (value: V) => boolean;
     /** Deletes all associations for a key. */
@@ -19,7 +77,13 @@ export interface ManyToManyMap<K, V> {
     /** Deletes all associations for a value. */
     deleteValue: (value: V) => boolean;
     /** Clears all associations in the map. */
-    clear(): void;
+    clear: () => void;
+    /** Number of distinct keys currently present. */
+    keyCount: () => number;
+    /** Number of distinct values currently present. */
+    valueCount: () => number;
+    /** Number of key-value pairs (associations) currently stored. */
+    pairCount: () => number;
 }
 /** Creates a {@link ManyToManyMap}. */
 export declare const createManyToManyMap: <K, V>() => ManyToManyMap<K, V>;

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

@@ -1 +1 @@
-{"version":3,"file":"ManyToManyMap.d.ts","sourceRoot":"","sources":["../../src/ManyToManyMap.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC;IACjC,+CAA+C;IAC/C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/C,gDAAgD;IAChD,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC,6CAA6C;IAC7C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAE1C,6CAA6C;IAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAE1C,kDAAkD;IAClD,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEvC,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IAExB,2CAA2C;IAC3C,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEhC,0CAA0C;IAC1C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAE/B,4CAA4C;IAC5C,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEnC,0CAA0C;IAC1C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,CAAC,EAAE,CAAC,OAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAyG9D,CAAC"}
+{"version":3,"file":"ManyToManyMap.d.ts","sourceRoot":"","sources":["../../src/ManyToManyMap.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC;IACjC;;;OAGG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEnC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC;;;OAGG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAElD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAElD;;;OAGG;IACH,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpE,kDAAkD;IAClD,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEvC,yCAAyC;IACzC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAE5B,2CAA2C;IAC3C,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEhC,0CAA0C;IAC1C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAE/B,4CAA4C;IAC5C,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEnC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,mDAAmD;IACnD,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,iEAAiE;IACjE,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,CAAC,EAAE,CAAC,OAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CA2I9D,CAAC"}

package/dist/src/ManyToManyMap.js

@@ -1,10 +1,14 @@
+import { assert } from "./Assert.js";
 /** Creates a {@link ManyToManyMap}. */
 export const createManyToManyMap = () => {
     const forwardMap = new Map();
     const reverseMap = new Map();
+    let pairCountInternal = 0;
     const map = {
         add(key, value) {
             let values = forwardMap.get(key);
+            if (values?.has(value))
+                return false;
             if (!values) {
                 values = new Set();
                 forwardMap.set(key, values);
@@ -16,7 +20,8 @@ export const createManyToManyMap = () => {
                 reverseMap.set(value, keys);
             }
             keys.add(key);
-            return map;
+            pairCountInternal++;
+            return true;
         },
         remove(key, value) {
             const values = forwardMap.get(key);
@@ -27,12 +32,12 @@ export const createManyToManyMap = () => {
                 forwardMap.delete(key);
             }
             const keys = reverseMap.get(value);
-            if (keys?.size) {
-                keys.delete(key);
-                if (keys.size === 0) {
-                    reverseMap.delete(value);
-                }
+            assert(keys, "Key-value mapping inconsistency");
+            keys.delete(key);
+            if (keys.size === 0) {
+                reverseMap.delete(value);
             }
+            pairCountInternal--;
             return true;
         },
         getValues(key) {
@@ -41,6 +46,22 @@ export const createManyToManyMap = () => {
         getKeys(value) {
             return reverseMap.get(value);
         },
+        forEach(callback) {
+            for (const [key, values] of forwardMap) {
+                for (const value of values)
+                    callback(key, value);
+            }
+        },
+        [Symbol.iterator]() {
+            const iterator = function* () {
+                for (const [key, values] of forwardMap) {
+                    for (const value of values) {
+                        yield [key, value];
+                    }
+                }
+            };
+            return iterator();
+        },
         hasPair(key, value) {
             const values = forwardMap.get(key);
             return values?.has(value) ?? false;
@@ -55,6 +76,7 @@ export const createManyToManyMap = () => {
             const values = forwardMap.get(key);
             if (!values)
                 return false;
+            const removed = values.size;
             for (const value of values) {
                 const keys = reverseMap.get(value);
                 if (keys) {
@@ -65,12 +87,14 @@ export const createManyToManyMap = () => {
                 }
             }
             forwardMap.delete(key);
+            pairCountInternal -= removed;
             return true;
         },
         deleteValue(value) {
             const keys = reverseMap.get(value);
             if (!keys)
                 return false;
+            const removed = keys.size;
             for (const key of keys) {
                 const values = forwardMap.get(key);
                 if (values) {
@@ -81,11 +105,22 @@ export const createManyToManyMap = () => {
                 }
             }
             reverseMap.delete(value);
+            pairCountInternal -= removed;
             return true;
         },
         clear() {
             forwardMap.clear();
             reverseMap.clear();
+            pairCountInternal = 0;
+        },
+        keyCount() {
+            return forwardMap.size;
+        },
+        valueCount() {
+            return reverseMap.size;
+        },
+        pairCount() {
+            return pairCountInternal;
         },
     };
     return map;

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. */

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,kBAAwB,WAAW;AAEnC,iBAAiB;AACjB,4BAAiC,WAAW,KAC3C,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC"}

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/RefCountedResourceManager.d.ts

@@ -0,0 +1,119 @@
+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, database connections, or file handles that need to be
+ * shared among multiple consumers.
+ */
+export interface RefCountedResourceManager<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 ResourceManagerConfig<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 a reference-counted resource manager.
+ *
+ * This manager 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 manager
+ * interface WebSocketConfig {
+ *   readonly url: WebSocketUrl;
+ * }
+ *
+ * type WebSocketUrl = string & Brand<"WebSocketUrl">;
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const wsManager = createRefCountedResourceManager<
+ *   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
+ * wsManager.addConsumer(user1, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ *   { url: "ws://server2.com" as WebSocketUrl },
+ * ]);
+ * wsManager.addConsumer(user2, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ * ]);
+ *
+ * // Remove users - server1 stays alive (user2 still using it)
+ * wsManager.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 createRefCountedResourceManager: <TResource extends Disposable, TResourceKey extends string, TResourceConfig, TConsumer, TConsumerId extends string>(config: ResourceManagerConfig<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>) => RefCountedResourceManager<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>;
+//# sourceMappingURL=RefCountedResourceManager.d.ts.map

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

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