@capacities/courier

Type-safe RPC for Web Workers over MessagePort.

Courier gives you a type-safe RPC layer between a host and one or more workers. You define the message contract once in TypeScript; emit, on and bind stay fully typed on both sides.

Built at Capacities and used in our own codebase.

Why Courier?

• End-to-end TypeScript - define your contract once; emit, on and handler arguments/returns are checked on host and every worker.
• Direct worker-to-worker calls - the host builds a full mesh of MessageChannels, so any participant can call any other without relaying through the main thread.
• Production-ready protocol - initialization handshake, optional heartbeat, per-event timeouts and disconnect handling are built in.
• Request middleware - intercept lets you gate, log, or reject incoming RPCs before they hit your handlers.
• Chrome DevTools profiling - isProfiling records round-trip measurements with handler vs messaging breakdown. See Profiling.

With three participants, a worker can call another worker directly:

type Definition = {
  main: {
    onSaved: (id: string) => void
  }
  processing: {
    ingest: (raw: string) => { id: string; title: string; tokens: string[] }
  }
  database: {
    save: (record: { id: string; title: string; tokens: string[] }) => void
    get: (id: string) => { id: string; title: string; tokens: string[] } | null
  }
}

// Inside the processing worker - no need to bounce through main
const ipc = await courier.worker<Definition, 'processing'>('processing', self)

ipc.on('ingest', async (raw) => {
  const record = {
    id: crypto.randomUUID(),
    title: raw.split('\n')[0] ?? '',
    tokens: raw.toLowerCase().split(/\s+/),
  }

  await ipc.emit('database', 'save', record)
  await ipc.emit('main', 'onSaved', record.id)

  return record
})

Comparison

| | Courier | Comlink | threads.js | Raw postMessage | | ----------------------------- | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- | --------------------- | | Model | Named participants, shared contract | Proxy over an exposed object | Thread pool for parallel tasks | Ad-hoc messages | | API | emit(target, event, …) / on(event, handler) | Comlink.wrap(endpoint).method() | pool.queue(fn) | Custom protocol | | Typing | ✅ One Definition types every participant's emit/on | ✅ Remote<T> from wrap<T>()¹ | ✅ via spawn<T>()¹ | ❌ | | Worker-to-worker | ✅ Mesh wired by courier.host | ⚠️ Works over MessagePort; channels are DIY | ❌ Not the focus | ⚠️ DIY | | Multi-worker setup | ✅ courier.host connects all ports | ⚠️ One wrap() per endpoint | ✅ Worker pool | ⚠️ DIY | | Handshake & heartbeat | ✅ Built-in | ❌ | ❌ | ❌ | | RPC timeouts & disconnect | ✅ Built-in | ❌ | ❌ | ❌ | | Per-RPC DevTools tracks | ✅ Optional isProfiling (handler vs messaging split)² | ❌ No built-in instrumentation | ❌ No built-in instrumentation | ❌ | | Transferables / callbacks | 🔜 Planned | ✅ Comlink.transfer, Comlink.proxy | ✅ Via Comlink | ⚠️ Manual |

¹ Comlink and threads.js both provide real generic typing (Remote<T>, typed spawn). The gap vs Courier is mostly shape: Courier's single Definition schema types named participants and cross-worker routes together; Comlink/threads.js type the exposed API surface, with occasional as unknown as at the edges.

² Chrome can profile any worker natively (chrome://inspect). This row is about library-level performance.measure() tracks per RPC, not whether profiling is possible at all.

✅ Built-in · ⚠️ Possible, not provided · ❌ Not provided · 🔜 Planned

Install

npm install @capacities/courier

Quick start

Define a definition - a map of participant names to their exposed handlers:

type Definition = {
  main: {
    onResult: (value: number) => void
  }
  worker: {
    compute: (a: number, b: number) => number
  }
}

Host

import { courier } from '@capacities/courier'

const ipc = courier.host<Definition, 'main'>('main', {
  worker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }),
})

ipc.on('onResult', (value) => {
  console.log('result:', value)
})

const sum = await ipc.emit('worker', 'compute', 2, 3)
console.log(sum) // 5

Worker

import { courier } from '@capacities/courier'

const ipc = await courier.worker<Definition, 'worker'>('worker', self)

ipc.on('compute', (a, b) => a + b)

await ipc.emit('main', 'onResult', 42)

Courier handles the handshake: the host spins up MessageChannels between all participants, transfers ports, waits for initialization, then signals readiness.

API

courier.host(self, workers, options?)

Creates the host-side IPC interface. workers maps each worker name to a factory that returns a Worker (or mock).

Returns an Courier.IPC instance synchronously. Workers are terminated when close() is called.

courier.worker(self, scope, options?)

Bootstraps a worker. Pass self (the global WorkerGlobalScope in a real worker).

Returns a Promise<Courier.IPC> that resolves once the host signals readiness.

courier.ipc({ self, ports, ready }, options)

Low-level setup when you manage MessagePorts yourself.

courier.mock(self, callback, options?)

Creates an in-memory host/worker pair for tests - no real Worker thread needed.

import { courier } from '@capacities/courier'

const mock = courier.mock<Definition, 'worker'>('worker', (ipc) => {
  ipc.on('compute', (a, b) => a + b)
})

const host = courier.host<Definition, 'main'>('main', {
  worker: () => mock,
})

await host.emit('worker', 'compute', 3, 9) // 12

IPC interface

Each side exposes:

| Method | Description | | ------------------------------ | --------------------------------------------------------------------------- | | emit(target, event, ...args) | Call a handler on another participant. Returns a Promise with the result. | | on(event, callback) | Register a handler for incoming requests. Returns an unsubscribe function. | | once(event, callback) | Same as on, but runs at most once. | | bind(handlers) | Register multiple handlers at once. | | close() | Tear down listeners and ports. | | self | This participant's name. |

Handlers may be sync or async - return values and thrown errors are propagated back to the caller.

Options

Pass partial options to override defaults from Courier.DEFAULTS (host, worker and low-level ipc each accept a slightly different subset):

courier.host(
  'main',
  { worker: () => new Worker('./worker.js') },
  {
    timeouts: {
      // (Host only) Max time to wait for every worker to finish the initialize handshake.
      initialization: 5_000,

      // Max time an `intercept` callback may run before the request is rejected.
      intercept: 5_000,

      // Max time an `emit` may take before its promise rejects.
      // Use a number for one global limit, or an object for per-target/per-event overrides.
      events: Infinity,
    },

    // Optional liveness checks. Sends periodic pings; marks a target dead after too many misses.
    heartbeat: {
      interval: 1_000, // How often to ping each target (ms).
      timeout: 500, // How long to wait for a pong before counting a miss (ms).
      threshold: 3, // Consecutive misses before `onDead` runs and the target is closed.
      isPaused: () => document.hidden, // When true, pauses probes and resets miss counters.
      targets: ['worker'], // Which peers to monitor. Defaults to all connected targets.
      onDead: (target) => console.warn(`${target} is unresponsive`),
    },

    // Middleware invoked on incoming requests before they reach your handler.
    // Call `proceed()` to continue or `reject(reason)` to fail the request.
    // Set to `null` (default) to disable.
    intercept: (event, parameters, { proceed, reject }) => {
      proceed()
    },

    // Called when a participant disconnects or is closed (including after heartbeat failure).
    onClose: (target) => console.warn(`${target} disconnected`),

    // Log internal warnings (handshake failures, port errors, heartbeat issues, etc.).
    isVerbose: false,

    // (Host only) Record `performance.measure()` entries for Chrome DevTools. See Profiling below.
    isProfiling: false,
  }
)

Worker options are the same except there is no timeouts.initialization and isProfiling / isVerbose are inherited from the host during handshake rather than set on the worker directly.

bind(handlers, { isOnce: true }) accepts a listen option to auto-unsubscribe after the first matching request.

Profiling

Courier has built-in support for the Performance API and Chrome DevTools custom tracks. Enable it on the host - the setting is forwarded to every worker during handshake:

const ipc = courier.host<Definition, 'main'>(
  'main',
  { worker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }) },
  { isProfiling: true }
)

Every emit then records a performance.measure() entry that shows up in the Chrome Performance panel.

Typical workflow:

1. Set isProfiling: true in development (keep it off in production).
2. Open Chrome DevTools → Performance.
3. Record a session while your app runs worker RPCs.
4. Look for the Courier track group - each bar is one typed emit, hover for the computation/communication breakdown.

Requirements

• Browser - relies on Worker, MessageChannel and MessagePort
• ESM - this package ships as ES modules only

Development

pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm build

License

MIT © Capacities Labs GmbH