@offmain/workerkit 0.9.2 → 0.10.0

package/README.md

@@ -92,6 +92,68 @@ const { data } = await factory.collectResults(settled, {
 
 ---
 
+## Pipeline
+
+Chain multiple workers together so data flows directly between them via `MessageChannel` — without passing through the main thread between steps.
+
+### Why use a pipeline?
+
+In a traditional multi-step workflow, intermediate data is serialized back to the main thread after each step:
+
+```
+Main → Worker A → Main → Worker B → Main → Worker C → Main
+         ↑ serialize    ↑ serialize    ↑ serialize
+```
+
+With large datasets (100k+ records), each serialization round-trip adds significant overhead — both in time and memory pressure on the main thread. The pipeline eliminates this:
+
+```
+Main → Worker A → Worker B → Worker C → Main
+                ↑ MessageChannel      ↑ only final result
+```
+
+Only the final result crosses back to the main thread. If your pipeline generates 20 MB of intermediate data but produces a 1 KB summary, you save ~40 MB of serialization (two round-trips avoided).
+
+### Usage
+
+```ts
+import { MainWorkerFactory } from '@offmain/workerkit';
+import { fetchData, transform, aggregate } from './workers.ts';
+
+const factory = new MainWorkerFactory({
+  workers: [
+    { name: 'fetchData', role: 'io', func: fetchData },
+    { name: 'transform', role: 'compute', func: transform },
+    { name: 'aggregate', role: 'compute', func: aggregate },
+  ] as const,
+});
+
+const result = await factory.pipeline<AggregateResult>([
+  { worker: 'fetchData', srcData: { url: '/api/records' } },
+  { worker: 'transform' }, // receives fetchData output directly
+  { worker: 'aggregate' }, // receives transform output directly
+]);
+
+console.log(result); // only this small result crossed to main thread
+```
+
+### How each step receives data
+
+- The first step receives `srcData` as `{ data: srcData, index: 0 }` — same as `runWorker`.
+- Each subsequent step receives the previous step's output as `{ data: previousOutput, index: 0 }`.
+- Worker functions don't need any special handling — they use the same `{ data }` parameter signature as regular workers.
+
+### When to use pipeline vs runWorker
+
+| Scenario                                             | Use                     |
+| ---------------------------------------------------- | ----------------------- |
+| Single step, or steps that need partitioning/retries | `runWorker`             |
+| Multi-step chain where intermediate data is large    | `pipeline`              |
+| Steps that are independent (not sequential)          | `runWorker` in parallel |
+| Steps where only the final result matters to the UI  | `pipeline`              |
+
+---
+
 ## ESLint Plugin
 
 The package ships with two ESLint rules to catch common worker mistakes at lint time.

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"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=>`
+"use strict";var w=Object.defineProperty;var y=(o,e,t)=>e in o?w(o,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):o[e]=t;var h=(o,e,t)=>y(o,typeof e!="symbol"?e+"":e,t);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=o=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -15,14 +15,86 @@ const extractTransferables = (value, seen = new Set()) => {
 
 self.addEventListener('message', async (event) => {
   try {
-    const output = await ${t}(event.data);
+    const output = await ${o}(event.data);
     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};
+`,v=o=>`
+const extractTransferables = (value, seen = new Set()) => {
+  if (value === null || typeof value !== 'object') return [];
+  if (seen.has(value)) return [];
+  seen.add(value);
+  if (value instanceof ArrayBuffer || value instanceof MessagePort ||
+      (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap) ||
+      (typeof OffscreenCanvas !== 'undefined' && value instanceof OffscreenCanvas)) {
+    return [value];
+  }
+  if (ArrayBuffer.isView(value)) return [value.buffer];
+  if (Array.isArray(value)) return value.flatMap(i => extractTransferables(i, seen));
+  return Object.values(value).flatMap(v => extractTransferables(v, seen));
+};
+
+const workerFn = ${o};
+let outputPort = null;
+let inputPort = null;
+let pendingData = null;
+
+async function processData(data) {
+  try {
+    const output = await workerFn(data);
+    const result = { ok: true, data: output };
+    const transfers = extractTransferables(output);
+    if (outputPort) {
+      outputPort.postMessage(result, transfers);
+    } else {
+      self.postMessage(result, transfers);
+    }
+  } catch (err) {
+    const result = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    if (outputPort) {
+      outputPort.postMessage(result);
+    } else {
+      self.postMessage(result);
+    }
+  }
+}
+
+self.addEventListener('message', (event) => {
+  if (event.data && event.data.__pipeline_ports__) {
+    if (event.data.outputPort) {
+      outputPort = event.data.outputPort;
+    }
+    if (event.data.inputPort) {
+      inputPort = event.data.inputPort;
+      inputPort.onmessage = (e) => {
+        if (e.data && e.data.ok === false) {
+          // Propagate errors through the pipeline
+          if (outputPort) outputPort.postMessage(e.data);
+          else self.postMessage(e.data);
+        } else {
+          processData({ data: e.data.data, index: 0 });
+        }
+      };
+    }
+    // If we already received data before ports, process it now
+    if (pendingData !== null) {
+      processData(pendingData);
+      pendingData = null;
+    }
+    return;
+  }
+  // First worker in pipeline or standalone — process directly
+  if (!inputPort) {
+    processData(event.data);
+  } else {
+    // Store data until ports are configured
+    pendingData = event.data;
+  }
+});
+`;class k{constructor(e,t){h(this,"_worker");const a=(t!=null&&t.pipeline?v:m)(e.toString()),u=new Blob([a],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(u))}get getWorker(){return this._worker}}class P{constructor(e){this.results=e}}function g(o,e=new Set){return o===null||typeof o!="object"?[]:e.has(o)?[]:(e.add(o),o instanceof ArrayBuffer||o instanceof MessagePort||typeof ImageBitmap<"u"&&o instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&o instanceof OffscreenCanvas?[o]:ArrayBuffer.isView(o)?[o.buffer]:Array.isArray(o)?o.flatMap(t=>g(t,e)):Object.values(o).flatMap(t=>g(t,e)))}class W{constructor(e){h(this,"_workers");h(this,"_threads");this._workers=e.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new k(e)}partitionArray(e,t){if(!e.length)return[];if(t<=0)throw new Error("numChunks must be positive");const n=Math.min(t,e.length),a=Math.floor(e.length/n),u=e.length%n,l=[];let f=0;for(let r=0;r<n;r++){const s=a+(r<u?1:0);l.push(e.slice(f,f+s)),f+=s}return l}findWorkerByName(e){return this._workers.find(t=>t.name===e)}async runWorker(e,{srcData:t,...n}){const a=this.findWorkerByName(e);if(!a)return Promise.reject(new Error(`Worker "${e}" not found`));const u=a.maxConcurrency??this._threads,l=!!(Array.isArray(t)&&t.length>1&&a.partition),f=l?this.partitionArray(t,u):t,r=this.createWorkerPromises(a,e,{data:f,...n},u,l),s=await Promise.allSettled(r);return new P(s)}createWorkerPromises(e,t,n,a,u){const{data:l,...f}=n;return Array.from({length:a},(r,s)=>{const i=u&&Array.isArray(l)?l[s]:l;return this.runWorkerWithRetry({workerFunc:e.func,workerName:t,index:s,data:{data:i,...f}},e.retries)})}async runWorkerWithRetry(e,t=2){try{return await this.initiateWorker(e)}catch(n){if(t>0)return console.error(`Worker ${e.index} failed, retrying (${t} left):`,n),this.runWorkerWithRetry(e,t-1);throw console.error("Worker failed after all retries:",n),n}}initiateWorker({workerFunc:e,workerName:t,index:n,data:a}){return new Promise((u,l)=>{const r=this.initWorker(e).getWorker;r.onerror=i=>{r.terminate(),l({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},failedResult:i})},r.onmessage=i=>{var c,p;if(((c=i.data)==null?void 0:c.ok)===!1){r.terminate(),l({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},failedResult:new ErrorEvent("error",{message:i.data.error})});return}u({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},successResult:new MessageEvent("message",{data:(p=i.data)==null?void 0:p.data})}),r.terminate()};const s={index:n,...Array.isArray(a)?{data:a}:a};r.postMessage(s,g(s))})}async collectResults(e,t={}){const n=e.results.filter(r=>r.status==="fulfilled"),a=e.results.filter(r=>r.status==="rejected"),u=n.map(r=>r.value.successResult.data),l=t.reducer?t.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((r,s)=>{const i=`
+        const reducer = ${l};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -31,4 +103,4 @@ self.addEventListener('message', async (event) => {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `,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;
+      `,c=new Blob([i],{type:"application/javascript"}),p=new Worker(URL.createObjectURL(c));p.onmessage=d=>{p.terminate(),d.data.ok?r(d.data.data):s(new Error(d.data.error))},p.onerror=d=>{p.terminate(),s(d)},p.postMessage(u)}),succeeded:n.length,failed:a.length,errors:a}}async pipeline(e){if(e.length===0)throw new Error("Pipeline requires at least one step");if(e.length===1){const t=e[0],n=this.findWorkerByName(t.worker);if(!n)throw new Error(`Worker "${t.worker}" not found`);const u=this.initWorker(n.func).getWorker;return new Promise((l,f)=>{u.onmessage=s=>{var i,c;u.terminate(),((i=s.data)==null?void 0:i.ok)===!1?f(new Error(s.data.error)):l((c=s.data)==null?void 0:c.data)},u.onerror=s=>{u.terminate(),f(s)};const r=t.srcData??{};u.postMessage({data:r,index:0},g(r))})}return new Promise((t,n)=>{const a=[],u=[];for(const r of e){const s=this.findWorkerByName(r.worker);if(!s){n(new Error(`Worker "${r.worker}" not found`));return}const i=new k(s.func,{pipeline:!0});a.push(i.getWorker)}for(let r=0;r<a.length-1;r++)u.push(new MessageChannel);for(let r=0;r<a.length;r++){const s=[],i={};r>0&&(i.inputPort=u[r-1].port1,s.push(i.inputPort)),r<a.length-1&&(i.outputPort=u[r].port2,s.push(i.outputPort)),a[r].postMessage({__pipeline_ports__:!0,...i},s)}const l=a[a.length-1];l.onmessage=r=>{var s,i;a.forEach(c=>c.terminate()),((s=r.data)==null?void 0:s.ok)===!1?n(new Error(r.data.error)):t((i=r.data)==null?void 0:i.data)},l.onerror=r=>{a.forEach(s=>s.terminate()),n(r)};const f=e[0].srcData??{};a[0].postMessage({data:f,index:0},g(f))})}}exports.MainWorkerFactory=W;exports.WorkerFactory=k;

package/dist/index.js

@@ -1,7 +1,7 @@
-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) => `
+var w = Object.defineProperty;
+var m = (o, e, t) => e in o ? w(o, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : o[e] = t;
+var h = (o, e, t) => m(o, typeof e != "symbol" ? e + "" : e, t);
+const y = (o) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -18,14 +18,86 @@ const extractTransferables = (value, seen = new Set()) => {
 
 self.addEventListener('message', async (event) => {
   try {
-    const output = await ${t}(event.data);
+    const output = await ${o}(event.data);
     self.postMessage({ ok: true, data: output }, extractTransferables(output));
   } catch (err) {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
+`, v = (o) => `
+const extractTransferables = (value, seen = new Set()) => {
+  if (value === null || typeof value !== 'object') return [];
+  if (seen.has(value)) return [];
+  seen.add(value);
+  if (value instanceof ArrayBuffer || value instanceof MessagePort ||
+      (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap) ||
+      (typeof OffscreenCanvas !== 'undefined' && value instanceof OffscreenCanvas)) {
+    return [value];
+  }
+  if (ArrayBuffer.isView(value)) return [value.buffer];
+  if (Array.isArray(value)) return value.flatMap(i => extractTransferables(i, seen));
+  return Object.values(value).flatMap(v => extractTransferables(v, seen));
+};
+
+const workerFn = ${o};
+let outputPort = null;
+let inputPort = null;
+let pendingData = null;
+
+async function processData(data) {
+  try {
+    const output = await workerFn(data);
+    const result = { ok: true, data: output };
+    const transfers = extractTransferables(output);
+    if (outputPort) {
+      outputPort.postMessage(result, transfers);
+    } else {
+      self.postMessage(result, transfers);
+    }
+  } catch (err) {
+    const result = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    if (outputPort) {
+      outputPort.postMessage(result);
+    } else {
+      self.postMessage(result);
+    }
+  }
+}
+
+self.addEventListener('message', (event) => {
+  if (event.data && event.data.__pipeline_ports__) {
+    if (event.data.outputPort) {
+      outputPort = event.data.outputPort;
+    }
+    if (event.data.inputPort) {
+      inputPort = event.data.inputPort;
+      inputPort.onmessage = (e) => {
+        if (e.data && e.data.ok === false) {
+          // Propagate errors through the pipeline
+          if (outputPort) outputPort.postMessage(e.data);
+          else self.postMessage(e.data);
+        } else {
+          processData({ data: e.data.data, index: 0 });
+        }
+      };
+    }
+    // If we already received data before ports, process it now
+    if (pendingData !== null) {
+      processData(pendingData);
+      pendingData = null;
+    }
+    return;
+  }
+  // First worker in pipeline or standalone — process directly
+  if (!inputPort) {
+    processData(event.data);
+  } else {
+    // Store data until ports are configured
+    pendingData = event.data;
+  }
+});
 `;
-class w {
+class k {
   /**
    * Creates a new `Worker` from the given function.
    *
@@ -35,13 +107,15 @@ class w {
    * @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(e) {
-    p(this, "_worker");
-    const r = m(e.toString()), s = new Blob([r], {
+  constructor(e, t) {
+    h(this, "_worker");
+    const a = (t != null && t.pipeline ? v : y)(e.toString()), u = new Blob([a], {
       type: "application/javascript"
     });
-    this._worker = new Worker(URL.createObjectURL(s));
+    this._worker = new Worker(URL.createObjectURL(u));
   }
   /**
    * Returns the underlying native `Worker` instance.
@@ -53,25 +127,25 @@ class w {
     return this._worker;
   }
 }
-class W {
+class P {
   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)
+function g(o, e = /* @__PURE__ */ new Set()) {
+  return o === null || typeof o != "object" ? [] : e.has(o) ? [] : (e.add(o), o instanceof ArrayBuffer || o instanceof MessagePort || typeof ImageBitmap < "u" && o instanceof ImageBitmap || typeof OffscreenCanvas < "u" && o instanceof OffscreenCanvas ? [o] : ArrayBuffer.isView(o) ? [o.buffer] : Array.isArray(o) ? o.flatMap((t) => g(t, e)) : Object.values(o).flatMap(
+    (t) => g(t, e)
   ));
 }
-class b {
+class M {
   /**
    * Creates a new `MainWorkerFactory`.
    *
    * @param options - Configuration object containing the `workers` registry.
    */
   constructor(e) {
-    p(this, "_workers");
-    p(this, "_threads");
+    h(this, "_workers");
+    h(this, "_threads");
     this._workers = e.workers, this._threads = navigator.hardwareConcurrency;
   }
   /**
@@ -81,7 +155,7 @@ class b {
    * @returns A new `WorkerFactory` wrapping the worker.
    */
   initWorker(e) {
-    return new w(e);
+    return new k(e);
   }
   /**
    * Splits an array into up to `numChunks` evenly-sized sub-arrays.
@@ -99,16 +173,16 @@ class b {
    * partitionArray([1, 2, 3, 4, 5], 3);
    * // → [[1, 2], [3, 4], [5]]
    */
-  partitionArray(e, r) {
+  partitionArray(e, t) {
     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 = [];
+    if (t <= 0) throw new Error("numChunks must be positive");
+    const n = Math.min(t, e.length), a = Math.floor(e.length / n), u = e.length % n, l = [];
     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;
+    for (let r = 0; r < n; r++) {
+      const s = a + (r < u ? 1 : 0);
+      l.push(e.slice(f, f + s)), f += s;
     }
-    return o;
+    return l;
   }
   /**
    * Looks up a registered worker configuration by name.
@@ -117,7 +191,7 @@ class b {
    * @returns The matching config, or `undefined` if not found.
    */
   findWorkerByName(e) {
-    return this._workers.find((r) => r.name === e);
+    return this._workers.find((t) => t.name === e);
   }
   /**
    * Runs a named worker against the provided data, distributing work across
@@ -146,20 +220,20 @@ class b {
    * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3] });
    */
   async runWorker(e, {
-    srcData: r,
-    ...s
+    srcData: t,
+    ...n
   }) {
-    const n = this.findWorkerByName(e);
-    if (!n)
+    const a = this.findWorkerByName(e);
+    if (!a)
       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,
+    const u = a.maxConcurrency ?? this._threads, l = !!(Array.isArray(t) && t.length > 1 && a.partition), f = l ? this.partitionArray(t, u) : t, r = this.createWorkerPromises(
+      a,
       e,
-      { data: f, ...s },
-      c,
-      o
-    ), i = await Promise.allSettled(a);
-    return new W(i);
+      { data: f, ...n },
+      u,
+      l
+    ), s = await Promise.allSettled(r);
+    return new P(s);
   }
   /**
    * Builds the array of per-thread worker promises for a single `runWorker`
@@ -175,16 +249,16 @@ class b {
    * @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: n }, (a, i) => {
-      const l = c && Array.isArray(o) ? o[i] : o;
+  createWorkerPromises(e, t, n, a, u) {
+    const { data: l, ...f } = n;
+    return Array.from({ length: a }, (r, s) => {
+      const i = u && Array.isArray(l) ? l[s] : l;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
-          workerName: r,
-          index: i,
-          data: { data: l, ...f }
+          workerName: t,
+          index: s,
+          data: { data: i, ...f }
         },
         e.retries
       );
@@ -202,16 +276,16 @@ class b {
    * @returns The successful {@link WorkerResult} once the worker resolves.
    * @throws The last caught error when all retries are exhausted.
    */
-  async runWorkerWithRetry(e, r = 2) {
+  async runWorkerWithRetry(e, t = 2) {
     try {
       return await this.initiateWorker(e);
-    } catch (s) {
-      if (r > 0)
+    } catch (n) {
+      if (t > 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;
+          `Worker ${e.index} failed, retrying (${t} left):`,
+          n
+        ), this.runWorkerWithRetry(e, t - 1);
+      throw console.error("Worker failed after all retries:", n), n;
     }
   }
   /**
@@ -234,43 +308,43 @@ class b {
    */
   initiateWorker({
     workerFunc: e,
-    workerName: r,
-    index: s,
-    data: n
+    workerName: t,
+    index: n,
+    data: a
   }) {
-    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
+    return new Promise((u, l) => {
+      const r = this.initWorker(e).getWorker;
+      r.onerror = (i) => {
+        r.terminate(), l({
+          index: n,
+          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+          failedResult: i
         });
-      }, 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 },
+      }, r.onmessage = (i) => {
+        var c, p;
+        if (((c = i.data) == null ? void 0 : c.ok) === !1) {
+          r.terminate(), l({
+            index: n,
+            workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
             failedResult: new ErrorEvent("error", {
-              message: l.data.error
+              message: i.data.error
             })
           });
           return;
         }
-        c({
-          index: s,
-          workerConfigs: { workerFunc: e, workerName: r, index: s, data: n },
+        u({
+          index: n,
+          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
           successResult: new MessageEvent("message", {
-            data: (u = l.data) == null ? void 0 : u.data
+            data: (p = i.data) == null ? void 0 : p.data
           })
-        }), a.terminate();
+        }), r.terminate();
       };
-      const i = {
-        index: s,
-        ...Array.isArray(n) ? { data: n } : n
+      const s = {
+        index: n,
+        ...Array.isArray(a) ? { data: a } : a
       };
-      a.postMessage(i, g(i));
+      r.postMessage(s, g(s));
     });
   }
   /**
@@ -305,16 +379,16 @@ class b {
    *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
    * });
    */
-  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()";
+  async collectResults(e, t = {}) {
+    const n = e.results.filter(
+      (r) => r.status === "fulfilled"
+    ), a = e.results.filter(
+      (r) => r.status === "rejected"
+    ), u = n.map((r) => r.value.successResult.data), l = t.reducer ? t.reducer.toString() : "(shards) => shards.flat()";
     return {
-      data: await new Promise((a, i) => {
-        const l = `
-        const reducer = ${o};
+      data: await new Promise((r, s) => {
+        const i = `
+        const reducer = ${l};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -323,20 +397,96 @@ class b {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, 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);
+      `, c = new Blob([i], { type: "application/javascript" }), p = new Worker(URL.createObjectURL(c));
+        p.onmessage = (d) => {
+          p.terminate(), d.data.ok ? r(d.data.data) : s(new Error(d.data.error));
+        }, p.onerror = (d) => {
+          p.terminate(), s(d);
+        }, p.postMessage(u);
       }),
-      succeeded: s.length,
-      failed: n.length,
-      errors: n
+      succeeded: n.length,
+      failed: a.length,
+      errors: a
     };
   }
+  /**
+   * 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
+   */
+  async pipeline(e) {
+    if (e.length === 0)
+      throw new Error("Pipeline requires at least one step");
+    if (e.length === 1) {
+      const t = e[0], n = this.findWorkerByName(t.worker);
+      if (!n) throw new Error(`Worker "${t.worker}" not found`);
+      const u = this.initWorker(n.func).getWorker;
+      return new Promise((l, f) => {
+        u.onmessage = (s) => {
+          var i, c;
+          u.terminate(), ((i = s.data) == null ? void 0 : i.ok) === !1 ? f(new Error(s.data.error)) : l((c = s.data) == null ? void 0 : c.data);
+        }, u.onerror = (s) => {
+          u.terminate(), f(s);
+        };
+        const r = t.srcData ?? {};
+        u.postMessage(
+          { data: r, index: 0 },
+          g(r)
+        );
+      });
+    }
+    return new Promise((t, n) => {
+      const a = [], u = [];
+      for (const r of e) {
+        const s = this.findWorkerByName(r.worker);
+        if (!s) {
+          n(new Error(`Worker "${r.worker}" not found`));
+          return;
+        }
+        const i = new k(s.func, { pipeline: !0 });
+        a.push(i.getWorker);
+      }
+      for (let r = 0; r < a.length - 1; r++)
+        u.push(new MessageChannel());
+      for (let r = 0; r < a.length; r++) {
+        const s = [], i = {};
+        r > 0 && (i.inputPort = u[r - 1].port1, s.push(i.inputPort)), r < a.length - 1 && (i.outputPort = u[r].port2, s.push(i.outputPort)), a[r].postMessage(
+          { __pipeline_ports__: !0, ...i },
+          s
+        );
+      }
+      const l = a[a.length - 1];
+      l.onmessage = (r) => {
+        var s, i;
+        a.forEach((c) => c.terminate()), ((s = r.data) == null ? void 0 : s.ok) === !1 ? n(new Error(r.data.error)) : t((i = r.data) == null ? void 0 : i.data);
+      }, l.onerror = (r) => {
+        a.forEach((s) => s.terminate()), n(r);
+      };
+      const f = e[0].srcData ?? {};
+      a[0].postMessage(
+        { data: f, index: 0 },
+        g(f)
+      );
+    });
+  }
 }
 export {
-  b as MainWorkerFactory,
-  w as WorkerFactory
+  M as MainWorkerFactory,
+  k as WorkerFactory
 };

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

@@ -1,2 +1,2 @@
 export { default as MainWorkerFactory } from './main-worker-factory.ts';
-export type { WorkerFunction, MainWorkerFactoryWorker, MainWorkerFactoryOptions, WorkerConfig, WorkerName, WorkerRole, } from './types.ts';
+export type { WorkerFunction, MainWorkerFactoryWorker, MainWorkerFactoryOptions, PipelineStep, WorkerConfig, WorkerName, WorkerRole, } from './types.ts';

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

@@ -1,4 +1,4 @@
-import { CollectOptions, CollectedResult, WorkerConfig, WorkerConfigMap, WorkerDataParam, WorkerFunction, WorkerReturnType, TypedSettledResults } 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)
@@ -176,5 +176,27 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
      * });
      */
     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

@@ -147,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,4 +1,8 @@
 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.
@@ -21,8 +25,10 @@ declare class WorkerFactory {
      * @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);
+    constructor(workerFunction: WorkerFunction, options?: WorkerFactoryOptions);
     /**
      * Returns the underlying native `Worker` instance.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offmain/workerkit",
-  "version": "0.9.2",
+  "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",