@evolu/common 7.4.1 → 8.0.0-next.1

package/dist/src/Worker.d.ts

@@ -1,67 +1,252 @@
-import { TransferableError } from "./Error.js";
-/** Cross-platform worker abstraction. */
-export interface Worker<Input, Output> {
-    /** Sends a message to the worker. */
-    readonly postMessage: (message: Input) => void;
-    /** Sets a callback for messages from the worker. */
-    readonly onMessage: (callback: (message: Output) => void) => void;
+/**
+ * Platform-agnostic Worker abstractions.
+ *
+ * @module
+ */
+import type { Brand } from "./Brand.js";
+import type { ConsoleDep, ConsoleStoreOutputEntryDep } from "./Console.js";
+/**
+ * Platform-agnostic Worker.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Worker
+ */
+export interface Worker<Input, Output = never> extends MessagePort<Input, Output> {
+}
+/**
+ * Platform-agnostic SharedWorker.
+ *
+ * A shared worker is shared across multiple clients (tabs, windows, iframes)
+ * and provides a port for bidirectional communication with each client.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker
+ */
+export interface SharedWorker<Input, Output = never> extends Disposable {
+    /** Port for communicating with the shared worker. */
+    readonly port: MessagePort<Input, Output>;
 }
-export interface WorkerPostMessageDep<Output> {
-    readonly postMessage: (message: Output) => void;
+/**
+ * Platform-agnostic MessagePort.
+ *
+ * Note: There is no reliable way to detect when a port is closed or
+ * disconnected. Calling `postMessage` on a disposed port does not throw — it
+ * silently fails. To detect dead ports, use a heartbeat pattern where the other
+ * end periodically sends "alive" messages and stale ports are pruned after a
+ * timeout.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
+ */
+export interface MessagePort<Input, Output = never> extends Disposable {
+    readonly postMessage: (message: Input, transfer?: ReadonlyArray<Transferable>) => void;
+    /**
+     * Handler for incoming messages. Messages are queued until this is assigned,
+     * matching native `MessagePort` behavior where setting `onmessage` implicitly
+     * calls `start()`. This enables safe async initialization — the sender can
+     * post messages immediately while the receiver sets up.
+     */
+    onMessage: ((message: Output) => void) | null;
+    /**
+     * The native underlying port for transferring via `postMessage`.
+     *
+     * ### Example
+     *
+     * ```ts
+     * sharedWorker.port.postMessage(
+     *   { type: "InitConsole", port: consoleChannel.port1.native },
+     *   [consoleChannel.port1.native],
+     * );
+     * ```
+     */
+    readonly native: NativeMessagePort<Input, Output>;
 }
 /**
- * Error reporting wrapper that catches synchronous errors in handlers and
- * converts them to transferable error messages sent to the main thread.
- */
-export type WithErrorReporting = <A extends Array<any>>(handler: (...args: A) => void) => (...args: A) => void;
-type HasInit<Input> = Extract<Input, {
-    type: "init";
-}> extends never ? ["Input must contain a variant with { type: 'init' }"] : unknown;
-type HasWorkerErrorOutput<T> = Extract<T, {
-    type: "onError";
-}> extends infer E ? [E] extends [never] ? [
-    "Output must contain { type: 'onError'; error: TransferableError | ... }"
-] : E extends {
-    error: infer Err;
-} ? TransferableError extends Err ? unknown : ["Output.onError.error must include TransferableError"] : ["Output.onError must have an error property"] : never;
-/**
- * Creates a {@link Worker} that supports initialization with dependencies and
- * safe error handling.
- */
-export declare const createInitializedWorker: <Input extends {
-    readonly type: string;
-} & HasInit<Input>, Output extends {
-    readonly type: string;
-} & HasWorkerErrorOutput<Output>, Deps>({ init, onMessage, }: {
-    readonly init: (initMessage: Extract<Input, {
-        type: "init";
-    }>, postMessage: (msg: Output) => void, withErrorReporting: WithErrorReporting) => Promise<Deps | null>;
-    readonly onMessage: (deps: Deps) => (message: Exclude<Input, {
-        type: "init";
-    }>) => void;
-}) => Worker<Input, Output>;
-/** Type helper to extract message types from a union type */
-export type MessageHandlers<Input extends {
-    readonly type: string;
-}, Deps> = {
-    readonly [K in Input["type"]]: (deps: Deps) => (message: Extract<Input, {
-        type: K;
-    }>) => void;
+ * Objects whose ownership can be transferred between threads via `postMessage`.
+ *
+ * Intentionally scoped to types Evolu uses. The web platform defines additional
+ * transferable types (`ImageBitmap`, `OffscreenCanvas`, `ReadableStream`, etc.)
+ * that can be added here if needed.
+ */
+export type Transferable = NativeMessagePort<any, any> | ArrayBuffer;
+/**
+ * Opaque type for platform-specific native MessagePort.
+ *
+ * Exists because `postMessage` transfer requires the native object itself, not
+ * a wrapper. Ensures type-safe wiring between {@link MessagePort.native} and
+ * {@link CreateMessagePort} without exposing platform details.
+ */
+export type NativeMessagePort<Input = unknown, Output = never> = Brand<"NativeMessagePort"> & {
+    readonly [nativeMessagePortInput]?: Input;
+    readonly [nativeMessagePortOutput]?: Output;
 };
+declare const nativeMessagePortInput: unique symbol;
+declare const nativeMessagePortOutput: unique symbol;
+/** Factory function to create a {@link MessagePort} from a native port. */
+export type CreateMessagePort = <Input, Output = never>(nativePort: NativeMessagePort<Input, Output>) => MessagePort<Input, Output>;
+export interface CreateMessagePortDep {
+    readonly createMessagePort: CreateMessagePort;
+}
+/** Common dependencies for worker entry points. */
+export type WorkerDeps = ConsoleDep & ConsoleStoreOutputEntryDep & CreateMessagePortDep;
+/**
+ * Platform-agnostic MessageChannel.
+ *
+ * Creates two entangled ports: keep one and transfer the other (e.g., to a
+ * SharedWorker via `postMessage` with `transfer`). Messages sent to one port
+ * are received by the other.
+ *
+ * Messages are queued until `onMessage` is assigned, enabling safe async
+ * initialization. The sender can post messages immediately while the receiver
+ * performs async setup — no manual buffering required.
+ *
+ * For one-way communication, omit `Output` (defaults to `never`).
+ *
+ * ### Example
+ *
+ * Transfer a channel port to a SharedWorker for async initialization:
+ *
+ * ```ts
+ * // Main thread: create channel, transfer port1, use port2 immediately.
+ * const channel = createMessageChannel<EvoluRequest, EvoluResponse>();
+ *
+ * sharedWorker.port.postMessage(
+ *   { type: "CreateEvolu", port: channel.port1.native },
+ *   [channel.port1.native],
+ * );
+ *
+ * // Safe to send immediately — messages queue until worker is ready.
+ * channel.port2.postMessage({ type: "Query", query });
+ * channel.port2.onMessage = (response) => {
+ *   handleResponse(response);
+ * };
+ * ```
+ *
+ * ```ts
+ * // Worker: receive the port, do async init, then start listening.
+ * const evoluPort = createMessagePort<EvoluResponse, EvoluRequest>(
+ *   message.port,
+ * );
+ * await openDatabase(name);
+ * evoluPort.onMessage = (request) => {
+ *   handleRequest(request);
+ * };
+ * // Queued messages are now delivered in order.
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
+ */
+export interface MessageChannel<Input, Output = never> extends Disposable {
+    /** The first port of the channel. */
+    readonly port1: MessagePort<Input, Output>;
+    /** The second port of the channel. */
+    readonly port2: MessagePort<Output, Input>;
+}
+/** Factory function to create a {@link MessageChannel}. */
+export type CreateMessageChannel = <Input, Output = never>() => MessageChannel<Input, Output>;
+export interface CreateMessageChannelDep {
+    readonly createMessageChannel: CreateMessageChannel;
+}
+/**
+ * Typed `self` for code running inside a dedicated worker.
+ *
+ * This is the worker-side counterpart to {@link Worker} — a typed
+ * {@link MessagePort} that wraps `self` inside the worker.
+ */
+export interface WorkerSelf<Input, Output = never> extends MessagePort<Output, Input> {
+}
+/**
+ * Typed `self` for code running inside a shared worker.
+ *
+ * This is the worker-side counterpart to {@link SharedWorker}. It wraps `self`
+ * inside the shared worker, providing typed `onConnect` callbacks.
+ */
+export interface SharedWorkerSelf<Input, Output = never> extends Disposable {
+    onConnect: ((port: MessagePort<Output, Input>) => void) | null;
+}
 /**
- * Creates a {@link Worker} with type-safe message handlers for each message
- * type. This provides better type safety and organization compared to a single
- * onMessage handler.
- */
-export declare const createInitializedWorkerWithHandlers: <Input extends {
-    readonly type: string;
-} & HasInit<Input>, Output extends {
-    readonly type: string;
-} & HasWorkerErrorOutput<Output>, Deps>({ init, handlers, }: {
-    readonly init: (initMessage: Extract<Input, {
-        type: "init";
-    }>, postMessage: (msg: Output) => void, withErrorReporting: WithErrorReporting) => Promise<Deps | null>;
-    readonly handlers: Omit<MessageHandlers<Input, Deps>, "init">;
-}) => Worker<Input, Output>;
+ * Creates an in-memory {@link Worker}.
+ *
+ * This is a memory-only fallback for platforms without native worker support.
+ * Message delivery is asynchronous in-process.
+ */
+export declare const createWorker: <Input, Output = never>(initWorker: (self: WorkerSelf<Input, Output>) => void) => Worker<Input, Output>;
+/**
+ * Creates an in-memory {@link SharedWorker}.
+ *
+ * This is a memory-only fallback for platforms without native SharedWorker
+ * support. Connection is synchronous while message delivery is asynchronous
+ * in-process.
+ *
+ * Intended usage is one shared worker instance per process/app runtime.
+ */
+export declare const createSharedWorker: <Input, Output = never>(initWorker: (self: SharedWorkerSelf<Input, Output>) => void) => SharedWorker<Input, Output>;
+/**
+ * Creates an in-memory {@link MessageChannel}.
+ *
+ * This is a memory-only fallback for platforms without native MessageChannel
+ * support. Message delivery is asynchronous in-process.
+ */
+export declare const createMessageChannel: CreateMessageChannel;
+/**
+ * Creates an in-memory {@link MessagePort} from a native token.
+ *
+ * This is a memory-only fallback for platforms without native MessagePort
+ * support. Message delivery through returned ports is asynchronous in-process.
+ */
+export declare const createMessagePort: CreateMessagePort;
+/**
+ * Test {@link Worker} with access to its paired worker-side `self`.
+ *
+ * Use `self` to simulate messages and behavior from inside the worker.
+ */
+export interface TestWorker<Input, Output = never> extends Worker<Input, Output> {
+    /** Typed `self` counterpart for worker-side testing assertions. */
+    readonly self: WorkerSelf<Input, Output>;
+}
+/**
+ * Test {@link SharedWorker} with direct access to `self` and `connect`.
+ *
+ * Call `connect()` to simulate a client connection and trigger
+ * `self.onConnect`.
+ */
+export interface TestSharedWorker<Input, Output = never> extends SharedWorker<Input, Output> {
+    readonly self: SharedWorkerSelf<Input, Output>;
+    readonly connect: () => void;
+}
+/** {@link MessageChannel} with disposal tracking for testing. */
+export interface TestMessageChannel<Input, Output = never> extends MessageChannel<Input, Output> {
+    readonly isDisposed: () => boolean;
+}
+/**
+ * Creates a connected {@link TestWorker} for testing.
+ *
+ * The returned worker includes its typed {@link TestWorker.self} counterpart, so
+ * tests can exercise dedicated worker communication without a real thread.
+ */
+export declare const testCreateWorker: <Input, Output = never>() => TestWorker<Input, Output>;
+/**
+ * Creates a connected {@link TestSharedWorker} for testing.
+ *
+ * The returned worker includes `self` and `connect` so tests can exercise the
+ * full worker ↔ client pipeline without a real worker thread.
+ */
+export declare const testCreateSharedWorker: <Input, Output = never>() => TestSharedWorker<Input, Output>;
+/**
+ * Creates an in-memory {@link MessageChannel} for testing.
+ *
+ * Messages are queued until `onMessage` is assigned, matching the browser
+ * MessagePort behavior where the port message queue starts disabled.
+ *
+ * Both ports are registered in the native port registry so
+ * {@link testCreateMessagePort} can look them up by their native token.
+ */
+export declare const testCreateMessageChannel: <Input, Output = never>() => TestMessageChannel<Input, Output>;
+/** Creates an in-memory {@link CreateMessagePort} for testing. */
+export declare const testCreateMessagePort: CreateMessagePort;
+/**
+ * Waits long enough for multi-hop in-memory worker message delivery in tests.
+ *
+ * Some flows require several queued macrotasks across worker/message-port
+ * boundaries; this helper advances that pipeline deterministically.
+ */
+export declare const testWaitForWorkerMessage: () => Promise<void>;
 export {};
 //# sourceMappingURL=Worker.d.ts.map

package/dist/src/Worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../src/Worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../src/Worker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAG3E;;;;GAIG;AACH,MAAM,WAAW,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,WAAW,CAChE,KAAK,EACL,MAAM,CACP;CAAG;AAEJ;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,UAAU;IACrE,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,UAAU;IACpE,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,KAAK,EACd,QAAQ,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,KACnC,IAAI,CAAC;IAEV;;;;;OAKG;IACH,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAE9C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CACnD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAC3B,KAAK,GAAG,OAAO,EACf,MAAM,GAAG,KAAK,IACZ,KAAK,CAAC,mBAAmB,CAAC,GAAG;IAC/B,QAAQ,CAAC,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC;IAC1C,QAAQ,CAAC,CAAC,uBAAuB,CAAC,CAAC,EAAE,MAAM,CAAC;CAC7C,CAAC;AAEF,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AACpD,OAAO,CAAC,MAAM,uBAAuB,EAAE,OAAO,MAAM,CAAC;AAErD,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EACpD,UAAU,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,KACzC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,UAAU,GACjC,0BAA0B,GAC1B,oBAAoB,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,UAAU;IACvE,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAE3C,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC5C;AAED,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,OAAO,cAAc,CAC5E,KAAK,EACL,MAAM,CACP,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;CACrD;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,WAAW,CACpE,MAAM,EACN,KAAK,CACN;CAAG;AAEJ;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,UAAU;IACzE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAChE;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,EAAE,MAAM,GAAG,KAAK,EAChD,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KACpD,MAAM,CAAC,KAAK,EAAE,MAAM,CAItB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,EAAE,MAAM,GAAG,KAAK,EACtD,YAAY,CAAC,IAAI,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,CAU5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAM/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,MAAM,CAC/D,KAAK,EACL,MAAM,CACP;IACC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,YAAY,CAC3E,KAAK,EACL,MAAM,CACP;IACC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB,CACjC,KAAK,EACL,MAAM,GAAG,KAAK,CACd,SAAQ,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC;CACpC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,EAAE,MAAM,GAAG,KAAK,OAAK,UAAU,CACnE,KAAK,EACL,MAAM,CASP,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,EACL,MAAM,GAAG,KAAK,OACX,gBAAgB,CAAC,KAAK,EAAE,MAAM,CASlC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACnC,KAAK,EACL,MAAM,GAAG,KAAK,OACX,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAcpC,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,EAAE,iBAE0B,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CAG7D,CAAC"}

package/dist/src/Worker.js

@@ -1,79 +1,235 @@
+/**
+ * Platform-agnostic Worker abstractions.
+ *
+ * @module
+ */
 import { assert } from "./Assert.js";
-import { createTransferableError } from "./Error.js";
+import { testWaitForMacrotask } from "./Test.js";
+/**
+ * Creates an in-memory {@link Worker}.
+ *
+ * This is a memory-only fallback for platforms without native worker support.
+ * Message delivery is asynchronous in-process.
+ */
+export const createWorker = (initWorker) => {
+    const { worker, self } = createMemoryWorkerPair();
+    initWorker(self);
+    return worker;
+};
+/**
+ * Creates an in-memory {@link SharedWorker}.
+ *
+ * This is a memory-only fallback for platforms without native SharedWorker
+ * support. Connection is synchronous while message delivery is asynchronous
+ * in-process.
+ *
+ * Intended usage is one shared worker instance per process/app runtime.
+ */
+export const createSharedWorker = (initWorker) => {
+    const { worker, self, connect } = createMemorySharedWorkerPair();
+    initWorker(self);
+    connect();
+    return worker;
+};
+/**
+ * Creates an in-memory {@link MessageChannel}.
+ *
+ * This is a memory-only fallback for platforms without native MessageChannel
+ * support. Message delivery is asynchronous in-process.
+ */
+export const createMessageChannel = () => {
+    const state1 = {
+        handler: null,
+        queue: [],
+        flushScheduled: false,
+    };
+    const state2 = {
+        handler: null,
+        queue: [],
+        flushScheduled: false,
+    };
+    const native1 = createNativeMessagePortToken();
+    const native2 = createNativeMessagePortToken();
+    const port1 = createTestPort(state1, state2, native1);
+    const port2 = createTestPort(state2, state1, native2);
+    nativePortRegistry.set(native1, port1);
+    nativePortRegistry.set(native2, port2);
+    return {
+        port1,
+        port2,
+        [Symbol.dispose]: () => {
+            port1[Symbol.dispose]();
+            port2[Symbol.dispose]();
+        },
+    };
+};
+/**
+ * Creates an in-memory {@link MessagePort} from a native token.
+ *
+ * This is a memory-only fallback for platforms without native MessagePort
+ * support. Message delivery through returned ports is asynchronous in-process.
+ */
+export const createMessagePort = (nativePort) => {
+    const pair = nativePortRegistry.get(nativePort);
+    assert(pair, "Unknown native port — did you transfer it?");
+    return pair;
+};
+/**
+ * Creates a connected {@link TestWorker} for testing.
+ *
+ * The returned worker includes its typed {@link TestWorker.self} counterpart, so
+ * tests can exercise dedicated worker communication without a real thread.
+ */
+export const testCreateWorker = () => {
+    let self;
+    const worker = createWorker((nextSelf) => {
+        self = nextSelf;
+    });
+    return Object.assign(worker, { self });
+};
+/**
+ * Creates a connected {@link TestSharedWorker} for testing.
+ *
+ * The returned worker includes `self` and `connect` so tests can exercise the
+ * full worker ↔ client pipeline without a real worker thread.
+ */
+export const testCreateSharedWorker = () => {
+    const { worker, self, connect } = createMemorySharedWorkerPair();
+    return Object.assign(worker, {
+        self,
+        connect,
+    });
+};
 /**
- * Creates a {@link Worker} that supports initialization with dependencies and
- * safe error handling.
+ * Creates an in-memory {@link MessageChannel} for testing.
+ *
+ * Messages are queued until `onMessage` is assigned, matching the browser
+ * MessagePort behavior where the port message queue starts disabled.
+ *
+ * Both ports are registered in the native port registry so
+ * {@link testCreateMessagePort} can look them up by their native token.
  */
-export const createInitializedWorker = ({ init, onMessage, }) => {
-    let onMessageCallback = null;
-    let deps = null;
-    const pendingMessages = [];
-    let initializing = false;
-    const postMessage = (msg) => {
-        assert(onMessageCallback != null, "The onMessage wasn't set");
-        onMessageCallback(msg);
+export const testCreateMessageChannel = () => {
+    const channel = createMessageChannel();
+    let disposed = false;
+    return {
+        port1: channel.port1,
+        port2: channel.port2,
+        isDisposed: () => disposed,
+        [Symbol.dispose]: () => {
+            disposed = true;
+            channel[Symbol.dispose]();
+        },
     };
-    const postMessageTransferableError = (error) => {
-        postMessage({
-            type: "onError",
-            error: createTransferableError(error),
-        });
+};
+/** Creates an in-memory {@link CreateMessagePort} for testing. */
+export const testCreateMessagePort = (nativePort) => createMessagePort(nativePort);
+/**
+ * Waits long enough for multi-hop in-memory worker message delivery in tests.
+ *
+ * Some flows require several queued macrotasks across worker/message-port
+ * boundaries; this helper advances that pipeline deterministically.
+ */
+export const testWaitForWorkerMessage = async () => {
+    await testWaitForMacrotask();
+    await testWaitForMacrotask();
+};
+const createMemoryWorkerPair = () => {
+    const channel = createMessageChannel();
+    const self = {
+        postMessage: channel.port2.postMessage,
+        get onMessage() {
+            return channel.port2.onMessage;
+        },
+        set onMessage(value) {
+            channel.port2.onMessage = value;
+        },
+        native: channel.port2.native,
+        [Symbol.dispose]: () => {
+            channel.port2[Symbol.dispose]();
+        },
+    };
+    const worker = {
+        postMessage: channel.port1.postMessage,
+        get onMessage() {
+            return channel.port1.onMessage;
+        },
+        set onMessage(value) {
+            channel.port1.onMessage = value;
+        },
+        native: channel.port1.native,
+        [Symbol.dispose]: () => {
+            channel[Symbol.dispose]();
+        },
     };
-    /**
-     * Wraps function to catch errors and send them to the main thread instead of
-     * crashing the worker.
-     */
-    const withErrorReporting = (handler) => (...args) => {
-        try {
-            handler(...args);
-        }
-        catch (error) {
-            postMessageTransferableError(error);
-        }
+    return { worker, self };
+};
+const createMemorySharedWorkerPair = () => {
+    const channel = createMessageChannel();
+    const self = {
+        onConnect: null,
+        [Symbol.dispose]: () => {
+            self.onConnect = null;
+        },
     };
     const worker = {
-        postMessage: (message) => {
-            if (message.type !== "init") {
-                if (!deps) {
-                    pendingMessages.push(message);
-                }
-                else {
-                    withErrorReporting(onMessage(deps))(message);
-                }
+        port: channel.port1,
+        [Symbol.dispose]: () => {
+            channel[Symbol.dispose]();
+        },
+    };
+    const connect = () => {
+        assert(self.onConnect, "onConnect must be set before receiving connections");
+        self.onConnect(channel.port2);
+    };
+    return { worker, self, connect };
+};
+const createPort = (receive, peerReceive, native) => {
+    const scheduleFlush = (state) => {
+        if (state.flushScheduled)
+            return;
+        state.flushScheduled = true;
+        // Native worker messages are task-queued; use macrotask timing.
+        setTimeout(() => {
+            state.flushScheduled = false;
+            const handler = state.handler;
+            if (!handler)
                 return;
+            for (const message of state.queue.splice(0)) {
+                handler(message);
             }
-            if (initializing)
-                return;
-            initializing = true;
-            init(message, postMessage, withErrorReporting)
-                .then((_deps) => {
-                if (_deps == null)
-                    return;
-                deps = _deps;
-                for (const message of pendingMessages) {
-                    withErrorReporting(onMessage(deps))(message);
-                }
-                pendingMessages.length = 0;
-            })
-                .catch(postMessageTransferableError);
+        }, 0);
+    };
+    return {
+        postMessage: (message) => {
+            peerReceive.queue.push(message);
+            scheduleFlush(peerReceive);
         },
-        onMessage: (callback) => {
-            onMessageCallback = callback;
+        get onMessage() {
+            return receive.handler;
+        },
+        set onMessage(fn) {
+            receive.handler = fn;
+            if (fn)
+                scheduleFlush(receive);
+        },
+        native,
+        [Symbol.dispose]: () => {
+            receive.handler = null;
+            receive.flushScheduled = false;
         },
     };
-    return worker;
 };
+const createTestPort = (receive, peerReceive, native) => createPort(receive, peerReceive, native);
+const createNativeMessagePortToken = () => ({});
 /**
- * Creates a {@link Worker} with type-safe message handlers for each message
- * type. This provides better type safety and organization compared to a single
- * onMessage handler.
+ * Registry mapping native port tokens to their in-memory port counterparts.
+ *
+ * When {@link testCreateMessageChannel} creates a pair, both ports are
+ * registered here. When {@link testCreateMessagePort} wraps a native token
+ * (received via `postMessage` transfer), it looks up the actual port.
+ *
+ * Uses `WeakMap` so entries are garbage collected when the native token is no
+ * longer referenced.
  */
-export const createInitializedWorkerWithHandlers = ({ init, handlers, }) => createInitializedWorker({
-    init,
-    onMessage: (deps) => (message) => {
-        const messageType = message.type;
-        const handler = handlers[messageType];
-        // TypeScript knows handler exists because handlers covers all non-init message types
-        handler(deps)(message);
-    },
-});
+const nativePortRegistry = new WeakMap();