@offmain/workerkit 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Amin Motamedi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# workerkit
+
+A lightweight TypeScript library for running functions in Web Workers with support for partitioning, retries, and concurrency control — all without the boilerplate.
+
+Instead of manually creating worker scripts and wiring up `postMessage` / `onmessage`, you write plain exported functions and hand them to `MainWorkerFactory`. The library serialises them into Blob workers, manages a pool per function, handles retries on failure, and merges results back on the main thread.
+
+---
+
+## Installation
+
+```bash
+npm install workerkit
+# or
+pnpm add workerkit
+```
+
+---
+
+## Quick Start
+
+### 1. Write a worker function
+
+Worker functions live in `*.worker.ts` files and must be plain named exports.
+
+```ts
+// sum.worker.ts
+export function sum({ data }: { data: number[] }): number {
+  return data.reduce((acc, n) => acc + n, 0);
+}
+```
+
+### 2. Register and run it
+
+```ts
+import { MainWorkerFactory } from 'workerkit';
+import { sum } from './sum.worker.ts';
+
+const factory = new MainWorkerFactory(initiator, {
+  workers: [
+    {
+      name: 'sum',
+      role: 'computation',
+      func: sum,
+      maxConcurrency: 4,
+      retries: 2,
+    },
+  ],
+});
+
+const result = await factory.runWorker('sum', { srcData: [1, 2, 3, 4, 5] });
+const { data } = await factory.collectResults(result);
+
+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                                                              |
+| `partition`      | `boolean`  | `false`                         | Split array input across multiple workers automatically                                             |
+
+---
+
+## Partitioning
+
+When `partition: true`, an array passed as `srcData` is automatically split across worker instances and results are merged back.
+
+```ts
+const result = await factory.runWorker('sum', {
+  srcData: largeArray, // split across workers
+});
+
+const { data, succeeded, failed } = await factory.collectResults(result);
+```
+
+You can also provide a custom reducer to control how shard results are merged:
+
+```ts
+const { data } = await factory.collectResults(result, {
+  reducer: (shards) => shards.flat().sort((a, b) => b.score - a.score),
+});
+```
+
+---
+
+## ESLint Plugin
+
+The package ships with two ESLint rules to catch common worker mistakes at lint time.
+
+### Setup
+
+```js
+// eslint.config.js
+import workerPlugin from 'workerkit/eslint-plugin';
+
+export default [...workerPlugin.configs.recommended];
+```
+
+This applies both rules to all `*.worker.ts` and `*.worker.js` files.
+
+### Rules
+
+#### `no-dom-in-worker`
+
+Flags usage of browser main-thread-only APIs that are unavailable inside Web Workers — things like `document`, `window`, `localStorage`, `alert`, DOM constructors, etc.
+
+```ts
+// sum.worker.ts ❌ — will be flagged
+export function sum({ data }: MessageEvent) {
+  document.title = 'working...'; // Error: 'document' is not available inside Web Workers
+  return data.reduce((a: number, b: number) => a + b, 0);
+}
+```
+
+```ts
+// sum.worker.ts ✅
+export function sum({ data }: MessageEvent) {
+  return data.reduce((a: number, b: number) => a + b, 0);
+}
+```
+
+#### `worker-exportable`
+
+Enforces that worker files only export named functions — the shape required by `MainWorkerFactory`. Flags `export default`, class exports, non-function value exports, and re-exports.
+
+```ts
+// bad.worker.ts ❌
+export default function() { ... }  // Error: must not use export default
+export class MyWorker { ... }      // Error: must not export classes
+export const config = { x: 1 };   // Error: must not export non-function values
+```
+
+```ts
+// good.worker.ts ✅
+export function processData({ data }: { data: number[] }) {
+  return data.map((n) => n * 2);
+}
+```
+
+### Using individual rules
+
+You can also import rules individually if you don't want the full recommended config:
+
+```js
+// eslint.config.js
+import noDomInWorker from 'workerkit/eslint-rules/no-dom-in-worker';
+import workerExportable from 'workerkit/eslint-rules/worker-exportable';
+
+export default [
+  {
+    files: ['**/*.worker.ts'],
+    plugins: {
+      workerkit: {
+        rules: {
+          'no-dom-in-worker': noDomInWorker,
+          'worker-exportable': workerExportable,
+        },
+      },
+    },
+    rules: {
+      'workerkit/no-dom-in-worker': 'error',
+      'workerkit/worker-exportable': 'warn',
+    },
+  },
+];
+```
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,31 @@
+"use strict";var g=Object.defineProperty;var m=(t,e,r)=>e in t?g(t,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):t[e]=r;var h=(t,e,r)=>m(t,typeof e!="symbol"?e+"":e,r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=t=>`
+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));
+};
+
+self.addEventListener('message', async (event) => {
+    const begin = performance.now();
+    const output = await ${t}(event.data);
+    self.postMessage(output, extractTransferables(output));
+  })
+`;class k{constructor(e){h(this,"_worker");const r=w(e.toString()),s=new Blob([r],{type:"application/javascript"});this._worker=new Worker(URL.createObjectURL(s))}get getWorker(){return this._worker}}function p(t,e=new Set){return t===null||typeof t!="object"?[]:e.has(t)?[]:(e.add(t),t instanceof ArrayBuffer||t instanceof MessagePort||typeof ImageBitmap<"u"&&t instanceof ImageBitmap||typeof OffscreenCanvas<"u"&&t instanceof OffscreenCanvas?[t]:ArrayBuffer.isView(t)?[t.buffer]:Array.isArray(t)?t.flatMap(r=>p(r,e)):Object.values(t).flatMap(r=>p(r,e)))}class W{constructor(e,r){h(this,"_workers");h(this,"_threads");this._workers=r.workers,this._threads=navigator.hardwareConcurrency}initWorker(e){return new k(e)}partitionArray(e,r){if(!e.length)return[];if(r<=0)throw new Error("numChunks must be positive");const s=Math.min(r,e.length),a=Math.floor(e.length/s),c=e.length%s,o=[];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}return o}findWorkerByName(e){return this._workers.find(r=>r.name===e)}async runWorker(e,{srcData:r,...s}){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(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;return this.runWorkerWithRetry({workerFunc:e.func,workerName:r,index:i,data:{data:u,...f}},e.retries)})}async runWorkerWithRetry(e,r=2){try{return await this.initiateWorker(e)}catch(s){if(r>0)return console.error(`Worker ${e.index} failed, retrying (${r} left):`,s),this.runWorkerWithRetry(e,r-1);throw console.error("Worker failed after all retries:",s),s}}initiateWorker({workerFunc:e,workerName:r,index:s,data: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})},n.onmessage=u=>{c({index:s,workerConfigs:{workerFunc:e,workerName:r,index:s,data:a},successResult:u}),n.terminate()};const i={index:s,...Array.isArray(a)?{data:a}:a};n.postMessage(i,p(i))})}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()";return{data:await new Promise((n,i)=>{const u=`
+        const reducer = ${o};
+        self.addEventListener('message', (event) => {
+          try {
+            const result = reducer(event.data);
+            self.postMessage({ ok: true, data: result });
+          } catch (err) {
+            self.postMessage({ ok: false, error: String(err) });
+          }
+        });
+      `,y=new Blob([u],{type:"application/javascript"}),l=new Worker(URL.createObjectURL(y));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)}),succeeded:s.length,failed:a.length,errors:a}}}exports.MainWorkerFactory=W;exports.WorkerFactory=k;

package/dist/index.js

@@ -0,0 +1,186 @@
+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) => `
+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));
+};
+
+self.addEventListener('message', async (event) => {
+    const begin = performance.now();
+    const output = await ${t}(event.data);
+    self.postMessage(output, extractTransferables(output));
+  })
+`;
+class w {
+  constructor(e) {
+    h(this, "_worker");
+    const r = m(e.toString()), s = new Blob([r], {
+      type: "application/javascript"
+    });
+    this._worker = new Worker(URL.createObjectURL(s));
+  }
+  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 v {
+  constructor(e, r) {
+    h(this, "_workers");
+    h(this, "_threads");
+    this._workers = r.workers, this._threads = navigator.hardwareConcurrency;
+  }
+  initWorker(e) {
+    return new w(e);
+  }
+  /**
+   * Partitions an array into up to numChunks evenly-sized chunks.
+   */
+  partitionArray(e, r) {
+    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 = [];
+    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;
+    }
+    return o;
+  }
+  findWorkerByName(e) {
+    return this._workers.find((r) => r.name === e);
+  }
+  async runWorker(e, { srcData: r, ...s }) {
+    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(
+      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;
+      return this.runWorkerWithRetry(
+        {
+          workerFunc: e.func,
+          workerName: r,
+          index: i,
+          data: { data: u, ...f }
+        },
+        e.retries
+      );
+    });
+  }
+  async runWorkerWithRetry(e, r = 2) {
+    try {
+      return await this.initiateWorker(e);
+    } catch (s) {
+      if (r > 0)
+        return console.error(
+          `Worker ${e.index} failed, retrying (${r} left):`,
+          s
+        ), this.runWorkerWithRetry(e, r - 1);
+      throw console.error("Worker failed after all retries:", s), s;
+    }
+  }
+  initiateWorker({
+    workerFunc: e,
+    workerName: r,
+    index: s,
+    data: 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
+        });
+      }, n.onmessage = (u) => {
+        c({
+          index: s,
+          workerConfigs: { workerFunc: e, workerName: r, index: s, data: a },
+          successResult: u
+        }), n.terminate();
+      };
+      const i = {
+        index: s,
+        ...Array.isArray(a) ? { data: a } : a
+      };
+      n.postMessage(i, p(i));
+    });
+  }
+  /**
+   * Collects and merges the settled results from `runWorker` — off the main thread.
+   *
+   * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
+   * @param options  Optional `reducer` function (must be self-contained)
+   *
+   * @example
+   * // default: flat array of all shard data
+   * const { data, succeeded, failed } = await foreman.collectResults(res);
+   *
+   * @example
+   * // custom reducer: sum numbers across shards
+   * const { data } = await foreman.collectResults<number[], number>(res, {
+   *   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()";
+    return {
+      data: await new Promise((n, i) => {
+        const u = `
+        const reducer = ${o};
+        self.addEventListener('message', (event) => {
+          try {
+            const result = reducer(event.data);
+            self.postMessage({ ok: true, data: result });
+          } catch (err) {
+            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);
+      }),
+      succeeded: s.length,
+      failed: a.length,
+      errors: a
+    };
+  }
+}
+export {
+  v as MainWorkerFactory,
+  w as WorkerFactory
+};

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

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

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

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

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

@@ -0,0 +1,42 @@
+import { CollectOptions, CollectedResult, MainWorkerFactoryOptions, WorkerFunction, WorkerResult } from './types.ts';
+/**
+ * Recursively collects all Transferable objects from a value.
+ * Transferables (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[];
+declare class MainWorkerFactory {
+    private readonly _workers;
+    private readonly _threads;
+    constructor(_initiator: WorkerFunction, options: MainWorkerFactoryOptions);
+    private initWorker;
+    /**
+     * Partitions an array into up to numChunks evenly-sized chunks.
+     */
+    partitionArray<T>(array: T[], numChunks: number): T[][];
+    private findWorkerByName;
+    runWorker(workerName: string, { srcData, ...otherParams }: {
+        srcData: unknown;
+    } & Record<string, unknown>): Promise<PromiseSettledResult<WorkerResult>[]>;
+    private createWorkerPromises;
+    private runWorkerWithRetry;
+    private initiateWorker;
+    /**
+     * Collects and merges the settled results from `runWorker` — off the main thread.
+     *
+     * @param settled  The `PromiseSettledResult[]` returned by `runWorker`
+     * @param options  Optional `reducer` function (must be self-contained)
+     *
+     * @example
+     * // default: flat array of all shard data
+     * const { data, succeeded, failed } = await foreman.collectResults(res);
+     *
+     * @example
+     * // custom reducer: sum numbers across shards
+     * const { data } = await foreman.collectResults<number[], number>(res, {
+     *   reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0),
+     * });
+     */
+    collectResults<T = unknown, R = T[]>(settled: PromiseSettledResult<WorkerResult>[], options?: CollectOptions<T, R>): Promise<CollectedResult<R>>;
+}
+export default MainWorkerFactory;

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

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

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

@@ -0,0 +1,56 @@
+import { WorkerFactory } from '../worker-factory';
+export type WorkerName = string;
+export type WorkerRole = string;
+export type WorkerFunction = (...params: unknown[]) => void;
+export interface WorkerConfig {
+    name: WorkerName;
+    role: WorkerRole;
+    func: WorkerFunction;
+    maxConcurrency?: number;
+    retries?: number;
+    partition?: boolean;
+}
+export interface MainWorkerFactoryOptions {
+    workers: WorkerConfig[];
+}
+export interface MainWorkerFactoryWorker extends WorkerConfig {
+    worker: WorkerFactory;
+}
+export interface WorkerInstanceConfig {
+    workerName: WorkerName;
+    workerFunc: WorkerFunction;
+    index: number;
+    data: unknown;
+}
+export type WorkerSuccessResult = MessageEvent;
+export type WorkerFailedResult = MessageEvent;
+export interface WorkerResult {
+    index: number;
+    workerConfigs: WorkerInstanceConfig;
+    successResult?: WorkerSuccessResult;
+    failedResult?: WorkerFailedResult;
+}
+/** Options for collectResults */
+export interface CollectOptions<T, R = T[]> {
+    /**
+     * Custom reducer applied to the array of fulfilled shard values.
+     * Runs inside a worker — must be self-contained (no external references).
+     * Defaults to a flat array of all shard data values.
+     *
+     * @example
+     * // sum all numbers across shards
+     * reducer: (shards) => shards.flat().reduce((a, b) => a + b, 0)
+     */
+    reducer?: (shards: T[]) => R;
+}
+/** Result returned by collectResults */
+export interface CollectedResult<R> {
+    /** The merged output produced by the reducer */
+    data: R;
+    /** Number of shards that succeeded */
+    succeeded: number;
+    /** Number of shards that failed (after all retries) */
+    failed: number;
+    /** Raw rejected results, if any */
+    errors: PromiseRejectedResult[];
+}

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

@@ -0,0 +1 @@
+export { default as WorkerFactory } from './worker-factory';

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

@@ -0,0 +1,7 @@
+import { WorkerFunction } from '../main-worker-factory/types';
+declare class WorkerFactory {
+    readonly _worker: Worker;
+    constructor(workerFunction: WorkerFunction);
+    get getWorker(): Worker;
+}
+export default WorkerFactory;

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

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

package/dist/types/workers/initiator.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => void;
+export default _default;

package/dist/types/workers/initiator.test.d.ts

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

package/eslint-rules/index.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+const noDomInWorker = require('./no-dom-in-worker.cjs');
+const workerExportable = require('./worker-exportable.cjs');
+
+/** All rules bundled as a flat-config-compatible ESLint plugin */
+module.exports = {
+  rules: {
+    'no-dom-in-worker': noDomInWorker,
+    'worker-exportable': workerExportable,
+  },
+
+  /**
+   * Ready-made flat config that applies both rules to *.worker.ts files.
+   *
+   * @example
+   * // eslint.config.js
+   * import workerPlugin from 'workerkit/eslint-plugin';
+   * export default [ ...workerPlugin.configs.recommended ];
+   */
+  configs: {
+    recommended: [
+      {
+        files: ['**/*.worker.ts', '**/*.worker.js'],
+        plugins: {
+          workerkit: module.exports,
+        },
+        rules: {
+          'workerkit/no-dom-in-worker': 'error',
+          'workerkit/worker-exportable': 'error',
+        },
+      },
+    ],
+  },
+};

package/eslint-rules/no-dom-in-worker.cjs

@@ -0,0 +1,226 @@
+/**
+ * Custom ESLint rule: no-dom-in-worker
+ *
+ * Flags usage of browser main-thread-only APIs that are NOT available
+ * inside Web Workers (DedicatedWorker, SharedWorker, ServiceWorker).
+ *
+ * Safe in workers: self, postMessage, fetch, setTimeout, setInterval,
+ *   performance, console, crypto, indexedDB, caches, WebSockets, etc.
+ *
+ * NOT safe in workers: document, window, navigator (partially),
+ *   localStorage, sessionStorage, alert/confirm/prompt, DOM constructors,
+ *   DOM element methods, history, location (partially), screen, etc.
+ */
+
+/** Global identifiers that are unavailable in Web Workers */
+const FORBIDDEN_GLOBALS = new Set([
+  'document',
+  'window',
+  'alert',
+  'confirm',
+  'prompt',
+  'localStorage',
+  'sessionStorage',
+  'history',
+  'screen',
+  'frames',
+  'parent',
+  'top',
+  'opener',
+  'frameElement',
+  'getComputedStyle',
+  'matchMedia',
+  'requestAnimationFrame',
+  'cancelAnimationFrame',
+  'requestIdleCallback',
+  'cancelIdleCallback',
+  'scrollTo',
+  'scrollBy',
+  'scroll',
+  'resizeTo',
+  'resizeBy',
+  'moveTo',
+  'moveBy',
+  'focus',
+  'blur',
+  'print',
+  'stop',
+  'open',
+  'close',
+]);
+
+/**
+ * DOM constructor names unavailable in workers.
+ * e.g. new HTMLElement(), new Document(), new Event() is fine but
+ * new HTMLDivElement() is not.
+ */
+const FORBIDDEN_CONSTRUCTORS = new Set([
+  'HTMLElement',
+  'HTMLDivElement',
+  'HTMLSpanElement',
+  'HTMLInputElement',
+  'HTMLButtonElement',
+  'HTMLFormElement',
+  'HTMLAnchorElement',
+  'HTMLImageElement',
+  'HTMLCanvasElement', // regular Canvas; OffscreenCanvas IS allowed
+  'HTMLVideoElement',
+  'HTMLAudioElement',
+  'HTMLTableElement',
+  'HTMLSelectElement',
+  'HTMLTextAreaElement',
+  'SVGElement',
+  'Document',
+  'Window',
+  'Navigator',
+  'Element',
+  'Node',
+  'NodeList',
+  'HTMLCollection',
+  'MutationObserver',
+  'IntersectionObserver',
+  'ResizeObserver',
+  'PerformanceObserver', // available in workers, but flag to be safe
+  'XPathResult',
+  'Range',
+  'Selection',
+  'TreeWalker',
+  'NodeIterator',
+  'DOMParser',
+  'XMLSerializer',
+  'CSSStyleDeclaration',
+  'CSSRule',
+  'StyleSheet',
+  'MediaQueryList',
+  'Screen',
+  'History',
+  'Location',
+  'Storage',
+  'Clipboard',
+  'Notification', // constructor exists but requires window context
+]);
+
+/**
+ * Member expressions whose object is a known forbidden global.
+ * e.g. document.querySelector, window.location, navigator.geolocation
+ */
+const FORBIDDEN_MEMBER_OBJECTS = new Set([
+  'document',
+  'window',
+  'localStorage',
+  'sessionStorage',
+  'history',
+  'screen',
+  'navigator', // navigator itself is partially available; flag member access
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow browser main-thread-only APIs inside Web Worker files',
+      category: 'Web Workers',
+      recommended: true,
+      url: 'https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers',
+    },
+    schema: [],
+    messages: {
+      forbiddenGlobal:
+        "'{{name}}' is not available inside Web Workers. " +
+        'Web Workers run in a separate thread without access to the main-thread DOM. ' +
+        "Use worker-safe alternatives (e.g. 'self', 'postMessage', 'fetch', 'indexedDB') " +
+        'or move this logic to the main thread and communicate via messages. ' +
+        'See: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers',
+      forbiddenConstructor:
+        "'new {{name}}(...)' is not available inside Web Workers. " +
+        'DOM constructors require a browsing context that workers do not have. ' +
+        "If you need to manipulate DOM elements, send a message to the main thread via 'postMessage' and handle it there. " +
+        'See: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers',
+      forbiddenMember:
+        "'{{object}}.{{property}}' is not available inside Web Workers. " +
+        "'{{object}}' is a main-thread-only global that does not exist in worker scope. " +
+        "Pass required data into the worker via 'postMessage' instead of accessing it directly. " +
+        'See: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers',
+    },
+  },
+
+  create(context) {
+    return {
+      // Flag standalone identifiers that are forbidden globals
+      // e.g. `alert()`, `localStorage` used directly (not as `document.X`)
+      Identifier(node) {
+        if (!FORBIDDEN_GLOBALS.has(node.name)) return;
+
+        const parent = node.parent;
+
+        // Skip property keys in member expressions / object literals / class methods
+        if (
+          parent.type === 'MemberExpression' &&
+          parent.property === node &&
+          !parent.computed
+        )
+          return;
+        if (parent.type === 'Property' && parent.key === node) return;
+        if (parent.type === 'MethodDefinition' && parent.key === node) return;
+
+        // Skip when this identifier is the *object* of a MemberExpression that
+        // is already in FORBIDDEN_MEMBER_OBJECTS — the MemberExpression handler
+        // will report a richer message for that case (e.g. document.querySelector).
+        if (
+          parent.type === 'MemberExpression' &&
+          parent.object === node &&
+          FORBIDDEN_MEMBER_OBJECTS.has(node.name)
+        ) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: 'forbiddenGlobal',
+          data: { name: node.name },
+        });
+      },
+
+      // Flag `new ForbiddenConstructor()`
+      NewExpression(node) {
+        const callee = node.callee;
+        if (
+          callee.type === 'Identifier' &&
+          FORBIDDEN_CONSTRUCTORS.has(callee.name)
+        ) {
+          context.report({
+            node,
+            messageId: 'forbiddenConstructor',
+            data: { name: callee.name },
+          });
+        }
+      },
+
+      // Flag member access on forbidden objects: document.X, window.X, etc.
+      MemberExpression(node) {
+        if (
+          node.object.type === 'Identifier' &&
+          FORBIDDEN_MEMBER_OBJECTS.has(node.object.name)
+        ) {
+          const property =
+            node.property.type === 'Identifier'
+              ? node.property.name
+              : node.computed
+                ? '<computed>'
+                : '?';
+
+          context.report({
+            node,
+            messageId: 'forbiddenMember',
+            data: {
+              object: node.object.name,
+              property,
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-rules/worker-exportable.cjs

@@ -0,0 +1,139 @@
+/**
+ * Custom ESLint rule: worker-exportable
+ *
+ * Enforces that Web Worker files (*.worker.ts) only export named, callable
+ * functions — the shape required by MainWorkerFactory.
+ *
+ * WHY: WorkerFactory serialises the function via `.toString()` and injects it
+ * into a Blob worker. For this to work the export must be:
+ *   ✓  export function myWorker(...) { ... }
+ *   ✓  export const myWorker = function(...) { ... }
+ *   ✓  export const myWorker = (...) => { ... }
+ *
+ * The following are flagged because they cannot be passed directly to
+ * MainWorkerFactory as a worker function:
+ *   ✗  export default ...          (anonymous / unnamed — no stable identifier)
+ *   ✗  export class Foo { ... }    (not a plain function)
+ *   ✗  export const x = 42        (not callable)
+ *   ✗  export { foo } from '...'  (re-exports hide the original source)
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Enforce that worker files only export named functions importable by MainWorkerFactory',
+      category: 'Web Workers',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      noDefaultExport:
+        'Worker files must not use `export default`. ' +
+        'Export a named function instead so it can be imported and passed to MainWorkerFactory. ' +
+        'Example: export function myWorker({ data }) { ... }',
+
+      noClassExport:
+        "Worker files must not export classes ('{{name}}'). " +
+        'MainWorkerFactory expects a plain callable function. ' +
+        'Example: export function myWorker({ data }) { ... }',
+
+      noNonFunctionExport:
+        "Worker files must not export non-function values ('{{name}}'). " +
+        'Only exported functions can be passed to MainWorkerFactory. ' +
+        'Example: export function myWorker({ data }) { ... }',
+
+      noReExport:
+        'Worker files must not use re-exports (`export { ... } from ...`). ' +
+        'Define and export the worker function directly in this file so ' +
+        'WorkerFactory can serialise it via .toString().',
+
+      mustExportFunction:
+        'Worker files must export at least one named function. ' +
+        'MainWorkerFactory requires a named exported function to run in the worker thread. ' +
+        'Example: export function myWorker({ data }) { ... }',
+    },
+  },
+
+  create(context) {
+    let hasNamedFunctionExport = false;
+
+    /** Returns true when an AST node represents a function (any flavour). */
+    function isFunction(node) {
+      return (
+        node.type === 'FunctionDeclaration' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'ArrowFunctionExpression'
+      );
+    }
+
+    return {
+      // export default <anything>
+      ExportDefaultDeclaration(node) {
+        context.report({ node, messageId: 'noDefaultExport' });
+      },
+
+      // export function foo() {}  /  export class Foo {}  /  export const x = ...
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+
+        // export { foo } from './somewhere'  — re-export from another module
+        if (!decl) {
+          if (node.source) {
+            context.report({ node, messageId: 'noReExport' });
+          }
+          // plain `export { localVar }` — allowed (re-surfaces a local name)
+          return;
+        }
+
+        if (decl.type === 'ClassDeclaration') {
+          const name = decl.id ? decl.id.name : '<anonymous>';
+          context.report({ node, messageId: 'noClassExport', data: { name } });
+          return;
+        }
+
+        if (decl.type === 'FunctionDeclaration') {
+          // export function foo() {}
+          hasNamedFunctionExport = true;
+          return;
+        }
+
+        if (decl.type === 'VariableDeclaration') {
+          for (const declarator of decl.declarations) {
+            const name =
+              declarator.id && declarator.id.type === 'Identifier'
+                ? declarator.id.name
+                : '<unknown>';
+
+            if (declarator.init && isFunction(declarator.init)) {
+              // export const foo = () => {}  or  export const foo = function() {}
+              hasNamedFunctionExport = true;
+            } else if (
+              decl.kind !== 'type' &&
+              declarator.init !== null &&
+              declarator.init !== undefined &&
+              !isFunction(declarator.init)
+            ) {
+              context.report({
+                node: declarator,
+                messageId: 'noNonFunctionExport',
+                data: { name },
+              });
+            }
+          }
+        }
+
+        // TSTypeAliasDeclaration / TSInterfaceDeclaration — always fine, skip.
+      },
+
+      // After visiting the whole file, ensure at least one named function was exported.
+      'Program:exit'(node) {
+        if (!hasNamedFunctionExport) {
+          context.report({ node, messageId: 'mustExportFunction' });
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@offmain/workerkit",
+  "version": "0.3.0",
+  "description": "A lightweight manager for running functions in Web Workers with partitioning, retries, and concurrency control",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/types/tools/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/tools/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./eslint-plugin": "./eslint-rules/index.cjs",
+    "./eslint-rules/no-dom-in-worker": "./eslint-rules/no-dom-in-worker.cjs",
+    "./eslint-rules/worker-exportable": "./eslint-rules/worker-exportable.cjs"
+  },
+  "files": [
+    "dist",
+    "eslint-rules"
+  ],
+  "keywords": [
+    "web-worker",
+    "worker",
+    "concurrency",
+    "parallel",
+    "thread",
+    "browser"
+  ],
+  "license": "MIT",
+  "lint-staged": {
+    "**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "**/*.{js,cjs,json,md}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "eslint": "^9.16.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-local-rules": "^3.0.2",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "jsdom": "^24.0.0",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2",
+    "vite": "^6.3.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:lib": "vite build --config vite.lib.config.ts",
+    "preview": "vite preview",
+    "lint": "eslint --fix .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release:patch": "pnpm version patch && pnpm run release:publish",
+    "release:minor": "pnpm version minor && pnpm run release:publish",
+    "release:major": "pnpm version major && pnpm run release:publish",
+    "release:publish": "pnpm run build:lib && pnpm publish"
+  }
+}