@evolu/common 6.0.1-preview.3 → 6.0.1-preview.30

package/src/ManyToManyMap.ts

@@ -1,22 +1,81 @@
-/** Represents a many-to-many mapping between keys and values. */
+import { assert } from "./Assert.js";
+
+/**
+ * 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.
+ *
+ * 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;
@@ -28,17 +87,26 @@ export interface ManyToManyMap<K, V> {
   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 const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
   const forwardMap = new Map<K, Set<V>>();
   const reverseMap = new Map<V, Set<K>>();
+  let pairCountInternal = 0;
 
   const map: ManyToManyMap<K, V> = {
     add(key: K, value: V) {
       let values = forwardMap.get(key);
+      if (values?.has(value)) return false;
       if (!values) {
         values = new Set<V>();
         forwardMap.set(key, values);
@@ -51,8 +119,8 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         reverseMap.set(value, keys);
       }
       keys.add(key);
-
-      return map;
+      pairCountInternal++;
+      return true;
     },
 
     remove(key: K, value: V) {
@@ -65,24 +133,41 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
       }
 
       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: K) {
+    getValues(key: K): ReadonlySet<V> | undefined {
       return forwardMap.get(key);
     },
 
-    getKeys(value: V) {
+    getKeys(value: V): ReadonlySet<K> | undefined {
       return reverseMap.get(value);
     },
 
+    forEach(callback: (key: K, value: V) => void) {
+      for (const [key, values] of forwardMap) {
+        for (const value of values) callback(key, value);
+      }
+    },
+
+    [Symbol.iterator](): IterableIterator<readonly [K, V]> {
+      const iterator = function* () {
+        for (const [key, values] of forwardMap) {
+          for (const value of values) {
+            yield [key, value] as const;
+          }
+        }
+      };
+      return iterator();
+    },
+
     hasPair(key: K, value: V) {
       const values = forwardMap.get(key);
       return values?.has(value) ?? false;
@@ -99,7 +184,7 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
     deleteKey(key: K) {
       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) {
@@ -110,13 +195,14 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         }
       }
       forwardMap.delete(key);
+      pairCountInternal -= removed;
       return true;
     },
 
     deleteValue(value: V) {
       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) {
@@ -127,12 +213,26 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         }
       }
       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;
     },
   };
 

package/src/Number.ts

@@ -2,12 +2,8 @@ import { NonEmptyReadonlyArray } from "./Array.js";
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok, Result } from "./Result.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
-import {
-  IntentionalNever,
-  IsBranded,
-  Predicate,
-  WidenLiteral,
-} from "./Types.js";
+import { IntentionalNever, Predicate, WidenLiteral } from "./Types.js";
+import { IsBranded } from "./Brand.js";
 
 export const increment = (n: number): number => n + 1;
 
@@ -63,15 +59,15 @@ export const computeBalancedBuckets = (
   numberOfItems: NonNegativeInt,
 
   /** Default: 16 */
-  numberOfBuckets = 16 as PositiveInt,
+  numberOfBuckets = PositiveInt.orThrow(16),
 
   /** Default: 2 */
-  minNumberOfItemsPerBucket = 2 as PositiveInt,
+  minNumberOfItemsPerBucket = PositiveInt.orThrow(2),
 ): Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt> => {
   const minRequiredItems = numberOfBuckets * minNumberOfItemsPerBucket;
 
   if (numberOfItems < minRequiredItems)
-    return err(minRequiredItems as PositiveInt);
+    return err(PositiveInt.orThrow(minRequiredItems));
 
   const indexes: Array<PositiveInt> = [];
   const itemsPerBucket = Math.floor(numberOfItems / numberOfBuckets);
@@ -82,7 +78,7 @@ export const computeBalancedBuckets = (
     const hasExtraItem = i < extraItems;
     const itemsInThisBucket = itemsPerBucket + (hasExtraItem ? 1 : 0);
     bucketBoundary += itemsInThisBucket;
-    indexes.push(bucketBoundary as PositiveInt);
+    indexes.push(PositiveInt.orThrow(bucketBoundary));
   }
 
   assertNonEmptyReadonlyArray(indexes);

package/src/Platform.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 as any).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/src/Random.ts

@@ -7,8 +7,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/src/Resources.ts

@@ -0,0 +1,367 @@
+import { err, ok, Result } from "./Result.js";
+import { PositiveInt } from "./Type.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 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
+> => {
+  let isDisposed = false;
+
+  const resourcesMap = new Map<TResourceKey, TResource>();
+  const consumerCounts = new Map<TResourceKey, Map<TConsumerId, PositiveInt>>();
+  const consumers = new Map<TConsumerId, TConsumer>();
+  const disposalTimeouts = new Map<
+    TResourceKey,
+    ReturnType<typeof setTimeout>
+  >();
+
+  const disposalDelay = config.disposalDelay ?? 100;
+
+  const ensureResource = (resourceConfig: TResourceConfig) => {
+    const key = config.getResourceKey(resourceConfig);
+    const timeout = disposalTimeouts.get(key);
+    if (timeout) {
+      clearTimeout(timeout);
+      disposalTimeouts.delete(key);
+    }
+
+    if (!resourcesMap.has(key)) {
+      const resource = config.createResource(resourceConfig);
+      resourcesMap.set(key, resource);
+    }
+  };
+
+  const scheduleDisposal = (key: TResourceKey): void => {
+    const timeout = setTimeout(() => {
+      const resource = resourcesMap.get(key);
+      if (resource) {
+        resource[Symbol.dispose]();
+        resourcesMap.delete(key);
+      }
+      disposalTimeouts.delete(key);
+    }, disposalDelay);
+
+    disposalTimeouts.set(key, timeout);
+  };
+
+  const resources: Resources<
+    TResource,
+    TResourceKey,
+    TResourceConfig,
+    TConsumer,
+    TConsumerId
+  > = {
+    addConsumer: (consumer, resourceConfigs) => {
+      if (isDisposed) return;
+
+      const consumerId = config.getConsumerId(consumer);
+
+      // Store consumer (last added consumer for this ID)
+      consumers.set(consumerId, consumer);
+
+      for (const resourceConfig of resourceConfigs) {
+        ensureResource(resourceConfig);
+        const resourceKey = config.getResourceKey(resourceConfig);
+
+        let counts = consumerCounts.get(resourceKey);
+        if (!counts) {
+          counts = new Map<TConsumerId, PositiveInt>();
+          consumerCounts.set(resourceKey, counts);
+        }
+
+        const currentCount = counts.get(consumerId) ?? 0;
+        const newCount = currentCount + 1;
+        counts.set(consumerId, PositiveInt.orThrow(newCount));
+
+        // Call onConsumerAdded callback only when consumer is added for the first time (0 -> 1)
+        if (currentCount === 0 && config.onConsumerAdded) {
+          const resource = resourcesMap.get(resourceKey);
+          if (resource) {
+            config.onConsumerAdded(consumer, resource, resourceKey);
+          }
+        }
+      }
+    },
+
+    removeConsumer: (consumer, resourceConfigs) => {
+      if (isDisposed) return ok();
+
+      const consumerId = config.getConsumerId(consumer);
+
+      for (const resourceConfig of resourceConfigs) {
+        const key = config.getResourceKey(resourceConfig);
+        const counts = consumerCounts.get(key);
+        if (!counts) {
+          return err({ type: "ResourceNotFoundError", resourceKey: key });
+        }
+
+        const currentCount = counts.get(consumerId);
+        if (currentCount == null) {
+          return err({
+            type: "ConsumerNotFoundError",
+            consumerId: consumerId,
+            resourceKey: key,
+          });
+        }
+
+        if (currentCount === 1) {
+          counts.delete(consumerId);
+
+          // Call onConsumerRemoved callback only when consumer is completely removed (1 -> 0)
+          if (config.onConsumerRemoved) {
+            const resource = resourcesMap.get(key);
+            if (resource) {
+              config.onConsumerRemoved(consumer, resource, key);
+            }
+          }
+
+          if (counts.size === 0) {
+            consumerCounts.delete(key);
+            scheduleDisposal(key);
+          }
+        } else {
+          counts.set(consumerId, PositiveInt.orThrow(currentCount - 1));
+        }
+      }
+
+      if (!resources.hasConsumerAnyResource(consumer)) {
+        consumers.delete(consumerId);
+      }
+
+      return ok();
+    },
+
+    getResource: (key) => {
+      if (isDisposed) return null;
+      return resourcesMap.get(key) ?? null;
+    },
+
+    getConsumersForResource: (key) => {
+      if (isDisposed) return [];
+      const counts = consumerCounts.get(key);
+      return counts ? Array.from(counts.keys()) : [];
+    },
+
+    hasConsumerAnyResource: (consumer) => {
+      if (isDisposed) return false;
+      const consumerId = config.getConsumerId(consumer);
+      // If slow, can be optimized with reverse index
+      return Array.from(consumerCounts.values()).some((counts) =>
+        counts.has(consumerId),
+      );
+    },
+
+    getConsumer: (consumerId) => {
+      if (isDisposed) return null;
+      const consumer = consumers.get(consumerId);
+      if (!consumer) return null;
+
+      // Only return consumer if it's currently using any resources
+      if (!resources.hasConsumerAnyResource(consumer)) {
+        return null;
+      }
+
+      return consumer;
+    },
+
+    [Symbol.dispose]: () => {
+      if (isDisposed) return;
+      isDisposed = true;
+
+      for (const timeout of disposalTimeouts.values()) {
+        clearTimeout(timeout);
+      }
+      disposalTimeouts.clear();
+
+      for (const resource of resourcesMap.values()) {
+        resource[Symbol.dispose]();
+      }
+      resourcesMap.clear();
+      consumerCounts.clear();
+      consumers.clear();
+    },
+  };
+
+  return resources;
+};