Initial Commit
This commit is contained in:
96
packages/foundation/data/web-workers/README.md
Normal file
96
packages/foundation/data/web-workers/README.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user