@offmain/workerkit 0.8.8 → 0.9.2

package/README.md

@@ -2,16 +2,16 @@
 
 A lightweight TypeScript library for running functions in Web Workers with support for partitioning, retries, and concurrency control — all without the boilerplate.
 
-Instead of manually creating worker scripts and wiring up `postMessage` / `onmessage`, you write plain exported functions and hand them to `MainWorkerFactory`. The library serialises them into Blob workers, manages a pool per function, handles retries on failure, and merges results back on the main thread.
+Instead of manually creating worker scripts and wiring up `postMessage` / `onmessage`, you write plain exported functions and hand them to `MainWorkerFactory`. The library serializes them into Blob workers, manages threads per function, handles retries on failure, and merges results back on the main thread.
 
 ---
 
 ## Installation
 
 ```bash
-npm install workerkit
+npm install @offmain/workerkit
 # or
-pnpm add workerkit
+pnpm add @offmain/workerkit
 ```
 
 ---
@@ -32,10 +32,10 @@ export function sum({ data }: { data: number[] }): number {
 ### 2. Register and run it
 
 ```ts
-import { MainWorkerFactory } from 'workerkit';
+import { MainWorkerFactory } from '@offmain/workerkit';
 import { sum } from './sum.worker.ts';
 
-const factory = new MainWorkerFactory(initiator, {
+const factory = new MainWorkerFactory({
   workers: [
     {
       name: 'sum',
@@ -47,10 +47,10 @@ const factory = new MainWorkerFactory(initiator, {
   ],
 });
 
-const result = await factory.runWorker('sum', { srcData: [1, 2, 3, 4, 5] });
-const { data } = await factory.collectResults(result);
+const settled = await factory.runWorker('sum', { srcData: [1, 2, 3, 4, 5] });
+const { data } = await factory.collectResults(settled);
 
-console.log(data); // 15
+console.log(data); // [15]
 ```
 
 ---
@@ -63,7 +63,7 @@ console.log(data); // 15
 | `role`           | `string`   | —                               | Logical grouping label                                                                              |
 | `func`           | `Function` | —                               | The exported worker function to run                                                                 |
 | `maxConcurrency` | `number`   | `navigator.hardwareConcurrency` | Max parallel worker instances — defaults to the number of logical CPU cores reported by the browser |
-| `retries`        | `number`   | `0`                             | How many times to retry a failed shard                                                              |
+| `retries`        | `number`   | `0`                             | How many times to retry a failed shard before marking it as rejected                                |
 | `partition`      | `boolean`  | `false`                         | Split array input across multiple workers automatically                                             |
 
 ---
@@ -73,21 +73,23 @@ console.log(data); // 15
 When `partition: true`, an array passed as `srcData` is automatically split across worker instances and results are merged back.
 
 ```ts
-const result = await factory.runWorker('sum', {
+const settled = await factory.runWorker('sum', {
   srcData: largeArray, // split across workers
 });
 
-const { data, succeeded, failed } = await factory.collectResults(result);
+const { data, succeeded, failed } = await factory.collectResults(settled);
 ```
 
 You can also provide a custom reducer to control how shard results are merged:
 
 ```ts
-const { data } = await factory.collectResults(result, {
+const { data } = await factory.collectResults(settled, {
   reducer: (shards) => shards.flat().sort((a, b) => b.score - a.score),
 });
 ```
 
+> **Note:** The reducer runs inside a worker thread and must be self-contained — it cannot reference variables from the outer scope.
+
 ---
 
 ## ESLint Plugin
@@ -98,7 +100,7 @@ The package ships with two ESLint rules to catch common worker mistakes at lint
 
 ```js
 // eslint.config.js
-import workerPlugin from 'workerkit/eslint-plugin';
+import workerPlugin from '@offmain/workerkit/eslint-plugin';
 
 export default [...workerPlugin.configs.recommended];
 ```
@@ -113,16 +115,16 @@ Flags usage of browser main-thread-only APIs that are unavailable inside Web Wor
 
 ```ts
 // sum.worker.ts ❌ — will be flagged
-export function sum({ data }: MessageEvent) {
+export function sum({ data }: { data: number[] }) {
   document.title = 'working...'; // Error: 'document' is not available inside Web Workers
-  return data.reduce((a: number, b: number) => a + b, 0);
+  return data.reduce((a, b) => a + b, 0);
 }
 ```
 
 ```ts
 // sum.worker.ts ✅
-export function sum({ data }: MessageEvent) {
-  return data.reduce((a: number, b: number) => a + b, 0);
+export function sum({ data }: { data: number[] }) {
+  return data.reduce((a, b) => a + b, 0);
 }
 ```
 
@@ -150,8 +152,8 @@ You can also import rules individually if you don't want the full recommended co
 
 ```js
 // eslint.config.js
-import noDomInWorker from 'workerkit/eslint-rules/no-dom-in-worker';
-import workerExportable from 'workerkit/eslint-rules/worker-exportable';
+import noDomInWorker from '@offmain/workerkit/eslint-rules/no-dom-in-worker';
+import workerExportable from '@offmain/workerkit/eslint-rules/worker-exportable';
 
 export default [
   {

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"use strict";var g=Object.defineProperty;var m=(t,e,r)=>e in t?g(t,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):t[e]=r;var h=(t,e,r)=>m(t,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=t=>`
+"use strict";var y=Object.defineProperty;var m=(t,e,r)=>e in t?y(t,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):t[e]=r;var g=(t,e,r)=>m(t,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=t=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -14,11 +14,14 @@ const extractTransferables = (value, seen = new Set()) => {
 };
 
 self.addEventListener('message', async (event) => {
-    const begin = performance.now();
+  try {
     const output = await ${t}(event.data);
-    self.postMessage(output, extractTransferables(output));
-  })
-`;class k{constructor(e){h(this,"_worker");const r=w(e.toString()),s=new Blob([r],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(s))}get getWorker(){return this._worker}}function p(t,e=new Set){return t===null||typeof t!="object"?[]:e.has(t)?[]:(e.add(t),t instanceof ArrayBuffer||t instanceof MessagePort||typeof ImageBitmap<"u"&&t instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&t instanceof OffscreenCanvas?[t]:ArrayBuffer.isView(t)?[t.buffer]:Array.isArray(t)?t.flatMap(r=>p(r,e)):Object.values(t).flatMap(r=>p(r,e)))}class W{constructor(e,r){h(this,"_workers");h(this,"_threads");this._workers=r.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new k(e)}partitionArray(e,r){if(!e.length)return[];if(r<=0)throw new Error("numChunks must be positive");const s=Math.min(r,e.length),a=Math.floor(e.length/s),c=e.length%s,o=[];let f=0;for(let n=0;n<s;n++){const i=a+(n<c?1:0);o.push(e.slice(f,f+i)),f+=i}return o}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...s}){const a=this.findWorkerByName(e);if(!a)return Promise.reject(new Error(`Worker "${e}" not found`));const c=a.maxConcurrency??this._threads,o=!!(Array.isArray(r)&&r.length>1&&a.partition),f=o?this.partitionArray(r,c):r,n=this.createWorkerPromises(a,e,{data:f,...s},c,o);return Promise.allSettled(n)}createWorkerPromises(e,r,s,a,c){const{data:o,...f}=s;return Array.from({length:a},(n,i)=>{const u=c&&Array.isArray(o)?o[i]:o;return this.runWorkerWithRetry({workerFunc:e.func,workerName:r,index:i,data:{data:u,...f}},e.retries)})}async runWorkerWithRetry(e,r=2){try{return await this.initiateWorker(e)}catch(s){if(r>0)return console.error(`Worker ${e.index} failed, retrying (${r} left):`,s),this.runWorkerWithRetry(e,r-1);throw console.error("Worker failed after all retries:",s),s}}initiateWorker({workerFunc:e,workerName:r,index:s,data:a}){return new Promise((c,o)=>{const n=this.initWorker(e).getWorker;n.onerror=u=>{n.terminate(),o({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:a},failedResult:u})},n.onmessage=u=>{c({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:a},successResult:u}),n.terminate()};const i={index:s,...Array.isArray(a)?{data:a}:a};n.postMessage(i,p(i))})}async collectResults(e,r={}){const s=e.filter(n=>n.status==="fulfilled"),a=e.filter(n=>n.status==="rejected"),c=s.map(n=>n.value.successResult.data),o=r.reducer?r.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((n,i)=>{const u=`
+    self.postMessage({ ok: true, data: output }, extractTransferables(output));
+  } catch (err) {
+    self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+})
+`;class p{constructor(e){g(this,"_worker");const r=w(e.toString()),s=new Blob([r],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(s))}get getWorker(){return this._worker}}class W{constructor(e){this.results=e}}function k(t,e=new Set){return t===null||typeof t!="object"?[]:e.has(t)?[]:(e.add(t),t instanceof ArrayBuffer||t instanceof MessagePort||typeof ImageBitmap<"u"&&t instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&t instanceof OffscreenCanvas?[t]:ArrayBuffer.isView(t)?[t.buffer]:Array.isArray(t)?t.flatMap(r=>k(r,e)):Object.values(t).flatMap(r=>k(r,e)))}class v{constructor(e){g(this,"_workers");g(this,"_threads");this._workers=e.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new p(e)}partitionArray(e,r){if(!e.length)return[];if(r<=0)throw new Error("numChunks must be positive");const s=Math.min(r,e.length),n=Math.floor(e.length/s),c=e.length%s,o=[];let f=0;for(let a=0;a<s;a++){const i=n+(a<c?1:0);o.push(e.slice(f,f+i)),f+=i}return o}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...s}){const n=this.findWorkerByName(e);if(!n)return Promise.reject(new Error(`Worker "${e}" not found`));const c=n.maxConcurrency??this._threads,o=!!(Array.isArray(r)&&r.length>1&&n.partition),f=o?this.partitionArray(r,c):r,a=this.createWorkerPromises(n,e,{data:f,...s},c,o),i=await Promise.allSettled(a);return new W(i)}createWorkerPromises(e,r,s,n,c){const{data:o,...f}=s;return Array.from({length:n},(a,i)=>{const l=c&&Array.isArray(o)?o[i]:o;return this.runWorkerWithRetry({workerFunc:e.func,workerName:r,index:i,data:{data:l,...f}},e.retries)})}async runWorkerWithRetry(e,r=2){try{return await this.initiateWorker(e)}catch(s){if(r>0)return console.error(`Worker ${e.index} failed, retrying (${r} left):`,s),this.runWorkerWithRetry(e,r-1);throw console.error("Worker failed after all retries:",s),s}}initiateWorker({workerFunc:e,workerName:r,index:s,data:n}){return new Promise((c,o)=>{const a=this.initWorker(e).getWorker;a.onerror=l=>{a.terminate(),o({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:n},failedResult:l})},a.onmessage=l=>{var h,u;if(((h=l.data)==null?void 0:h.ok)===!1){a.terminate(),o({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:n},failedResult:new ErrorEvent("error",{message:l.data.error})});return}c({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:n},successResult:new MessageEvent("message",{data:(u=l.data)==null?void 0:u.data})}),a.terminate()};const i={index:s,...Array.isArray(n)?{data:n}:n};a.postMessage(i,k(i))})}async collectResults(e,r={}){const s=e.results.filter(a=>a.status==="fulfilled"),n=e.results.filter(a=>a.status==="rejected"),c=s.map(a=>a.value.successResult.data),o=r.reducer?r.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((a,i)=>{const l=`
         const reducer = ${o};
         self.addEventListener('message', (event) => {
           try {
@@ -28,4 +31,4 @@ self.addEventListener('message', async (event) => {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `,y=new Blob([u],{type:"application/javascript"}),l=new Worker(URL.createObjectURL(y));l.onmessage=d=>{l.terminate(),d.data.ok?n(d.data.data):i(new Error(d.data.error))},l.onerror=d=>{l.terminate(),i(d)},l.postMessage(c)}),succeeded:s.length,failed:a.length,errors:a}}}exports.MainWorkerFactory=W;exports.WorkerFactory=k;
+      `,h=new Blob([l],{type:"application/javascript"}),u=new Worker(URL.createObjectURL(h));u.onmessage=d=>{u.terminate(),d.data.ok?a(d.data.data):i(new Error(d.data.error))},u.onerror=d=>{u.terminate(),i(d)},u.postMessage(c)}),succeeded:s.length,failed:n.length,errors:n}}}exports.MainWorkerFactory=v;exports.WorkerFactory=p;

package/dist/index.js

@@ -1,6 +1,6 @@
-var y = Object.defineProperty;
-var g = (t, e, r) => e in t ? y(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
-var h = (t, e, r) => g(t, typeof e != "symbol" ? e + "" : e, r);
+var k = Object.defineProperty;
+var y = (t, e, r) => e in t ? k(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
+var p = (t, e, r) => y(t, typeof e != "symbol" ? e + "" : e, r);
 const m = (t) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
@@ -17,82 +17,191 @@ const extractTransferables = (value, seen = new Set()) => {
 };
 
 self.addEventListener('message', async (event) => {
-    const begin = performance.now();
+  try {
     const output = await ${t}(event.data);
-    self.postMessage(output, extractTransferables(output));
-  })
+    self.postMessage({ ok: true, data: output }, extractTransferables(output));
+  } catch (err) {
+    self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+})
 `;
 class w {
+  /**
+   * 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()`.
+   */
   constructor(e) {
-    h(this, "_worker");
+    p(this, "_worker");
     const r = m(e.toString()), s = new Blob([r], {
       type: "application/javascript"
     });
     this._worker = new Worker(URL.createObjectURL(s));
   }
+  /**
+   * Returns the underlying native `Worker` instance.
+   *
+   * Use this to attach `onmessage` / `onerror` handlers and call
+   * `postMessage` / `terminate` directly.
+   */
   get getWorker() {
     return this._worker;
   }
 }
-function p(t, e = /* @__PURE__ */ new Set()) {
-  return t === null || typeof t != "object" ? [] : e.has(t) ? [] : (e.add(t), t instanceof ArrayBuffer || t instanceof MessagePort || typeof ImageBitmap < "u" && t instanceof ImageBitmap || typeof OffscreenCanvas < "u" && t instanceof OffscreenCanvas ? [t] : ArrayBuffer.isView(t) ? [t.buffer] : Array.isArray(t) ? t.flatMap((r) => p(r, e)) : Object.values(t).flatMap(
-    (r) => p(r, e)
+class W {
+  constructor(e) {
+    this.results = e;
+  }
+}
+function g(t, e = /* @__PURE__ */ new Set()) {
+  return t === null || typeof t != "object" ? [] : e.has(t) ? [] : (e.add(t), t instanceof ArrayBuffer || t instanceof MessagePort || typeof ImageBitmap < "u" && t instanceof ImageBitmap || typeof OffscreenCanvas < "u" && t instanceof OffscreenCanvas ? [t] : ArrayBuffer.isView(t) ? [t.buffer] : Array.isArray(t) ? t.flatMap((r) => g(r, e)) : Object.values(t).flatMap(
+    (r) => g(r, e)
   ));
 }
-class v {
-  constructor(e, r) {
-    h(this, "_workers");
-    h(this, "_threads");
-    this._workers = r.workers, this._threads = navigator.hardwareConcurrency;
+class b {
+  /**
+   * Creates a new `MainWorkerFactory`.
+   *
+   * @param options - Configuration object containing the `workers` registry.
+   */
+  constructor(e) {
+    p(this, "_workers");
+    p(this, "_threads");
+    this._workers = e.workers, this._threads = navigator.hardwareConcurrency;
   }
+  /**
+   * 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.
+   */
   initWorker(e) {
     return new w(e);
   }
   /**
-   * 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(e, r) {
     if (!e.length) return [];
     if (r <= 0) throw new Error("numChunks must be positive");
-    const s = Math.min(r, e.length), a = Math.floor(e.length / s), c = e.length % s, o = [];
+    const s = Math.min(r, e.length), n = Math.floor(e.length / s), c = e.length % s, o = [];
     let f = 0;
-    for (let n = 0; n < s; n++) {
-      const i = a + (n < c ? 1 : 0);
+    for (let a = 0; a < s; a++) {
+      const i = n + (a < c ? 1 : 0);
       o.push(e.slice(f, f + i)), f += i;
     }
     return o;
   }
+  /**
+   * 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.
+   */
   findWorkerByName(e) {
     return this._workers.find((r) => r.name === e);
   }
-  async runWorker(e, { srcData: r, ...s }) {
-    const a = this.findWorkerByName(e);
-    if (!a)
+  /**
+   * 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] });
+   */
+  async runWorker(e, {
+    srcData: r,
+    ...s
+  }) {
+    const n = this.findWorkerByName(e);
+    if (!n)
       return Promise.reject(new Error(`Worker "${e}" not found`));
-    const c = a.maxConcurrency ?? this._threads, o = !!(Array.isArray(r) && r.length > 1 && a.partition), f = o ? this.partitionArray(r, c) : r, n = this.createWorkerPromises(
-      a,
+    const c = n.maxConcurrency ?? this._threads, o = !!(Array.isArray(r) && r.length > 1 && n.partition), f = o ? this.partitionArray(r, c) : r, a = this.createWorkerPromises(
+      n,
       e,
       { data: f, ...s },
       c,
       o
-    );
-    return Promise.allSettled(n);
+    ), i = await Promise.allSettled(a);
+    return new W(i);
   }
-  createWorkerPromises(e, r, s, a, c) {
+  /**
+   * 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.
+   */
+  createWorkerPromises(e, r, s, n, c) {
     const { data: o, ...f } = s;
-    return Array.from({ length: a }, (n, i) => {
-      const u = c && Array.isArray(o) ? o[i] : o;
+    return Array.from({ length: n }, (a, i) => {
+      const l = c && Array.isArray(o) ? o[i] : o;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
           workerName: r,
           index: i,
-          data: { data: u, ...f }
+          data: { data: l, ...f }
         },
         e.retries
       );
     });
   }
+  /**
+   * 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.
+   */
   async runWorkerWithRetry(e, r = 2) {
     try {
       return await this.initiateWorker(e);
@@ -105,39 +214,86 @@ class v {
       throw console.error("Worker failed after all retries:", s), s;
     }
   }
+  /**
+   * 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.
+   */
   initiateWorker({
     workerFunc: e,
     workerName: r,
     index: s,
-    data: a
+    data: n
   }) {
     return new Promise((c, o) => {
-      const n = this.initWorker(e).getWorker;
-      n.onerror = (u) => {
-        n.terminate(), o({
+      const a = this.initWorker(e).getWorker;
+      a.onerror = (l) => {
+        a.terminate(), o({
           index: s,
-          workerConfigs: { workerFunc: e, workerName: r, index: s, data: a },
-          failedResult: u
+          workerConfigs: { workerFunc: e, workerName: r, index: s, data: n },
+          failedResult: l
         });
-      }, n.onmessage = (u) => {
+      }, a.onmessage = (l) => {
+        var h, u;
+        if (((h = l.data) == null ? void 0 : h.ok) === !1) {
+          a.terminate(), o({
+            index: s,
+            workerConfigs: { workerFunc: e, workerName: r, index: s, data: n },
+            failedResult: new ErrorEvent("error", {
+              message: l.data.error
+            })
+          });
+          return;
+        }
         c({
           index: s,
-          workerConfigs: { workerFunc: e, workerName: r, index: s, data: a },
-          successResult: u
-        }), n.terminate();
+          workerConfigs: { workerFunc: e, workerName: r, index: s, data: n },
+          successResult: new MessageEvent("message", {
+            data: (u = l.data) == null ? void 0 : u.data
+          })
+        }), a.terminate();
       };
       const i = {
         index: s,
-        ...Array.isArray(a) ? { data: a } : a
+        ...Array.isArray(n) ? { data: n } : n
       };
-      n.postMessage(i, p(i));
+      a.postMessage(i, g(i));
     });
   }
   /**
-   * 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`.
+   *
+   * @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.
    *
-   * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
-   * @param options  Optional `reducer` function (must be self-contained)
+   * @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
@@ -150,14 +306,14 @@ class v {
    * });
    */
   async collectResults(e, r = {}) {
-    const s = e.filter(
-      (n) => n.status === "fulfilled"
-    ), a = e.filter(
-      (n) => n.status === "rejected"
-    ), c = s.map((n) => n.value.successResult.data), o = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
+    const s = e.results.filter(
+      (a) => a.status === "fulfilled"
+    ), n = e.results.filter(
+      (a) => a.status === "rejected"
+    ), c = s.map((a) => a.value.successResult.data), o = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
     return {
-      data: await new Promise((n, i) => {
-        const u = `
+      data: await new Promise((a, i) => {
+        const l = `
         const reducer = ${o};
         self.addEventListener('message', (event) => {
           try {
@@ -167,20 +323,20 @@ class v {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, k = new Blob([u], { type: "application/javascript" }), l = new Worker(URL.createObjectURL(k));
-        l.onmessage = (d) => {
-          l.terminate(), d.data.ok ? n(d.data.data) : i(new Error(d.data.error));
-        }, l.onerror = (d) => {
-          l.terminate(), i(d);
-        }, l.postMessage(c);
+      `, h = new Blob([l], { type: "application/javascript" }), u = new Worker(URL.createObjectURL(h));
+        u.onmessage = (d) => {
+          u.terminate(), d.data.ok ? a(d.data.data) : i(new Error(d.data.error));
+        }, u.onerror = (d) => {
+          u.terminate(), i(d);
+        }, u.postMessage(c);
       }),
       succeeded: s.length,
-      failed: a.length,
-      errors: a
+      failed: n.length,
+      errors: n
     };
   }
 }
 export {
-  v as MainWorkerFactory,
+  b as MainWorkerFactory,
   w as WorkerFactory
 };

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, 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`.
+     *
+     * @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.
      *
-     * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
-     * @param options  Optional `reducer` function (must be self-contained)
+     * @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,6 @@ 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>>;
 }
 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[]> {
     /**

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

@@ -1,7 +1,34 @@
 import { WorkerFunction } from '../main-worker-factory/types';
+/**
+ * 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;
+    /**
+     * 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()`.
+     */
     constructor(workerFunction: WorkerFunction);
+    /**
+     * 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.8",
+  "version": "0.9.2",
   "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 {};