Skip to content

worker-protocol

The message protocol between WorkerComponent on the main thread and exposeWorkerApi inside a worker.

This module imports nothing, so a worker entry point bundled by @mnaoumov/obsidian-dev-toolkit’s workers feature can import it: a worker has no obsidian module and no Node builtins. Its message shapes are a wire format between the plugin’s main bundle and its worker bundle, which may come from different copies of this library, so fields are only ever added and a change of meaning moves to a new WORKER_PROTOCOL value.

Interface Description
SerializedWorkerError An error reduced to plain data, because an Error loses its class across the worker boundary.
TransferredValue A result marked to transfer some of its objects rather than copy them. Build it with withTransfer.
UnwrappedTransferredValue A value split from its transfer list, ready to post.
WorkerCallContext The context of one call, passed to a handler as this.
WorkerCallMessage A call from the main thread.
WorkerCancelMessage A cancellation of a call from the main thread.
WorkerErrorMessage A failed call, answered by the worker.
WorkerMessagePort The port a worker talks through: the worker’s global scope, or a test double.
WorkerResultMessage A successful call, answered by the worker.
Function Description
exposeWorkerApi Exposes handlers to the main thread. Call it once, at the top level of a worker entry point. A handler that throws or rejects answers with a SerializedWorkerError, which the caller receives as a WorkerCallError. An unknown method answers with an error too, so a caller never waits for nothing.
invokeWorkerHandler Calls one handler by name, as the worker does. WorkerComponent uses it for its main-thread fallback, so both paths behave alike.
isTransferredValue Tells whether a value is a TransferredValue.
isWorkerRequestMessage Tells whether a message is a request of this protocol.
isWorkerResponseMessage Tells whether a message is a response of this protocol.
serializeWorkerError Reduces a thrown value to plain data.
unwrapTransferredValue Splits a result into the value to post and the objects to transfer.
withTransfer Marks a result to transfer some of its objects (an ArrayBuffer, a MessagePort, an OffscreenCanvas…) instead of copying them. A transferred object is unusable on the sending side afterwards.
Type Description
WorkerApi An API a worker exposes: an object whose every member is a function.
WorkerApiHandlers The handlers implementing a WorkerApi, with the WorkerCallContext as this. Each handler takes the method’s arguments and returns its result, or a promise of it, or the result wrapped by withTransfer to transfer buffers back instead of copying them. Declare the handlers as methods or function expressions, not arrow functions, when they need this.
WorkerHandlerResult What a handler may return.
WorkerRequestMessage Any message sent to the worker.
WorkerResponseMessage Any message sent by the worker.
Variable Description
WORKER_PROTOCOL The tag every message of this protocol carries. Messages without it are ignored on both sides, so a worker can exchange its own messages too.