@offmain/workerkit 0.12.3 → 0.14.0

package/README.md

@@ -57,48 +57,55 @@ console.log(data); // [15]
 
 ## WorkerConfig Options
 
-| Option           | Type            | Default                         | Description                                                                                         |
-| ---------------- | --------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `name`           | `string`        | —                               | Unique identifier used to call the worker                                                           |
-| `role`           | `string`        | —                               | Logical grouping label                                                                              |
-| `func`           | `Function`      | —                               | The exported worker function to run (optional if `workerURL` is provided)                           |
-| `workerURL`      | `string \| URL` | —                               | Worker script URL or `new URL(..., import.meta.url)` for module bundlers                            |
-| `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 before marking it as rejected                                |
-| `partition`      | `boolean`       | `false`                         | Split array input across multiple workers automatically                                             |
+| Option           | Type           | Default                         | Description                                                                                         |
+| ---------------- | -------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `name`           | `string`       | —                               | Unique identifier used to call the worker                                                           |
+| `role`           | `string`       | —                               | Logical grouping label                                                                              |
+| `func`           | `Function`     | —                               | The exported worker function to run (optional if `createWorker` is provided)                        |
+| `createWorker`   | `() => Worker` | —                               | Worker factory function `() => new Worker(new URL(...))` for Webpack 5 / Vite static analysis       |
+| `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 before marking it as rejected                                |
+| `partition`      | `boolean`      | `false`                         | Split array input across multiple workers automatically                                             |
 
 ---
 
-## Module Bundler Integration (`workerURL`)
+## Module Bundler Integration (`createWorker`)
 
 When worker logic relies on external npm packages (such as Luxon, `date-fns`, `i18next`, or custom data transformation modules), dynamic inline stringification (`.toString()`) cannot access those closed-over imports.
 
-Passing `workerURL` enables modern module bundlers (Webpack 5, Vite, Rollup, Parcel) to analyze and bundle the worker file along with all of its dependencies into a dedicated ES module worker chunk.
+Passing `createWorker` enables modern module bundlers (Webpack 5, Vite, Rollup, Parcel) to analyze and bundle the worker file along with all of its dependencies into a dedicated ES module worker chunk.
 
-### Dedicated Worker Script
+### Dedicated Worker Script with `defineWorker`
+
+When writing standalone worker files, wrap your export in `defineWorker`. This automatically handles standard runs, worker-to-worker pipelines (`pipeline()`), and persistent dataset caching without manual `postMessage` / `onmessage` boilerplate:
 
 ```ts
 // transform-data.worker.ts
+import { defineWorker } from '@offmain/workerkit';
 import { format } from 'date-fns';
 import { t } from './i18n.ts';
 
-self.addEventListener('message', (event) => {
-  try {
-    const { items, locale } = event.data.data;
-    const result = items.map((item: any) => ({
+export default defineWorker(
+  async ({
+    data,
+    options,
+  }: {
+    data: { items: any[]; locale: string };
+    options?: { prefix?: string };
+  }) => {
+    const { items, locale } = data;
+    return items.map((item: any) => ({
       ...item,
       formattedDate: format(new Date(item.timestamp), 'yyyy-MM-dd'),
-      label: t('transaction', locale),
+      label: (options?.prefix ?? '') + t('transaction', locale),
     }));
-
-    self.postMessage({ ok: true, data: result });
-  } catch (err) {
-    self.postMessage({ ok: false, error: (err as Error).message });
-  }
-});
+  },
+);
 ```
 
-### Registering with `workerURL`
+### Webpack 5 & Vite Static Analysis (`createWorker`)
+
+Webpack 5 and Vite look for literal `new Worker(new URL(..., import.meta.url))` calls inside consumer source files. By providing a `createWorker` factory function, bundlers statically detect and bundle the worker into a separate JS file, while allowing `MainWorkerFactory` to scale `maxConcurrency` across multiple threads:
 
 ```ts
 import { MainWorkerFactory } from '@offmain/workerkit';
@@ -108,9 +115,13 @@ const factory = new MainWorkerFactory({
     {
       name: 'transformData',
       role: 'compute',
-      // Webpack 5 / Vite statically analyzes new URL(..., import.meta.url)
-      workerURL: new URL('./transform-data.worker.ts', import.meta.url),
-      maxConcurrency: 4,
+      // Webpack 5 and Vite statically analyze new Worker(new URL(..., import.meta.url))
+      // written inside this factory function and emit an individual bundled JS chunk.
+      createWorker: () =>
+        new Worker(new URL('./transform-data.worker.ts', import.meta.url), {
+          type: 'module',
+        }),
+      maxConcurrency: 4, // Spawns up to 4 parallel worker instances
     },
   ] as const,
 });
@@ -170,7 +181,7 @@ Only the final result crosses back to the main thread. If your pipeline generate
 
 ### Usage
 
-```ts
+````ts
 import { MainWorkerFactory } from '@offmain/workerkit';
 import { fetchData, transform, aggregate } from './workers.ts';
 
@@ -182,20 +193,33 @@ const factory = new MainWorkerFactory({
   ] as const,
 });
 
+### Step-Specific Options and Configs in Pipeline
+
+You can pass step-specific parameters (such as `options`, `configs`, etc.) directly to each pipeline step:
+
+```ts
 const result = await factory.pipeline<AggregateResult>([
-  { worker: 'fetchData', srcData: { url: '/api/records' } },
-  { worker: 'transform' }, // receives fetchData output directly
-  { worker: 'aggregate' }, // receives transform output directly
+  {
+    worker: 'fetchData',
+    srcData: { url: '/api/records' },
+    options: { timeout: 5000 },
+  },
+  {
+    worker: 'transform',
+    configs: { multiplier: 2 },
+  },
+  {
+    worker: 'aggregate',
+    options: { threshold: 10 },
+  },
 ]);
+````
 
-console.log(result); // only this small result crossed to main thread
-```
-
-### How each step receives data
+### How each step receives data and parameters
 
-- 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.
+- The first step receives `srcData` merged with its step parameters as `{ data: srcData, options: { timeout: 5000 }, index: 0 }`.
+- Each subsequent step receives the previous step's output merged with its step parameters as `{ data: previousOutput, configs: { multiplier: 2 }, index: 0 }`.
+- Worker functions (both inline functions and native scripts using `defineWorker`) receive all step parameters in their first argument.
 
 ### When to use pipeline vs runWorker
 
@@ -304,11 +328,42 @@ The framework handles the caching transparently — your function always receive
 
 The cached dataset lives in worker memory until `release()` is called. For large datasets, always call `release()` when you're done to free the memory:
 
+After releasing, the next `runPersistent` call will create a fresh worker instance (requiring a new dataset).
+
+---
+
+## Lifecycle Management (`terminate`, `destroy`, `reset`, `restart`)
+
+`MainWorkerFactory` provides built-in lifecycle management to terminate running workers and clean up browser resources:
+
+### `terminate()` / `destroy()`
+
+Immediately stops all active workers (one-shot tasks, pipelines, reducers) and releases all cached persistent workers:
+
 ```ts
-factory.release('transform');
+// Stop all active threads and release persistent workers
+factory.terminate();
+// or
+factory.destroy(); // Alias for terminate()
+
+console.log(factory.isTerminated); // true
 ```
 
-After releasing, the next `runPersistent` call will create a fresh worker instance (requiring a new dataset).
+After calling `terminate()`, any attempt to run workers on the factory instance will immediately reject.
+
+### `reset()` / `restart()`
+
+Terminates all active/persistent worker instances and restores the factory to an active state (`isTerminated = false`), allowing new worker instances to be initiated cleanly:
+
+```ts
+// Stop existing workers and reset factory state
+factory.reset(); // or factory.restart()
+
+console.log(factory.isTerminated); // false
+
+// Factory is ready to initiate fresh worker instances again
+const settled = await factory.runWorker('sum', { srcData: [1, 2, 3] });
+```
 
 ---
 

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"use strict";var v=Object.defineProperty;var y=(n,e,r)=>e in n?v(n,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):n[e]=r;var k=(n,e,r)=>y(n,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=n=>`
+"use strict";var S=Object.defineProperty;var x=(n,e,r)=>e in n?S(n,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):n[e]=r;var y=(n,e,r)=>x(n,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const O=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -21,7 +21,7 @@ self.addEventListener('message', async (event) => {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
-`,P=n=>`
+`,F=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -40,10 +40,15 @@ const workerFn = ${n};
 let outputPort = null;
 let inputPort = null;
 let pendingData = null;
+let stepParams = {};
 
 async function processData(data) {
   try {
-    const output = await workerFn(data);
+    const payload =
+      typeof data === 'object' && data !== null && 'data' in data
+        ? { ...stepParams, ...data }
+        : { data, ...stepParams, index: 0 };
+    const output = await workerFn(payload);
     const result = { ok: true, data: output };
     const transfers = extractTransferables(output);
     if (outputPort) {
@@ -63,6 +68,9 @@ async function processData(data) {
 
 self.addEventListener('message', (event) => {
   if (event.data && event.data.__pipeline_ports__) {
+    if (event.data.stepParams) {
+      stepParams = event.data.stepParams;
+    }
     if (event.data.outputPort) {
       outputPort = event.data.outputPort;
     }
@@ -74,7 +82,7 @@ self.addEventListener('message', (event) => {
           if (outputPort) outputPort.postMessage(e.data);
           else self.postMessage(e.data);
         } else {
-          processData({ data: e.data.data, index: 0 });
+          processData({ data: e.data.data, ...stepParams, index: 0 });
         }
       };
     }
@@ -93,7 +101,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`,W=n=>`
+`,R=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -149,8 +157,8 @@ self.addEventListener('message', async (event) => {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 });
-`;var w=(n=>(n.Default="default",n.Pipeline="pipeline",n.Persistent="persistent",n))(w||{});const M=Object.freeze({persistent:W,pipeline:P,default:m});class h{constructor(e,r){k(this,"_worker");if(r!=null&&r.workerInstance)this._worker=r.workerInstance;else if(r!=null&&r.workerURL)this._worker=new Worker(r.workerURL,{type:"module"});else if(e){const o=(r==null?void 0:r.mode)??"default",a=M[o](e.toString()),i=new Blob([a],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(i))}else throw new Error("Either workerFunction or options.workerURL must be provided to WorkerFactory.")}get getWorker(){return this._worker}}class b{constructor(e){this.results=e}}function g(n,e=new Set){return n===null||typeof n!="object"?[]:e.has(n)?[]:(e.add(n),n instanceof ArrayBuffer||n instanceof MessagePort||typeof ImageBitmap<"u"&&n instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&n instanceof OffscreenCanvas?[n]:ArrayBuffer.isView(n)?[n.buffer]:Array.isArray(n)?n.flatMap(r=>g(r,e)):Object.values(n).flatMap(r=>g(r,e)))}class E{constructor(e){k(this,"_workers");k(this,"_threads");k(this,"_persistentWorkers",new Map);this._workers=e.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new h(e.func,{workerURL:e.workerURL})}partitionArray(e,r){if(!e.length)return[];if(r<=0)throw new Error("numChunks must be positive");const o=Math.min(r,e.length),a=Math.floor(e.length/o),i=e.length%o,l=[];let f=0;for(let t=0;t<o;t++){const s=a+(t<i?1:0);l.push(e.slice(f,f+s)),f+=s}return l}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...o}){const a=this.findWorkerByName(e);if(!a)return Promise.reject(new Error(`Worker "${e}" not found`));const i=a.maxConcurrency??this._threads,l=!!(Array.isArray(r)&&r.length>1&&a.partition),f=l?this.partitionArray(r,i):r,t=this.createWorkerPromises(a,e,{data:f,...o},i,l),s=await Promise.allSettled(t);return new b(s)}createWorkerPromises(e,r,o,a,i){const{data:l,...f}=o;return Array.from({length:a},(t,s)=>{const u=i&&Array.isArray(l)?l[s]:l;return this.runWorkerWithRetry({workerFunc:e.func,workerURL:e.workerURL,workerName:r,index:s,data:{data:u,...f}},e.retries)})}async runWorkerWithRetry(e,r=2){try{return await this.initiateWorker(e)}catch(o){if(r>0)return console.error(`Worker ${e.index} failed, retrying (${r} left):`,o),this.runWorkerWithRetry(e,r-1);throw console.error("Worker failed after all retries:",o),o}}initiateWorker({workerFunc:e,workerURL:r,workerName:o,index:a,data:i}){return new Promise((l,f)=>{const s=this.initWorker({name:o,role:"",func:e,workerURL:r}).getWorker;s.onerror=c=>{s.terminate(),f({index:a,workerConfigs:{workerFunc:e,workerName:o,index:a,data:i},failedResult:c})},s.onmessage=c=>{var d,p;if(((d=c.data)==null?void 0:d.ok)===!1){s.terminate(),f({index:a,workerConfigs:{workerFunc:e,workerName:o,index:a,data:i},failedResult:new ErrorEvent("error",{message:c.data.error})});return}l({index:a,workerConfigs:{workerFunc:e,workerName:o,index:a,data:i},successResult:new MessageEvent("message",{data:(p=c.data)==null?void 0:p.data})}),s.terminate()};const u={index:a,...Array.isArray(i)?{data:i}:i};s.postMessage(u,g(u))})}async collectResults(e,r={}){const o=e.results.filter(t=>t.status==="fulfilled"),a=e.results.filter(t=>t.status==="rejected"),i=o.map(t=>t.value.successResult.data),l=r.reducer?r.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((t,s)=>{const u=`
-        const reducer = ${l};
+`;var P=(n=>(n.Default="default",n.Pipeline="pipeline",n.Persistent="persistent",n))(P||{});const C=Object.freeze({persistent:R,pipeline:F,default:O});class v{constructor(e,r){y(this,"_worker");if(r!=null&&r.createWorker)this._worker=r.createWorker();else if(e){const s=(r==null?void 0:r.mode)??"default",t=C[s](e.toString()),l=new Blob([t],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(l))}else throw new Error("Either workerFunction or options.createWorker must be provided to WorkerFactory.")}get getWorker(){return this._worker}}class j{constructor(e){this.results=e}}function m(n,e=new Set){return n===null||typeof n!="object"?[]:e.has(n)?[]:(e.add(n),n instanceof ArrayBuffer||n instanceof MessagePort||typeof ImageBitmap<"u"&&n instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&n instanceof OffscreenCanvas?[n]:ArrayBuffer.isView(n)?[n.buffer]:Array.isArray(n)?n.flatMap(r=>m(r,e)):Object.values(n).flatMap(r=>m(r,e)))}class L{constructor(e){y(this,"_workers");y(this,"_threads");y(this,"_persistentWorkers",new Map);y(this,"_activeWorkers",new Set);y(this,"_isTerminated",!1);this._workers=e.workers,this._threads=navigator.hardwareConcurrency}get isTerminated(){return this._isTerminated}trackWorker(e){if(this._isTerminated)throw e.terminate(),new Error("MainWorkerFactory has been terminated");return this._activeWorkers.add(e),e}terminateWorker(e){this._activeWorkers.delete(e);try{e.terminate()}catch{}}initWorker(e){const r=new v(e.func,{createWorker:e.createWorker});return this.trackWorker(r.getWorker),r}partitionArray(e,r){if(!e.length)return[];if(r<=0)throw new Error("numChunks must be positive");const s=Math.min(r,e.length),t=Math.floor(e.length/s),l=e.length%s,c=[];let f=0;for(let a=0;a<s;a++){const o=t+(a<l?1:0);c.push(e.slice(f,f+o)),f+=o}return c}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...s}){if(this._isTerminated)return Promise.reject(new Error("MainWorkerFactory has been terminated"));const t=this.findWorkerByName(e);if(!t)return Promise.reject(new Error(`Worker "${e}" not found`));const l=t.maxConcurrency??this._threads,c=!!(Array.isArray(r)&&r.length>1&&t.partition),f=c?this.partitionArray(r,l):r,a=this.createWorkerPromises(t,e,{data:f,...s},l,c),o=await Promise.allSettled(a);return new j(o)}createWorkerPromises(e,r,s,t,l){const{data:c,...f}=s;return Array.from({length:t},(a,o)=>{const d=l&&Array.isArray(c)?c[o]:c;return this.runWorkerWithRetry({workerFunc:e.func,createWorker:e.createWorker,workerName:r,index:o,data:{data:d,...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,createWorker:r,workerName:s,index:t,data:l}){return new Promise((c,f)=>{const o=this.initWorker({name:s,role:"",func:e,createWorker:r}).getWorker;o.onerror=p=>{this.terminateWorker(o),f({index:t,workerConfigs:{workerFunc:e,createWorker:r,workerName:s,index:t,data:l},failedResult:p})},o.onmessage=p=>{var i,u;if(((i=p.data)==null?void 0:i.ok)===!1){this.terminateWorker(o),f({index:t,workerConfigs:{workerFunc:e,createWorker:r,workerName:s,index:t,data:l},failedResult:new ErrorEvent("error",{message:p.data.error})});return}c({index:t,workerConfigs:{workerFunc:e,createWorker:r,workerName:s,index:t,data:l},successResult:new MessageEvent("message",{data:(u=p.data)==null?void 0:u.data})}),this.terminateWorker(o)};const d={index:t,...Array.isArray(l)?{data:l}:l};o.postMessage(d,m(d))})}async collectResults(e,r={}){if(this._isTerminated)throw new Error("MainWorkerFactory has been terminated");const s=e.results.filter(a=>a.status==="fulfilled"),t=e.results.filter(a=>a.status==="rejected"),l=s.map(a=>a.value.successResult.data),c=r.reducer?r.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((a,o)=>{const d=`
+        const reducer = ${c};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -159,4 +167,4 @@ self.addEventListener('message', async (event) => {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `,c=new Blob([u],{type:"application/javascript"}),d=new Worker(URL.createObjectURL(c));d.onmessage=p=>{d.terminate(),p.data.ok?t(p.data.data):s(new Error(p.data.error))},d.onerror=p=>{d.terminate(),s(p)},d.postMessage(i)}),succeeded:o.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 r=e[0],o=this.findWorkerByName(r.worker);if(!o)throw new Error(`Worker "${r.worker}" not found`);const i=this.initWorker(o).getWorker;return new Promise((l,f)=>{i.onmessage=s=>{var u,c;i.terminate(),((u=s.data)==null?void 0:u.ok)===!1?f(new Error(s.data.error)):l((c=s.data)==null?void 0:c.data)},i.onerror=s=>{i.terminate(),f(s)};const t=r.srcData??{};i.postMessage({data:t,index:0},g(t))})}return new Promise((r,o)=>{const a=[],i=[];for(const t of e){const s=this.findWorkerByName(t.worker);if(!s){o(new Error(`Worker "${t.worker}" not found`));return}const u=new h(s.func,{mode:w.Pipeline,workerURL:s.workerURL});a.push(u.getWorker)}for(let t=0;t<a.length-1;t++)i.push(new MessageChannel);for(let t=0;t<a.length;t++){const s=[],u={};t>0&&(u.inputPort=i[t-1].port1,s.push(u.inputPort)),t<a.length-1&&(u.outputPort=i[t].port2,s.push(u.outputPort)),a[t].postMessage({__pipeline_ports__:!0,...u},s)}const l=a[a.length-1];l.onmessage=t=>{var s,u;a.forEach(c=>c.terminate()),((s=t.data)==null?void 0:s.ok)===!1?o(new Error(t.data.error)):r((u=t.data)==null?void 0:u.data)},l.onerror=t=>{a.forEach(s=>s.terminate()),o(t)};const f=e[0].srcData??{};a[0].postMessage({data:f,index:0},g(f))})}async runPersistent(e,r){const o=this.findWorkerByName(e);if(!o)throw new Error(`Worker "${e}" not found`);let a=this._persistentWorkers.get(e);return a||(a=new h(o.func,{mode:w.Persistent,workerURL:o.workerURL}).getWorker,this._persistentWorkers.set(e,a)),new Promise((i,l)=>{a.onmessage=t=>{var s,u;((s=t.data)==null?void 0:s.ok)===!1?l(new Error(t.data.error)):i((u=t.data)==null?void 0:u.data)},a.onerror=t=>{l(t)};const f={type:"run",config:r.config};r.dataset!==void 0&&(f.dataset=r.dataset),a.postMessage(f,g(f))})}release(e){const r=this._persistentWorkers.get(e);r&&(r.postMessage({type:"release"}),r.terminate(),this._persistentWorkers.delete(e))}}exports.MainWorkerFactory=E;exports.WorkerFactory=h;
+      `,p=new Blob([d],{type:"application/javascript"}),i=this.trackWorker(new Worker(URL.createObjectURL(p)));i.onmessage=u=>{this.terminateWorker(i),u.data.ok?a(u.data.data):o(new Error(u.data.error))},i.onerror=u=>{this.terminateWorker(i),o(u)},i.postMessage(l)}),succeeded:s.length,failed:t.length,errors:t}}async pipeline(e){if(this._isTerminated)throw new Error("MainWorkerFactory has been terminated");if(e.length===0)throw new Error("Pipeline requires at least one step");if(e.length===1){const r=e[0],{worker:s,srcData:t,...l}=r,c=this.findWorkerByName(r.worker);if(!c)throw new Error(`Worker "${r.worker}" not found`);const a=this.initWorker(c).getWorker;return new Promise((o,d)=>{a.onmessage=u=>{var k,g;this.terminateWorker(a),((k=u.data)==null?void 0:k.ok)===!1?d(new Error(u.data.error)):o((g=u.data)==null?void 0:g.data)},a.onerror=u=>{this.terminateWorker(a),d(u)};const i={data:t??{},...l,index:0};a.postMessage(i,m(i))})}return new Promise((r,s)=>{const t=[],l=[];for(const i of e){const u=this.findWorkerByName(i.worker);if(!u){s(new Error(`Worker "${i.worker}" not found`));return}const k=new v(u.func,{mode:P.Pipeline,createWorker:u.createWorker}),g=this.trackWorker(k.getWorker);t.push(g)}for(let i=0;i<t.length-1;i++)l.push(new MessageChannel);for(let i=0;i<t.length;i++){const{worker:u,srcData:k,...g}=e[i],W=[],w={};if(i>0&&(w.inputPort=l[i-1].port1,W.push(w.inputPort)),i<t.length-1&&(w.outputPort=l[i].port2,W.push(w.outputPort)),t[i].postMessage({__pipeline_ports__:!0,stepParams:g,...w},W),i<t.length-1){const _=t[i],A=t[i+1],{worker:I,srcData:U,...D}=e[i+1];_.onmessage=h=>{var E,T;if(h.data&&h.data.__pipeline_ports__)return;if(((E=h.data)==null?void 0:E.ok)===!1){t.forEach(B=>this.terminateWorker(B)),s(new Error(h.data.error));return}const b={data:((T=h.data)==null?void 0:T.ok)!==void 0?h.data.data:h.data,...D,index:0};A.postMessage(b,m(b))},_.onerror=h=>{t.forEach(M=>this.terminateWorker(M)),s(h)}}}const c=t[t.length-1];c.onmessage=i=>{var u,k;t.forEach(g=>this.terminateWorker(g)),((u=i.data)==null?void 0:u.ok)===!1?s(new Error(i.data.error)):r((k=i.data)==null?void 0:k.data)},c.onerror=i=>{t.forEach(u=>this.terminateWorker(u)),s(i)};const{worker:f,srcData:a,...o}=e[0],p={data:a??{},...o,index:0};t[0].postMessage(p,m(p))})}async runPersistent(e,r){if(this._isTerminated)throw new Error("MainWorkerFactory has been terminated");const s=this.findWorkerByName(e);if(!s)throw new Error(`Worker "${e}" not found`);let t=this._persistentWorkers.get(e);if(!t){const l=new v(s.func,{mode:P.Persistent,createWorker:s.createWorker});t=this.trackWorker(l.getWorker),this._persistentWorkers.set(e,t)}return new Promise((l,c)=>{t.onmessage=a=>{var o,d;((o=a.data)==null?void 0:o.ok)===!1?c(new Error(a.data.error)):l((d=a.data)==null?void 0:d.data)},t.onerror=a=>{c(a)};const f={type:"run",config:r.config};r.dataset!==void 0&&(f.dataset=r.dataset),t.postMessage(f,m(f))})}release(e){const r=this._persistentWorkers.get(e);if(r){try{r.postMessage({type:"release"})}catch{}this.terminateWorker(r),this._persistentWorkers.delete(e)}}terminate(){this._isTerminated=!0;for(const e of this._persistentWorkers.values()){try{e.postMessage({type:"release"})}catch{}this.terminateWorker(e)}this._persistentWorkers.clear();for(const e of Array.from(this._activeWorkers))this.terminateWorker(e);this._activeWorkers.clear()}destroy(){this.terminate()}reset(){this.terminate(),this._isTerminated=!1}restart(){this.reset()}}function $(n){if(typeof self>"u")return;let e=null,r=null,s=null,t={};const l=(f,a)=>{self.postMessage(f,a)};async function c(f){try{const a=typeof f=="object"&&f!==null&&"data"in f?{...t,...f}:{data:f,...t,index:0},o=await n(a),d={ok:!0,data:o},p=m(o);e?e.postMessage(d,p):l(d,p)}catch(a){const o={ok:!1,error:a instanceof Error?a.message:String(a)};e?e.postMessage(o):l(o)}}self.addEventListener("message",f=>{const a=f.data;if(a&&a.__pipeline_ports__){a.stepParams&&(t=a.stepParams),a.outputPort&&(e=a.outputPort),a.inputPort&&(r=a.inputPort,r.onmessage=o=>{var d;o.data&&o.data.ok===!1?e?e.postMessage(o.data):l(o.data):c({data:(d=o.data)==null?void 0:d.data,...t,index:0})}),s!==null&&(c(s),s=null);return}r?s=a:c(a)})}exports.MainWorkerFactory=L;exports.WorkerFactory=v;exports.defineWorker=$;

package/dist/index.js

@@ -1,7 +1,7 @@
-var v = Object.defineProperty;
-var m = (n, e, r) => e in n ? v(n, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[e] = r;
-var k = (n, e, r) => m(n, typeof e != "symbol" ? e + "" : e, r);
-const y = (n) => `
+var S = Object.defineProperty;
+var x = (n, e, r) => e in n ? S(n, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[e] = r;
+var y = (n, e, r) => x(n, typeof e != "symbol" ? e + "" : e, r);
+const O = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -24,7 +24,7 @@ self.addEventListener('message', async (event) => {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
-`, P = (n) => `
+`, R = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -43,10 +43,15 @@ const workerFn = ${n};
 let outputPort = null;
 let inputPort = null;
 let pendingData = null;
+let stepParams = {};
 
 async function processData(data) {
   try {
-    const output = await workerFn(data);
+    const payload =
+      typeof data === 'object' && data !== null && 'data' in data
+        ? { ...stepParams, ...data }
+        : { data, ...stepParams, index: 0 };
+    const output = await workerFn(payload);
     const result = { ok: true, data: output };
     const transfers = extractTransferables(output);
     if (outputPort) {
@@ -66,6 +71,9 @@ async function processData(data) {
 
 self.addEventListener('message', (event) => {
   if (event.data && event.data.__pipeline_ports__) {
+    if (event.data.stepParams) {
+      stepParams = event.data.stepParams;
+    }
     if (event.data.outputPort) {
       outputPort = event.data.outputPort;
     }
@@ -77,7 +85,7 @@ self.addEventListener('message', (event) => {
           if (outputPort) outputPort.postMessage(e.data);
           else self.postMessage(e.data);
         } else {
-          processData({ data: e.data.data, index: 0 });
+          processData({ data: e.data.data, ...stepParams, index: 0 });
         }
       };
     }
@@ -96,7 +104,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`, W = (n) => `
+`, F = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -153,39 +161,33 @@ self.addEventListener('message', async (event) => {
   }
 });
 `;
-var w = /* @__PURE__ */ ((n) => (n.Default = "default", n.Pipeline = "pipeline", n.Persistent = "persistent", n))(w || {});
-const M = Object.freeze({
-  persistent: W,
-  pipeline: P,
-  default: y
+var P = /* @__PURE__ */ ((n) => (n.Default = "default", n.Pipeline = "pipeline", n.Persistent = "persistent", n))(P || {});
+const C = Object.freeze({
+  persistent: F,
+  pipeline: R,
+  default: O
 });
-class h {
+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.
+   * Creates a new `Worker` from the given function or factory option.
    *
    * @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 serialized via `.toString()`.
-   * @param options - Optional configuration. Set `mode` to control the
-   *   worker execution mode (default, pipeline, or persistent).
+   * @param options - Optional configuration containing `createWorker` or `mode`.
    */
   constructor(e, r) {
-    k(this, "_worker");
-    if (r != null && r.workerInstance)
-      this._worker = r.workerInstance;
-    else if (r != null && r.workerURL)
-      this._worker = new Worker(r.workerURL, { type: "module" });
+    y(this, "_worker");
+    if (r != null && r.createWorker)
+      this._worker = r.createWorker();
     else if (e) {
-      const o = (r == null ? void 0 : r.mode) ?? "default", a = M[o](e.toString()), i = new Blob([a], {
+      const s = (r == null ? void 0 : r.mode) ?? "default", t = C[s](e.toString()), l = new Blob([t], {
         type: "application/javascript"
       });
-      this._worker = new Worker(URL.createObjectURL(i));
+      this._worker = new Worker(URL.createObjectURL(l));
     } else
       throw new Error(
-        "Either workerFunction or options.workerURL must be provided to WorkerFactory."
+        "Either workerFunction or options.createWorker must be provided to WorkerFactory."
       );
   }
   /**
@@ -198,38 +200,65 @@ class h {
     return this._worker;
   }
 }
-class b {
+class L {
   constructor(e) {
     this.results = e;
   }
 }
-function g(n, e = /* @__PURE__ */ new Set()) {
-  return n === null || typeof n != "object" ? [] : e.has(n) ? [] : (e.add(n), n instanceof ArrayBuffer || n instanceof MessagePort || typeof ImageBitmap < "u" && n instanceof ImageBitmap || typeof OffscreenCanvas < "u" && n instanceof OffscreenCanvas ? [n] : ArrayBuffer.isView(n) ? [n.buffer] : Array.isArray(n) ? n.flatMap((r) => g(r, e)) : Object.values(n).flatMap(
-    (r) => g(r, e)
+function m(n, e = /* @__PURE__ */ new Set()) {
+  return n === null || typeof n != "object" ? [] : e.has(n) ? [] : (e.add(n), n instanceof ArrayBuffer || n instanceof MessagePort || typeof ImageBitmap < "u" && n instanceof ImageBitmap || typeof OffscreenCanvas < "u" && n instanceof OffscreenCanvas ? [n] : ArrayBuffer.isView(n) ? [n.buffer] : Array.isArray(n) ? n.flatMap((r) => m(r, e)) : Object.values(n).flatMap(
+    (r) => m(r, e)
   ));
 }
-class _ {
+class U {
   /**
    * Creates a new `MainWorkerFactory`.
    *
    * @param options - Configuration object containing the `workers` registry.
    */
   constructor(e) {
-    k(this, "_workers");
-    k(this, "_threads");
-    k(this, "_persistentWorkers", /* @__PURE__ */ new Map());
+    y(this, "_workers");
+    y(this, "_threads");
+    y(this, "_persistentWorkers", /* @__PURE__ */ new Map());
+    y(this, "_activeWorkers", /* @__PURE__ */ new Set());
+    y(this, "_isTerminated", !1);
     this._workers = e.workers, this._threads = navigator.hardwareConcurrency;
   }
+  /**
+   * Returns `true` if the factory has been terminated.
+   */
+  get isTerminated() {
+    return this._isTerminated;
+  }
+  /**
+   * Registers an active worker instance for lifecycle tracking.
+   */
+  trackWorker(e) {
+    if (this._isTerminated)
+      throw e.terminate(), new Error("MainWorkerFactory has been terminated");
+    return this._activeWorkers.add(e), e;
+  }
+  /**
+   * Terminates a worker instance and removes it from tracking.
+   */
+  terminateWorker(e) {
+    this._activeWorkers.delete(e);
+    try {
+      e.terminate();
+    } catch {
+    }
+  }
   /**
    * Instantiates a {@link WorkerFactory} for the given worker configuration.
    *
-   * @param config - The worker configuration containing `func` or `workerURL`.
+   * @param config - The worker configuration containing `func` or `createWorker`.
    * @returns A new `WorkerFactory` wrapping the worker.
    */
   initWorker(e) {
-    return new h(e.func, {
-      workerURL: e.workerURL
+    const r = new W(e.func, {
+      createWorker: e.createWorker
     });
+    return this.trackWorker(r.getWorker), r;
   }
   /**
    * Splits an array into up to `numChunks` evenly-sized sub-arrays.
@@ -250,13 +279,13 @@ class _ {
   partitionArray(e, r) {
     if (!e.length) return [];
     if (r <= 0) throw new Error("numChunks must be positive");
-    const o = Math.min(r, e.length), a = Math.floor(e.length / o), i = e.length % o, f = [];
-    let l = 0;
-    for (let t = 0; t < o; t++) {
-      const s = a + (t < i ? 1 : 0);
-      f.push(e.slice(l, l + s)), l += s;
+    const s = Math.min(r, e.length), t = Math.floor(e.length / s), l = e.length % s, c = [];
+    let f = 0;
+    for (let a = 0; a < s; a++) {
+      const o = t + (a < l ? 1 : 0);
+      c.push(e.slice(f, f + o)), f += o;
     }
-    return f;
+    return c;
   }
   /**
    * Looks up a registered worker configuration by name.
@@ -295,19 +324,21 @@ class _ {
    */
   async runWorker(e, {
     srcData: r,
-    ...o
+    ...s
   }) {
-    const a = this.findWorkerByName(e);
-    if (!a)
+    if (this._isTerminated)
+      return Promise.reject(new Error("MainWorkerFactory has been terminated"));
+    const t = this.findWorkerByName(e);
+    if (!t)
       return Promise.reject(new Error(`Worker "${e}" not found`));
-    const i = a.maxConcurrency ?? this._threads, f = !!(Array.isArray(r) && r.length > 1 && a.partition), l = f ? this.partitionArray(r, i) : r, t = this.createWorkerPromises(
-      a,
+    const l = t.maxConcurrency ?? this._threads, c = !!(Array.isArray(r) && r.length > 1 && t.partition), f = c ? this.partitionArray(r, l) : r, a = this.createWorkerPromises(
+      t,
       e,
-      { data: l, ...o },
-      i,
-      f
-    ), s = await Promise.allSettled(t);
-    return new b(s);
+      { data: f, ...s },
+      l,
+      c
+    ), o = await Promise.allSettled(a);
+    return new L(o);
   }
   /**
    * Builds the array of per-thread worker promises for a single `runWorker`
@@ -323,17 +354,17 @@ class _ {
    * @param isPartitioned  - Whether `data` is a pre-split array of shards.
    * @returns An array of promises, one per thread.
    */
-  createWorkerPromises(e, r, o, a, i) {
-    const { data: f, ...l } = o;
-    return Array.from({ length: a }, (t, s) => {
-      const u = i && Array.isArray(f) ? f[s] : f;
+  createWorkerPromises(e, r, s, t, l) {
+    const { data: c, ...f } = s;
+    return Array.from({ length: t }, (a, o) => {
+      const d = l && Array.isArray(c) ? c[o] : c;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
-          workerURL: e.workerURL,
+          createWorker: e.createWorker,
           workerName: r,
-          index: s,
-          data: { data: u, ...l }
+          index: o,
+          data: { data: d, ...f }
         },
         e.retries
       );
@@ -354,13 +385,13 @@ class _ {
   async runWorkerWithRetry(e, r = 2) {
     try {
       return await this.initiateWorker(e);
-    } catch (o) {
+    } catch (s) {
       if (r > 0)
         return console.error(
           `Worker ${e.index} failed, retrying (${r} left):`,
-          o
+          s
         ), this.runWorkerWithRetry(e, r - 1);
-      throw console.error("Worker failed after all retries:", o), o;
+      throw console.error("Worker failed after all retries:", s), s;
     }
   }
   /**
@@ -375,57 +406,74 @@ class _ {
    * 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.
+   * The underlying `Worker` is always terminated after the message completes.
    *
-   * @param instanceConfig - Worker function, URL, name, shard index, and data.
+   * @param instanceConfig - Worker function, factory, name, shard index, and data.
    * @returns A promise that resolves with the worker's result.
    */
   initiateWorker({
     workerFunc: e,
-    workerURL: r,
-    workerName: o,
-    index: a,
-    data: i
+    createWorker: r,
+    workerName: s,
+    index: t,
+    data: l
   }) {
-    return new Promise((f, l) => {
-      const s = this.initWorker({
-        name: o,
+    return new Promise((c, f) => {
+      const o = this.initWorker({
+        name: s,
         role: "",
         func: e,
-        workerURL: r
+        createWorker: r
       }).getWorker;
-      s.onerror = (c) => {
-        s.terminate(), l({
-          index: a,
-          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
-          failedResult: c
+      o.onerror = (p) => {
+        this.terminateWorker(o), f({
+          index: t,
+          workerConfigs: {
+            workerFunc: e,
+            createWorker: r,
+            workerName: s,
+            index: t,
+            data: l
+          },
+          failedResult: p
         });
-      }, s.onmessage = (c) => {
-        var d, p;
-        if (((d = c.data) == null ? void 0 : d.ok) === !1) {
-          s.terminate(), l({
-            index: a,
-            workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
+      }, o.onmessage = (p) => {
+        var i, u;
+        if (((i = p.data) == null ? void 0 : i.ok) === !1) {
+          this.terminateWorker(o), f({
+            index: t,
+            workerConfigs: {
+              workerFunc: e,
+              createWorker: r,
+              workerName: s,
+              index: t,
+              data: l
+            },
             failedResult: new ErrorEvent("error", {
-              message: c.data.error
+              message: p.data.error
             })
           });
           return;
         }
-        f({
-          index: a,
-          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
+        c({
+          index: t,
+          workerConfigs: {
+            workerFunc: e,
+            createWorker: r,
+            workerName: s,
+            index: t,
+            data: l
+          },
           successResult: new MessageEvent("message", {
-            data: (p = c.data) == null ? void 0 : p.data
+            data: (u = p.data) == null ? void 0 : u.data
           })
-        }), s.terminate();
+        }), this.terminateWorker(o);
       };
-      const u = {
-        index: a,
-        ...Array.isArray(i) ? { data: i } : i
+      const d = {
+        index: t,
+        ...Array.isArray(l) ? { data: l } : l
       };
-      s.postMessage(u, g(u));
+      o.postMessage(d, m(d));
     });
   }
   /**
@@ -461,15 +509,17 @@ class _ {
    * });
    */
   async collectResults(e, r = {}) {
-    const o = e.results.filter(
-      (t) => t.status === "fulfilled"
-    ), a = e.results.filter(
-      (t) => t.status === "rejected"
-    ), i = o.map((t) => t.value.successResult.data), f = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
+    if (this._isTerminated)
+      throw new Error("MainWorkerFactory has been terminated");
+    const s = e.results.filter(
+      (a) => a.status === "fulfilled"
+    ), t = e.results.filter(
+      (a) => a.status === "rejected"
+    ), l = s.map((a) => a.value.successResult.data), c = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
     return {
-      data: await new Promise((t, s) => {
-        const u = `
-        const reducer = ${f};
+      data: await new Promise((a, o) => {
+        const d = `
+        const reducer = ${c};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -478,16 +528,16 @@ class _ {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, c = new Blob([u], { type: "application/javascript" }), d = new Worker(URL.createObjectURL(c));
-        d.onmessage = (p) => {
-          d.terminate(), p.data.ok ? t(p.data.data) : s(new Error(p.data.error));
-        }, d.onerror = (p) => {
-          d.terminate(), s(p);
-        }, d.postMessage(i);
+      `, p = new Blob([d], { type: "application/javascript" }), i = this.trackWorker(new Worker(URL.createObjectURL(p)));
+        i.onmessage = (u) => {
+          this.terminateWorker(i), u.data.ok ? a(u.data.data) : o(new Error(u.data.error));
+        }, i.onerror = (u) => {
+          this.terminateWorker(i), o(u);
+        }, i.postMessage(l);
       }),
-      succeeded: o.length,
-      failed: a.length,
-      errors: a
+      succeeded: s.length,
+      failed: t.length,
+      errors: t
     };
   }
   /**
@@ -517,61 +567,71 @@ class _ {
    * console.log(result); // final transformed + filtered data
    */
   async pipeline(e) {
+    if (this._isTerminated)
+      throw new Error("MainWorkerFactory has been terminated");
     if (e.length === 0)
       throw new Error("Pipeline requires at least one step");
     if (e.length === 1) {
-      const r = e[0], o = this.findWorkerByName(r.worker);
-      if (!o) throw new Error(`Worker "${r.worker}" not found`);
-      const i = this.initWorker(o).getWorker;
-      return new Promise((f, l) => {
-        i.onmessage = (s) => {
-          var u, c;
-          i.terminate(), ((u = s.data) == null ? void 0 : u.ok) === !1 ? l(new Error(s.data.error)) : f((c = s.data) == null ? void 0 : c.data);
-        }, i.onerror = (s) => {
-          i.terminate(), l(s);
+      const r = e[0], { worker: s, srcData: t, ...l } = r, c = this.findWorkerByName(r.worker);
+      if (!c) throw new Error(`Worker "${r.worker}" not found`);
+      const a = this.initWorker(c).getWorker;
+      return new Promise((o, d) => {
+        a.onmessage = (u) => {
+          var k, g;
+          this.terminateWorker(a), ((k = u.data) == null ? void 0 : k.ok) === !1 ? d(new Error(u.data.error)) : o((g = u.data) == null ? void 0 : g.data);
+        }, a.onerror = (u) => {
+          this.terminateWorker(a), d(u);
         };
-        const t = r.srcData ?? {};
-        i.postMessage(
-          { data: t, index: 0 },
-          g(t)
-        );
+        const i = { data: t ?? {}, ...l, index: 0 };
+        a.postMessage(i, m(i));
       });
     }
-    return new Promise((r, o) => {
-      const a = [], i = [];
-      for (const t of e) {
-        const s = this.findWorkerByName(t.worker);
-        if (!s) {
-          o(new Error(`Worker "${t.worker}" not found`));
+    return new Promise((r, s) => {
+      const t = [], l = [];
+      for (const i of e) {
+        const u = this.findWorkerByName(i.worker);
+        if (!u) {
+          s(new Error(`Worker "${i.worker}" not found`));
           return;
         }
-        const u = new h(s.func, {
-          mode: w.Pipeline,
-          workerURL: s.workerURL
-        });
-        a.push(u.getWorker);
+        const k = new W(u.func, {
+          mode: P.Pipeline,
+          createWorker: u.createWorker
+        }), g = this.trackWorker(k.getWorker);
+        t.push(g);
       }
-      for (let t = 0; t < a.length - 1; t++)
-        i.push(new MessageChannel());
-      for (let t = 0; t < a.length; t++) {
-        const s = [], u = {};
-        t > 0 && (u.inputPort = i[t - 1].port1, s.push(u.inputPort)), t < a.length - 1 && (u.outputPort = i[t].port2, s.push(u.outputPort)), a[t].postMessage(
-          { __pipeline_ports__: !0, ...u },
-          s
-        );
+      for (let i = 0; i < t.length - 1; i++)
+        l.push(new MessageChannel());
+      for (let i = 0; i < t.length; i++) {
+        const { worker: u, srcData: k, ...g } = e[i], v = [], w = {};
+        if (i > 0 && (w.inputPort = l[i - 1].port1, v.push(w.inputPort)), i < t.length - 1 && (w.outputPort = l[i].port2, v.push(w.outputPort)), t[i].postMessage(
+          { __pipeline_ports__: !0, stepParams: g, ...w },
+          v
+        ), i < t.length - 1) {
+          const _ = t[i], A = t[i + 1], { worker: j, srcData: $, ...D } = e[i + 1];
+          _.onmessage = (h) => {
+            var E, T;
+            if (h.data && h.data.__pipeline_ports__) return;
+            if (((E = h.data) == null ? void 0 : E.ok) === !1) {
+              t.forEach((B) => this.terminateWorker(B)), s(new Error(h.data.error));
+              return;
+            }
+            const b = { data: ((T = h.data) == null ? void 0 : T.ok) !== void 0 ? h.data.data : h.data, ...D, index: 0 };
+            A.postMessage(b, m(b));
+          }, _.onerror = (h) => {
+            t.forEach((M) => this.terminateWorker(M)), s(h);
+          };
+        }
       }
-      const f = a[a.length - 1];
-      f.onmessage = (t) => {
-        var s, u;
-        a.forEach((c) => c.terminate()), ((s = t.data) == null ? void 0 : s.ok) === !1 ? o(new Error(t.data.error)) : r((u = t.data) == null ? void 0 : u.data);
-      }, f.onerror = (t) => {
-        a.forEach((s) => s.terminate()), o(t);
+      const c = t[t.length - 1];
+      c.onmessage = (i) => {
+        var u, k;
+        t.forEach((g) => this.terminateWorker(g)), ((u = i.data) == null ? void 0 : u.ok) === !1 ? s(new Error(i.data.error)) : r((k = i.data) == null ? void 0 : k.data);
+      }, c.onerror = (i) => {
+        t.forEach((u) => this.terminateWorker(u)), s(i);
       };
-      const l = e[0].srcData ?? {};
-      a[0].postMessage(
-        { data: l, index: 0 },
-        g(l)
-      );
+      const { worker: f, srcData: a, ...o } = e[0], p = { data: a ?? {}, ...o, index: 0 };
+      t[0].postMessage(p, m(p));
     });
   }
   /**
@@ -609,24 +669,30 @@ class _ {
    * factory.release('transform');
    */
   async runPersistent(e, r) {
-    const o = this.findWorkerByName(e);
-    if (!o) throw new Error(`Worker "${e}" not found`);
-    let a = this._persistentWorkers.get(e);
-    return a || (a = new h(o.func, {
-      mode: w.Persistent,
-      workerURL: o.workerURL
-    }).getWorker, this._persistentWorkers.set(e, a)), new Promise((i, f) => {
-      a.onmessage = (t) => {
-        var s, u;
-        ((s = t.data) == null ? void 0 : s.ok) === !1 ? f(new Error(t.data.error)) : i((u = t.data) == null ? void 0 : u.data);
-      }, a.onerror = (t) => {
-        f(t);
+    if (this._isTerminated)
+      throw new Error("MainWorkerFactory has been terminated");
+    const s = this.findWorkerByName(e);
+    if (!s) throw new Error(`Worker "${e}" not found`);
+    let t = this._persistentWorkers.get(e);
+    if (!t) {
+      const l = new W(s.func, {
+        mode: P.Persistent,
+        createWorker: s.createWorker
+      });
+      t = this.trackWorker(l.getWorker), this._persistentWorkers.set(e, t);
+    }
+    return new Promise((l, c) => {
+      t.onmessage = (a) => {
+        var o, d;
+        ((o = a.data) == null ? void 0 : o.ok) === !1 ? c(new Error(a.data.error)) : l((d = a.data) == null ? void 0 : d.data);
+      }, t.onerror = (a) => {
+        c(a);
       };
-      const l = {
+      const f = {
         type: "run",
         config: r.config
       };
-      r.dataset !== void 0 && (l.dataset = r.dataset), a.postMessage(l, g(l));
+      r.dataset !== void 0 && (f.dataset = r.dataset), t.postMessage(f, m(f));
     });
   }
   /**
@@ -640,10 +706,86 @@ class _ {
    */
   release(e) {
     const r = this._persistentWorkers.get(e);
-    r && (r.postMessage({ type: "release" }), r.terminate(), this._persistentWorkers.delete(e));
+    if (r) {
+      try {
+        r.postMessage({ type: "release" });
+      } catch {
+      }
+      this.terminateWorker(r), this._persistentWorkers.delete(e);
+    }
   }
+  /**
+   * Terminates the factory and all active and persistent worker instances.
+   *
+   * Calling `terminate()` immediately stops all running worker threads, releases
+   * cached persistent workers, and clears all internal worker state.
+   */
+  terminate() {
+    this._isTerminated = !0;
+    for (const e of this._persistentWorkers.values()) {
+      try {
+        e.postMessage({ type: "release" });
+      } catch {
+      }
+      this.terminateWorker(e);
+    }
+    this._persistentWorkers.clear();
+    for (const e of Array.from(this._activeWorkers))
+      this.terminateWorker(e);
+    this._activeWorkers.clear();
+  }
+  /**
+   * Alias for {@link terminate}. Terminates the factory and all worker instances.
+   */
+  destroy() {
+    this.terminate();
+  }
+  /**
+   * Resets the factory by terminating all active and persistent workers
+   * and resetting the factory state, allowing new worker instances to be initiated.
+   */
+  reset() {
+    this.terminate(), this._isTerminated = !1;
+  }
+  /**
+   * Alias for {@link reset}. Resets the factory state to initiate new worker instances.
+   */
+  restart() {
+    this.reset();
+  }
+}
+function V(n) {
+  if (typeof self > "u") return;
+  let e = null, r = null, s = null, t = {};
+  const l = (f, a) => {
+    self.postMessage(f, a);
+  };
+  async function c(f) {
+    try {
+      const a = typeof f == "object" && f !== null && "data" in f ? { ...t, ...f } : { data: f, ...t, index: 0 }, o = await n(a), d = { ok: !0, data: o }, p = m(o);
+      e ? e.postMessage(d, p) : l(d, p);
+    } catch (a) {
+      const o = {
+        ok: !1,
+        error: a instanceof Error ? a.message : String(a)
+      };
+      e ? e.postMessage(o) : l(o);
+    }
+  }
+  self.addEventListener("message", (f) => {
+    const a = f.data;
+    if (a && a.__pipeline_ports__) {
+      a.stepParams && (t = a.stepParams), a.outputPort && (e = a.outputPort), a.inputPort && (r = a.inputPort, r.onmessage = (o) => {
+        var d;
+        o.data && o.data.ok === !1 ? e ? e.postMessage(o.data) : l(o.data) : c({ data: (d = o.data) == null ? void 0 : d.data, ...t, index: 0 });
+      }), s !== null && (c(s), s = null);
+      return;
+    }
+    r ? s = a : c(a);
+  });
 }
 export {
-  _ as MainWorkerFactory,
-  h as WorkerFactory
+  U as MainWorkerFactory,
+  W as WorkerFactory,
+  V as defineWorker
 };

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

@@ -0,0 +1,21 @@
+import { WorkerFunction } from './main-worker-factory/types';
+/**
+ * Defines and exports a function to run inside a native Web Worker script,
+ * providing full compatibility with `MainWorkerFactory` features including
+ * standard runs, worker-to-worker pipelines (`foreman.pipeline()`), and
+ * dataset caching (`foreman.runPersistent()`).
+ *
+ * @typeParam TParams - The type of the payload sent to the worker.
+ * @typeParam TResult - The return type of the worker function.
+ *
+ * @param workerFn - The worker execution function.
+ *
+ * @example
+ * // my-native-worker.ts
+ * import { defineWorker } from '@offmain/workerkit';
+ *
+ * export default defineWorker(async ({ data }: { data: number[] }) => {
+ *   return data.map((x) => x * 2);
+ * });
+ */
+export declare function defineWorker<TParams = unknown, TResult = unknown>(workerFn: WorkerFunction<TParams, TResult | Promise<TResult>>): void;

package/dist/types/tools/define-worker.test.d.ts

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

package/dist/types/tools/index.d.ts

@@ -1,2 +1,3 @@
 export * from './worker-factory';
 export * from './main-worker-factory';
+export * from './define-worker';

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

@@ -1,10 +1,10 @@
 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)
+ * Transferable (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[];
+export declare function extractTransferable(value: unknown, seen?: Set<object>): Transferable[];
 /**
  * Central orchestrator for running typed Web Workers in parallel.
  *
@@ -36,6 +36,8 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
     private readonly _workers;
     private readonly _threads;
     private readonly _persistentWorkers;
+    private readonly _activeWorkers;
+    private _isTerminated;
     /**
      * Creates a new `MainWorkerFactory`.
      *
@@ -44,10 +46,22 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
     constructor(options: {
         workers: TConfigs;
     });
+    /**
+     * Returns `true` if the factory has been terminated.
+     */
+    get isTerminated(): boolean;
+    /**
+     * Registers an active worker instance for lifecycle tracking.
+     */
+    private trackWorker;
+    /**
+     * Terminates a worker instance and removes it from tracking.
+     */
+    private terminateWorker;
     /**
      * Instantiates a {@link WorkerFactory} for the given worker configuration.
      *
-     * @param config - The worker configuration containing `func` or `workerURL`.
+     * @param config - The worker configuration containing `func` or `createWorker`.
      * @returns A new `WorkerFactory` wrapping the worker.
      */
     private initWorker;
@@ -144,10 +158,9 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
      * 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.
+     * The underlying `Worker` is always terminated after the message completes.
      *
-     * @param instanceConfig - Worker function, URL, name, shard index, and data.
+     * @param instanceConfig - Worker function, factory, name, shard index, and data.
      * @returns A promise that resolves with the worker's result.
      */
     private initiateWorker;
@@ -259,5 +272,25 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
      * @param workerName - Name of the persistent worker to release.
      */
     release(workerName: string): void;
+    /**
+     * Terminates the factory and all active and persistent worker instances.
+     *
+     * Calling `terminate()` immediately stops all running worker threads, releases
+     * cached persistent workers, and clears all internal worker state.
+     */
+    terminate(): void;
+    /**
+     * Alias for {@link terminate}. Terminates the factory and all worker instances.
+     */
+    destroy(): void;
+    /**
+     * Resets the factory by terminating all active and persistent workers
+     * and resetting the factory state, allowing new worker instances to be initiated.
+     */
+    reset(): void;
+    /**
+     * Alias for {@link reset}. Resets the factory state to initiate new worker instances.
+     */
+    restart(): void;
 }
 export default MainWorkerFactory;

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

@@ -23,13 +23,14 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
     name: WorkerName;
     /** Human-readable role label (e.g. `'compute'`, `'transform'`). */
     role: WorkerRole;
-    /** The worker function that will be serialised and run in a thread. Optional if `workerURL` is provided. */
+    /** The worker function that will be serialised and run in a thread. Optional if `createWorker` is provided. */
     func?: TFunc;
     /**
-     * The worker script URL (or `URL` object created via `new URL(..., import.meta.url)`).
-     * Enables module bundlers like Webpack 5, Vite, Rollup, and Parcel to bundle worker code and its dependencies.
+     * Factory function returning a native `Worker` instance (e.g. `() => new Worker(new URL('./worker.ts', import.meta.url))`).
+     * Enables bundlers like Webpack 5, Vite, Rollup, and Parcel to statically analyze and bundle worker code into individual chunks,
+     * while allowing `MainWorkerFactory` to scale concurrency and manage worker thread lifecycles.
      */
-    workerURL?: string | URL;
+    createWorker?: () => Worker;
     /**
      * Maximum number of parallel threads to spawn for this worker.
      * Defaults to `navigator.hardwareConcurrency` when omitted.
@@ -103,10 +104,10 @@ export interface MainWorkerFactoryWorker extends WorkerConfig {
 export interface WorkerInstanceConfig<TFunc extends WorkerFunction = WorkerFunction> {
     /** Name of the parent worker config, used in logs and error objects. */
     workerName: WorkerName;
-    /** The function serialised and executed inside the thread (optional if `workerURL` is set). */
+    /** The function serialised and executed inside the thread (optional if `createWorker` is set). */
     workerFunc?: TFunc;
-    /** Worker script URL (string or URL object). */
-    workerURL?: string | URL;
+    /** Factory function returning a Worker instance. */
+    createWorker?: () => Worker;
     /** Zero-based shard index assigned to this thread. */
     index: number;
     /** The data payload (full or partitioned shard) sent to the thread. */
@@ -167,4 +168,6 @@ export interface PipelineStep {
     worker: string;
     /** Input data for the first step (subsequent steps receive previous output) */
     srcData?: unknown;
+    /** Any additional step parameters, configs, or options forwarded to the worker payload. */
+    [key: string]: unknown;
 }

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

@@ -7,10 +7,8 @@ export declare enum WorkerMode {
 export interface WorkerFactoryOptions {
     /** The worker execution mode. Defaults to `WorkerMode.Default`. */
     mode?: WorkerMode;
-    /** The worker instance to use instead of creating a worker from a function. */
-    workerInstance?: Worker;
-    /** The worker URL to use instead of creating a worker from a function. */
-    workerURL?: string | URL;
+    /** Factory function returning a native `Worker` instance. */
+    createWorker?: () => Worker;
 }
 /**
  * Low-level factory that serializes a {@link WorkerFunction} into a Blob URL
@@ -36,16 +34,12 @@ export interface WorkerFactoryOptions {
 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.
+     * Creates a new `Worker` from the given function or factory option.
      *
      * @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 serialized via `.toString()`.
-     * @param options - Optional configuration. Set `mode` to control the
-     *   worker execution mode (default, pipeline, or persistent).
+     * @param options - Optional configuration containing `createWorker` or `mode`.
      */
     constructor(workerFunction?: WorkerFunction, options?: WorkerFactoryOptions);
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offmain/workerkit",
-  "version": "0.12.3",
+  "version": "0.14.0",
   "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
   "type": "module",
   "main": "./dist/index.cjs",