@offmain/workerkit 0.11.0 → 0.12.3

package/README.md

@@ -57,14 +57,68 @@ 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                                                                 |
-| `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 `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                                             |
+
+---
+
+## Module Bundler Integration (`workerURL`)
+
+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.
+
+### Dedicated Worker Script
+
+```ts
+// transform-data.worker.ts
+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) => ({
+      ...item,
+      formattedDate: format(new Date(item.timestamp), 'yyyy-MM-dd'),
+      label: t('transaction', locale),
+    }));
+
+    self.postMessage({ ok: true, data: result });
+  } catch (err) {
+    self.postMessage({ ok: false, error: (err as Error).message });
+  }
+});
+```
+
+### Registering with `workerURL`
+
+```ts
+import { MainWorkerFactory } from '@offmain/workerkit';
+
+const factory = new MainWorkerFactory({
+  workers: [
+    {
+      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,
+    },
+  ] as const,
+});
+
+const settled = await factory.runWorker('transformData', {
+  srcData: { locale: 'es', items: [{ timestamp: Date.now() }] },
+});
+```
 
 ---
 

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"use strict";var y=Object.defineProperty;var m=(s,e,t)=>e in s?y(s,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):s[e]=t;var h=(s,e,t)=>m(s,typeof e!="symbol"?e+"":e,t);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=s=>`
+"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=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -15,13 +15,13 @@ const extractTransferables = (value, seen = new Set()) => {
 
 self.addEventListener('message', async (event) => {
   try {
-    const output = await ${s}(event.data);
+    const output = await ${n}(event.data);
     self.postMessage({ ok: true, data: output }, extractTransferables(output));
   } catch (err) {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
-`,P=s=>`
+`,P=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -36,7 +36,7 @@ const extractTransferables = (value, seen = new Set()) => {
   return Object.values(value).flatMap(v => extractTransferables(v, seen));
 };
 
-const workerFn = ${s};
+const workerFn = ${n};
 let outputPort = null;
 let inputPort = null;
 let pendingData = null;
@@ -93,7 +93,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`,M=s=>`
+`,W=n=>`
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -108,7 +108,7 @@ const extractTransferables = (value, seen = new Set()) => {
   return Object.values(value).flatMap(v => extractTransferables(v, seen));
 };
 
-const workerFn = ${s};
+const workerFn = ${n};
 let cachedDataset = null;
 
 self.addEventListener('message', async (event) => {
@@ -149,8 +149,8 @@ self.addEventListener('message', async (event) => {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 });
-`;var v=(s=>(s.Default="default",s.Pipeline="pipeline",s.Persistent="persistent",s))(v||{});const W=Object.freeze({persistent:M,pipeline:P,default:w});class k{constructor(e,t){h(this,"_worker");const n=(t==null?void 0:t.mode)??"default",a=W[n](e.toString()),u=new Blob([a],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(u))}get getWorker(){return this._worker}}class b{constructor(e){this.results=e}}function p(s,e=new Set){return s===null||typeof s!="object"?[]:e.has(s)?[]:(e.add(s),s instanceof ArrayBuffer||s instanceof MessagePort||typeof ImageBitmap<"u"&&s instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&s instanceof OffscreenCanvas?[s]:ArrayBuffer.isView(s)?[s.buffer]:Array.isArray(s)?s.flatMap(t=>p(t,e)):Object.values(s).flatMap(t=>p(t,e)))}class A{constructor(e){h(this,"_workers");h(this,"_threads");h(this,"_persistentWorkers",new Map);this._workers=e.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new k(e)}partitionArray(e,t){if(!e.length)return[];if(t<=0)throw new Error("numChunks must be positive");const n=Math.min(t,e.length),a=Math.floor(e.length/n),u=e.length%n,f=[];let l=0;for(let r=0;r<n;r++){const o=a+(r<u?1:0);f.push(e.slice(l,l+o)),l+=o}return f}findWorkerByName(e){return this._workers.find(t=>t.name===e)}async runWorker(e,{srcData:t,...n}){const a=this.findWorkerByName(e);if(!a)return Promise.reject(new Error(`Worker "${e}" not found`));const u=a.maxConcurrency??this._threads,f=!!(Array.isArray(t)&&t.length>1&&a.partition),l=f?this.partitionArray(t,u):t,r=this.createWorkerPromises(a,e,{data:l,...n},u,f),o=await Promise.allSettled(r);return new b(o)}createWorkerPromises(e,t,n,a,u){const{data:f,...l}=n;return Array.from({length:a},(r,o)=>{const i=u&&Array.isArray(f)?f[o]:f;return this.runWorkerWithRetry({workerFunc:e.func,workerName:t,index:o,data:{data:i,...l}},e.retries)})}async runWorkerWithRetry(e,t=2){try{return await this.initiateWorker(e)}catch(n){if(t>0)return console.error(`Worker ${e.index} failed, retrying (${t} left):`,n),this.runWorkerWithRetry(e,t-1);throw console.error("Worker failed after all retries:",n),n}}initiateWorker({workerFunc:e,workerName:t,index:n,data:a}){return new Promise((u,f)=>{const r=this.initWorker(e).getWorker;r.onerror=i=>{r.terminate(),f({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},failedResult:i})},r.onmessage=i=>{var c,d;if(((c=i.data)==null?void 0:c.ok)===!1){r.terminate(),f({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},failedResult:new ErrorEvent("error",{message:i.data.error})});return}u({index:n,workerConfigs:{workerFunc:e,workerName:t,index:n,data:a},successResult:new MessageEvent("message",{data:(d=i.data)==null?void 0:d.data})}),r.terminate()};const o={index:n,...Array.isArray(a)?{data:a}:a};r.postMessage(o,p(o))})}async collectResults(e,t={}){const n=e.results.filter(r=>r.status==="fulfilled"),a=e.results.filter(r=>r.status==="rejected"),u=n.map(r=>r.value.successResult.data),f=t.reducer?t.reducer.toString():"(shards) => shards.flat()";return{data:await new Promise((r,o)=>{const i=`
-        const reducer = ${f};
+`;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};
         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([i],{type:"application/javascript"}),d=new Worker(URL.createObjectURL(c));d.onmessage=g=>{d.terminate(),g.data.ok?r(g.data.data):o(new Error(g.data.error))},d.onerror=g=>{d.terminate(),o(g)},d.postMessage(u)}),succeeded:n.length,failed:a.length,errors:a}}async pipeline(e){if(e.length===0)throw new Error("Pipeline requires at least one step");if(e.length===1){const t=e[0],n=this.findWorkerByName(t.worker);if(!n)throw new Error(`Worker "${t.worker}" not found`);const u=this.initWorker(n.func).getWorker;return new Promise((f,l)=>{u.onmessage=o=>{var i,c;u.terminate(),((i=o.data)==null?void 0:i.ok)===!1?l(new Error(o.data.error)):f((c=o.data)==null?void 0:c.data)},u.onerror=o=>{u.terminate(),l(o)};const r=t.srcData??{};u.postMessage({data:r,index:0},p(r))})}return new Promise((t,n)=>{const a=[],u=[];for(const r of e){const o=this.findWorkerByName(r.worker);if(!o){n(new Error(`Worker "${r.worker}" not found`));return}const i=new k(o.func,{mode:v.Pipeline});a.push(i.getWorker)}for(let r=0;r<a.length-1;r++)u.push(new MessageChannel);for(let r=0;r<a.length;r++){const o=[],i={};r>0&&(i.inputPort=u[r-1].port1,o.push(i.inputPort)),r<a.length-1&&(i.outputPort=u[r].port2,o.push(i.outputPort)),a[r].postMessage({__pipeline_ports__:!0,...i},o)}const f=a[a.length-1];f.onmessage=r=>{var o,i;a.forEach(c=>c.terminate()),((o=r.data)==null?void 0:o.ok)===!1?n(new Error(r.data.error)):t((i=r.data)==null?void 0:i.data)},f.onerror=r=>{a.forEach(o=>o.terminate()),n(r)};const l=e[0].srcData??{};a[0].postMessage({data:l,index:0},p(l))})}async runPersistent(e,t){const n=this.findWorkerByName(e);if(!n)throw new Error(`Worker "${e}" not found`);let a=this._persistentWorkers.get(e);return a||(a=new k(n.func,{mode:v.Persistent}).getWorker,this._persistentWorkers.set(e,a)),new Promise((u,f)=>{a.onmessage=r=>{var o,i;((o=r.data)==null?void 0:o.ok)===!1?f(new Error(r.data.error)):u((i=r.data)==null?void 0:i.data)},a.onerror=r=>{f(r)};const l={type:"run",config:t.config};t.dataset!==void 0&&(l.dataset=t.dataset),a.postMessage(l,p(l))})}release(e){const t=this._persistentWorkers.get(e);t&&(t.postMessage({type:"release"}),t.terminate(),this._persistentWorkers.delete(e))}}exports.MainWorkerFactory=A;exports.WorkerFactory=k;
+      `,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;

package/dist/index.js

@@ -1,7 +1,7 @@
-var w = Object.defineProperty;
-var m = (s, e, t) => e in s ? w(s, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : s[e] = t;
-var h = (s, e, t) => m(s, typeof e != "symbol" ? e + "" : e, t);
-const y = (s) => `
+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) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -18,13 +18,13 @@ const extractTransferables = (value, seen = new Set()) => {
 
 self.addEventListener('message', async (event) => {
   try {
-    const output = await ${s}(event.data);
+    const output = await ${n}(event.data);
     self.postMessage({ ok: true, data: output }, extractTransferables(output));
   } catch (err) {
     self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
   }
 })
-`, P = (s) => `
+`, P = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -39,7 +39,7 @@ const extractTransferables = (value, seen = new Set()) => {
   return Object.values(value).flatMap(v => extractTransferables(v, seen));
 };
 
-const workerFn = ${s};
+const workerFn = ${n};
 let outputPort = null;
 let inputPort = null;
 let pendingData = null;
@@ -96,7 +96,7 @@ self.addEventListener('message', (event) => {
     pendingData = event.data;
   }
 });
-`, M = (s) => `
+`, W = (n) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -111,7 +111,7 @@ const extractTransferables = (value, seen = new Set()) => {
   return Object.values(value).flatMap(v => extractTransferables(v, seen));
 };
 
-const workerFn = ${s};
+const workerFn = ${n};
 let cachedDataset = null;
 
 self.addEventListener('message', async (event) => {
@@ -153,13 +153,13 @@ self.addEventListener('message', async (event) => {
   }
 });
 `;
-var v = /* @__PURE__ */ ((s) => (s.Default = "default", s.Pipeline = "pipeline", s.Persistent = "persistent", s))(v || {});
-const W = Object.freeze({
-  persistent: M,
+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
 });
-class k {
+class h {
   /**
    * Creates a new `Worker` from the given function.
    *
@@ -168,16 +168,25 @@ class k {
    *
    * @param workerFunction - The function to run inside the worker thread.
    *   Must be self-contained — it cannot reference variables from the outer
-   *   scope because it is serialised via `.toString()`.
+   *   scope because it is serialized via `.toString()`.
    * @param options - Optional configuration. Set `mode` to control the
    *   worker execution mode (default, pipeline, or persistent).
    */
-  constructor(e, t) {
-    h(this, "_worker");
-    const n = (t == null ? void 0 : t.mode) ?? "default", a = W[n](e.toString()), f = new Blob([a], {
-      type: "application/javascript"
-    });
-    this._worker = new Worker(URL.createObjectURL(f));
+  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."
+      );
   }
   /**
    * Returns the underlying native `Worker` instance.
@@ -194,31 +203,33 @@ class b {
     this.results = e;
   }
 }
-function p(s, e = /* @__PURE__ */ new Set()) {
-  return s === null || typeof s != "object" ? [] : e.has(s) ? [] : (e.add(s), s instanceof ArrayBuffer || s instanceof MessagePort || typeof ImageBitmap < "u" && s instanceof ImageBitmap || typeof OffscreenCanvas < "u" && s instanceof OffscreenCanvas ? [s] : ArrayBuffer.isView(s) ? [s.buffer] : Array.isArray(s) ? s.flatMap((t) => p(t, e)) : Object.values(s).flatMap(
-    (t) => p(t, 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)
   ));
 }
-class B {
+class _ {
   /**
    * Creates a new `MainWorkerFactory`.
    *
    * @param options - Configuration object containing the `workers` registry.
    */
   constructor(e) {
-    h(this, "_workers");
-    h(this, "_threads");
-    h(this, "_persistentWorkers", /* @__PURE__ */ new Map());
+    k(this, "_workers");
+    k(this, "_threads");
+    k(this, "_persistentWorkers", /* @__PURE__ */ new Map());
     this._workers = e.workers, this._threads = navigator.hardwareConcurrency;
   }
   /**
-   * Instantiates a {@link WorkerFactory} for the given worker function.
+   * Instantiates a {@link WorkerFactory} for the given worker configuration.
    *
-   * @param workerFunction - The function to run inside the worker thread.
+   * @param config - The worker configuration containing `func` or `workerURL`.
    * @returns A new `WorkerFactory` wrapping the worker.
    */
   initWorker(e) {
-    return new k(e);
+    return new h(e.func, {
+      workerURL: e.workerURL
+    });
   }
   /**
    * Splits an array into up to `numChunks` evenly-sized sub-arrays.
@@ -236,16 +247,16 @@ class B {
    * partitionArray([1, 2, 3, 4, 5], 3);
    * // → [[1, 2], [3, 4], [5]]
    */
-  partitionArray(e, t) {
+  partitionArray(e, r) {
     if (!e.length) return [];
-    if (t <= 0) throw new Error("numChunks must be positive");
-    const n = Math.min(t, e.length), a = Math.floor(e.length / n), f = e.length % n, u = [];
+    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 r = 0; r < n; r++) {
-      const o = a + (r < f ? 1 : 0);
-      u.push(e.slice(l, l + o)), l += o;
+    for (let t = 0; t < o; t++) {
+      const s = a + (t < i ? 1 : 0);
+      f.push(e.slice(l, l + s)), l += s;
     }
-    return u;
+    return f;
   }
   /**
    * Looks up a registered worker configuration by name.
@@ -254,7 +265,7 @@ class B {
    * @returns The matching config, or `undefined` if not found.
    */
   findWorkerByName(e) {
-    return this._workers.find((t) => t.name === e);
+    return this._workers.find((r) => r.name === e);
   }
   /**
    * Runs a named worker against the provided data, distributing work across
@@ -283,20 +294,20 @@ class B {
    * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3] });
    */
   async runWorker(e, {
-    srcData: t,
-    ...n
+    srcData: r,
+    ...o
   }) {
     const a = this.findWorkerByName(e);
     if (!a)
       return Promise.reject(new Error(`Worker "${e}" not found`));
-    const f = a.maxConcurrency ?? this._threads, u = !!(Array.isArray(t) && t.length > 1 && a.partition), l = u ? this.partitionArray(t, f) : t, r = this.createWorkerPromises(
+    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,
       e,
-      { data: l, ...n },
-      f,
-      u
-    ), o = await Promise.allSettled(r);
-    return new b(o);
+      { data: l, ...o },
+      i,
+      f
+    ), s = await Promise.allSettled(t);
+    return new b(s);
   }
   /**
    * Builds the array of per-thread worker promises for a single `runWorker`
@@ -312,16 +323,17 @@ class B {
    * @param isPartitioned  - Whether `data` is a pre-split array of shards.
    * @returns An array of promises, one per thread.
    */
-  createWorkerPromises(e, t, n, a, f) {
-    const { data: u, ...l } = n;
-    return Array.from({ length: a }, (r, o) => {
-      const i = f && Array.isArray(u) ? u[o] : u;
+  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;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
-          workerName: t,
-          index: o,
-          data: { data: i, ...l }
+          workerURL: e.workerURL,
+          workerName: r,
+          index: s,
+          data: { data: u, ...l }
         },
         e.retries
       );
@@ -339,16 +351,16 @@ class B {
    * @returns The successful {@link WorkerResult} once the worker resolves.
    * @throws The last caught error when all retries are exhausted.
    */
-  async runWorkerWithRetry(e, t = 2) {
+  async runWorkerWithRetry(e, r = 2) {
     try {
       return await this.initiateWorker(e);
-    } catch (n) {
-      if (t > 0)
+    } catch (o) {
+      if (r > 0)
         return console.error(
-          `Worker ${e.index} failed, retrying (${t} left):`,
-          n
-        ), this.runWorkerWithRetry(e, t - 1);
-      throw console.error("Worker failed after all retries:", n), n;
+          `Worker ${e.index} failed, retrying (${r} left):`,
+          o
+        ), this.runWorkerWithRetry(e, r - 1);
+      throw console.error("Worker failed after all retries:", o), o;
     }
   }
   /**
@@ -366,48 +378,54 @@ class B {
    * The underlying `Worker` is always terminated after the first message,
    * whether it succeeded or failed.
    *
-   * @param instanceConfig - Worker function, name, shard index, and data.
+   * @param instanceConfig - Worker function, URL, name, shard index, and data.
    * @returns A promise that resolves with the worker's result.
    */
   initiateWorker({
     workerFunc: e,
-    workerName: t,
-    index: n,
-    data: a
+    workerURL: r,
+    workerName: o,
+    index: a,
+    data: i
   }) {
-    return new Promise((f, u) => {
-      const r = this.initWorker(e).getWorker;
-      r.onerror = (i) => {
-        r.terminate(), u({
-          index: n,
-          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
-          failedResult: i
+    return new Promise((f, l) => {
+      const s = this.initWorker({
+        name: o,
+        role: "",
+        func: e,
+        workerURL: r
+      }).getWorker;
+      s.onerror = (c) => {
+        s.terminate(), l({
+          index: a,
+          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
+          failedResult: c
         });
-      }, r.onmessage = (i) => {
-        var c, d;
-        if (((c = i.data) == null ? void 0 : c.ok) === !1) {
-          r.terminate(), u({
-            index: n,
-            workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+      }, 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 },
             failedResult: new ErrorEvent("error", {
-              message: i.data.error
+              message: c.data.error
             })
           });
           return;
         }
         f({
-          index: n,
-          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+          index: a,
+          workerConfigs: { workerFunc: e, workerName: o, index: a, data: i },
           successResult: new MessageEvent("message", {
-            data: (d = i.data) == null ? void 0 : d.data
+            data: (p = c.data) == null ? void 0 : p.data
           })
-        }), r.terminate();
+        }), s.terminate();
       };
-      const o = {
-        index: n,
-        ...Array.isArray(a) ? { data: a } : a
+      const u = {
+        index: a,
+        ...Array.isArray(i) ? { data: i } : i
       };
-      r.postMessage(o, p(o));
+      s.postMessage(u, g(u));
     });
   }
   /**
@@ -442,16 +460,16 @@ class B {
    *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
    * });
    */
-  async collectResults(e, t = {}) {
-    const n = e.results.filter(
-      (r) => r.status === "fulfilled"
+  async collectResults(e, r = {}) {
+    const o = e.results.filter(
+      (t) => t.status === "fulfilled"
     ), a = e.results.filter(
-      (r) => r.status === "rejected"
-    ), f = n.map((r) => r.value.successResult.data), u = t.reducer ? t.reducer.toString() : "(shards) => shards.flat()";
+      (t) => t.status === "rejected"
+    ), i = o.map((t) => t.value.successResult.data), f = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
     return {
-      data: await new Promise((r, o) => {
-        const i = `
-        const reducer = ${u};
+      data: await new Promise((t, s) => {
+        const u = `
+        const reducer = ${f};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -460,14 +478,14 @@ class B {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, c = new Blob([i], { type: "application/javascript" }), d = new Worker(URL.createObjectURL(c));
-        d.onmessage = (g) => {
-          d.terminate(), g.data.ok ? r(g.data.data) : o(new Error(g.data.error));
-        }, d.onerror = (g) => {
-          d.terminate(), o(g);
-        }, d.postMessage(f);
+      `, 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: n.length,
+      succeeded: o.length,
       failed: a.length,
       errors: a
     };
@@ -502,56 +520,57 @@ class B {
     if (e.length === 0)
       throw new Error("Pipeline requires at least one step");
     if (e.length === 1) {
-      const t = e[0], n = this.findWorkerByName(t.worker);
-      if (!n) throw new Error(`Worker "${t.worker}" not found`);
-      const f = this.initWorker(n.func).getWorker;
-      return new Promise((u, l) => {
-        f.onmessage = (o) => {
-          var i, c;
-          f.terminate(), ((i = o.data) == null ? void 0 : i.ok) === !1 ? l(new Error(o.data.error)) : u((c = o.data) == null ? void 0 : c.data);
-        }, f.onerror = (o) => {
-          f.terminate(), l(o);
+      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 = t.srcData ?? {};
-        f.postMessage(
-          { data: r, index: 0 },
-          p(r)
+        const t = r.srcData ?? {};
+        i.postMessage(
+          { data: t, index: 0 },
+          g(t)
         );
       });
     }
-    return new Promise((t, n) => {
-      const a = [], f = [];
-      for (const r of e) {
-        const o = this.findWorkerByName(r.worker);
-        if (!o) {
-          n(new Error(`Worker "${r.worker}" not found`));
+    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 i = new k(o.func, {
-          mode: v.Pipeline
+        const u = new h(s.func, {
+          mode: w.Pipeline,
+          workerURL: s.workerURL
         });
-        a.push(i.getWorker);
+        a.push(u.getWorker);
       }
-      for (let r = 0; r < a.length - 1; r++)
-        f.push(new MessageChannel());
-      for (let r = 0; r < a.length; r++) {
-        const o = [], i = {};
-        r > 0 && (i.inputPort = f[r - 1].port1, o.push(i.inputPort)), r < a.length - 1 && (i.outputPort = f[r].port2, o.push(i.outputPort)), a[r].postMessage(
-          { __pipeline_ports__: !0, ...i },
-          o
+      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 u = a[a.length - 1];
-      u.onmessage = (r) => {
-        var o, i;
-        a.forEach((c) => c.terminate()), ((o = r.data) == null ? void 0 : o.ok) === !1 ? n(new Error(r.data.error)) : t((i = r.data) == null ? void 0 : i.data);
-      }, u.onerror = (r) => {
-        a.forEach((o) => o.terminate()), n(r);
+      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 l = e[0].srcData ?? {};
       a[0].postMessage(
         { data: l, index: 0 },
-        p(l)
+        g(l)
       );
     });
   }
@@ -589,24 +608,25 @@ class B {
    * // Release when done
    * factory.release('transform');
    */
-  async runPersistent(e, t) {
-    const n = this.findWorkerByName(e);
-    if (!n) throw new Error(`Worker "${e}" not found`);
+  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 k(n.func, {
-      mode: v.Persistent
-    }).getWorker, this._persistentWorkers.set(e, a)), new Promise((f, u) => {
-      a.onmessage = (r) => {
-        var o, i;
-        ((o = r.data) == null ? void 0 : o.ok) === !1 ? u(new Error(r.data.error)) : f((i = r.data) == null ? void 0 : i.data);
-      }, a.onerror = (r) => {
-        u(r);
+    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);
       };
       const l = {
         type: "run",
-        config: t.config
+        config: r.config
       };
-      t.dataset !== void 0 && (l.dataset = t.dataset), a.postMessage(l, p(l));
+      r.dataset !== void 0 && (l.dataset = r.dataset), a.postMessage(l, g(l));
     });
   }
   /**
@@ -619,11 +639,11 @@ class B {
    * @param workerName - Name of the persistent worker to release.
    */
   release(e) {
-    const t = this._persistentWorkers.get(e);
-    t && (t.postMessage({ type: "release" }), t.terminate(), this._persistentWorkers.delete(e));
+    const r = this._persistentWorkers.get(e);
+    r && (r.postMessage({ type: "release" }), r.terminate(), this._persistentWorkers.delete(e));
   }
 }
 export {
-  B as MainWorkerFactory,
-  k as WorkerFactory
+  _ as MainWorkerFactory,
+  h as WorkerFactory
 };

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

@@ -45,9 +45,9 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
         workers: TConfigs;
     });
     /**
-     * Instantiates a {@link WorkerFactory} for the given worker function.
+     * Instantiates a {@link WorkerFactory} for the given worker configuration.
      *
-     * @param workerFunction - The function to run inside the worker thread.
+     * @param config - The worker configuration containing `func` or `workerURL`.
      * @returns A new `WorkerFactory` wrapping the worker.
      */
     private initWorker;
@@ -147,7 +147,7 @@ declare class MainWorkerFactory<TConfigs extends readonly WorkerConfig<WorkerFun
      * The underlying `Worker` is always terminated after the first message,
      * whether it succeeded or failed.
      *
-     * @param instanceConfig - Worker function, name, shard index, and data.
+     * @param instanceConfig - Worker function, URL, name, shard index, and data.
      * @returns A promise that resolves with the worker's result.
      */
     private initiateWorker;

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

@@ -23,8 +23,13 @@ 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. */
-    func: TFunc;
+    /** The worker function that will be serialised and run in a thread. Optional if `workerURL` 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.
+     */
+    workerURL?: string | URL;
     /**
      * Maximum number of parallel threads to spawn for this worker.
      * Defaults to `navigator.hardwareConcurrency` when omitted.
@@ -41,6 +46,11 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
      * array.
      */
     partition?: boolean;
+    /**
+     * A list of worker functions that must complete before this worker can start.
+     * If any dependency fails, this worker will not run.
+     */
+    dependencies?: Array<() => void>;
 }
 /**
  * Derives a `name → function` map from a readonly tuple of
@@ -52,9 +62,11 @@ export interface WorkerConfig<TFunc extends WorkerFunction = WorkerFunction> {
  * @typeParam T - The readonly tuple of `WorkerConfig` values.
  */
 export type WorkerConfigMap<T extends readonly WorkerConfig<WorkerFunction<any, any>>[]> = {
-    [K in T[number]['name']]: Extract<T[number], {
+    [K in T[number]['name']]: NonNullable<Extract<T[number], {
+        name: K;
+    }>['func']> extends WorkerFunction ? NonNullable<Extract<T[number], {
         name: K;
-    }>['func'];
+    }>['func']> : WorkerFunction;
 };
 /**
  * Extracts the `params` type from a {@link WorkerFunction}.
@@ -91,8 +103,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. */
-    workerFunc: TFunc;
+    /** The function serialised and executed inside the thread (optional if `workerURL` is set). */
+    workerFunc?: TFunc;
+    /** Worker script URL (string or URL object). */
+    workerURL?: string | URL;
     /** 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,9 +7,13 @@ 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;
 }
 /**
- * Low-level factory that serialises a {@link WorkerFunction} into a Blob URL
+ * Low-level factory that serializes a {@link WorkerFunction} into a Blob URL
  * and spawns a native `Worker` from it.
  *
  * `WorkerFactory` is an internal building block used by `MainWorkerFactory`.
@@ -39,11 +43,11 @@ declare class WorkerFactory {
      *
      * @param workerFunction - The function to run inside the worker thread.
      *   Must be self-contained — it cannot reference variables from the outer
-     *   scope because it is serialised via `.toString()`.
+     *   scope because it is serialized via `.toString()`.
      * @param options - Optional configuration. Set `mode` to control the
      *   worker execution mode (default, pipeline, or persistent).
      */
-    constructor(workerFunction: WorkerFunction, options?: WorkerFactoryOptions);
+    constructor(workerFunction?: WorkerFunction, options?: WorkerFactoryOptions);
     /**
      * Returns the underlying native `Worker` instance.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offmain/workerkit",
-  "version": "0.11.0",
+  "version": "0.12.3",
   "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -76,6 +76,9 @@
     "typescript": "^5.7.2",
     "vite": "^6.3.3",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^1.0.0"
+    "vitest": "^1.0.0",
+    "luxon": "^3.7.2",
+    "i18next": "^25.5.1",
+    "@types/luxon": "^3.7.2"
   }
 }