Vielzeug
familiar logoFamiliarWorkers
Typed ES module Worker pools with cancellation, priority scheduling, streaming, and test utilities.
Version
v3.0.0
Size
3.9 KB gzip
Runtime support
Browser
Key exports
createWorkercreateStreamWorkerrunBatchFamiliarErrorFamiliarInvalidOptionsError View all 10 exports
Works well with
ripple herald

Why Familiar? ​

Raw workers force every application to maintain its own message contract, lifecycle, cancellation, and pool scheduler. Familiar provides those boundaries while keeping worker code in normal typed ES modules.

ts
// Before
const worker = new Worker(new URL('./sum.worker.ts', import.meta.url), { type: 'module' });
worker.postMessage([1, 2, 3]);

// After
const pool = createWorker<number[], number>(new URL('./sum.worker.ts', import.meta.url));
await pool.run([1, 2, 3]);
FeatureFamiliarRaw WorkerComlink
Bundle size3.9 KBbuilt-in~2 kB
Module-worker contractmanual
Pool scheduling
AbortSignal cancellationmanualmanual
Versioned protocolimplementation-specific
Zero dependencies

Use Familiar when worker jobs need bounded concurrency, typed errors, cancellation, or queue policy.

Consider raw Worker when one isolated worker and custom messaging are enough.

Installation ​

sh
pnpm add @vielzeug/familiar
sh
npm install @vielzeug/familiar
sh
yarn add @vielzeug/familiar

Quick Start ​

Register task logic inside a worker module.

ts
// double.worker.ts
import { exposeTask } from '@vielzeug/familiar/protocol';

exposeTask((value: number) => value * 2);

Create pool from module URL and dispose it after use.

ts
import { createWorker } from '@vielzeug/familiar';

const worker = createWorker<number, number>(new URL('./double.worker.ts', import.meta.url));

try {
  console.log(await worker.run(21));
} finally {
  worker.dispose();
}

Features ​

  • createWorker() — versioned task protocol over ES module workers
  • createStreamWorker() — stream-only worker capability
  • run() — validated priority scheduling, transferables, timeout, and cancellation
  • runBatch() — ordered progressive results with shared fail-fast cancellation
  • stats — active, queued, completed, and failed counters
  • createTestWorker() — faithful in-process task-pool testing
  • dispose() and drain() — immediate or draining teardown, with using support
  • Application-owned promise composition — domain task groups without pool-owned orchestration state

Documentation ​

See Also ​

  • Ripple — expose worker results through reactive state.
  • Herald — publish application events after worker jobs settle.