# @suaveplan/web-workers - Enterprise browser-tier Web Worker / SharedWorker / worker-pool runtime: typed RPC with AbortSignal + transfer-list + backpressure + circuit breaker + streaming, FIFO + round-robin / least-busy schedulers, restart-on-crash supervision, EventBus lifecycle emission, OTel observability, typed WEB_WORKERS.* error registry, defineWorker() helper.

Enterprise browser-tier runtime for managing Web Workers, SharedWorkers, and
fixed-size worker pools with typed RPC, AbortSignal-aware cancellation,
transfer-list zero-copy handoff, pending-request backpressure, per-worker
circuit breakers, streaming RPC, FIFO + round-robin / least-busy scheduling,
restart-on-crash supervision, EventBus lifecycle emission, and a
`createWebWorkersObservability()` OpenTelemetry bundle. Typed errors live
under the `WEB_WORKERS.*` registry.

<!-- begin:auto-docs -->
## Documentation tree

- [base-manager](./src/base-manager/base-manager.md) — `base-manager.ts` declares `BaseWorkerManager<TTransport>`, the abstract class that hosts everything shared between the…
  - [base-manager](./src/base-manager/base-manager.md) — `base-manager.ts` declares `BaseWorkerManager<TTransport>`, the abstract class that hosts everything shared between the…
  - [helpers](./src/base-manager/helpers.md) — `helpers.ts` co-locates the small utilities the base manager and the message bus both depend on: a default wall-clock i…
- [circuit-breaker](./src/circuit-breaker/circuit-breaker.md) — `circuit-breaker.ts` exposes `CircuitBreaker`, a per-worker failure- isolating state machine the base manager uses to s…
  - [circuit-breaker](./src/circuit-breaker/circuit-breaker.md) — `circuit-breaker.ts` exposes `CircuitBreaker`, a per-worker failure- isolating state machine the base manager uses to s…
- [errors](./src/errors/errors.md) — `errors.ts` declares the stable error-code registry, typed error class, and metadata table for `@suaveplan/web-workers`…
  - [errors](./src/errors/errors.md) — `errors.ts` declares the stable error-code registry, typed error class, and metadata table for `@suaveplan/web-workers`…
- [helpers](./src/helpers/define-worker.md) — `define-worker.ts` exposes `defineWorker()`, a small helper that wraps the canonical `new Worker(url, { type })` patter…
  - [define-worker](./src/helpers/define-worker.md) — `define-worker.ts` exposes `defineWorker()`, a small helper that wraps the canonical `new Worker(url, { type })` patter…
- [message-bus](./src/message-bus/message-bus.md) — `message-bus.ts` declares `MessageBus`, an in-process publish/subscribe + request/response message bus. It's the right…
  - [message-bus](./src/message-bus/message-bus.md) — `message-bus.ts` declares `MessageBus`, an in-process publish/subscribe + request/response message bus. It's the right…
- [observability](./src/observability/observability.md) — `observability.ts` exposes `createWebWorkersObservability()`, the factory that builds the OpenTelemetry counter + histo…
  - [observability](./src/observability/observability.md) — `observability.ts` exposes `createWebWorkersObservability()`, the factory that builds the OpenTelemetry counter + histo…
- [shared-worker-manager](./src/shared-worker-manager/shared-worker-manager.md) — `shared-worker-manager.ts` declares `SharedWorkerManager`, the concrete SharedWorker manager. It extends `BaseWorkerMan…
  - [shared-worker-manager](./src/shared-worker-manager/shared-worker-manager.md) — `shared-worker-manager.ts` declares `SharedWorkerManager`, the concrete SharedWorker manager. It extends `BaseWorkerMan…
- [streaming](./src/streaming/stream.md) — `stream.ts` exposes `sendStream`, a streaming RPC primitive that returns an `AsyncIterable<TChunk>` driven by frames th…
  - [stream](./src/streaming/stream.md) — `stream.ts` exposes `sendStream`, a streaming RPC primitive that returns an `AsyncIterable<TChunk>` driven by frames th…
- [worker-manager](./src/worker-manager/worker-manager.md) — `worker-manager.ts` declares `WorkerManager`, the concrete classic-`Worker` manager. It extends `BaseWorkerManager<Work…
  - [worker-manager](./src/worker-manager/worker-manager.md) — `worker-manager.ts` declares `WorkerManager`, the concrete classic-`Worker` manager. It extends `BaseWorkerManager<Work…
- [worker-pool](./src/worker-pool/worker-pool.md) — `worker-pool.ts` declares `WorkerPool`, the fixed-size pool that fans incoming tasks across multiple `Worker` slots wit…
  - [internals](./src/worker-pool/internals.md) — `internals.ts` holds the small internal types and helpers `worker-pool.ts` needs but that don't make sense to surface i…
  - [scheduler](./src/worker-pool/scheduler.md) — `scheduler.ts` exposes `pickSlot`, the pure function `WorkerPool` calls to decide which slot receives the next submit.…
  - [worker-pool](./src/worker-pool/worker-pool.md) — `worker-pool.ts` declares `WorkerPool`, the fixed-size pool that fans incoming tasks across multiple `Worker` slots wit…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/web-workers
```

## Quick start

```ts
import { defineWorker, WorkerManager } from "@suaveplan/web-workers";

const factory = defineWorker({
    url: new URL("./my-worker.ts", import.meta.url),
    type: "module",
});

const manager = new WorkerManager({ factory });
manager.create({ name: "hash", url: "ignored-by-factory" });

const digest = await manager.sendRequest<string, string>(
    "hash",
    "sha256",
    "hello world"
);
manager.terminateAll();
```

## Modules

- [`./src/errors/errors.md`](./src/errors/errors.md) — `WEB_WORKERS_CODES`,
  `WebWorkersError`, metadata table, `asWebWorkersError`.
- [`./src/types/web-workers.types.md`](./src/types/web-workers.types.md) —
  zero-runtime public type surface.
- [`./src/observability/observability.md`](./src/observability/observability.md)
  — `createWebWorkersObservability()` OpenTelemetry counters + histograms.
- [`./src/base-manager/base-manager.md`](./src/base-manager/base-manager.md)
  — shared lifecycle / RPC state for the two concrete managers.
- [`./src/base-manager/helpers.md`](./src/base-manager/helpers.md) — clock,
  id-generator, transfer-list validation, abort-signal wiring helpers.
- [`./src/worker-manager/worker-manager.md`](./src/worker-manager/worker-manager.md)
  — classic `Worker` manager.
- [`./src/shared-worker-manager/shared-worker-manager.md`](./src/shared-worker-manager/shared-worker-manager.md)
  — `SharedWorker` manager.
- [`./src/worker-pool/worker-pool.md`](./src/worker-pool/worker-pool.md) —
  fixed-size pool with FIFO queue + restart-on-crash + health probe.
- [`./src/worker-pool/scheduler.md`](./src/worker-pool/scheduler.md) —
  round-robin / least-busy slot picker.
- [`./src/worker-pool/internals.md`](./src/worker-pool/internals.md) —
  internal slot / queued-task types for the pool.
- [`./src/message-bus/message-bus.md`](./src/message-bus/message-bus.md) —
  in-process pub/sub + request/response bus.
- [`./src/streaming/stream.md`](./src/streaming/stream.md) — `sendStream`
  async-iterable streaming RPC.
- [`./src/circuit-breaker/circuit-breaker.md`](./src/circuit-breaker/circuit-breaker.md)
  — per-worker failure-isolating breaker.
- [`./src/helpers/define-worker.md`](./src/helpers/define-worker.md) —
  canonical Vite/Webpack worker-bundle factory.