@hybrid-compute/core 0.0.2

package/.release-it.json

@@ -0,0 +1,64 @@
+{
+  "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/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/README.md

@@ -0,0 +1,78 @@
+# @hybrid-compute/core
+
+[![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
+
+[HybridCompute Core API Documentation](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/core/src/classes/HybridCompute.md)
+
+## 📦 Package Info
+
+This package provides:
+
+- The core orchestrator `HybridCompute` class
+- Strategy-based task routing (`local`, `worker`, `remote`, or `auto`)
+- Unified API for compute execution
+
+## Usage
+
+```bash
+npm install @hybrid-compute/core
+```
+
+```ts
+import { HybridCompute } from '@hybrid-compute/core';
+```
+
+---
+
+## 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,51 @@
+{
+  "name": "@hybrid-compute/core",
+  "version": "0.0.2",
+  "description": "Core orchestrator for dispatching compute tasks to local, threaded, or remote backends.",
+  "keywords": [
+    "compute",
+    "task-dispatch",
+    "core",
+    "strategy",
+    "hybrid",
+    "orchestrator",
+    "execution",
+    "modular",
+    "framework"
+  ],
+  "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": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "release": "release-it",
+    "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\""
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.24",
+    "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__/core.spec.ts

@@ -0,0 +1,139 @@
+import test, { describe } from 'node:test';
+import assert from 'node:assert';
+import {
+  ComputeBackendInterface,
+  createHybridCompute,
+  HybridCompute
+} from '..';
+
+// Mocks
+const mockTaskName = 'double';
+const mockInput = 21;
+const mockOutput = 42;
+
+function createMockBackend(): ComputeBackendInterface {
+  return {
+    canRun: (taskName) => taskName === 'double',
+    runTask: async <Input, Output>(
+      taskName: string,
+      input: Input
+    ): Promise<Output> => {
+      // mock response — force-cast for test purposes
+      return 42 as unknown as Output;
+    }
+  };
+}
+
+function createNonRunnableMockBackend(): ComputeBackendInterface {
+  return {
+    canRun: () => false,
+    runTask: async <Input, Output>() => {
+      throw new Error('Should not be called');
+    }
+  };
+}
+
+describe('HybridCompute', () => {
+  test('runs task using local strategy', async () => {
+    const compute = new HybridCompute({ local: createMockBackend() });
+
+    const result = await compute.runTask(mockTaskName, mockInput, 'local');
+    assert.strictEqual(result, mockOutput);
+  });
+
+  test('runs task using worker strategy', async () => {
+    const compute = new HybridCompute({ worker: createMockBackend() });
+
+    const result = await compute.runTask(mockTaskName, mockInput, 'worker');
+    assert.strictEqual(result, mockOutput);
+  });
+
+  test('runs task using remote strategy', async () => {
+    const compute = new HybridCompute({ remote: createMockBackend() });
+
+    const result = await compute.runTask(mockTaskName, mockInput, 'remote');
+    assert.strictEqual(result, mockOutput);
+  });
+  test('uses auto strategy with priority: worker > local > remote', async () => {
+    const callOrder: string[] = [];
+
+    const worker: ComputeBackendInterface = {
+      canRun: () => (callOrder.push('worker'), true),
+      runTask: async <Input, Output>(
+        taskName: string,
+        input: Input
+      ): Promise<Output> => {
+        callOrder.push('runWorker');
+        return mockOutput as unknown as Output;
+      }
+    };
+
+    const local: ComputeBackendInterface = {
+      canRun: () => (callOrder.push('local'), true),
+      runTask: async <Input, Output>(
+        taskName: string,
+        input: Input
+      ): Promise<Output> => {
+        callOrder.push('runLocal');
+        return mockOutput as unknown as Output;
+      }
+    };
+
+    const remote: ComputeBackendInterface = {
+      canRun: () => (callOrder.push('remote'), true),
+      runTask: async <Input, Output>(
+        taskName: string,
+        input: Input
+      ): Promise<Output> => {
+        callOrder.push('runRemote');
+        return mockOutput as unknown as Output;
+      }
+    };
+
+    const compute = new HybridCompute({ worker, local, remote });
+    const result = await compute.runTask(mockTaskName, mockInput, 'auto');
+
+    assert.strictEqual(result, mockOutput);
+    assert.deepStrictEqual(callOrder, ['worker', 'runWorker']);
+  });
+
+  test('falls back in auto strategy if earlier backends cannot run', async () => {
+    const compute = new HybridCompute({
+      worker: createMockBackend(),
+      local: createMockBackend(),
+      remote: createMockBackend()
+    });
+
+    const result = await compute.runTask(mockTaskName, mockInput, 'auto');
+    assert.strictEqual(result, mockOutput);
+  });
+
+  test('throws if no backend matches the strategy', async () => {
+    const compute = new HybridCompute({});
+
+    await assert.rejects(
+      () => compute.runTask(mockTaskName, mockInput, 'local'),
+      /No backend available/
+    );
+  });
+
+  test('throws if no backend can run in auto strategy', async () => {
+    const compute = new HybridCompute({
+      worker: createNonRunnableMockBackend(),
+      local: createNonRunnableMockBackend(),
+      remote: createNonRunnableMockBackend()
+    });
+
+    await assert.rejects(
+      () => compute.runTask(mockTaskName, mockInput, 'auto'),
+      /No backend available/
+    );
+  });
+});
+
+describe('createHybridCompute', () => {
+  test('returns HybridCompute instance', () => {
+    const instance = createHybridCompute({ local: createMockBackend() });
+    assert.ok(instance instanceof HybridCompute);
+  });
+});

package/src/index.ts

@@ -0,0 +1,103 @@
+export * from './types.js';
+
+import {
+  ExecutionStrategyType,
+  HybridComputeOptionsInterface
+} from './types.js';
+
+/**
+ * The HybridCompute class acts as an orchestrator to delegate compute tasks
+ * across different backends (local, worker, or remote) using a flexible strategy.
+ *
+ * It supports four strategies:
+ * - `'local'`: Forces execution on the local (main thread) backend.
+ * - `'worker'`: Forces execution on a threaded/WebWorker backend.
+ * - `'remote'`: Forces execution on a remote/server backend.
+ * - `'auto'`: Automatically selects the first available backend that supports the task.
+ *
+ * @example
+ * ```ts
+ * const compute = new HybridCompute({
+ *   local: createLocalCompute(),
+ *   worker: createThreadedCompute(workerPath, ['double']),
+ *   remote: createRemoteCompute({ transport: 'fetch', endpoint: '/api/compute' })
+ * });
+ *
+ * const result = await compute.runTask<number, number>('double', 21, 'auto');
+ * console.log(result); // 42
+ * ```
+ */
+export class HybridCompute {
+  private backends: HybridComputeOptionsInterface;
+
+  /**
+   * Creates a new HybridCompute orchestrator.
+   *
+   * @param backends - An object containing optional local, worker, and remote backends.
+   */
+  constructor(backends: HybridComputeOptionsInterface) {
+    this.backends = backends;
+  }
+
+  /**
+   * Runs a task using the specified execution strategy.
+   *
+   * If `strategy` is `'auto'`, it will try the worker, then local, then remote backend in order of priority.
+   *
+   * @typeParam Input - The type of the input expected by the task.
+   * @typeParam Output - The expected output type returned by the task.
+   *
+   * @param taskName - The name of the task to execute.
+   * @param input - The input payload for the task.
+   * @param strategy - The execution strategy to use. Defaults to `'auto'`.
+   *
+   * @returns A Promise resolving to the task's output.
+   *
+   * @throws If no backend is available or able to run the task.
+   *
+   * @example
+   * ```ts
+   * const output = await compute.runTask('greetUser', { name: 'Alice' }, 'worker');
+   * ```
+   */
+  async runTask<Input, Output>(
+    taskName: string,
+    input: Input,
+    strategy: ExecutionStrategyType = 'auto'
+  ): Promise<Output> {
+    if (strategy === 'local' && this.backends.local) {
+      return this.backends.local.runTask(taskName, input);
+    } else if (strategy === 'worker' && this.backends.worker) {
+      return this.backends.worker.runTask(taskName, input);
+    } else if (strategy === 'remote' && this.backends.remote) {
+      return this.backends.remote.runTask(taskName, input);
+    } else if (strategy === 'auto') {
+      if (this.backends.worker?.canRun(taskName)) {
+        return this.backends.worker.runTask(taskName, input);
+      } else if (this.backends.local?.canRun(taskName)) {
+        return this.backends.local.runTask(taskName, input);
+      } else if (this.backends.remote?.canRun(taskName)) {
+        return this.backends.remote.runTask(taskName, input);
+      }
+    }
+
+    throw new Error(
+      `No backend available for task '${taskName}' using strategy '${strategy}'`
+    );
+  }
+}
+
+/**
+ * Factory function for creating a HybridCompute instance.
+ *
+ * @param backends - Configuration options specifying available backends.
+ * @returns A new HybridCompute orchestrator.
+ *
+ * @example
+ * ```ts
+ * const hybrid = createHybridCompute({ local: createLocalCompute() });
+ * ```
+ */
+export function createHybridCompute(backends: HybridComputeOptionsInterface) {
+  return new HybridCompute(backends);
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+/**
+ * The strategy used to determine which compute backend to use.
+ *
+ * - `auto`: Automatically select the best backend available.
+ * - `local`: Run tasks directly on the main thread.
+ * - `worker`: Offload tasks to WebWorker or thread-based compute.
+ * - `remote`: Offload tasks to a remote server or service.
+ *
+ * @example
+ * ```ts
+ * const strategy: ExecutionStrategyType = 'worker';
+ * ```
+ */
+export type ExecutionStrategyType = 'auto' | 'local' | 'worker' | 'remote';
+
+/**
+ * Describes a unit of work that can be executed by a compute backend.
+ *
+ * @template Input The input type expected by the task.
+ * @template Output The output type returned by the task.
+ *
+ * @property name - A unique name used to identify the task.
+ * @property run - A function that takes input and returns a Promise of the output.
+ *
+ * @example
+ * ```ts
+ * const task: ComputeTaskInterface<number, number> = {
+ *   name: 'double',
+ *   run: async (x) => x * 2
+ * };
+ * ```
+ */
+export interface ComputeTaskInterface<Input = unknown, Output = unknown> {
+  name: string;
+  run(input: Input): Promise<Output>;
+}
+
+/**
+ * Represents a backend capable of executing registered compute tasks.
+ *
+ * Each backend must be able to:
+ * - Determine if it can run a given task (`canRun`)
+ * - Execute a named task with input and return a Promise of output (`runTask`)
+ *
+ * @template Input The input type for task execution.
+ * @template Output The output type for task execution.
+ *
+ * @example
+ * ```ts
+ * const backend: ComputeBackendInterface = {
+ *   canRun: (taskName) => taskName === 'double',
+ *   runTask: async (taskName, input) => {
+ *     if (taskName === 'double') return (input as number) * 2;
+ *     throw new Error('Unknown task');
+ *   }
+ * };
+ * ```
+ */
+export interface ComputeBackendInterface {
+  canRun(taskName: string): boolean;
+  runTask<Input, Output>(taskName: string, input: Input): Promise<Output>;
+}
+
+/**
+ * Configuration options for initializing the HybridCompute orchestrator.
+ *
+ * Backends are optional, and can be combined or omitted based on the environment or needs.
+ *
+ * @property local - A local synchronous compute backend (main thread).
+ * @property worker - A background-thread compute backend (e.g. WebWorker).
+ * @property remote - A server-side or cloud compute backend.
+ *
+ * @example
+ * ```ts
+ * const options: HybridComputeOptionsInterface = {
+ *   local: createLocalCompute(),
+ *   remote: createRemoteCompute({ ... })
+ * };
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+ */
+export interface HybridComputeOptionsInterface {
+  local?: ComputeBackendInterface;
+  worker?: ComputeBackendInterface;
+  remote?: ComputeBackendInterface;
+}

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": []
+}