skills/plugins/document-navigator/docs/api-stack/api/api-events-worker-proxy/README.md

@suaveplan/api-events-worker-proxy - Worker-tier proxy over a main-process @suaveplan/events EventBus. The main side calls createEventBusProxyServer(port, bus) to expose the bus over a MessagePort via @suaveplan/api-worker-rpc; worker-tier plugins call createEventBusProxyClient(port) to obtain an EventBus-shaped surface that marshals on/once/off/emit/emitAsync across the port. Subscriptions become long-lived stream-* frames that deliver one stream-chunk per main-side event. Zod-validated payload codec rejects non-structured-clone-safe payloads with EVENTS_PROXY.UNSERIALISABLE_PAYLOAD.

Worker-tier proxy over a main-process @suaveplan/events EventBus.

The host (main process) owns one EventBus<TMap> instance. Worker-tier plugins want to publish to and subscribe from the same bus without running the bus in every worker. This package marshals every on / once / off / emit / emitAsync call across a MessagePort via @suaveplan/api-worker-rpc, so worker-tier plugin code compiles unchanged against an EventBus-shaped proxy surface.

This is an adapter, not a new contract — the design doc (§5.2a) is explicit that no abstract api-events contract package exists. The host injects @suaveplan/events directly; this package is the worker-side surface over that existing bus.

Documentation tree

• error-codes — Defines the stable string registry of EVENTS_PROXY.* error codes raised by every failure path in `@suaveplan/api-even…
  • error-codes — Defines the stable string registry of EVENTS_PROXY.* error codes raised by every failure path in `@suaveplan/api-even…
• main-side — Mounts a main-process @suaveplan/events EventBus on a MessagePort via the @suaveplan/api-worker-rpc server so w…
  • main-side — Mounts a main-process @suaveplan/events EventBus on a MessagePort via the @suaveplan/api-worker-rpc server so w…
• payload-codec — Encodes and decodes the wire envelope used to ship a single event from the main-process EventBus across a `MessagePor…
  • payload-codec — Encodes and decodes the wire envelope used to ship a single event from the main-process EventBus across a `MessagePor…
• testing — Re-usable test fixtures for @suaveplan/api-events-worker-proxy. Builds a real EventBus, a real Node.js `MessageChan…
  • testing — Re-usable test fixtures for @suaveplan/api-events-worker-proxy. Builds a real EventBus, a real Node.js `MessageChan…
• worker-side — Builds a worker-side proxy that exposes an EventBus-shaped surface backed by a PortLike connected to a main-process…
  • worker-side — Builds a worker-side proxy that exposes an EventBus-shaped surface backed by a PortLike connected to a main-process…

Install

bun add @suaveplan/api-events-worker-proxy

Main-side (host)

import { EventBus } from "@suaveplan/events";
import { createEventBusProxyServer } from "@suaveplan/api-events-worker-proxy/main-side";
import { createInProcessPortPair } from "@suaveplan/api-worker-rpc";

const bus = new EventBus<{ "billing.invoice.created": { id: string } }>();
const { clientPort, serverPort, close } = createInProcessPortPair();
const server = createEventBusProxyServer(serverPort, bus);
// Hand `clientPort` to a worker; tear down with `server.dispose()` + close().

Worker-side

import { createEventBusProxyClient } from "@suaveplan/api-events-worker-proxy/worker-side";

type Map = { "billing.invoice.created": { id: string } };
const events = createEventBusProxyClient<Map>(port);
events.on("billing.invoice.created", ({ id }) => console.log("got", id));
const result = await events.emitAsync("billing.invoice.created", {
    id: "i_1",
});
console.log(result.delivered);

Exports

• ./main-side — createEventBusProxyServer(port, bus).
• ./worker-side — createEventBusProxyClient(port).
• ./payload-codec — Zod schema + structured-clone probe.
• ./error-codes — EVENTS_PROXY.* codes + EventsProxyError.
• ./testing — createProxyPair + waitFor for downstream tests.

Error codes

• EVENTS_PROXY.UNSERIALISABLE_PAYLOAD — payload failed the structured-clone safety probe (functions, class instances, cycles).
• EVENTS_PROXY.SUBSCRIPTION_DROPPED — subscription terminated unexpectedly (server disposed, port closed mid-stream).
• EVENTS_PROXY.BACKPRESSURE_EXCEEDED — worker-side queue exceeded the configured high-water mark.
• EVENTS_PROXY.PROXY_DISPOSED — method called after dispose().

Docs

• main-side
• worker-side
• payload-codec
• error-codes
• testing