@offmain/workerkit 0.12.3 → 0.13.0

package/README.md

@@ -57,23 +57,23 @@ 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
 
@@ -98,7 +98,9 @@ self.addEventListener('message', (event) => {
 });
 ```
 
-### 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 +110,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,
 });

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 y=Object.defineProperty;var w=(n,e,r)=>e in n?y(n,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):n[e]=r;var h=(n,e,r)=>w(n,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const v=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=>`
+`,W=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -93,7 +93,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`,W=n=>`
+`,M=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -149,8 +149,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 m=(n=>(n.Default="default",n.Pipeline="pipeline",n.Persistent="persistent",n))(m||{});const P=Object.freeze({persistent:M,pipeline:W,default:v});class g{constructor(e,r){h(this,"_worker");if(r!=null&&r.createWorker)this._worker=r.createWorker();else if(e){const o=(r==null?void 0:r.mode)??"default",a=P[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.createWorker must be provided to WorkerFactory.")}get getWorker(){return this._worker}}class b{constructor(e){this.results=e}}function k(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=>k(r,e)):Object.values(n).flatMap(r=>k(r,e)))}class _{constructor(e){h(this,"_workers");h(this,"_threads");h(this,"_persistentWorkers",new Map);h(this,"_activeWorkers",new Set);h(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 g(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 o=Math.min(r,e.length),a=Math.floor(e.length/o),i=e.length%o,c=[];let u=0;for(let t=0;t<o;t++){const s=a+(t<i?1:0);c.push(e.slice(u,u+s)),u+=s}return c}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...o}){if(this._isTerminated)return Promise.reject(new Error("MainWorkerFactory has been terminated"));const a=this.findWorkerByName(e);if(!a)return Promise.reject(new Error(`Worker "${e}" not found`));const i=a.maxConcurrency??this._threads,c=!!(Array.isArray(r)&&r.length>1&&a.partition),u=c?this.partitionArray(r,i):r,t=this.createWorkerPromises(a,e,{data:u,...o},i,c),s=await Promise.allSettled(t);return new b(s)}createWorkerPromises(e,r,o,a,i){const{data:c,...u}=o;return Array.from({length:a},(t,s)=>{const f=i&&Array.isArray(c)?c[s]:c;return this.runWorkerWithRetry({workerFunc:e.func,createWorker:e.createWorker,workerName:r,index:s,data:{data:f,...u}},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,createWorker:r,workerName:o,index:a,data:i}){return new Promise((c,u)=>{const s=this.initWorker({name:o,role:"",func:e,createWorker:r}).getWorker;s.onerror=l=>{this.terminateWorker(s),u({index:a,workerConfigs:{workerFunc:e,createWorker:r,workerName:o,index:a,data:i},failedResult:l})},s.onmessage=l=>{var d,p;if(((d=l.data)==null?void 0:d.ok)===!1){this.terminateWorker(s),u({index:a,workerConfigs:{workerFunc:e,createWorker:r,workerName:o,index:a,data:i},failedResult:new ErrorEvent("error",{message:l.data.error})});return}c({index:a,workerConfigs:{workerFunc:e,createWorker:r,workerName:o,index:a,data:i},successResult:new MessageEvent("message",{data:(p=l.data)==null?void 0:p.data})}),this.terminateWorker(s)};const f={index:a,...Array.isArray(i)?{data:i}:i};s.postMessage(f,k(f))})}async collectResults(e,r={}){if(this._isTerminated)throw new Error("MainWorkerFactory has been terminated");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),c=r.reducer?r.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((t,s)=>{const f=`
+        const reducer = ${c};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -159,4 +159,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;
+      `,l=new Blob([f],{type:"application/javascript"}),d=this.trackWorker(new Worker(URL.createObjectURL(l)));d.onmessage=p=>{this.terminateWorker(d),p.data.ok?t(p.data.data):s(new Error(p.data.error))},d.onerror=p=>{this.terminateWorker(d),s(p)},d.postMessage(i)}),succeeded:o.length,failed:a.length,errors:a}}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((c,u)=>{i.onmessage=s=>{var f,l;this.terminateWorker(i),((f=s.data)==null?void 0:f.ok)===!1?u(new Error(s.data.error)):c((l=s.data)==null?void 0:l.data)},i.onerror=s=>{this.terminateWorker(i),u(s)};const t=r.srcData??{};i.postMessage({data:t,index:0},k(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 f=new g(s.func,{mode:m.Pipeline,createWorker:s.createWorker}),l=this.trackWorker(f.getWorker);a.push(l)}for(let t=0;t<a.length-1;t++)i.push(new MessageChannel);for(let t=0;t<a.length;t++){const s=[],f={};t>0&&(f.inputPort=i[t-1].port1,s.push(f.inputPort)),t<a.length-1&&(f.outputPort=i[t].port2,s.push(f.outputPort)),a[t].postMessage({__pipeline_ports__:!0,...f},s)}const c=a[a.length-1];c.onmessage=t=>{var s,f;a.forEach(l=>this.terminateWorker(l)),((s=t.data)==null?void 0:s.ok)===!1?o(new Error(t.data.error)):r((f=t.data)==null?void 0:f.data)},c.onerror=t=>{a.forEach(s=>this.terminateWorker(s)),o(t)};const u=e[0].srcData??{};a[0].postMessage({data:u,index:0},k(u))})}async runPersistent(e,r){if(this._isTerminated)throw new Error("MainWorkerFactory has been terminated");const o=this.findWorkerByName(e);if(!o)throw new Error(`Worker "${e}" not found`);let a=this._persistentWorkers.get(e);if(!a){const i=new g(o.func,{mode:m.Persistent,createWorker:o.createWorker});a=this.trackWorker(i.getWorker),this._persistentWorkers.set(e,a)}return new Promise((i,c)=>{a.onmessage=t=>{var s,f;((s=t.data)==null?void 0:s.ok)===!1?c(new Error(t.data.error)):i((f=t.data)==null?void 0:f.data)},a.onerror=t=>{c(t)};const u={type:"run",config:r.config};r.dataset!==void 0&&(u.dataset=r.dataset),a.postMessage(u,k(u))})}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()}}exports.MainWorkerFactory=_;exports.WorkerFactory=g;

package/dist/index.js

@@ -1,6 +1,6 @@
-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);
+var w = Object.defineProperty;
+var v = (n, e, r) => e in n ? w(n, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[e] = r;
+var h = (n, e, r) => v(n, typeof e != "symbol" ? e + "" : e, r);
 const y = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
@@ -24,7 +24,7 @@ self.addEventListener('message', async (event) => {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
-`, P = (n) => `
+`, W = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -96,7 +96,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`, W = (n) => `
+`, M = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -153,39 +153,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,
+var m = /* @__PURE__ */ ((n) => (n.Default = "default", n.Pipeline = "pipeline", n.Persistent = "persistent", n))(m || {});
+const P = Object.freeze({
+  persistent: M,
+  pipeline: W,
   default: y
 });
-class h {
+class g {
   /**
-   * 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" });
+    h(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 o = (r == null ? void 0 : r.mode) ?? "default", a = P[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."
+        "Either workerFunction or options.createWorker must be provided to WorkerFactory."
       );
   }
   /**
@@ -203,33 +197,60 @@ class b {
     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 k(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) => k(r, e)) : Object.values(n).flatMap(
+    (r) => k(r, e)
   ));
 }
-class _ {
+class E {
   /**
    * 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());
+    h(this, "_workers");
+    h(this, "_threads");
+    h(this, "_persistentWorkers", /* @__PURE__ */ new Map());
+    h(this, "_activeWorkers", /* @__PURE__ */ new Set());
+    h(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 g(e.func, {
+      createWorker: e.createWorker
     });
+    return this.trackWorker(r.getWorker), r;
   }
   /**
    * Splits an array into up to `numChunks` evenly-sized sub-arrays.
@@ -250,13 +271,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;
+    const o = Math.min(r, e.length), a = Math.floor(e.length / o), i = e.length % o, c = [];
+    let u = 0;
     for (let t = 0; t < o; t++) {
       const s = a + (t < i ? 1 : 0);
-      f.push(e.slice(l, l + s)), l += s;
+      c.push(e.slice(u, u + s)), u += s;
     }
-    return f;
+    return c;
   }
   /**
    * Looks up a registered worker configuration by name.
@@ -297,15 +318,17 @@ class _ {
     srcData: r,
     ...o
   }) {
+    if (this._isTerminated)
+      return Promise.reject(new Error("MainWorkerFactory has been terminated"));
     const a = this.findWorkerByName(e);
     if (!a)
       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(
+    const i = a.maxConcurrency ?? this._threads, c = !!(Array.isArray(r) && r.length > 1 && a.partition), u = c ? this.partitionArray(r, i) : r, t = this.createWorkerPromises(
       a,
       e,
-      { data: l, ...o },
+      { data: u, ...o },
       i,
-      f
+      c
     ), s = await Promise.allSettled(t);
     return new b(s);
   }
@@ -324,16 +347,16 @@ class _ {
    * @returns An array of promises, one per thread.
    */
   createWorkerPromises(e, r, o, a, i) {
-    const { data: f, ...l } = o;
+    const { data: c, ...u } = o;
     return Array.from({ length: a }, (t, s) => {
-      const u = i && Array.isArray(f) ? f[s] : f;
+      const f = i && Array.isArray(c) ? c[s] : c;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
-          workerURL: e.workerURL,
+          createWorker: e.createWorker,
           workerName: r,
           index: s,
-          data: { data: u, ...l }
+          data: { data: f, ...u }
         },
         e.retries
       );
@@ -375,57 +398,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,
+    createWorker: r,
     workerName: o,
     index: a,
     data: i
   }) {
-    return new Promise((f, l) => {
+    return new Promise((c, u) => {
       const s = this.initWorker({
         name: o,
         role: "",
         func: e,
-        workerURL: r
+        createWorker: r
       }).getWorker;
-      s.onerror = (c) => {
-        s.terminate(), l({
+      s.onerror = (l) => {
+        this.terminateWorker(s), u({
           index: a,
-          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
-          failedResult: c
+          workerConfigs: {
+            workerFunc: e,
+            createWorker: r,
+            workerName: o,
+            index: a,
+            data: i
+          },
+          failedResult: l
         });
-      }, s.onmessage = (c) => {
+      }, s.onmessage = (l) => {
         var d, p;
-        if (((d = c.data) == null ? void 0 : d.ok) === !1) {
-          s.terminate(), l({
+        if (((d = l.data) == null ? void 0 : d.ok) === !1) {
+          this.terminateWorker(s), u({
             index: a,
-            workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
+            workerConfigs: {
+              workerFunc: e,
+              createWorker: r,
+              workerName: o,
+              index: a,
+              data: i
+            },
             failedResult: new ErrorEvent("error", {
-              message: c.data.error
+              message: l.data.error
             })
           });
           return;
         }
-        f({
+        c({
           index: a,
-          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
+          workerConfigs: {
+            workerFunc: e,
+            createWorker: r,
+            workerName: o,
+            index: a,
+            data: i
+          },
           successResult: new MessageEvent("message", {
-            data: (p = c.data) == null ? void 0 : p.data
+            data: (p = l.data) == null ? void 0 : p.data
           })
-        }), s.terminate();
+        }), this.terminateWorker(s);
       };
-      const u = {
+      const f = {
         index: a,
         ...Array.isArray(i) ? { data: i } : i
       };
-      s.postMessage(u, g(u));
+      s.postMessage(f, k(f));
     });
   }
   /**
@@ -461,15 +501,17 @@ class _ {
    * });
    */
   async collectResults(e, r = {}) {
+    if (this._isTerminated)
+      throw new Error("MainWorkerFactory has been terminated");
     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()";
+    ), i = o.map((t) => t.value.successResult.data), c = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
     return {
       data: await new Promise((t, s) => {
-        const u = `
-        const reducer = ${f};
+        const f = `
+        const reducer = ${c};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -478,11 +520,11 @@ class _ {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, c = new Blob([u], { type: "application/javascript" }), d = new Worker(URL.createObjectURL(c));
+      `, l = new Blob([f], { type: "application/javascript" }), d = this.trackWorker(new Worker(URL.createObjectURL(l)));
         d.onmessage = (p) => {
-          d.terminate(), p.data.ok ? t(p.data.data) : s(new Error(p.data.error));
+          this.terminateWorker(d), p.data.ok ? t(p.data.data) : s(new Error(p.data.error));
         }, d.onerror = (p) => {
-          d.terminate(), s(p);
+          this.terminateWorker(d), s(p);
         }, d.postMessage(i);
       }),
       succeeded: o.length,
@@ -517,23 +559,25 @@ 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) => {
+      return new Promise((c, u) => {
         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);
+          var f, l;
+          this.terminateWorker(i), ((f = s.data) == null ? void 0 : f.ok) === !1 ? u(new Error(s.data.error)) : c((l = s.data) == null ? void 0 : l.data);
         }, i.onerror = (s) => {
-          i.terminate(), l(s);
+          this.terminateWorker(i), u(s);
         };
         const t = r.srcData ?? {};
         i.postMessage(
           { data: t, index: 0 },
-          g(t)
+          k(t)
         );
       });
     }
@@ -545,32 +589,32 @@ class _ {
           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);
+        const f = new g(s.func, {
+          mode: m.Pipeline,
+          createWorker: s.createWorker
+        }), l = this.trackWorker(f.getWorker);
+        a.push(l);
       }
       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 },
+        const s = [], f = {};
+        t > 0 && (f.inputPort = i[t - 1].port1, s.push(f.inputPort)), t < a.length - 1 && (f.outputPort = i[t].port2, s.push(f.outputPort)), a[t].postMessage(
+          { __pipeline_ports__: !0, ...f },
           s
         );
       }
-      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 = a[a.length - 1];
+      c.onmessage = (t) => {
+        var s, f;
+        a.forEach((l) => this.terminateWorker(l)), ((s = t.data) == null ? void 0 : s.ok) === !1 ? o(new Error(t.data.error)) : r((f = t.data) == null ? void 0 : f.data);
+      }, c.onerror = (t) => {
+        a.forEach((s) => this.terminateWorker(s)), o(t);
       };
-      const l = e[0].srcData ?? {};
+      const u = e[0].srcData ?? {};
       a[0].postMessage(
-        { data: l, index: 0 },
-        g(l)
+        { data: u, index: 0 },
+        k(u)
       );
     });
   }
@@ -609,24 +653,30 @@ class _ {
    * factory.release('transform');
    */
   async runPersistent(e, r) {
+    if (this._isTerminated)
+      throw new Error("MainWorkerFactory has been terminated");
     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) => {
+    if (!a) {
+      const i = new g(o.func, {
+        mode: m.Persistent,
+        createWorker: o.createWorker
+      });
+      a = this.trackWorker(i.getWorker), this._persistentWorkers.set(e, a);
+    }
+    return new Promise((i, c) => {
       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);
+        var s, f;
+        ((s = t.data) == null ? void 0 : s.ok) === !1 ? c(new Error(t.data.error)) : i((f = t.data) == null ? void 0 : f.data);
       }, a.onerror = (t) => {
-        f(t);
+        c(t);
       };
-      const l = {
+      const u = {
         type: "run",
         config: r.config
       };
-      r.dataset !== void 0 && (l.dataset = r.dataset), a.postMessage(l, g(l));
+      r.dataset !== void 0 && (u.dataset = r.dataset), a.postMessage(u, k(u));
     });
   }
   /**
@@ -640,10 +690,55 @@ 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();
   }
 }
 export {
-  _ as MainWorkerFactory,
-  h as WorkerFactory
+  E as MainWorkerFactory,
+  g as WorkerFactory
 };

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. */

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.13.0",
   "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
   "type": "module",
   "main": "./dist/index.cjs",