API reference › @evolu/common › Callbacks › Callbacks

Defined in: packages/common/src/Callbacks.ts:75

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. A callback whose response will never come is removed with unregister.

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 Result because it's the callback's responsibility to handle its own errors.

Correlating callback responses

import { assertEqual, createCallbacks, testCreateDeps } from "@evolu/common";

const deps = testCreateDeps();

// No-argument callback
using callbacks = createCallbacks(deps);
let noArgumentCalls = 0;
const noArgumentId = callbacks.register(() => {
  noArgumentCalls++;
});
callbacks.execute(noArgumentId);
callbacks.execute(noArgumentId);
assertEqual(noArgumentCalls, 1);

// A callback whose response will never come
const failedId = callbacks.register(() => {
  noArgumentCalls++;
});
callbacks.unregister(failedId);
callbacks.execute(failedId);
assertEqual(noArgumentCalls, 1);

// Typed callback
using stringCallbacks = createCallbacks<string>(deps);
let received = "";
const stringCallbackId = stringCallbacks.register((value) => {
  received = value;
});
stringCallbacks.execute(stringCallbackId, "hello");
assertEqual(received, "hello");

// Promise.withResolvers
using promiseCallbacks = createCallbacks<string>(deps);
const { promise, resolve } = Promise.withResolvers<string>();
const promiseCallbackId = promiseCallbacks.register(resolve);
promiseCallbacks.execute(promiseCallbackId, "resolved value");
assertEqual(await promise, "resolved value");

Extends

Methods

[dispose]()

[dispose](): void;

Defined in: node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts:34

Inherited from

Disposable.[dispose]

Properties

execute

readonly execute: T extends undefined ? (id: string & Brand<"Id">) => undefined : (id: string & Brand<"Id">, arg: T) => undefined;

Defined in: packages/common/src/Callbacks.ts:80

Executes and removes a callback associated with the given ID.

register

readonly register: (callback: Callback<T>) => string & Brand<"Id">;

Defined in: packages/common/src/Callbacks.ts:77

Registers a callback function and returns a unique ID.

unregister

readonly unregister: (id: string & Brand<"Id">) => void;

Defined in: packages/common/src/Callbacks.ts:85

Removes a callback associated with the given ID without executing it.

Markdown for LLMs