{"id":28444089,"url":"https://github.com/phun-ky/hybrid-compute","last_synced_at":"2026-04-14T14:00:57.281Z","repository":{"id":296398444,"uuid":"992105751","full_name":"phun-ky/hybrid-compute","owner":"phun-ky","description":"Run compute tasks wherever they run best - local, threaded, or remote - with a pluggable backend architecture.","archived":false,"fork":false,"pushed_at":"2026-03-30T06:21:32.000Z","size":4094,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T04:57:47.735Z","etag":null,"topics":["abstraction","agent-tools","ai","api","compute","fetch","framework","hybrid","llm","modular","multithreading","offloading","orchestration","remote","rpc","serverless","task-runner","web-worker","websocket","worker-pool"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phun-ky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"phun-ky"}},"created_at":"2025-05-28T16:16:53.000Z","updated_at":"2026-03-30T06:21:35.000Z","dependencies_parsed_at":"2026-03-09T12:04:53.777Z","dependency_job_id":null,"html_url":"https://github.com/phun-ky/hybrid-compute","commit_stats":null,"previous_names":["phun-ky/hybrid-compute"],"tags_count":164,"template":false,"template_full_name":"phun-ky/ts-template","purl":"pkg:github/phun-ky/hybrid-compute","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun-ky%2Fhybrid-compute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun-ky%2Fhybrid-compute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun-ky%2Fhybrid-compute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun-ky%2Fhybrid-compute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phun-ky","download_url":"https://codeload.github.com/phun-ky/hybrid-compute/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun-ky%2Fhybrid-compute/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31799411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstraction","agent-tools","ai","api","compute","fetch","framework","hybrid","llm","modular","multithreading","offloading","orchestration","remote","rpc","serverless","task-runner","web-worker","websocket","worker-pool"],"created_at":"2025-06-06T08:40:41.760Z","updated_at":"2026-04-14T14:00:57.046Z","avatar_url":"https://github.com/phun-ky.png","language":"TypeScript","funding_links":["https://github.com/sponsors/phun-ky"],"categories":[],"sub_categories":[],"readme":"# @hybrid-compute\n\n![@hybrid-compute banner with logo and text](./public/logo-banner.png)\n\n\u003e **Run compute tasks wherever they run best - local, threaded, or remote - with a pluggable backend architecture.**\n\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](http://makeapullrequest.com)\n[![SemVer 2.0](https://img.shields.io/badge/SemVer-2.0-green.svg)](http://semver.org/spec/v2.0.0.html)\n![issues](https://img.shields.io/github/issues/phun-ky/hybrid-compute)\n![GitHub Repo stars](https://img.shields.io/github/stars/phun-ky/hybrid-compute)\n[![codecov](https://codecov.io/gh/phun-ky/hybrid-compute/graph/badge.svg?token=VA91DL7ZLZ)](https://codecov.io/gh/phun-ky/hybrid-compute)\n[![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)\n\n## About\n\n`@hybrid-compute` is a flexible, modular compute orchestration framework that\ndispatches computational tasks to the most appropriate backend — whether that's:\n\n- The local JS thread (for fast, simple tasks)\n- A dedicated Web Worker (for multi-threaded offloading)\n- Or a remote compute service over HTTP or WebSocket\n\nAll you do is define tasks and call `runTask()`. HybridCompute takes care of the\nrest.\n\n## Table of Contents\u003c!-- omit from toc --\u003e\n\n- [@hybrid-compute](#hybrid-compute)\n  - [About](#about)\n  - [API](#api)\n  - [Usage](#usage)\n    - [Usage with local](#usage-with-local)\n    - [Usage with remote](#usage-with-remote)\n      - [Fetch](#fetch)\n      - [WebSocket](#websocket)\n    - [Usage with worker](#usage-with-worker)\n  - [Example](#example)\n  - [Visual overviews](#visual-overviews)\n    - [High-Level Package Architecture](#high-level-package-architecture)\n    - [Task Dispatch Flow (HybridCompute Core)](#task-dispatch-flow-hybridcompute-core)\n    - [Threaded Worker Lifecycle](#threaded-worker-lifecycle)\n    - [Remote Compute Flow (WebSocket or Fetch)](#remote-compute-flow-websocket-or-fetch)\n  - [Development](#development)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Changelog](#changelog)\n  - [Sponsor me](#sponsor-me)\n\n## API\n\nCheck out the full documentation\n[here](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/README.md).\n\nIncludes:\n\n- All public classes and methods\n- Task registration and execution patterns\n- Transport and backend setup guides\n\n## Usage\n\n```shell-session\nnpm install @hybrid-compute/core\n```\n\n### Usage with local\n\n```bash\nnpm install @hybrid-compute/core\nnpm install @hybrid-compute/local\n```\n\n```ts\nimport { createHybridCompute } from '@hybrid-compute/core';\nimport { createLocalCompute } from '@hybrid-compute/local';\n\n// Define a simple echo task\nconst echoTask = {\n  name: 'echo',\n  async run(input: string): Promise\u003cstring\u003e {\n    return `Echo: ${input}`;\n  }\n};\n\n// Set up the local backend and register the task\nconst local = createLocalCompute();\nlocal.registerTask(echoTask);\n\n// Set up the HybridCompute instance with only the local backend\nconst compute = createHybridCompute({\n  local\n});\n\n// Run the task\nasync function main() {\n  try {\n    const result = await compute.runTask('echo', 'Hello from HybridCompute!');\n    console.log(result); // Output: Echo: Hello from HybridCompute!\n  } catch (error) {\n    console.error('Task failed:', error);\n  }\n}\n\nmain();\n```\n\n### Usage with remote\n\n```bash\nnpm install @hybrid-compute/core\nnpm install @hybrid-compute/remote\n```\n\n#### Fetch\n\n```ts\nimport { createHybridCompute } from '@hybrid-compute/core';\nimport { createRemoteCompute } from '@hybrid-compute/remote';\n\nconst remote = createRemoteCompute({\n  transport: 'fetch',\n  endpoint: 'https://your-remote-service.com/compute',\n  canRunTasks: ['echo']\n});\n\nconst compute = createHybridCompute({\n  remote\n});\n\nasync function main() {\n  try {\n    const result = await compute.runTask('echo', 'Remote via fetch!');\n    console.log(result); // Output from remote server\n  } catch (error) {\n    console.error('Task failed:', error);\n  }\n}\n\nmain();\n```\n\n##### Example server for the remote fetch example\n\n```js\nimport express from 'express';\n\nconst app = express();\nconst port = 3000;\n\n// Middleware to parse JSON\napp.use(express.json());\n\n// Dummy task implementations\nconst tasks = {\n  echo: async (input) =\u003e {\n    return `Echo from remote server: ${input}`;\n  },\n\n  // Example additional task\n  reverse: async (input) =\u003e {\n    if (typeof input !== 'string') throw new Error('Input must be a string');\n    return input.split('').reverse().join('');\n  }\n};\n\n// Route to handle compute requests\napp.post('/compute', async (req, res) =\u003e {\n  const { task, input } = req.body;\n\n  try {\n    if (!task || !tasks[task]) {\n      throw new Error(`Unknown task '${task}'`);\n    }\n\n    const result = await tasks[task](input);\n    res.json({ result });\n  } catch (error) {\n    res.status(400).json({ error: error.message });\n  }\n});\n\napp.listen(port, () =\u003e {\n  console.log(\n    `🧠 RemoteCompute server listening at http://localhost:${port}/compute`\n  );\n});\n```\n\nThis can be tested locally:\n\n```curl\ncurl -X POST http://localhost:3000/compute \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"task\": \"echo\", \"input\": \"hello\"}'\n```\n\n#### WebSocket\n\n```ts\nimport { createHybridCompute } from '@hybrid-compute/core';\nimport { createRemoteCompute } from '@hybrid-compute/remote';\n\nconst remote = createRemoteCompute({\n  transport: 'websocket',\n  endpoint: 'wss://your-remote-service.com/socket',\n  canRunTasks: ['echo']\n});\n\nconst compute = createHybridCompute({\n  remote\n});\n\nasync function main() {\n  try {\n    const result = await compute.runTask('echo', 'Remote via WebSocket!');\n    console.log(result); // Output from remote service\n  } catch (error) {\n    console.error('Task failed:', error);\n  }\n}\n\nmain();\n```\n\n##### Example server for the remote WebSocket example\n\n```js\nimport { WebSocketServer } from 'ws';\nimport http from 'http';\n\n// Simple task definitions\nconst tasks = {\n  echo: async (input) =\u003e {\n    return `Echo from WebSocket server: ${input}`;\n  },\n\n  reverse: async (input) =\u003e {\n    if (typeof input !== 'string') throw new Error('Input must be a string');\n    return input.split('').reverse().join('');\n  }\n};\n\n// Create an HTTP server to attach WebSocket\nconst server = http.createServer();\nconst wss = new WebSocketServer({ server });\n\nwss.on('connection', (ws) =\u003e {\n  ws.on('message', async (message) =\u003e {\n    let request;\n\n    try {\n      request = JSON.parse(message.toString());\n    } catch (err) {\n      ws.send(JSON.stringify({ id: null, error: 'Invalid JSON' }));\n      return;\n    }\n\n    const { id, task, input } = request;\n\n    if (!id || typeof task !== 'string') {\n      ws.send(JSON.stringify({ id, error: 'Missing or invalid task name' }));\n      return;\n    }\n\n    try {\n      if (!tasks[task]) throw new Error(`Unknown task '${task}'`);\n\n      const result = await tasks[task](input);\n      ws.send(JSON.stringify({ id, result }));\n    } catch (error) {\n      ws.send(JSON.stringify({ id, error: error.message }));\n    }\n  });\n});\n\nserver.listen(3001, () =\u003e {\n  console.log(\n    '🔌 WebSocket RemoteCompute server listening at ws://localhost:3001'\n  );\n});\n```\n\n### Usage with worker\n\n```bash\nnpm install @hybrid-compute/core\nnpm install @hybrid-compute/worker\n```\n\nCreate a file named `worker.ts`:\n\n```ts\nself.onmessage = async (event) =\u003e {\n  const { task, input, id } = event.data;\n\n  try {\n    let result;\n\n    switch (task) {\n      case 'echo':\n        result = `Echo from Worker: ${input}`;\n        break;\n\n      // Add more cases for additional tasks\n      default:\n        throw new Error(`Unknown task: ${task}`);\n    }\n\n    self.postMessage({ id, result });\n  } catch (error) {\n    self.postMessage({ id, error: (error as Error).message });\n  }\n};\n```\n\nAnd your `main.ts`:\n\n```ts\nimport { createHybridCompute } from '@hybrid-compute/core';\nimport { createThreadedCompute } from '@hybrid-compute/worker';\n\n// Worker must be served as a module\nconst worker = createThreadedCompute(\n  new URL('./worker.ts', import.meta.url).href,\n  ['echo']\n);\n\nconst compute = createHybridCompute({\n  worker\n});\n\nconst main = async () =\u003e {\n  try {\n    const result = await compute.runTask('echo', 'Hello from Worker!');\n    console.log(result); // Echo from Worker: Hello from Worker!\n  } catch (error) {\n    console.error('Task failed:', error);\n  }\n};\n\nmain();\n```\n\n## Example\n\nThis example expects a task setup for `double` on the backends that doubles the\ninput number. `auto` is used to use first available backend that has the task\nset up.\n\n```ts\nimport {\n  HybridCompute,\n  createLocalCompute,\n  createThreadedCompute,\n  createRemoteCompute\n} from '@hybrid-compute/core';\n\nconst compute = new HybridCompute({\n  local: createLocalCompute(),\n  worker: createThreadedCompute(new URL('./worker.js', import.meta.url), [\n    'double'\n  ]),\n  remote: createRemoteCompute({ transport: 'fetch', endpoint: '/api/compute' })\n});\n\nconst result = await compute.runTask\u003cnumber, number\u003e('double', 21, 'auto');\nconsole.log(result); // 42\n```\n\n## Visual overviews\n\n### High-Level Package Architecture\n\n```mermaid\ngraph TD\n  subgraph HybridCompute\n    HC[HybridCompute Core]\n    HC --\u003e|uses| Local[Local Backend]\n    HC --\u003e|uses| Worker[Threaded Backend]\n    HC --\u003e|uses| Remote[Remote Backend]\n  end\n\n  Local -.-\u003e|executes task locally| TaskLocal[ComputeTask]\n  Worker -.-\u003e|delegates task to| WebWorker\n  Remote -.-\u003e|calls| HTTP[HTTP API] \u0026 WS[WebSocket API]\n```\n\n### Task Dispatch Flow (HybridCompute Core)\n\n```mermaid\nflowchart TD\n  A[\"runTask(taskName, input, strategy)\"] --\u003e B{Strategy}\n  B --\u003e|local| C[local.runTask]\n  B --\u003e|worker| D[worker.runTask]\n  B --\u003e|remote| E[remote.runTask]\n  B --\u003e|auto| F{canRun?}\n\n  F --\u003e|worker| D\n  F --\u003e|local| C\n  F --\u003e|remote| E\n  D \u0026 C \u0026 E --\u003e G[Promise\u003cOutput\u003e]\n```\n\n### Threaded Worker Lifecycle\n\n```mermaid\nsequenceDiagram\n  participant MainThread\n  participant ThreadedCompute\n  participant WebWorker\n\n  MainThread-\u003e\u003eThreadedCompute: runTask(\"task\", input)\n  ThreadedCompute-\u003e\u003eWebWorker: postMessage({ id, task, input })\n  WebWorker--\u003e\u003eThreadedCompute: postMessage({ id, result })\n  ThreadedCompute--\u003e\u003eMainThread: resolve(result)\n\n```\n\n### Remote Compute Flow (WebSocket or Fetch)\n\n```mermaid\nflowchart TD\n  subgraph RemoteCompute\n    RC[\"runTask()\"]\n    style RC fill:#eef,stroke:#333,stroke-width:1px\n    RC --\u003e T{Transport}\n    T --\u003e|fetch| F[POST /compute]\n    T --\u003e|websocket| WS[\"WebSocket.send()\"]\n  end\n\n  F --\u003e JSON[\"JSON-RPC {task, input}\"]\n  WS --\u003e JSON\n  JSON --\u003e|response| RC\n\n```\n\n## Development\n\n```shell-session\n// Build\n$ npm run build\n// Test\n$ npm test\n```\n\n## Contributing\n\nWant to contribute? Please read the\n[CONTRIBUTING.md](https://github.com/phun-ky/hybrid-compute/blob/main/CONTRIBUTING.md)\nand\n[CODE_OF_CONDUCT.md](https://github.com/phun-ky/hybrid-compute/blob/main/CODE_OF_CONDUCT.md)\n\n## License\n\nThis project is licensed under the MIT License - see the\n[LICENSE](https://github.com/phun-ky/hybrid-compute/blob/main/LICENSE) file for\ndetails.\n\n## Changelog\n\nSee the respective package changelogs.\n\n## Sponsor me\n\nI'm an Open Source evangelist, creating stuff that does not exist yet to help\nget rid of secondary activities and to enhance systems already in place, be it\ndocumentation, tools or web sites.\n\nThe sponsorship is an unique opportunity to alleviate more hours for me to\nmaintain my projects, create new ones and contribute to the large community\nwe're all part of :)\n\n[Support me on GitHub Sponsors](https://github.com/sponsors/phun-ky).\n\np.s. **Ukraine is still under brutal Russian invasion. A lot of Ukrainian people\nare hurt, without shelter and need help**. You can help in various ways, for\ninstance, directly helping refugees, spreading awareness, putting pressure on\nyour local government or companies. You can also support Ukraine by donating\ne.g. to [Red Cross](https://www.icrc.org/en/donate/ukraine),\n[Ukraine humanitarian organisation](https://savelife.in.ua/en/donate-en/#donate-army-card-weekly)\nor\n[donate Ambulances for Ukraine](https://www.gofundme.com/f/help-to-save-the-lives-of-civilians-in-a-war-zone).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphun-ky%2Fhybrid-compute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphun-ky%2Fhybrid-compute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphun-ky%2Fhybrid-compute/lists"}