@offmain/workerkit 0.8.9 → 0.10.0

package/dist/index.js

@@ -1,7 +1,7 @@
-var y = Object.defineProperty;
-var g = (t, e, r) => e in t ? y(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
-var h = (t, e, r) => g(t, typeof e != "symbol" ? e + "" : e, r);
-const m = (t) => `
+var w = Object.defineProperty;
+var m = (o, e, t) => e in o ? w(o, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : o[e] = t;
+var h = (o, e, t) => m(o, typeof e != "symbol" ? e + "" : e, t);
+const y = (o) => `
 const extractTransferables = (value, seen = new Set()) => {
   if (value === null || typeof value !== 'object') return [];
   if (seen.has(value)) return [];
@@ -17,127 +17,357 @@ const extractTransferables = (value, seen = new Set()) => {
 };
 
 self.addEventListener('message', async (event) => {
-    const begin = performance.now();
-    const output = await ${t}(event.data);
-    self.postMessage(output, extractTransferables(output));
-  })
+  try {
+    const output = await ${o}(event.data);
+    self.postMessage({ ok: true, data: output }, extractTransferables(output));
+  } catch (err) {
+    self.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+})
+`, v = (o) => `
+const extractTransferables = (value, seen = new Set()) => {
+  if (value === null || typeof value !== 'object') return [];
+  if (seen.has(value)) return [];
+  seen.add(value);
+  if (value instanceof ArrayBuffer || value instanceof MessagePort ||
+      (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap) ||
+      (typeof OffscreenCanvas !== 'undefined' && value instanceof OffscreenCanvas)) {
+    return [value];
+  }
+  if (ArrayBuffer.isView(value)) return [value.buffer];
+  if (Array.isArray(value)) return value.flatMap(i => extractTransferables(i, seen));
+  return Object.values(value).flatMap(v => extractTransferables(v, seen));
+};
+
+const workerFn = ${o};
+let outputPort = null;
+let inputPort = null;
+let pendingData = null;
+
+async function processData(data) {
+  try {
+    const output = await workerFn(data);
+    const result = { ok: true, data: output };
+    const transfers = extractTransferables(output);
+    if (outputPort) {
+      outputPort.postMessage(result, transfers);
+    } else {
+      self.postMessage(result, transfers);
+    }
+  } catch (err) {
+    const result = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    if (outputPort) {
+      outputPort.postMessage(result);
+    } else {
+      self.postMessage(result);
+    }
+  }
+}
+
+self.addEventListener('message', (event) => {
+  if (event.data && event.data.__pipeline_ports__) {
+    if (event.data.outputPort) {
+      outputPort = event.data.outputPort;
+    }
+    if (event.data.inputPort) {
+      inputPort = event.data.inputPort;
+      inputPort.onmessage = (e) => {
+        if (e.data && e.data.ok === false) {
+          // Propagate errors through the pipeline
+          if (outputPort) outputPort.postMessage(e.data);
+          else self.postMessage(e.data);
+        } else {
+          processData({ data: e.data.data, index: 0 });
+        }
+      };
+    }
+    // If we already received data before ports, process it now
+    if (pendingData !== null) {
+      processData(pendingData);
+      pendingData = null;
+    }
+    return;
+  }
+  // First worker in pipeline or standalone — process directly
+  if (!inputPort) {
+    processData(event.data);
+  } else {
+    // Store data until ports are configured
+    pendingData = event.data;
+  }
+});
 `;
-class w {
-  constructor(e) {
+class k {
+  /**
+   * Creates a new `Worker` from the given function.
+   *
+   * The function is stringified, embedded into a self-contained worker script,
+   * converted to a `Blob` URL, and passed to the `Worker` constructor.
+   *
+   * @param workerFunction - The function to run inside the worker thread.
+   *   Must be self-contained — it cannot reference variables from the outer
+   *   scope because it is serialised via `.toString()`.
+   * @param options - Optional configuration. Set `pipeline: true` for
+   *   pipeline-aware workers that support MessagePort forwarding.
+   */
+  constructor(e, t) {
     h(this, "_worker");
-    const r = m(e.toString()), s = new Blob([r], {
+    const a = (t != null && t.pipeline ? v : y)(e.toString()), u = new Blob([a], {
       type: "application/javascript"
     });
-    this._worker = new Worker(URL.createObjectURL(s));
+    this._worker = new Worker(URL.createObjectURL(u));
   }
+  /**
+   * Returns the underlying native `Worker` instance.
+   *
+   * Use this to attach `onmessage` / `onerror` handlers and call
+   * `postMessage` / `terminate` directly.
+   */
   get getWorker() {
     return this._worker;
   }
 }
-function p(t, e = /* @__PURE__ */ new Set()) {
-  return t === null || typeof t != "object" ? [] : e.has(t) ? [] : (e.add(t), t instanceof ArrayBuffer || t instanceof MessagePort || typeof ImageBitmap < "u" && t instanceof ImageBitmap || typeof OffscreenCanvas < "u" && t instanceof OffscreenCanvas ? [t] : ArrayBuffer.isView(t) ? [t.buffer] : Array.isArray(t) ? t.flatMap((r) => p(r, e)) : Object.values(t).flatMap(
-    (r) => p(r, e)
+class P {
+  constructor(e) {
+    this.results = e;
+  }
+}
+function g(o, e = /* @__PURE__ */ new Set()) {
+  return o === null || typeof o != "object" ? [] : e.has(o) ? [] : (e.add(o), o instanceof ArrayBuffer || o instanceof MessagePort || typeof ImageBitmap < "u" && o instanceof ImageBitmap || typeof OffscreenCanvas < "u" && o instanceof OffscreenCanvas ? [o] : ArrayBuffer.isView(o) ? [o.buffer] : Array.isArray(o) ? o.flatMap((t) => g(t, e)) : Object.values(o).flatMap(
+    (t) => g(t, e)
   ));
 }
-class v {
-  constructor(e, r) {
+class M {
+  /**
+   * Creates a new `MainWorkerFactory`.
+   *
+   * @param options - Configuration object containing the `workers` registry.
+   */
+  constructor(e) {
     h(this, "_workers");
     h(this, "_threads");
-    this._workers = r.workers, this._threads = navigator.hardwareConcurrency;
+    this._workers = e.workers, this._threads = navigator.hardwareConcurrency;
   }
+  /**
+   * Instantiates a {@link WorkerFactory} for the given worker function.
+   *
+   * @param workerFunction - The function to run inside the worker thread.
+   * @returns A new `WorkerFactory` wrapping the worker.
+   */
   initWorker(e) {
-    return new w(e);
+    return new k(e);
   }
   /**
-   * Partitions an array into up to numChunks evenly-sized chunks.
+   * Splits an array into up to `numChunks` evenly-sized sub-arrays.
+   *
+   * When the array length is not evenly divisible, the first `remainder`
+   * chunks receive one extra element so no data is lost.
+   *
+   * @param array     - The source array to partition.
+   * @param numChunks - Maximum number of chunks to produce.
+   *   Clamped to `array.length` so you never get empty chunks.
+   * @returns An array of sub-arrays. Returns `[]` when `array` is empty.
+   * @throws {Error} When `numChunks` is not a positive integer.
+   *
+   * @example
+   * partitionArray([1, 2, 3, 4, 5], 3);
+   * // → [[1, 2], [3, 4], [5]]
    */
-  partitionArray(e, r) {
+  partitionArray(e, t) {
     if (!e.length) return [];
-    if (r <= 0) throw new Error("numChunks must be positive");
-    const s = Math.min(r, e.length), a = Math.floor(e.length / s), c = e.length % s, o = [];
+    if (t <= 0) throw new Error("numChunks must be positive");
+    const n = Math.min(t, e.length), a = Math.floor(e.length / n), u = e.length % n, l = [];
     let f = 0;
-    for (let n = 0; n < s; n++) {
-      const i = a + (n < c ? 1 : 0);
-      o.push(e.slice(f, f + i)), f += i;
+    for (let r = 0; r < n; r++) {
+      const s = a + (r < u ? 1 : 0);
+      l.push(e.slice(f, f + s)), f += s;
     }
-    return o;
+    return l;
   }
+  /**
+   * Looks up a registered worker configuration by name.
+   *
+   * @param name - The `name` field of the target {@link WorkerConfig}.
+   * @returns The matching config, or `undefined` if not found.
+   */
   findWorkerByName(e) {
-    return this._workers.find((r) => r.name === e);
+    return this._workers.find((t) => t.name === e);
   }
-  async runWorker(e, { srcData: r, ...s }) {
+  /**
+   * Runs a named worker against the provided data, distributing work across
+   * threads when the worker is configured for partitioning.
+   *
+   * When `config.partition` is `true` and `srcData` is an array with more
+   * than one element, the array is split into up to `maxConcurrency` (or
+   * `navigator.hardwareConcurrency`) shards and each shard is processed by
+   * a separate worker thread in parallel.
+   *
+   * All threads are awaited with `Promise.allSettled`, so a failure in one
+   * shard does not cancel the others. Use {@link collectResults} to merge
+   * the settled output.
+   *
+   * @typeParam TName - The literal name of the worker to run (inferred from
+   *   the registered `workers` tuple).
+   *
+   * @param workerName - Name of the worker as declared in the `workers` config.
+   * @param params     - Object containing `srcData` (the payload) plus any
+   *   additional key/value pairs forwarded to the worker verbatim.
+   *
+   * @returns A {@link TypedSettledResults} wrapping the settled promises from
+   *   all spawned worker threads.
+   *
+   * @example
+   * const settled = await foreman.runWorker('sum', { srcData: [1, 2, 3] });
+   */
+  async runWorker(e, {
+    srcData: t,
+    ...n
+  }) {
     const a = this.findWorkerByName(e);
     if (!a)
       return Promise.reject(new Error(`Worker "${e}" not found`));
-    const c = a.maxConcurrency ?? this._threads, o = !!(Array.isArray(r) && r.length > 1 && a.partition), f = o ? this.partitionArray(r, c) : r, n = this.createWorkerPromises(
+    const u = a.maxConcurrency ?? this._threads, l = !!(Array.isArray(t) && t.length > 1 && a.partition), f = l ? this.partitionArray(t, u) : t, r = this.createWorkerPromises(
       a,
       e,
-      { data: f, ...s },
-      c,
-      o
-    );
-    return Promise.allSettled(n);
-  }
-  createWorkerPromises(e, r, s, a, c) {
-    const { data: o, ...f } = s;
-    return Array.from({ length: a }, (n, i) => {
-      const u = c && Array.isArray(o) ? o[i] : o;
+      { data: f, ...n },
+      u,
+      l
+    ), s = await Promise.allSettled(r);
+    return new P(s);
+  }
+  /**
+   * Builds the array of per-thread worker promises for a single `runWorker`
+   * call.
+   *
+   * When `isPartitioned` is `true`, each promise receives its own slice of
+   * `srcData`; otherwise every thread receives the full payload.
+   *
+   * @param config         - The resolved {@link WorkerConfig} for this run.
+   * @param workerName     - Name used in error/retry logging.
+   * @param srcWorkerData  - Combined `{ data, ...otherParams }` payload.
+   * @param threadCount    - Number of parallel worker threads to spawn.
+   * @param isPartitioned  - Whether `data` is a pre-split array of shards.
+   * @returns An array of promises, one per thread.
+   */
+  createWorkerPromises(e, t, n, a, u) {
+    const { data: l, ...f } = n;
+    return Array.from({ length: a }, (r, s) => {
+      const i = u && Array.isArray(l) ? l[s] : l;
       return this.runWorkerWithRetry(
         {
           workerFunc: e.func,
-          workerName: r,
-          index: i,
-          data: { data: u, ...f }
+          workerName: t,
+          index: s,
+          data: { data: i, ...f }
         },
         e.retries
       );
     });
   }
-  async runWorkerWithRetry(e, r = 2) {
+  /**
+   * Runs a single worker instance, retrying on failure up to `retryCount`
+   * times before re-throwing the last error.
+   *
+   * Each retry is logged to `console.error` with the remaining attempt count
+   * so failures are visible during development.
+   *
+   * @param instanceConfig - Full configuration for the worker instance.
+   * @param retryCount     - Remaining retry attempts (default `2`).
+   * @returns The successful {@link WorkerResult} once the worker resolves.
+   * @throws The last caught error when all retries are exhausted.
+   */
+  async runWorkerWithRetry(e, t = 2) {
     try {
       return await this.initiateWorker(e);
-    } catch (s) {
-      if (r > 0)
+    } catch (n) {
+      if (t > 0)
         return console.error(
-          `Worker ${e.index} failed, retrying (${r} left):`,
-          s
-        ), this.runWorkerWithRetry(e, r - 1);
-      throw console.error("Worker failed after all retries:", s), s;
+          `Worker ${e.index} failed, retrying (${t} left):`,
+          n
+        ), this.runWorkerWithRetry(e, t - 1);
+      throw console.error("Worker failed after all retries:", n), n;
     }
   }
+  /**
+   * Spawns a single worker thread, posts the payload, and resolves or rejects
+   * based on the message the worker sends back.
+   *
+   * The worker is expected to respond with either:
+   * - `{ ok: true, data: T }` — success; resolves with a {@link WorkerResult}.
+   * - `{ ok: false, error: string }` — logical failure; rejects with a
+   *   structured error object.
+   *
+   * Any transferable objects found in the payload are moved (not copied) to
+   * the worker via the `transfer` list of `postMessage`.
+   *
+   * The underlying `Worker` is always terminated after the first message,
+   * whether it succeeded or failed.
+   *
+   * @param instanceConfig - Worker function, name, shard index, and data.
+   * @returns A promise that resolves with the worker's result.
+   */
   initiateWorker({
     workerFunc: e,
-    workerName: r,
-    index: s,
+    workerName: t,
+    index: n,
     data: a
   }) {
-    return new Promise((c, o) => {
-      const n = this.initWorker(e).getWorker;
-      n.onerror = (u) => {
-        n.terminate(), o({
-          index: s,
-          workerConfigs: { workerFunc: e, workerName: r, index: s, data: a },
-          failedResult: u
+    return new Promise((u, l) => {
+      const r = this.initWorker(e).getWorker;
+      r.onerror = (i) => {
+        r.terminate(), l({
+          index: n,
+          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+          failedResult: i
         });
-      }, n.onmessage = (u) => {
-        c({
-          index: s,
-          workerConfigs: { workerFunc: e, workerName: r, index: s, data: a },
-          successResult: u
-        }), n.terminate();
+      }, r.onmessage = (i) => {
+        var c, p;
+        if (((c = i.data) == null ? void 0 : c.ok) === !1) {
+          r.terminate(), l({
+            index: n,
+            workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+            failedResult: new ErrorEvent("error", {
+              message: i.data.error
+            })
+          });
+          return;
+        }
+        u({
+          index: n,
+          workerConfigs: { workerFunc: e, workerName: t, index: n, data: a },
+          successResult: new MessageEvent("message", {
+            data: (p = i.data) == null ? void 0 : p.data
+          })
+        }), r.terminate();
       };
-      const i = {
-        index: s,
+      const s = {
+        index: n,
         ...Array.isArray(a) ? { data: a } : a
       };
-      n.postMessage(i, p(i));
+      r.postMessage(s, g(s));
     });
   }
   /**
-   * Collects and merges the settled results from `runWorker` — off the main thread.
+   * Collects and merges the settled results from {@link runWorker} — off the
+   * main thread.
+   *
+   * Fulfilled shards are extracted and passed to the `reducer` function, which
+   * runs inside a dedicated inline worker so the merge itself never blocks the
+   * main thread. Failed shards are counted and their raw rejection reasons are
+   * preserved in `errors`.
    *
-   * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
-   * @param options  Optional `reducer` function (must be self-contained)
+   * @typeParam T - The per-shard data type (inferred from `settled`).
+   * @typeParam R - The final merged output type (defaults to a flat array of
+   *   `T` items when no custom reducer is provided).
+   *
+   * @param settled  - The {@link TypedSettledResults} returned by `runWorker`.
+   * @param options  - Optional {@link CollectOptions}. Supply a `reducer` to
+   *   control how shards are merged. The reducer **must be self-contained**
+   *   (no closures over external variables) because it is serialised and run
+   *   inside a worker.
+   *
+   * @returns A {@link CollectedResult} with the merged `data`, counts of
+   *   `succeeded`/`failed` shards, and the raw `errors` array.
    *
    * @example
    * // default: flat array of all shard data
@@ -149,16 +379,16 @@ class v {
    *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
    * });
    */
-  async collectResults(e, r = {}) {
-    const s = e.filter(
-      (n) => n.status === "fulfilled"
-    ), a = e.filter(
-      (n) => n.status === "rejected"
-    ), c = s.map((n) => n.value.successResult.data), o = r.reducer ? r.reducer.toString() : "(shards) => shards.flat()";
+  async collectResults(e, t = {}) {
+    const n = e.results.filter(
+      (r) => r.status === "fulfilled"
+    ), a = e.results.filter(
+      (r) => r.status === "rejected"
+    ), u = n.map((r) => r.value.successResult.data), l = t.reducer ? t.reducer.toString() : "(shards) => shards.flat()";
     return {
-      data: await new Promise((n, i) => {
-        const u = `
-        const reducer = ${o};
+      data: await new Promise((r, s) => {
+        const i = `
+        const reducer = ${l};
         self.addEventListener('message', (event) => {
           try {
             const result = reducer(event.data);
@@ -167,20 +397,96 @@ class v {
             self.postMessage({ ok: false, error: String(err) });
           }
         });
-      `, k = new Blob([u], { type: "application/javascript" }), l = new Worker(URL.createObjectURL(k));
-        l.onmessage = (d) => {
-          l.terminate(), d.data.ok ? n(d.data.data) : i(new Error(d.data.error));
-        }, l.onerror = (d) => {
-          l.terminate(), i(d);
-        }, l.postMessage(c);
+      `, c = new Blob([i], { type: "application/javascript" }), p = new Worker(URL.createObjectURL(c));
+        p.onmessage = (d) => {
+          p.terminate(), d.data.ok ? r(d.data.data) : s(new Error(d.data.error));
+        }, p.onerror = (d) => {
+          p.terminate(), s(d);
+        }, p.postMessage(u);
       }),
-      succeeded: s.length,
+      succeeded: n.length,
       failed: a.length,
       errors: a
     };
   }
+  /**
+   * Runs a chain of workers where each step's output feeds directly into the
+   * next step — **without passing through the main thread**.
+   *
+   * Internally, adjacent workers are connected via `MessageChannel` ports.
+   * Only the final result is sent back to the main thread, minimising
+   * serialisation overhead for large intermediate data.
+   *
+   * @param steps - An ordered array of pipeline steps. The first step must
+   *   include `srcData`; subsequent steps receive the previous step's output.
+   *
+   * @returns A promise that resolves with the final step's output.
+   *
+   * @example
+   * const result = await foreman.pipeline([
+   *   { worker: 'fetchPosts', srcData: { url: '/api/posts' } },
+   *   { worker: 'transformPosts' },
+   *   { worker: 'filterPosts' },
+   * ]);
+   * console.log(result); // final transformed + filtered data
+   */
+  async pipeline(e) {
+    if (e.length === 0)
+      throw new Error("Pipeline requires at least one step");
+    if (e.length === 1) {
+      const t = e[0], n = this.findWorkerByName(t.worker);
+      if (!n) throw new Error(`Worker "${t.worker}" not found`);
+      const u = this.initWorker(n.func).getWorker;
+      return new Promise((l, f) => {
+        u.onmessage = (s) => {
+          var i, c;
+          u.terminate(), ((i = s.data) == null ? void 0 : i.ok) === !1 ? f(new Error(s.data.error)) : l((c = s.data) == null ? void 0 : c.data);
+        }, u.onerror = (s) => {
+          u.terminate(), f(s);
+        };
+        const r = t.srcData ?? {};
+        u.postMessage(
+          { data: r, index: 0 },
+          g(r)
+        );
+      });
+    }
+    return new Promise((t, n) => {
+      const a = [], u = [];
+      for (const r of e) {
+        const s = this.findWorkerByName(r.worker);
+        if (!s) {
+          n(new Error(`Worker "${r.worker}" not found`));
+          return;
+        }
+        const i = new k(s.func, { pipeline: !0 });
+        a.push(i.getWorker);
+      }
+      for (let r = 0; r < a.length - 1; r++)
+        u.push(new MessageChannel());
+      for (let r = 0; r < a.length; r++) {
+        const s = [], i = {};
+        r > 0 && (i.inputPort = u[r - 1].port1, s.push(i.inputPort)), r < a.length - 1 && (i.outputPort = u[r].port2, s.push(i.outputPort)), a[r].postMessage(
+          { __pipeline_ports__: !0, ...i },
+          s
+        );
+      }
+      const l = a[a.length - 1];
+      l.onmessage = (r) => {
+        var s, i;
+        a.forEach((c) => c.terminate()), ((s = r.data) == null ? void 0 : s.ok) === !1 ? n(new Error(r.data.error)) : t((i = r.data) == null ? void 0 : i.data);
+      }, l.onerror = (r) => {
+        a.forEach((s) => s.terminate()), n(r);
+      };
+      const f = e[0].srcData ?? {};
+      a[0].postMessage(
+        { data: f, index: 0 },
+        g(f)
+      );
+    });
+  }
 }
 export {
-  v as MainWorkerFactory,
-  w as WorkerFactory
+  M as MainWorkerFactory,
+  k as WorkerFactory
 };

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

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