Rename Callbacks to CallbackRegistry, improve docs

Author: steida

packages/common/src/CallbackRegistry.ts

@@ -0,0 +1,49 @@
+import { Brand } from "./Brand.js";
+import { NanoIdLibDep } from "./NanoId.js";
+import { Result } from "./Result.js";
+
+/**
+ * A registry for one-time callback functions.
+ *
+ * Stores callbacks with unique IDs and executes them once with an optional
+ * argument. Executed callbacks are automatically removed from the registry.
+ *
+ * This is useful for correlating asynchronous operations across boundaries
+ * where callback functions cannot be passed directly (e.g., web workers).
+ *
+ * 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.
+ */
+export interface CallbackRegistry {
+  /** Registers a callback function and returns a unique ID. */
+  readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+
+  /** Executes and removes a callback associated with the given ID. */
+  readonly execute: (id: CallbackId, arg?: unknown) => void;
+}
+
+export type CallbackId = string & Brand<"CallbackId">;
+
+export const createCallbackRegistry = (
+  deps: NanoIdLibDep,
+): CallbackRegistry => {
+  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
+
+  return {
+    register: (callback) => {
+      const id = deps.nanoIdLib.nanoid() as CallbackId;
+      callbackMap.set(id, callback);
+      return id;
+    },
+
+    execute: (id, arg) => {
+      const callback = callbackMap.get(id);
+      if (callback) {
+        callbackMap.delete(id);
+        callback(arg);
+      }
+    },
+  };
+};

packages/common/src/Callbacks.ts

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

packages/common/src/Evolu/Db.ts

@@ -1,7 +1,7 @@
 import { pack } from "msgpackr";
 import { isNonEmptyArray, isNonEmptyReadonlyArray } from "../Array.js";
 import { assert, assertNonEmptyArray } from "../Assert.js";
-import { createCallbacks } from "../Callbacks.js";
+import { createCallbackRegistry } from "../CallbackRegistry.js";
 import { ConsoleDep } from "../Console.js";
 import { SymmetricCryptoDecryptError } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
@@ -673,7 +673,7 @@ const createEvoluInstance =
 
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);
-    const callbacks = createCallbacks(deps);
+    const callbackRegistry = createCallbackRegistry(deps);
 
     const appState = deps.createAppState(config);
     const dbWorker = deps.createDbWorker(config.name);
@@ -726,7 +726,7 @@ const createEvoluInstance =
           }
 
           for (const id of message.onCompleteIds) {
-            callbacks.execute(id);
+            callbackRegistry.execute(id);
           }
           break;
         }
@@ -746,13 +746,13 @@ const createEvoluInstance =
           if (message.reload) {
             appState.reset();
           } else {
-            callbacks.execute(message.onCompleteId);
+            callbackRegistry.execute(message.onCompleteId);
           }
           break;
         }
 
         case "onExport": {
-          callbacks.execute(message.onCompleteId, message.file);
+          callbackRegistry.execute(message.onCompleteId, message.file);
           break;
         }
 
@@ -867,7 +867,7 @@ const createEvoluInstance =
               }
 
               const onCompleteIds = onCompletes.map((onComplete) =>
-                callbacks.register(onComplete),
+                callbackRegistry.register(onComplete),
               );
 
               loadingPromises.releaseUnsubscribed();
@@ -960,7 +960,7 @@ const createEvoluInstance =
         // Eslint bug, Promise<void> is correct by docs.
         // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
         const { promise, resolve } = Promise.withResolvers<void>();
-        const onCompleteId = callbacks.register(() => {
+        const onCompleteId = callbackRegistry.register(() => {
           resolve();
         });
         dbWorker.postMessage({
@@ -975,7 +975,7 @@ const createEvoluInstance =
         // Eslint bug, Promise<void> is correct by docs.
         // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
         const { promise, resolve } = Promise.withResolvers<void>();
-        const onCompleteId = callbacks.register(() => {
+        const onCompleteId = callbackRegistry.register(() => {
           resolve();
         });
 
@@ -1000,7 +1000,7 @@ const createEvoluInstance =
 
       exportDatabase: () => {
         const { promise, resolve } = Promise.withResolvers<Uint8Array>();
-        const onCompleteId = callbacks.register((arg) => {
+        const onCompleteId = callbackRegistry.register((arg) => {
           if (arg instanceof Uint8Array) resolve(arg);
         });
         dbWorker.postMessage({ type: "export", onCompleteId });

packages/common/src/Evolu/Evolu.ts

@@ -3,7 +3,7 @@ export * from "./Assert.js";
 export * from "./BigInt.js";
 export * from "./Brand.js";
 export * from "./Buffer.js";
-export * from "./Callbacks.js";
+export * from "./CallbackRegistry.js";
 export * from "./Console.js";
 export * from "./Crypto.js";
 export * from "./Eq.js";

packages/common/src/index.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "vitest";
+import { createCallbackRegistry } from "../src/CallbackRegistry.js";
+import { testNanoIdLibDep } from "./_deps.js";
+
+test("CallbackRegistry", () => {
+  const registry = createCallbackRegistry(testNanoIdLibDep);
+
+  let called = false;
+  const id = registry.register(() => {
+    called = true;
+  });
+
+  expect(id).toBeDefined();
+  registry.execute(id);
+  expect(called).toBe(true);
+
+  called = false;
+  registry.execute(id);
+  expect(called).toBe(false);
+});

packages/common/test/CallbackRegistry.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { CallbackId } from "../../src/Callbacks.js";
+import { CallbackId } from "../../src/CallbackRegistry.js";
 import { createConsole } from "../../src/Console.js";
 import { defaultConfig } from "../../src/Evolu/Config.js";
 import {

packages/common/test/Callbacks.test.ts

@@ -63,7 +63,7 @@ test("deleteOwner", async () => {
     change: new Uint8Array([1, 2, 3]) as EncryptedDbChange,
   };
 
-  storage.writeMessages(testOwnerBinaryId, [message]);
+  await storage.writeMessages(testOwnerBinaryId, [message]);
 
   expect(storage.getSize(testOwnerBinaryId)).toBe(1);
 

packages/common/test/Evolu/Db.test.ts

@@ -16,7 +16,7 @@
     "src/BigInt.ts",
     "src/Brand.ts",
     "src/Buffer.ts",
-    "src/Callbacks.ts",
+    "src/CallbackRegistry.ts",
     "src/Console.ts",
     "src/Crypto.ts",
     "src/Eq.ts",