SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
skills/plugins/document-navigator/docs/foundation/flow/queue-distribution/README.md
admin 427a5bd919 updated skills
2026-06-09 21:06:27 +01:00

20 KiB
Raw Permalink Blame History

@suaveplan/queue-distribution - Worker-pool distribution layer: load-balancing strategies (round-robin / least-busy / weighted), worker pool, manager with retry + health checks, in-process LocalWorker. Transport-agnostic — HTTP and worker-thread plugins ship as separate packages.

Summary

Worker-pool distribution layer: load-balancing strategies, worker pool management, manager with retry and health checks, in-process LocalWorker. Transport-agnostic — HTTP and worker-thread transports ship as separate plugin packages (@suaveplan/queue-distribution-http, @suaveplan/queue-distribution-worker-thread).

The package is decoupled from @suaveplan/queue's Job model: distribution operates on a minimal DistributedTask<I, O> contract so it can serve any consumer that produces typed work units (queue, batch, RPC, agent dispatch).

Documentation tree

- [queue-distribution-error](./src/errors/queue-distribution-error.md) — _(no submodules)_- [health-checker](./src/health-checker/health-checker.md) — _(no submodules)_- [health-checker](./src/health-checker/health-checker.md) — _(no submodules)_- [internal](./src/internal/noop-logger.md) — _(no submodules)_- [noop-logger](./src/internal/noop-logger.md) — _(no submodules)_- [base](./src/load-balancing/base/base.md) — _(no submodules)_- [base](./src/load-balancing/base/base.md) — _(no submodules)_- [least-busy](./src/load-balancing/least-busy/least-busy.md) — _(no submodules)_- [least-busy](./src/load-balancing/least-busy/least-busy.md) — _(no submodules)_- [round-robin](./src/load-balancing/round-robin/round-robin.md) — _(no submodules)_- [round-robin](./src/load-balancing/round-robin/round-robin.md) — _(no submodules)_- [weighted](./src/load-balancing/weighted/weighted.md) — _(no submodules)_- [weighted](./src/load-balancing/weighted/weighted.md) — _(no submodules)_- [manager](./src/manager/manager.md) — _(no submodules)_- [manager-dispatch](./src/manager/manager-dispatch.md) — `dispatchWithRetry` is the core retry loop of `WorkerManager`. It picks a worker via the configured `LoadBalancingStrat…

Install

bun add @suaveplan/queue-distribution

Quick start

import {
    LocalWorker,
    WorkerManager,
    WorkerPool,
} from "@suaveplan/queue-distribution";

const pool = new WorkerPool();
pool.addWorker(new LocalWorker({}, { id: "a", capacity: 4 }));
pool.addWorker(new LocalWorker({}, { id: "b", capacity: 4 }));
await pool.startAllWorkers();

const manager = new WorkerManager(pool, {
    autoHealthCheck: false,
    maxTaskRetries: 2,
});

const task = {
    id: "double",
    execute: async (n: number) => n * 2,
    getStatus: () => "PENDING" as const,
    setStatus: () => {},
    getMetadata: () => ({ createdAt: new Date(), attempts: 0 }),
};

console.log(await manager.assignTask(task, 21)); // 42

Modules

Design highlights

  • 100% test coverage (statements + branches + functions + lines) under provider: "istanbul".
  • Injectable Clock, IdGenerator, Rng, LoggerLike everywhere — no Math.random / Date.now / uuid at module scope.
  • AbortSignal threaded through every async public method.
  • Retry routed through @suaveplan/retry; bounded loop, no recursion.
  • Zod schemas at every public boundary (WorkerHealthSchema, WorkerInfoSchema, TaskMetadataSchema, …).
  • Structured SuaveplanError subclasses with a frozen stable-code registry.
  • Tree-shakeable via 15 per-feature subpath exports.

Status

This package is part of the rebuild — version 0.1.0 while it stabilises. Graduation to 1.0.0 follows the criteria in CLAUDE.md.

Reference in New Issue View Git Blame Copy Permalink