Rename CallbackRegistry and RefCountedResourceManager

Author: steida

.changeset/warm-squids-look.md

@@ -0,0 +1,11 @@
+---
+"@evolu/common": patch
+---
+
+Renaming
+
+- `CallbackRegistry` → `Callbacks`
+- `createCallbackRegistry` → `createCallbacks`
+- `RefCountedResourceManager` → `Resources`
+- `createRefCountedResourceManager` → `createResources`
+- `ResourceManagerConfig` → `ResourcesConfig`

packages/common/src/CallbackRegistry.ts packages/common/src/Callbacks.tspackages/common/src/CallbackRegistry.ts renamed to packages/common/src/Callbacks.ts

@@ -4,46 +4,45 @@ import { Result } from "./Result.js";
 import { createId, Id } from "./Type.js";
 
 /**
- * A registry for one-time callback functions.
+ * Request-response correlation for callbacks across boundaries.
  *
  * Stores callbacks with unique IDs and executes them once with an optional
- * argument. Executed callbacks are automatically removed from the registry.
+ * argument. Executed callbacks are automatically removed.
  *
- * This is useful for correlating asynchronous operations across boundaries
- * where callback functions cannot be passed directly (e.g., web workers).
+ * This is useful for correlating asynchronous request-response operations
+ * across boundaries where callback functions cannot be passed directly (e.g.,
+ * web workers, message queues).
  *
  * The `execute` method intentionally does not use try-catch or {@link Result}
- * because it's the callback's responsibility to handle its own errors. The
- * registry is just a correlation mechanism and should not interfere with error
- * handling or debugging by masking the original error location.
+ * because it's the callback's responsibility to handle its own errors.
  *
  * ### Example
  *
  * ```ts
  * // No-argument callbacks
- * const registry = createCallbackRegistry(deps);
- * const id = registry.register(() => console.log("called"));
- * registry.execute(id);
+ * const callbacks = createCallbacks(deps);
+ * const id = callbacks.register(() => console.log("called"));
+ * callbacks.execute(id);
  *
  * // With argument callbacks
- * const stringRegistry = createCallbackRegistry<string>(deps);
- * const id = stringRegistry.register((value) => {
+ * const stringCallbacks = createCallbacks<string>(deps);
+ * const id = stringCallbacks.register((value) => {
  *   console.log(value);
  * });
- * stringRegistry.execute(id, "hello");
+ * stringCallbacks.execute(id, "hello");
  *
  * // Promise.withResolvers pattern
- * const promiseRegistry = createCallbackRegistry<string>(deps);
+ * const promiseCallbacks = createCallbacks<string>(deps);
  * const { promise, resolve } = Promise.withResolvers<string>();
- * const id = promiseRegistry.register(resolve);
- * promiseRegistry.execute(id, "resolved value");
+ * const id = promiseCallbacks.register(resolve);
+ * promiseCallbacks.execute(id, "resolved value");
  * await promise; // "resolved value"
  * ```
  *
  * @template T - The type of argument passed to callbacks (defaults to undefined
  *   for no-argument callbacks)
  */
-export interface CallbackRegistry<T = undefined> {
+export interface Callbacks<T = undefined> {
   /** Registers a callback function and returns a unique ID. */
   readonly register: (callback: (arg: T) => void) => CallbackId;
 
@@ -53,12 +52,13 @@ export interface CallbackRegistry<T = undefined> {
     : (id: CallbackId, arg: T) => undefined;
 }
 
+/** Unique identifier for a callback in {@link Callbacks}. */
 export type CallbackId = Id & Brand<"Callback">;
 
-/** Creates a new {@link CallbackRegistry} for one-time callback functions. */
-export const createCallbackRegistry = <T = undefined>(
+/** Creates a new {@link Callbacks}. */
+export const createCallbacks = <T = undefined>(
   deps: RandomBytesDep,
-): CallbackRegistry<T> => {
+): Callbacks<T> => {
   const callbackMap = new Map<CallbackId, (arg: T) => void>();
 
   return {
@@ -70,15 +70,14 @@ export const createCallbackRegistry = <T = undefined>(
 
     execute: (id: CallbackId, ...args: T extends undefined ? [] : [T]) => {
       const callback = callbackMap.get(id);
-      if (callback) {
-        callbackMap.delete(id);
-        if (args.length === 0) {
-          // Called without argument (undefined case)
-          (callback as () => void)();
-        } else {
-          callback(args[0]);
-        }
+      if (!callback) return;
+      callbackMap.delete(id);
+      if (args.length === 0) {
+        // Called without argument (undefined case)
+        (callback as () => void)();
+      } else {
+        callback(args[0]);
       }
     },
-  } as CallbackRegistry<T>;
+  } as Callbacks<T>;
 };

packages/common/src/Evolu/Db.ts

@@ -1,5 +1,5 @@
 import { isNonEmptyArray, NonEmptyReadonlyArray } from "../Array.js";
-import { CallbackId } from "../CallbackRegistry.js";
+import { CallbackId } from "../Callbacks.js";
 import { ConsoleConfig, ConsoleDep } from "../Console.js";
 import {
   createSymmetricCrypto,

packages/common/src/Evolu/Evolu.ts

@@ -1,7 +1,7 @@
 import { pack } from "msgpackr";
 import { isNonEmptyArray, isNonEmptyReadonlyArray } from "../Array.js";
 import { assert, assertNonEmptyArray } from "../Assert.js";
-import { createCallbackRegistry } from "../CallbackRegistry.js";
+import { createCallbacks } from "../Callbacks.js";
 import { ConsoleDep } from "../Console.js";
 import { RandomBytesDep, SymmetricCryptoDecryptError } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
@@ -549,9 +549,8 @@ const createEvoluInstance =
 
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);
-    const onCompleteRegistry = createCallbackRegistry(deps);
-    const exportRegistry =
-      createCallbackRegistry<Uint8Array<ArrayBuffer>>(deps);
+    const onCompleteCallbacks = createCallbacks(deps);
+    const exportCallbacks = createCallbacks<Uint8Array<ArrayBuffer>>(deps);
 
     const dbWorker = deps.createDbWorker(dbConfig.name);
 
@@ -601,7 +600,7 @@ const createEvoluInstance =
           }
 
           for (const id of message.onCompleteIds) {
-            onCompleteRegistry.execute(id);
+            onCompleteCallbacks.execute(id);
           }
           break;
         }
@@ -628,13 +627,13 @@ const createEvoluInstance =
           if (message.reload) {
             deps.reloadApp(reloadUrl);
           } else {
-            onCompleteRegistry.execute(message.onCompleteId);
+            onCompleteCallbacks.execute(message.onCompleteId);
           }
           break;
         }
 
         case "onExport": {
-          exportRegistry.execute(
+          exportCallbacks.execute(
             message.onCompleteId,
             message.file as Uint8Array<ArrayBuffer>,
           );
@@ -748,11 +747,11 @@ const createEvoluInstance =
 
     const processMutationQueue = () => {
       const changes: Array<MutationChange> = [];
-      const onCompleteCallbacks = [];
+      const onCompletes = [];
 
       for (const [change, onComplete] of mutateMicrotaskQueue) {
         if (change !== null) changes.push(change);
-        if (onComplete) onCompleteCallbacks.push(onComplete);
+        if (onComplete) onCompletes.push(onComplete);
       }
 
       const queueLength = mutateMicrotaskQueue.length;
@@ -764,10 +763,7 @@ const createEvoluInstance =
         return;
       }
 
-      const onCompleteIds = onCompleteCallbacks.map(
-        onCompleteRegistry.register,
-      );
-
+      const onCompleteIds = onCompletes.map(onCompleteCallbacks.register);
       loadingPromises.releaseUnsubscribedOnMutation();
 
       if (!isNonEmptyArray(changes)) return;
@@ -846,7 +842,7 @@ const createEvoluInstance =
 
       resetAppOwner: (options) => {
         const { promise, resolve } = Promise.withResolvers<undefined>();
-        const onCompleteId = onCompleteRegistry.register(resolve);
+        const onCompleteId = onCompleteCallbacks.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -857,7 +853,7 @@ const createEvoluInstance =
 
       restoreAppOwner: (mnemonic, options) => {
         const { promise, resolve } = Promise.withResolvers<undefined>();
-        const onCompleteId = onCompleteRegistry.register(resolve);
+        const onCompleteId = onCompleteCallbacks.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -880,7 +876,7 @@ const createEvoluInstance =
       exportDatabase: () => {
         const { promise, resolve } =
           Promise.withResolvers<Uint8Array<ArrayBuffer>>();
-        const onCompleteId = exportRegistry.register(resolve);
+        const onCompleteId = exportCallbacks.register(resolve);
         dbWorker.postMessage({ type: "export", onCompleteId });
         return promise;
       },

packages/common/src/Evolu/Sync.ts

@@ -12,7 +12,7 @@ import { createTransferableError, TransferableError } from "../Error.js";
 import { constFalse } from "../Function.js";
 import { objectToEntries } from "../Object.js";
 import { RandomDep } from "../Random.js";
-import { createRefCountedResourceManager } from "../RefCountedResourceManager.js";
+import { createResources } from "../Resources.js";
 import { err, ok, Result } from "../Result.js";
 import { sql, SqliteDep, SqliteError, SqliteValue } from "../Sqlite.js";
 import { AbortError, createMutex } from "../Task.js";
@@ -253,7 +253,7 @@ export const createSync =
       });
     };
 
-    const transports = createRefCountedResourceManager<
+    const transports = createResources<
       WebSocket,
       TransportKey,
       OwnerTransport,

packages/common/src/Instances.ts

@@ -38,7 +38,7 @@ export interface Instances<K extends string, T extends Disposable>
   readonly delete: (key: K) => boolean;
 }
 
-/** Creates an {@link Instances} manager. */
+/** Creates an {@link Instances}. */
 export const createInstances = <
   K extends string,
   T extends Disposable,