@hybrid-compute/worker 0.0.1

package/.release-it.json

@@ -0,0 +1,70 @@
+{
+  "git": false,
+  "github": {
+    "release": true,
+    "tokenRef": "GH_TOKEN"
+  },
+  "npm": {
+    "publish": true,
+    "skipChecks": true
+  },
+  "hooks": {
+    "after:release": "echo Successfully released ${name} v${version} to ${repo.repository}."
+  },
+  "plugins": {
+    "@release-it/bumper": {
+      "out": {
+        "file": "package.json",
+        "path": ["dependencies.@hybrid-compute/core"]
+      }
+    },
+    "@release-it/conventional-changelog": {
+      "header": "# Changelog",
+      "preset": {
+        "name": "conventionalcommits",
+        "types": [
+          {
+            "type": "chore",
+            "section": "Tasks"
+          },
+          {
+            "type": "docs",
+            "section": "Documentation"
+          },
+          {
+            "type": "feat",
+            "section": "Feature"
+          },
+          {
+            "type": "fix",
+            "section": "Bug"
+          },
+          {
+            "type": "perf",
+            "section": "Performance change"
+          },
+          {
+            "type": "refactor",
+            "section": "Refactoring"
+          },
+          {
+            "type": "release",
+            "section": "Create a release commit",
+            "hidden": true
+          },
+          {
+            "type": "style",
+            "section": "Markup, white-space, formatting, missing semi-colons...",
+            "hidden": true
+          },
+          {
+            "type": "test",
+            "section": "Adding missing tests",
+            "hidden": true
+          }
+        ]
+      },
+      "infile": "CHANGELOG.md"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.0.1 (2025-06-01)
+
+### Tasks
+
+* 🤖 Add deps ([0a08767](https://github.com/phun-ky/hybrid-compute/commit/0a08767abed76c91ea902363890bb8f99e44a1da))
+* 🤖 Adjustments before release ([ee23ac6](https://github.com/phun-ky/hybrid-compute/commit/ee23ac627f7d04c3c2b4fdf9b2dc1f826fa21593))
+* 🤖 More adjustments ([f9dfee8](https://github.com/phun-ky/hybrid-compute/commit/f9dfee8fb9eb2e1cb104fca9ea24903a69d16f26))
+* 🤖 Preparing for first release, with setup ([13f8f03](https://github.com/phun-ky/hybrid-compute/commit/13f8f03def7941c79b3695d0ba2409c6f9ba0896))
+* 🤖 Remove lerna ([f4ba79e](https://github.com/phun-ky/hybrid-compute/commit/f4ba79ed10bb66271859cdfb905b8e4a8979784e))
+* 🤖 Update references, keywords and description + badges ([bc0b1ac](https://github.com/phun-ky/hybrid-compute/commit/bc0b1ac537bc9610ade89fc001132776d096fd55))
+* 🤖 Update workflows ([7f9d6b5](https://github.com/phun-ky/hybrid-compute/commit/7f9d6b55f7180bb0179fc9159d7453395e2ca1af))
+* preparing for release ([d07d107](https://github.com/phun-ky/hybrid-compute/commit/d07d10777a200a755965cef115106430805fe70b))
+
+### Documentation
+
+* ✏️ Add documentation ([81e6fa1](https://github.com/phun-ky/hybrid-compute/commit/81e6fa189a3fb974e89c03a846d030118fdedbe4))
+* ✏️ Regenerate documentation ([487d54f](https://github.com/phun-ky/hybrid-compute/commit/487d54ffb40abc03315e04fd2e5c1434fc3e9b27))
+* ✏️ Update documentation ([1039082](https://github.com/phun-ky/hybrid-compute/commit/10390822d4a087a7a26b7a25ce25cb9099dbce94))

package/README.md

@@ -0,0 +1,83 @@
+# @hybrid-compute/worker
+
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](http://makeapullrequest.com)
+[![SemVer 2.0](https://img.shields.io/badge/SemVer-2.0-green.svg)](http://semver.org/spec/v2.0.0.html)
+![npm version](https://img.shields.io/npm/v/@hybrid-compute/core)
+![issues](https://img.shields.io/github/issues/phun-ky/hybrid-compute)
+![license](https://img.shields.io/npm/l/@hybrid-compute/core)
+![size](https://img.shields.io/bundlephobia/min/@hybrid-compute/core)
+![npm](https://img.shields.io/npm/dm/%40hybrid-compute/core)
+![GitHub Repo stars](https://img.shields.io/github/stars/phun-ky/hybrid-compute)
+[![codecov](https://codecov.io/gh/phun-ky/hybrid-compute/graph/badge.svg?token=VA91DL7ZLZ)](https://codecov.io/gh/phun-ky/hybrid-compute)
+[![build](https://github.com/phun-ky/hybrid-compute/actions/workflows/check.yml/badge.svg)](https://github.com/phun-ky/hybrid-compute/actions/workflows/check.yml)
+
+Part of the [`@hybrid-compute`](https://github.com/phun-ky/hybrid-compute)
+monorepo.
+
+> See the [main README](https://github.com/phun-ky/hybrid-compute#readme) for
+> full project overview, usage examples, architecture, and contribution
+> guidelines.
+
+## API Docs
+
+[ThreadedCompute API Documentation](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/worker/src/classes/ThreadedCompute.md)
+
+## 📦 Package Info
+
+This package provides:
+
+- A compute backend that runs tasks in a dedicated Web Worker
+- Asynchronous task messaging via `postMessage`
+- Useful for offloading CPU-intensive work from the main thread
+
+## Usage
+
+```bash
+npm install @hybrid-compute/worker
+```
+
+```ts
+import { createThreadedCompute } from '@hybrid-compute/worker';
+
+const threaded = createThreadedCompute(
+  new URL('./worker.js', import.meta.url),
+  ['add']
+);
+```
+
+---
+
+## Contributing
+
+Want to contribute? Please read the
+[CONTRIBUTING.md](https://github.com/phun-ky/hybrid-compute/blob/main/CONTRIBUTING.md)
+and
+[CODE_OF_CONDUCT.md](https://github.com/phun-ky/hybrid-compute/blob/main/CODE_OF_CONDUCT.md)
+
+## License
+
+This project is licensed under the MIT License - see the
+[LICENSE](https://github.com/phun-ky/hybrid-compute/blob/main/LICENSE) file for
+details.
+
+## Sponsor me
+
+I'm an Open Source evangelist, creating stuff that does not exist yet to help
+get rid of secondary activities and to enhance systems already in place, be it
+documentation, tools or web sites.
+
+The sponsorship is an unique opportunity to alleviate more hours for me to
+maintain my projects, create new ones and contribute to the large community
+we're all part of :)
+
+[Support me on GitHub Sponsors](https://github.com/sponsors/phun-ky).
+
+p.s. **Ukraine is still under brutal Russian invasion. A lot of Ukrainian people
+are hurt, without shelter and need help**. You can help in various ways, for
+instance, directly helping refugees, spreading awareness, putting pressure on
+your local government or companies. You can also support Ukraine by donating
+e.g. to [Red Cross](https://www.icrc.org/en/donate/ukraine),
+[Ukraine humanitarian organisation](https://savelife.in.ua/en/donate-en/#donate-army-card-weekly)
+or
+[donate Ambulances for Ukraine](https://www.gofundme.com/f/help-to-save-the-lives-of-civilians-in-a-war-zone).

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import SharedConfig from '../../eslint.config.mjs';
+
+export default SharedConfig;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hybrid-compute/worker",
+  "version": "0.0.1",
+  "description": "Threaded compute backend for executing tasks in Web Workers.",
+  "keywords": [
+    "web-worker",
+    "worker",
+    "thread",
+    "multithreaded",
+    "compute",
+    "offload",
+    "async",
+    "frontend",
+    "task"
+  ],
+  "homepage": "https://phun-ky.net/projects/hybrid-compute",
+  "bugs": {
+    "url": "https://github.com/phun-ky/hybrid-compute/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phun-ky/hybrid-compute.git"
+  },
+  "funding": "https://github.com/phun-ky/hybrid-compute?sponsor=1",
+  "license": "MIT",
+  "author": "Alexander Vassbotn Røyne-Helgesen <alexander@phun-ky.net>",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "release": "release-it",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "tsx --test **/__tests__/**/*.spec.ts",
+    "pretest:ci": "rm -rf coverage && mkdir -p coverage",
+    "test:ci": "glob -c \"node --import tsx --test --no-warnings --experimental-test-coverage --test-reporter=cobertura --test-reporter-destination=coverage/cobertura-coverage.xml --test-reporter=spec --test-reporter-destination=stdout\" \"**/__tests__/**/*.spec.ts\""
+  },
+  "dependencies": {
+    "@hybrid-compute/core": "0.0.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.27.0",
+    "eslint-config-phun-ky": "^1.0.3",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/worker.spec.ts

@@ -0,0 +1,139 @@
+import test, { describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createThreadedCompute,
+  ThreadedCompute,
+  WorkerResultMessageInterface,
+  WorkerTaskMessageInterface
+} from '..';
+
+describe('ThreadedCompute', () => {
+  test('canRun returns true for registered task', () => {
+    const OriginalWorker = globalThis.Worker;
+
+    class MockWorker {
+      public onmessage: ((event: any) => void) | null = null;
+      constructor(
+        public path: string,
+        public options: object
+      ) {}
+      postMessage() {}
+    }
+
+    // @ts-expect-error allow override
+    globalThis.Worker = MockWorker;
+
+    try {
+      const threaded = new ThreadedCompute('mock-worker.js', ['foo', 'bar']);
+      assert.equal(threaded.canRun('foo'), true);
+      assert.equal(threaded.canRun('baz'), false);
+    } finally {
+      globalThis.Worker = OriginalWorker;
+    }
+  });
+
+  test('runTask resolves with worker result', async () => {
+    const OriginalWorker = globalThis.Worker;
+
+    class MockWorker {
+      public onmessage:
+        | ((event: MessageEvent<WorkerResultMessageInterface>) => void)
+        | null = null;
+      public received: WorkerTaskMessageInterface | null = null;
+
+      constructor(
+        public path: string,
+        public options: object
+      ) {}
+
+      postMessage(msg: WorkerTaskMessageInterface) {
+        this.received = msg;
+
+        setTimeout(() => {
+          this.onmessage?.({
+            data: {
+              id: msg.id,
+              result: `result-${msg.input}`
+            }
+          } as MessageEvent<WorkerResultMessageInterface>);
+        }, 10);
+      }
+    }
+
+    // @ts-expect-error override
+    globalThis.Worker = MockWorker;
+
+    try {
+      const compute = new ThreadedCompute('mock-worker.js', ['echo']);
+      const result = await compute.runTask<string, string>('echo', 'ping');
+      assert.equal(result, 'result-ping');
+    } finally {
+      globalThis.Worker = OriginalWorker;
+    }
+  });
+
+  test('runTask rejects with worker error', async () => {
+    const OriginalWorker = globalThis.Worker;
+
+    class MockWorker {
+      public onmessage:
+        | ((event: MessageEvent<WorkerResultMessageInterface>) => void)
+        | null = null;
+
+      constructor(
+        public path: string,
+        public options: object
+      ) {}
+
+      postMessage(msg: WorkerTaskMessageInterface) {
+        setTimeout(() => {
+          this.onmessage?.({
+            data: {
+              id: msg.id,
+              error: 'Something went wrong'
+            }
+          } as MessageEvent<WorkerResultMessageInterface>);
+        }, 10);
+      }
+    }
+
+    // @ts-expect-error override
+    globalThis.Worker = MockWorker;
+
+    try {
+      const compute = new ThreadedCompute('mock-worker.js', ['fail']);
+      await assert.rejects(
+        () => compute.runTask('fail', 42),
+        /Something went wrong/
+      );
+    } finally {
+      globalThis.Worker = OriginalWorker;
+    }
+  });
+});
+describe('createThreadedCompute', () => {
+  test('returns instance of ThreadedCompute', () => {
+    const OriginalWorker = globalThis.Worker;
+
+    class MockWorker {
+      public onmessage:
+        | ((event: MessageEvent<WorkerResultMessageInterface>) => void)
+        | null = null;
+      constructor(
+        public path: string,
+        public options: object
+      ) {}
+      postMessage() {}
+    }
+
+    // @ts-expect-error override
+    globalThis.Worker = MockWorker;
+
+    try {
+      const instance = createThreadedCompute('mock-worker.js', ['foo']);
+      assert.ok(instance instanceof ThreadedCompute);
+    } finally {
+      globalThis.Worker = OriginalWorker;
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,118 @@
+import { ComputeBackendInterface } from '@hybrid-compute/core';
+
+import {
+  WorkerResultMessageInterface,
+  WorkerTaskMessageInterface
+} from './types.js';
+
+export * from './types.js';
+
+/**
+ * `ThreadedCompute` is a compute backend that runs tasks in a dedicated Web Worker.
+ *
+ * It manages communication with the worker via `postMessage`, assigns unique task
+ * request IDs, and resolves results asynchronously. Tasks are registered by name
+ * during construction and mapped internally for availability checks.
+ *
+ * @example
+ * ```ts
+ * const threaded = new ThreadedCompute(new URL('./worker.js', import.meta.url), ['add']);
+ *
+ * const result = await threaded.runTask<number, number>('add', 5);
+ * console.log(result); // Output from worker
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Worker
+ */
+export class ThreadedCompute implements ComputeBackendInterface {
+  private worker: Worker;
+  private taskMap = new Set<string>();
+
+  // Map of task response IDs to success callbacks
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private callbacks = new Map<number, (value: any) => void>();
+
+  // Map of task response IDs to error callbacks
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private errors = new Map<number, (err: any) => void>();
+
+  private nextId = 1;
+
+  /**
+   * Constructs a new `ThreadedCompute` backend with a specified worker and list of available task names.
+   *
+   * @param workerPath - Path to the worker script (typically a URL via `import.meta.url`).
+   * @param taskNames - A list of task identifiers this worker is capable of executing.
+   */
+  constructor(workerPath: string, taskNames: string[]) {
+    this.worker = new Worker(workerPath, { type: 'module' });
+    this.taskMap = new Set(taskNames);
+
+    this.worker.onmessage = (e: MessageEvent<WorkerResultMessageInterface>) => {
+      const { id, result, error } = e.data;
+
+      if (error) this.errors.get(id)?.(error);
+      else this.callbacks.get(id)?.(result);
+
+      this.callbacks.delete(id);
+      this.errors.delete(id);
+    };
+  }
+
+  /**
+   * Checks whether the current worker is registered to handle a given task.
+   *
+   * @param taskName - The name of the task to check.
+   * @returns `true` if the task is supported, otherwise `false`.
+   */
+  canRun(taskName: string): boolean {
+    return this.taskMap.has(taskName);
+  }
+
+  /**
+   * Runs a task inside the Web Worker.
+   *
+   * The task is assigned a unique ID and sent via `postMessage`. The result or error
+   * is resolved asynchronously when the worker responds.
+   *
+   * @typeParam Input - The input type for the task.
+   * @typeParam Output - The output type returned by the task.
+   *
+   * @param taskName - The name of the task to execute.
+   * @param input - The input payload for the task.
+   * @returns A Promise resolving to the task output.
+   *
+   * @example
+   * ```ts
+   * const result = await threaded.runTask('square', 9); // 81
+   * ```
+   */
+  runTask<Input, Output>(taskName: string, input: Input): Promise<Output> {
+    return new Promise<Output>((resolve, reject) => {
+      const id = this.nextId++;
+
+      this.callbacks.set(id, resolve);
+      this.errors.set(id, reject);
+
+      const message: WorkerTaskMessageInterface = { task: taskName, input, id };
+
+      this.worker.postMessage(message);
+    });
+  }
+}
+
+/**
+ * Factory function to create a new `ThreadedCompute` backend.
+ *
+ * @param workerPath - The module worker file path (e.g. `new URL('./worker.js', import.meta.url)`).
+ * @param tasks - A list of supported task names this worker can execute.
+ * @returns A new `ThreadedCompute` instance.
+ *
+ * @example
+ * ```ts
+ * const backend = createThreadedCompute(new URL('./worker.js', import.meta.url), ['resizeImage']);
+ * ```
+ */
+export function createThreadedCompute(workerPath: string, tasks: string[]) {
+  return new ThreadedCompute(workerPath, tasks);
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+/**
+ * The message format sent from the main thread to a Web Worker when executing a task.
+ *
+ * This message includes a task name, its input payload, and a unique ID used to match
+ * the response from the worker.
+ *
+ * @property task - The name of the task to be executed in the worker.
+ * @property input - The input data for the task. This can be any JSON-serializable value.
+ * @property id - A unique identifier for correlating the response message.
+ *
+ * @example
+ * ```ts
+ * const message: WorkerTaskMessageInterface = {
+ *   task: 'double',
+ *   input: 21,
+ *   id: 1
+ * };
+ * worker.postMessage(message);
+ * ```
+ */
+export interface WorkerTaskMessageInterface {
+  task: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  input: any;
+  id: number;
+}
+
+/**
+ * The message format sent from a Web Worker back to the main thread upon task completion.
+ *
+ * This message includes the result of the task execution or an error message if the task failed.
+ *
+ * @property id - The unique identifier that matches a previously sent task message.
+ * @property result - The result of the task execution (if successful).
+ * @property error - An optional error message if the task failed.
+ *
+ * @example
+ * ```ts
+ * const response: WorkerResultMessageInterface = {
+ *   id: 1,
+ *   result: 42
+ * };
+ * postMessage(response);
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
+ */
+export interface WorkerResultMessageInterface {
+  id: number;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  result: any;
+  error?: string;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "../core" }]
+}