@evolu/common 6.0.1-preview.27 → 6.0.1-preview.28

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

@@ -42,7 +42,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.
      *
@@ -399,15 +399,10 @@ export type EvoluDeps = ConsoleDep & CreateDbWorkerDep & Partial<FlushSyncDep> &
  *
  * ### 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 declare const createEvolu: (deps: EvoluDeps) => <S extends EvoluSchema>(schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>, config?: EvoluConfig) => Evolu<S>;
 export declare const createQuery: <R extends Row>(queryCallback: Parameters<CreateQuery<EvoluSchema>>[0], options?: Parameters<CreateQuery<EvoluSchema>>[1]) => Query<R>;

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

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

package/dist/src/Evolu/Evolu.js

@@ -4,6 +4,7 @@ import { assert, assertNonEmptyArray } from "../Assert.js";
 import { createCallbackRegistry } from "../CallbackRegistry.js";
 import { eqArrayNumber } from "../Eq.js";
 import { exhaustiveCheck } from "../Function.js";
+import { createMultiton } from "../Multiton.js";
 import { err, ok } from "../Result.js";
 import { isSqlMutation } from "../Sqlite.js";
 import { createStore } from "../Store.js";
@@ -14,7 +15,11 @@ import { createSubscribedQueries, emptyRows, serializeQuery, } from "./Query.js"
 import { evoluSchemaToDbSchema, insertable, kysely, updateable, upsertable, } from "./Schema.js";
 import { DbChange } from "./Storage.js";
 import { initialSyncState } from "./Sync.js";
-const evoluInstances = new Map();
+const evoluInstances = createMultiton();
+/**
+ * Unique identifier for the current browser tab or app instance, lazily
+ * initialized on first use to distinguish between multiple tabs.
+ */
 let tabId = null;
 /**
  * Creates an {@link Evolu} instance for a platform configured with the specified
@@ -51,29 +56,15 @@ let tabId = 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) => (schema, config) => {
-    const name = config?.name ?? defaultDbConfig.name;
-    let evolu = evoluInstances.get(name);
-    if (evolu == null) {
-        evolu = createEvoluInstance(deps)(schema, config);
-        evoluInstances.set(name, evolu);
-    }
-    else {
-        // Hot reloading. Note that indexes are intentionally omitted.
-        evolu.ensureSchema(schema);
-    }
-    return evolu;
-};
+export const createEvolu = (deps) => (schema, config) => evoluInstances.ensure(config?.name ?? defaultDbConfig.name, () => createEvoluInstance(deps)(schema, config), (evolu) => {
+    // Hot reloading. Note that indexes are intentionally omitted.
+    evolu.ensureSchema(schema);
+});
 const createEvoluInstance = (deps) => (schema, config) => {
     deps.console.enabled = config?.enableLogging ?? false;
     const { indexes, reloadUrl = "/", ...partialDbConfig } = config ?? {};
@@ -376,6 +367,10 @@ const createEvoluInstance = (deps) => (schema, config) => {
             };
             return unuse;
         },
+        /** Disposal is not implemented yet. */
+        [Symbol.dispose]: () => {
+            throw new Error("Evolu instance disposal is not yet implemented");
+        },
     };
     return evolu;
 };

package/dist/src/Multiton.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare const createMultiton: <K extends string, T extends Disposable>() => Multiton<K, T>;
+//# sourceMappingURL=Multiton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Multiton.d.ts","sourceRoot":"","sources":["../../src/Multiton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,UAAU,CAC9D,SAAQ,UAAU;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CACf,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,MAAM,CAAC,EACf,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,KAC/B,CAAC,CAAC;IAEP,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAEnC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;CAC/C;AAED,mDAAmD;AACnD,eAAO,MAAM,cAAc,GACzB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,UAAU,OACjB,QAAQ,CAAC,CAAC,EAAE,CAAC,CAqCjB,CAAC"}

package/dist/src/Multiton.js

@@ -0,0 +1,33 @@
+/** Creates a {@link Multiton} instance manager. */
+export const createMultiton = () => {
+    const instances = new Map();
+    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();
+        },
+    };
+};

package/dist/src/index.d.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";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/src/index.js

@@ -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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "6.0.1-preview.27",
+  "version": "6.0.1-preview.28",
   "description": "TypeScript library and local-first framework",
   "keywords": [
     "evolu",

package/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;

package/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();
+    },
+  };
+};

package/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";