first commit
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# @suaveplan/queue-distribution-worker-thread - Web-Worker / Node worker_threads transport plugin for @suaveplan/queue-distribution: caller-injected WorkerFactory bridges to the platform-native worker, message correlation, Zod-validated reply envelope, bounded outstanding-request map.
|
||||
|
||||
## Summary
|
||||
|
||||
Web-Worker / Node `worker_threads` transport plugin for `@suaveplan/queue-distribution`. Ships `WorkerThreadCommunicator` (a `ThreadWorkerLike`-based message bridge with Zod-validated envelopes, bounded outstanding-request map, AbortSignal cancellation, structured timeouts) and `WorkerThreadWorker` (an `AbstractWorker` subclass that drives the communicator and reacts to crash / exit events).
|
||||
|
||||
The plugin lives separately from the core distribution package so HTTP-only and in-process-only consumers don't carry worker-thread bridge code they never use.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [worker-thread](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [worker-thread-communicator](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [errors](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [queue-distribution-worker-thread-error](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [observability](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [instruments](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [worker-thread](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [worker-thread-worker](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
<!-- end:auto-docs --> - [worker-thread-communicator](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [queue-distribution-worker-thread-error](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [instruments](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-worker](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-communicator](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [queue-distribution-worker-thread-error](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [instruments](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-worker](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-communicator](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [queue-distribution-worker-thread-error](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [instruments](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-worker](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread-communicator](./src/communicator/worker-thread/worker-thread-communicator.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [queue-distribution-worker-thread-error](./src/errors/queue-distribution-worker-thread-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_ - [instruments](./src/observability/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [worker-thread](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_ - [worker-thread-worker](./src/worker/worker-thread/worker-thread-worker.md) — <!-- begin:auto-docs --> _(no submodules)_
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/queue-distribution-worker-thread
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import {
|
||||
WorkerManager,
|
||||
WorkerPool,
|
||||
} from "@suaveplan/queue-distribution";
|
||||
import { WorkerThreadWorker } from "@suaveplan/queue-distribution-worker-thread";
|
||||
|
||||
const pool = new WorkerPool();
|
||||
pool.addWorker(
|
||||
new WorkerThreadWorker(
|
||||
() => new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }),
|
||||
{ id: "hot-1", capacity: 4 },
|
||||
),
|
||||
);
|
||||
await pool.startAllWorkers();
|
||||
|
||||
const manager = new WorkerManager(pool, { autoHealthCheck: false });
|
||||
const result = await manager.assignTask(task, input);
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [Errors](./src/errors/queue-distribution-worker-thread-error.md) — `QueueDistributionWorkerThreadError` + 4 stable `WT.*` codes.
|
||||
- [WorkerThreadCommunicator](./src/communicator/worker-thread/worker-thread-communicator.md) — message bridge with Zod envelope.
|
||||
- [WorkerThreadWorker](./src/worker/worker-thread/worker-thread-worker.md) — `AbstractWorker` subclass.
|
||||
- [Observability](./src/observability/instruments.md) — OTel counters, histograms, tracer.
|
||||
|
||||
## Design highlights
|
||||
|
||||
- 100% test coverage (statements + branches + functions + lines).
|
||||
- Same class runs against browser `Worker` and Node `worker_threads` via injectable `WorkerFactory`.
|
||||
- Bounded `Map<requestId, PendingRequest>` — never leaks outstanding entries.
|
||||
- Zod-validated envelope in both directions rejects malformed traffic at the boundary.
|
||||
- Structured `QueueDistributionWorkerThreadError` subclasses with a frozen stable-code registry.
|
||||
- AbortSignal threaded through every request; terminate() fails all in-flight requests.
|
||||
|
||||
## Status
|
||||
|
||||
Part of the rebuild — version `0.1.0` while it stabilises.
|
||||
|
||||
Reference in New Issue
Block a user