skills/docs/foundation/data/web-workers

@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.

Documentation tree

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

Install

bun add @suaveplan/web-workers

Quick start

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