@offmain/workerkit 0.8.9 → 0.10.0

package/dist/types/tools/main-worker-factory/main-worker-factory.d.ts

@@ -1,31 +1,169 @@
-import { CollectOptions, CollectedResult, MainWorkerFactoryOptions, WorkerFunction, WorkerResult } from './types.ts';
+import { CollectOptions, CollectedResult, PipelineStep, WorkerConfig, WorkerConfigMap, WorkerDataParam, WorkerFunction, WorkerReturnType, TypedSettledResults } from './types.ts';
 /**
  * Recursively collects all Transferable objects from a value.
  * Transferables (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas)
  * are zero-copy — they are moved to the worker instead of cloned.
  */
 export declare function extractTransferables(value: unknown, seen?: Set<object>): Transferable[];
-declare class MainWorkerFactory {
+/**
+ * Central orchestrator for running typed Web Workers in parallel.
+ *
+ * `MainWorkerFactory` manages a registry of named worker configurations and
+ * handles the full lifecycle of each worker: spawning, partitioning input
+ * data across threads, retrying on failure, and collecting results.
+ *
+ * @typeParam TConfigs - A readonly tuple of {@link WorkerConfig} objects that
+ *   defines the set of available workers and their typed signatures.
+ *
+ * @example
+ * const foreman = new MainWorkerFactory({
+ *   workers: [
+ *     { name: 'sum', role: 'compute', func: sumWorker, partition: true },
+ *   ],
+ * });
+ *
+ * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3, 4] });
+ * const { data } = await foreman.collectResults(settled);
+ */
+declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFunction<any, any>>[]> {
     private readonly _workers;
     private readonly _threads;
-    constructor(_initiator: WorkerFunction, options: MainWorkerFactoryOptions);
+    /**
+     * Creates a new `MainWorkerFactory`.
+     *
+     * @param options - Configuration object containing the `workers` registry.
+     */
+    constructor(options: {
+        workers: TConfigs;
+    });
+    /**
+     * Instantiates a {@link WorkerFactory} for the given worker function.
+     *
+     * @param workerFunction - The function to run inside the worker thread.
+     * @returns A new `WorkerFactory` wrapping the worker.
+     */
     private initWorker;
     /**
-     * Partitions an array into up to numChunks evenly-sized chunks.
+     * Splits an array into up to `numChunks` evenly-sized sub-arrays.
+     *
+     * When the array length is not evenly divisible, the first `remainder`
+     * chunks receive one extra element so no data is lost.
+     *
+     * @param array     - The source array to partition.
+     * @param numChunks - Maximum number of chunks to produce.
+     *   Clamped to `array.length` so you never get empty chunks.
+     * @returns An array of sub-arrays. Returns `[]` when `array` is empty.
+     * @throws {Error} When `numChunks` is not a positive integer.
+     *
+     * @example
+     * partitionArray([1, 2, 3, 4, 5], 3);
+     * // → [[1, 2], [3, 4], [5]]
      */
     partitionArray<T>(array: T[], numChunks: number): T[][];
+    /**
+     * Looks up a registered worker configuration by name.
+     *
+     * @param name - The `name` field of the target {@link WorkerConfig}.
+     * @returns The matching config, or `undefined` if not found.
+     */
     private findWorkerByName;
-    runWorker(workerName: string, { srcData, ...otherParams }: {
-        srcData: unknown;
-    } & Record<string, unknown>): Promise<PromiseSettledResult<WorkerResult>[]>;
+    /**
+     * Runs a named worker against the provided data, distributing work across
+     * threads when the worker is configured for partitioning.
+     *
+     * When `config.partition` is `true` and `srcData` is an array with more
+     * than one element, the array is split into up to `maxConcurrency` (or
+     * `navigator.hardwareConcurrency`) shards and each shard is processed by
+     * a separate worker thread in parallel.
+     *
+     * All threads are awaited with `Promise.allSettled`, so a failure in one
+     * shard does not cancel the others. Use {@link collectResults} to merge
+     * the settled output.
+     *
+     * @typeParam TName - The literal name of the worker to run (inferred from
+     *   the registered `workers` tuple).
+     *
+     * @param workerName - Name of the worker as declared in the `workers` config.
+     * @param params     - Object containing `srcData` (the payload) plus any
+     *   additional key/value pairs forwarded to the worker verbatim.
+     *
+     * @returns A {@link TypedSettledResults} wrapping the settled promises from
+     *   all spawned worker threads.
+     *
+     * @example
+     * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3] });
+     */
+    runWorker<TName extends keyof WorkerConfigMap<TConfigs> & string>(workerName: TName, { srcData, ...otherParams }: {
+        srcData: WorkerDataParam<WorkerConfigMap<TConfigs>[TName]>;
+    } & Record<string, unknown>): Promise<TypedSettledResults<WorkerReturnType<WorkerConfigMap<TConfigs>[TName]>>>;
+    /**
+     * Builds the array of per-thread worker promises for a single `runWorker`
+     * call.
+     *
+     * When `isPartitioned` is `true`, each promise receives its own slice of
+     * `srcData`; otherwise every thread receives the full payload.
+     *
+     * @param config         - The resolved {@link WorkerConfig} for this run.
+     * @param workerName     - Name used in error/retry logging.
+     * @param srcWorkerData  - Combined `{ data, ...otherParams }` payload.
+     * @param threadCount    - Number of parallel worker threads to spawn.
+     * @param isPartitioned  - Whether `data` is a pre-split array of shards.
+     * @returns An array of promises, one per thread.
+     */
     private createWorkerPromises;
+    /**
+     * Runs a single worker instance, retrying on failure up to `retryCount`
+     * times before re-throwing the last error.
+     *
+     * Each retry is logged to `console.error` with the remaining attempt count
+     * so failures are visible during development.
+     *
+     * @param instanceConfig - Full configuration for the worker instance.
+     * @param retryCount     - Remaining retry attempts (default `2`).
+     * @returns The successful {@link WorkerResult} once the worker resolves.
+     * @throws The last caught error when all retries are exhausted.
+     */
     private runWorkerWithRetry;
+    /**
+     * Spawns a single worker thread, posts the payload, and resolves or rejects
+     * based on the message the worker sends back.
+     *
+     * The worker is expected to respond with either:
+     * - `{ ok: true, data: T }` — success; resolves with a {@link WorkerResult}.
+     * - `{ ok: false, error: string }` — logical failure; rejects with a
+     *   structured error object.
+     *
+     * Any transferable objects found in the payload are moved (not copied) to
+     * the worker via the `transfer` list of `postMessage`.
+     *
+     * The underlying `Worker` is always terminated after the first message,
+     * whether it succeeded or failed.
+     *
+     * @param instanceConfig - Worker function, name, shard index, and data.
+     * @returns A promise that resolves with the worker's result.
+     */
     private initiateWorker;
     /**
-     * Collects and merges the settled results from `runWorker` — off the main thread.
+     * Collects and merges the settled results from {@link runWorker} — off the
+     * main thread.
+     *
+     * Fulfilled shards are extracted and passed to the `reducer` function, which
+     * runs inside a dedicated inline worker so the merge itself never blocks the
+     * main thread. Failed shards are counted and their raw rejection reasons are
+     * preserved in `errors`.
      *
-     * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
-     * @param options  Optional `reducer` function (must be self-contained)
+     * @typeParam T - The per-shard data type (inferred from `settled`).
+     * @typeParam R - The final merged output type (defaults to a flat array of
+     *   `T` items when no custom reducer is provided).
+     *
+     * @param settled  - The {@link TypedSettledResults} returned by `runWorker`.
+     * @param options  - Optional {@link CollectOptions}. Supply a `reducer` to
+     *   control how shards are merged. The reducer **must be self-contained**
+     *   (no closures over external variables) because it is serialised and run
+     *   inside a worker.
+     *
+     * @returns A {@link CollectedResult} with the merged `data`, counts of
+     *   `succeeded`/`failed` shards, and the raw `errors` array.
      *
      * @example
      * // default: flat array of all shard data
@@ -37,6 +175,28 @@ declare class MainWorkerFactory {
      *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
      * });
      */
-    collectResults<T = unknown, R = T[]>(settled: PromiseSettledResult<WorkerResult>[], options?: CollectOptions<T, R>): Promise<CollectedResult<R>>;
+    collectResults<T = unknown, R = T extends (infer Item)[] ? Item[] : T[]>(settled: TypedSettledResults<T>, options?: CollectOptions<T, R>): Promise<CollectedResult<R>>;
+    /**
+     * Runs a chain of workers where each step's output feeds directly into the
+     * next step — **without passing through the main thread**.
+     *
+     * Internally, adjacent workers are connected via `MessageChannel` ports.
+     * Only the final result is sent back to the main thread, minimising
+     * serialisation overhead for large intermediate data.
+     *
+     * @param steps - An ordered array of pipeline steps. The first step must
+     *   include `srcData`; subsequent steps receive the previous step's output.
+     *
+     * @returns A promise that resolves with the final step's output.
+     *
+     * @example
+     * const result = await foreman.pipeline([
+     *   { worker: 'fetchPosts', srcData: { url: '/api/posts' } },
+     *   { worker: 'transformPosts' },
+     *   { worker: 'filterPosts' },
+     * ]);
+     * console.log(result); // final transformed + filtered data
+     */
+    pipeline<TResult = unknown>(steps: PipelineStep[]): Promise<TResult>;
 }
 export default MainWorkerFactory;

package/dist/types/tools/main-worker-factory/types.d.ts

@@ -1,35 +1,128 @@
 import { WorkerFactory } from '../worker-factory';
+/** A unique string identifier for a worker, matching its `name` field. */
 export type WorkerName = string;
+/** A descriptive label for the worker's role (e.g. `'compute'`, `'io'`). */
 export type WorkerRole = string;
-export type WorkerFunction = (...params: unknown[]) => void;
-export interface WorkerConfig {
+/**
+ * The shape of a function that runs inside a Web Worker.
+ *
+ * Workers receive a single `params` argument posted from the main thread and
+ * return (or resolve) a result that is posted back.
+ *
+ * @typeParam TParams - The type of the message payload sent to the worker.
+ * @typeParam TResult - The type of the value the worker posts back.
+ */
+export type WorkerFunction<TParams = unknown, TResult = unknown> = (params: TParams) => TResult;
+/**
+ * Configuration object that registers a named worker with the factory.
+ *
+ * @typeParam TFunc - The concrete {@link WorkerFunction} type for this worker.
+ */
+export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
+    /** Unique name used to look up this worker via `runWorker`. */
     name: WorkerName;
+    /** Human-readable role label (e.g. `'compute'`, `'transform'`). */
     role: WorkerRole;
-    func: WorkerFunction;
+    /** The worker function that will be serialised and run in a thread. */
+    func: TFunc;
+    /**
+     * Maximum number of parallel threads to spawn for this worker.
+     * Defaults to `navigator.hardwareConcurrency` when omitted.
+     */
     maxConcurrency?: number;
+    /**
+     * Number of times a failed worker thread is retried before the shard is
+     * marked as rejected. Defaults to `2`.
+     */
     retries?: number;
+    /**
+     * When `true`, an array `srcData` is split into per-thread shards before
+     * being dispatched. Each thread receives one shard instead of the full
+     * array.
+     */
     partition?: boolean;
 }
+/**
+ * Derives a `name → function` map from a readonly tuple of
+ * {@link WorkerConfig} objects.
+ *
+ * Used internally to give `runWorker` a fully-typed `workerName` parameter
+ * and to infer the correct `srcData` type for each worker.
+ *
+ * @typeParam T - The readonly tuple of `WorkerConfig` values.
+ */
+export type WorkerConfigMap<T extends readonly WorkerConfig<WorkerFunction<any, any>>[]> = {
+    [K in T[number]['name']]: Extract<T[number], {
+        name: K;
+    }>['func'];
+};
+/**
+ * Extracts the `params` type from a {@link WorkerFunction}.
+ *
+ * @typeParam TFunc - The worker function to inspect.
+ */
+export type WorkerParams<TFunc extends WorkerFunction> = TFunc extends WorkerFunction<infer P, unknown> ? P : never;
+/**
+ * Extracts the `data` field type from a worker function's params.
+ * Workers receive `{ data: T, index: number, ...otherParams }` — this
+ * pulls out just `T` so callers only need to supply the payload.
+ *
+ * Always allows `D | D[]` so partitioned workers can receive an array
+ * that the framework splits into per-shard items.
+ */
+export type WorkerDataParam<TFunc extends WorkerFunction> = WorkerParams<TFunc> extends {
+    data: infer D;
+} ? D extends (infer Item)[] ? Item[] : D | D[] : WorkerParams<TFunc>;
+/** Extracts the return type from a {@link WorkerFunction}, unwrapping `Promise<T>` → `T`. */
+export type WorkerReturnType<TFunc extends WorkerFunction> = TFunc extends WorkerFunction<any, infer R> ? R extends Promise<infer Resolved> ? Resolved : R : never;
+/** Options passed to the `MainWorkerFactory` constructor. */
 export interface MainWorkerFactoryOptions {
     workers: WorkerConfig[];
 }
+/** Internal representation of a worker config that has been instantiated. */
 export interface MainWorkerFactoryWorker extends WorkerConfig {
     worker: WorkerFactory;
 }
-export interface WorkerInstanceConfig {
+/**
+ * Runtime configuration for a single worker thread instance.
+ *
+ * @typeParam TFunc - The worker function type for this instance.
+ */
+export interface WorkerInstanceConfig<TFunc extends WorkerFunction = WorkerFunction> {
+    /** Name of the parent worker config, used in logs and error objects. */
     workerName: WorkerName;
-    workerFunc: WorkerFunction;
+    /** The function serialised and executed inside the thread. */
+    workerFunc: TFunc;
+    /** Zero-based shard index assigned to this thread. */
     index: number;
+    /** The data payload (full or partitioned shard) sent to the thread. */
     data: unknown;
 }
+/** The raw `MessageEvent` received when a worker thread succeeds. */
 export type WorkerSuccessResult = MessageEvent;
+/** The raw `MessageEvent` (or `ErrorEvent`) received when a worker thread fails. */
 export type WorkerFailedResult = MessageEvent;
+/** Structured result returned by a single worker thread, whether it succeeded or failed. */
 export interface WorkerResult {
+    /** Zero-based shard index of the thread that produced this result. */
     index: number;
+    /** The full instance config used to spawn this thread. */
     workerConfigs: WorkerInstanceConfig;
+    /** Present when the thread resolved successfully. */
     successResult?: WorkerSuccessResult;
+    /** Present when the thread rejected or posted `{ ok: false }`. */
     failedResult?: WorkerFailedResult;
 }
+/**
+ * Typed wrapper around the settled results from `runWorker`.
+ * Carries `T` (the worker's return type) so `collectResults` can infer it.
+ */
+export declare class TypedSettledResults<T> {
+    readonly results: PromiseSettledResult<WorkerResult>[];
+    constructor(results: PromiseSettledResult<WorkerResult>[]);
+    /** Never actually exists at runtime — used only for type inference. */
+    readonly __type: T;
+}
 /** Options for collectResults */
 export interface CollectOptions<T, R = T[]> {
     /**
@@ -54,3 +147,10 @@ export interface CollectedResult<R> {
     /** Raw rejected results, if any */
     errors: PromiseRejectedResult[];
 }
+/** A single step in a worker pipeline */
+export interface PipelineStep {
+    /** Name of the registered worker to run */
+    worker: string;
+    /** Input data for the first step (subsequent steps receive previous output) */
+    srcData?: unknown;
+}

package/dist/types/tools/worker-factory/worker-factory.d.ts

@@ -1,7 +1,40 @@
 import { WorkerFunction } from '../main-worker-factory/types';
+export interface WorkerFactoryOptions {
+    /** When true, generates a pipeline-aware worker that supports MessagePort forwarding */
+    pipeline?: boolean;
+}
+/**
+ * Low-level factory that serialises a {@link WorkerFunction} into a Blob URL
+ * and spawns a native `Worker` from it.
+ *
+ * `WorkerFactory` is an internal building block used by `MainWorkerFactory`.
+ * It handles the mechanics of turning a plain TypeScript function into a
+ * runnable worker thread — you rarely need to use it directly.
+ *
+ * The worker script is generated by {@link workerTemplate}, which wraps the
+ * function with a message listener and transferable-extraction logic.
+ */
 declare class WorkerFactory {
     readonly _worker: Worker;
-    constructor(workerFunction: WorkerFunction);
+    /**
+     * Creates a new `Worker` from the given function.
+     *
+     * The function is stringified, embedded into a self-contained worker script,
+     * converted to a `Blob` URL, and passed to the `Worker` constructor.
+     *
+     * @param workerFunction - The function to run inside the worker thread.
+     *   Must be self-contained — it cannot reference variables from the outer
+     *   scope because it is serialised via `.toString()`.
+     * @param options - Optional configuration. Set `pipeline: true` for
+     *   pipeline-aware workers that support MessagePort forwarding.
+     */
+    constructor(workerFunction: WorkerFunction, options?: WorkerFactoryOptions);
+    /**
+     * Returns the underlying native `Worker` instance.
+     *
+     * Use this to attach `onmessage` / `onerror` handlers and call
+     * `postMessage` / `terminate` directly.
+     */
     get getWorker(): Worker;
 }
 export default WorkerFactory;

package/dist/types/workers/initiator.d.ts

@@ -1,2 +1,18 @@
+/**o with
+ * Default initiator — a minimal echo worker used as a no-op placeholder.
+ *
+ * When no custom initiator is passed to `MainWorkerFactory`, this function
+ * is used. It simply reflects every incoming message back to the sender,
+ * which is useful for testing the messaging pipeline without any real
+ * computation.
+ *
+ * @example
+ * // Automatically used as the default:
+ * new MainWorkerFactory({ workers: [...] });
+ *
+ * // Equivalent explicit usage:
+ * import defaultInitiator from './initiator';
+ * new MainWorkerFactory({ workers: [...] }, defaultInitiator);
+ */
 declare const _default: () => void;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offmain/workerkit",
-  "version": "0.8.9",
+  "version": "0.10.0",
   "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,11 +28,11 @@
     "lint": "eslint --fix .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "release:patch": "npm version patch && npm run release:publish",
-    "release:minor": "npm version minor && npm run release:publish",
-    "release:major": "npm version major && npm run release:publish",
-    "release:publish": "npm run build:lib && npm publish",
-    "prepublishOnly": "npm run build:lib",
+    "release": "release-it --ci",
+    "release:patch": "release-it --increment patch --ci",
+    "release:minor": "release-it --increment minor --ci",
+    "release:major": "release-it --increment major --ci",
+    "release:dry": "release-it --dry-run",
     "lint-staged": "lint-staged",
     "prepare": "husky"
   },
@@ -59,6 +59,7 @@
     ]
   },
   "devDependencies": {
+    "@release-it/conventional-changelog": "11.0.0",
     "@typescript-eslint/eslint-plugin": "^8.58.2",
     "@typescript-eslint/parser": "^8.58.2",
     "date-fns": "^4.1.0",
@@ -71,6 +72,7 @@
     "jsdom": "^24.0.0",
     "lint-staged": "^16.4.0",
     "prettier": "^3.4.2",
+    "release-it": "19.0.3",
     "typescript": "^5.7.2",
     "vite": "^6.3.3",
     "vite-plugin-dts": "^4.5.4",

package/dist/types/workers/initiator.test.d.ts

@@ -1 +0,0 @@
-export {};