Refactor CallbackRegistry to support typed arguments

Updated CallbackRegistry to be generic, allowing registration and execution of callbacks with typed arguments. Refactored Evolu to use separate registries for different callback types and simplified Promise.withResolvers usage. Added comprehensive tests for typed and no-argument callback scenarios.

Author: steida

packages/common/src/CallbackRegistry.ts

@@ -1,6 +1,7 @@
 import { Brand } from "./Brand.js";
 import { NanoIdLibDep } from "./NanoId.js";
 import { Result } from "./Result.js";
+import { createId, Id } from "./Type.js";
 
 /**
  * A registry for one-time callback functions.
@@ -15,35 +16,69 @@ import { Result } from "./Result.js";
  * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // No-argument callbacks
+ * const registry = createCallbackRegistry(deps);
+ * const id = registry.register(() => console.log("called"));
+ * registry.execute(id);
+ *
+ * // With argument callbacks
+ * const stringRegistry = createCallbackRegistry<string>(deps);
+ * const id = stringRegistry.register((value) => {
+ *   console.log(value);
+ * });
+ * stringRegistry.execute(id, "hello");
+ *
+ * // Promise.withResolvers pattern
+ * const promiseRegistry = createCallbackRegistry<string>(deps);
+ * const { promise, resolve } = Promise.withResolvers<string>();
+ * const id = promiseRegistry.register(resolve);
+ * promiseRegistry.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 {
+export interface CallbackRegistry<T = undefined> {
   /** Registers a callback function and returns a unique ID. */
-  readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+  readonly register: (callback: (arg: T) => void) => CallbackId;
 
   /** Executes and removes a callback associated with the given ID. */
-  readonly execute: (id: CallbackId, arg?: unknown) => void;
+  readonly execute: T extends undefined
+    ? (id: CallbackId) => undefined
+    : (id: CallbackId, arg: T) => undefined;
 }
 
-export type CallbackId = string & Brand<"CallbackId">;
+export type CallbackId = Id & Brand<"Callback">;
 
-export const createCallbackRegistry = (
+/** Creates a new {@link CallbackRegistry} for one-time callback functions. */
+export const createCallbackRegistry = <T = undefined>(
   deps: NanoIdLibDep,
-): CallbackRegistry => {
-  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
+): CallbackRegistry<T> => {
+  const callbackMap = new Map<CallbackId, (arg: T) => void>();
 
   return {
     register: (callback) => {
-      const id = deps.nanoIdLib.nanoid() as CallbackId;
+      const id = createId<"Callback">(deps);
       callbackMap.set(id, callback);
       return id;
     },
 
-    execute: (id, arg) => {
+    execute: (id: CallbackId, ...args: T extends undefined ? [] : [T]) => {
       const callback = callbackMap.get(id);
       if (callback) {
         callbackMap.delete(id);
-        callback(arg);
+        if (args.length === 0) {
+          // Called without argument (undefined case)
+          (callback as () => void)();
+        } else {
+          callback(args[0]);
+        }
       }
     },
-  };
+  } as CallbackRegistry<T>;
 };

packages/common/src/Evolu/Evolu.ts

@@ -673,7 +673,8 @@ const createEvoluInstance =
 
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);
-    const callbackRegistry = createCallbackRegistry(deps);
+    const onCompleteRegistry = createCallbackRegistry(deps);
+    const exportRegistry = createCallbackRegistry<Uint8Array>(deps);
 
     const appState = deps.createAppState(config);
     const dbWorker = deps.createDbWorker(config.name);
@@ -726,7 +727,7 @@ const createEvoluInstance =
           }
 
           for (const id of message.onCompleteIds) {
-            callbackRegistry.execute(id);
+            onCompleteRegistry.execute(id);
           }
           break;
         }
@@ -746,13 +747,13 @@ const createEvoluInstance =
           if (message.reload) {
             appState.reset();
           } else {
-            callbackRegistry.execute(message.onCompleteId);
+            onCompleteRegistry.execute(message.onCompleteId);
           }
           break;
         }
 
         case "onExport": {
-          callbackRegistry.execute(message.onCompleteId, message.file);
+          exportRegistry.execute(message.onCompleteId, message.file);
           break;
         }
 
@@ -850,11 +851,11 @@ const createEvoluInstance =
           if (mutateMicrotaskQueue.length === 1)
             queueMicrotask(() => {
               const changes: Array<MutationChange> = [];
-              const onCompletes = [];
+              const onCompleteCallbacks = [];
 
               for (const [change, onComplete] of mutateMicrotaskQueue) {
                 if (change !== null) changes.push(change);
-                if (onComplete) onCompletes.push(onComplete);
+                if (onComplete) onCompleteCallbacks.push(onComplete);
               }
 
               const queueLength = mutateMicrotaskQueue.length;
@@ -866,8 +867,8 @@ const createEvoluInstance =
                 return;
               }
 
-              const onCompleteIds = onCompletes.map((onComplete) =>
-                callbackRegistry.register(onComplete),
+              const onCompleteIds = onCompleteCallbacks.map(
+                onCompleteRegistry.register,
               );
 
               loadingPromises.releaseUnsubscribed();
@@ -957,12 +958,8 @@ const createEvoluInstance =
       upsert: createMutation("upsert"),
 
       resetAppOwner: (options) => {
-        // 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 = callbackRegistry.register(() => {
-          resolve();
-        });
+        const { promise, resolve } = Promise.withResolvers<undefined>();
+        const onCompleteId = onCompleteRegistry.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -972,13 +969,8 @@ const createEvoluInstance =
       },
 
       restoreAppOwner: (mnemonic, options) => {
-        // 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 = callbackRegistry.register(() => {
-          resolve();
-        });
-
+        const { promise, resolve } = Promise.withResolvers<undefined>();
+        const onCompleteId = onCompleteRegistry.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -1000,9 +992,7 @@ const createEvoluInstance =
 
       exportDatabase: () => {
         const { promise, resolve } = Promise.withResolvers<Uint8Array>();
-        const onCompleteId = callbackRegistry.register((arg) => {
-          if (arg instanceof Uint8Array) resolve(arg);
-        });
+        const onCompleteId = exportRegistry.register(resolve);
         dbWorker.postMessage({ type: "export", onCompleteId });
         return promise;
       },

packages/common/test/CallbackRegistry.test.ts

@@ -2,19 +2,45 @@ import { expect, test } from "vitest";
 import { createCallbackRegistry } from "../src/CallbackRegistry.js";
 import { testNanoIdLibDep } from "./_deps.js";
 
-test("CallbackRegistry", () => {
+test("CallbackRegistry with no argument", () => {
   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);
 });
+
+test("CallbackRegistry with string type", () => {
+  const registry = createCallbackRegistry<string>(testNanoIdLibDep);
+
+  let receivedValue: string | null = null;
+  const id = registry.register((value) => {
+    receivedValue = value;
+  });
+
+  registry.execute(id, "test value");
+  expect(receivedValue).toBe("test value");
+
+  receivedValue = null;
+  registry.execute(id, "should not execute");
+  expect(receivedValue).toBe(null);
+});
+
+test("CallbackRegistry with Promise.withResolvers pattern", () => {
+  const registry = createCallbackRegistry<string>(testNanoIdLibDep);
+
+  const { promise, resolve } = Promise.withResolvers<string>();
+  const id = registry.register(resolve);
+
+  registry.execute(id, "resolved value");
+
+  return expect(promise).resolves.toBe("resolved value");
+});