Add Multiton instance manager and integrate with Evolu

Author: steida

.changeset/wide-rocks-beam.md

@@ -0,0 +1,9 @@
+---
+"@evolu/common": patch
+---
+
+Add Multiton
+
+Multiton manages multiple named instances using a key-based registry with structured disposal. It's used internally for Evolu instance caching to support hot reloading and prevent database corruption from multiple connections.
+
+See the Multiton documentation for usage patterns and caveats.

packages/common/src/Evolu/Evolu.ts

@@ -7,6 +7,7 @@ import { RandomBytesDep, SymmetricCryptoDecryptError } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { TransferableError } from "../Error.js";
 import { exhaustiveCheck } from "../Function.js";
+import { createMultiton, Multiton } from "../Multiton.js";
 import { err, ok, Result } from "../Result.js";
 import { isSqlMutation, SafeSql, SqliteError, SqliteQuery } from "../Sqlite.js";
 import { createStore, StoreSubscribe } from "../Store.js";
@@ -19,6 +20,7 @@ import {
   InferType,
   Mnemonic,
   ObjectType,
+  SimpleName,
   ValidMutationSize,
   ValidMutationSizeError,
 } from "../Type.js";
@@ -92,7 +94,7 @@ export interface EvoluConfig extends Partial<DbConfig> {
   readonly reloadUrl?: string;
 }
 
-export interface Evolu<S extends EvoluSchema = EvoluSchema> {
+export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
   /**
    * Subscribe to {@link EvoluError} changes.
    *
@@ -457,8 +459,12 @@ export type EvoluDeps = ConsoleDep &
   ReloadAppDep &
   TimeDep;
 
-const evoluInstances = new Map<string, InternalEvoluInstance>();
+const evoluInstances = createMultiton<SimpleName, InternalEvoluInstance>();
 
+/**
+ * Unique identifier for the current browser tab or app instance, lazily
+ * initialized on first use to distinguish between multiple tabs.
+ */
 let tabId: Id | null = null;
 
 /**
@@ -496,35 +502,25 @@ let tabId: Id | null = null;
  *
  * ### Instance Caching
  *
- * Evolu caches instances by {@link EvoluConfig} name to enable hot reloading and
- * multitenancy. Multiple calls to `createEvolu` with the same name return the
- * same instance, preserving database connections and state across module
- * reloads during development. This ensures a seamless developer experience
- * where edits don't interrupt ongoing sync or lose in-memory state.
- *
- * For testing, either dispose of instances after each test (TODO: implement
- * dispose method) or use unique instance names to ensure proper isolation
- * between test cases.
+ * `createEvolu` caches instances using {@link Multiton} by {@link EvoluConfig}
+ * name to enable hot reloading and prevent database corruption from multiple
+ * connections. For testing, use unique instance names to ensure proper
+ * isolation.
  */
 export const createEvolu =
   (deps: EvoluDeps) =>
   <S extends EvoluSchema>(
     schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>,
     config?: EvoluConfig,
-  ): Evolu<S> => {
-    const name = config?.name ?? defaultDbConfig.name;
-    let evolu = evoluInstances.get(name);
-
-    if (evolu == null) {
-      evolu = createEvoluInstance(deps)(schema as EvoluSchema, config);
-      evoluInstances.set(name, evolu);
-    } else {
-      // Hot reloading. Note that indexes are intentionally omitted.
-      evolu.ensureSchema(schema as EvoluSchema);
-    }
-
-    return evolu as Evolu<S>;
-  };
+  ): Evolu<S> =>
+    evoluInstances.ensure(
+      config?.name ?? defaultDbConfig.name,
+      () => createEvoluInstance(deps)(schema as EvoluSchema, config),
+      (evolu) => {
+        // Hot reloading. Note that indexes are intentionally omitted.
+        evolu.ensureSchema(schema as EvoluSchema);
+      },
+    ) as Evolu<S>;
 
 const createEvoluInstance =
   (deps: EvoluDeps) =>
@@ -943,6 +939,11 @@ const createEvoluInstance =
 
         return unuse;
       },
+
+      /** Disposal is not implemented yet. */
+      [Symbol.dispose]: () => {
+        throw new Error("Evolu instance disposal is not yet implemented");
+      },
     };
 
     return evolu;

packages/common/src/Multiton.ts

@@ -0,0 +1,98 @@
+/**
+ * Manages multiple named instances using the Multiton pattern.
+ *
+ * Unlike Singleton (one instance globally), Multiton maintains one instance per
+ * unique key.
+ *
+ * **Note:** Multiton is generally considered an anti-pattern because it
+ * introduces hidden global state and makes testing harder. Use it only when
+ * there's a compelling reason, such as:
+ *
+ * - Supporting hot reloading while preserving state across module reloads
+ * - Enforcing physical constraints (e.g., preventing multiple SQLite connections
+ *   to the same database, which causes corruption)
+ * - Managing resources where instance identity is intrinsic to correctness
+ *
+ * For most cases, prefer explicit dependency injection and instance management.
+ *
+ * Compatibility and future work:
+ *
+ * - We will adopt the ECMAScript `DisposableStack` for structured cleanup and
+ *   robust error handling as runtimes converge (Node.js ≥ 24, Safari stable).
+ *   Safari Technology Preview already includes support, so broad availability
+ *   is expected soon.
+ * - Until then, this module uses a simple Map-based approach and calls
+ *   `instance[Symbol.dispose]()` directly during disposal.
+ * - We don't use a polyfill because we avoid global mutation, keep bundles lean,
+ *   and prefer explicit feature detection.
+ * - MDN reference:
+ *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack
+ */
+export interface Multiton<K extends string, T extends Disposable>
+  extends Disposable {
+  /**
+   * Ensures an instance exists for the given key, creating it if necessary. If
+   * the instance already exists, the optional `onCacheHit` callback is invoked
+   * to update the existing instance.
+   */
+  readonly ensure: (
+    key: K,
+    create: () => T,
+    onCacheHit?: (instance: T) => void,
+  ) => T;
+
+  /** Gets an instance by key, or returns `null` if it doesn't exist. */
+  readonly get: (key: K) => T | null;
+
+  /** Checks if an instance exists for the given key. */
+  readonly has: (key: K) => boolean;
+
+  /**
+   * Removes and disposes an instance by key. Returns `true` if the instance
+   * existed and was disposed, `false` otherwise.
+   */
+  readonly disposeInstance: (key: K) => boolean;
+}
+
+/** Creates a {@link Multiton} instance manager. */
+export const createMultiton = <
+  K extends string,
+  T extends Disposable,
+>(): Multiton<K, T> => {
+  const instances = new Map<K, T>();
+
+  return {
+    ensure: (key, create, onCacheHit) => {
+      let instance = instances.get(key);
+
+      if (instance == null) {
+        instance = create();
+        instances.set(key, instance);
+      } else if (onCacheHit) {
+        onCacheHit(instance);
+      }
+
+      return instance;
+    },
+
+    get: (key) => instances.get(key) ?? null,
+
+    has: (key) => instances.has(key),
+
+    disposeInstance: (key) => {
+      const instance = instances.get(key);
+      if (instance) {
+        instance[Symbol.dispose]();
+        return instances.delete(key);
+      }
+      return false;
+    },
+
+    [Symbol.dispose]: () => {
+      for (const instance of instances.values()) {
+        instance[Symbol.dispose]();
+      }
+      instances.clear();
+    },
+  };
+};

packages/common/src/index.ts

@@ -13,6 +13,7 @@ export * from "./Evolu/Public.js";
 export * from "./Function.js";
 export * from "./Identicon.js";
 export * from "./ManyToManyMap.js";
+export * from "./Multiton.js";
 export * from "./Number.js";
 export * from "./Object.js";
 export * from "./Order.js";