97 lines
7.2 KiB
Markdown
97 lines
7.2 KiB
Markdown
# @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.
|
|
|