@hybrid-compute/remote 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/README.md

@@ -0,0 +1,88 @@
+# @hybrid-compute/remote
+
+[![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
+
+[RemoteCompute API Documentation](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/remote/src/classes/RemoteCompute.md)
+
+## 📦 Package Info
+
+This package provides:
+
+- A remote compute backend that delegates tasks over HTTP or WebSocket
+- Transport-agnostic JSON message protocol
+- Suitable for offloading work to distributed compute services
+
+## Usage
+
+```bash
+npm install @hybrid-compute/remote
+```
+
+```ts
+import { createRemoteCompute } from '@hybrid-compute/remote';
+
+const remote = createRemoteCompute({
+  transport: 'fetch',
+  endpoint: '/api/compute'
+});
+```
+
+You can see
+[examples here](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/remote/docs/example.md),
+and a
+[testing guide here](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/remote/docs/testing.md)
+
+---
+
+## 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/docs/example.md

@@ -0,0 +1,154 @@
+# RemoteCompute Usage Guide
+
+This guide explains how to use the `RemoteCompute` backend for remote task
+execution via `fetch` or `WebSocket`, and also illustrates how to implement the
+server side for each transport.
+
+## Table of Contents<!-- omit from toc -->
+
+- [RemoteCompute Usage Guide](#remotecompute-usage-guide)
+  - [Overview](#overview)
+  - [Client-Side Usage](#client-side-usage)
+    - [1. Using `fetch` Transport](#1-using-fetch-transport)
+    - [2. Using `websocket` Transport](#2-using-websocket-transport)
+  - [Backend Implementation](#backend-implementation)
+    - [1. Backend for Fetch (Node.js/Express)](#1-backend-for-fetch-nodejsexpress)
+    - [2. Backend for WebSocket (Node.js/ws)](#2-backend-for-websocket-nodejsws)
+  - [Best Practices](#best-practices)
+  - [Troubleshooting](#troubleshooting)
+  - [References](#references)
+
+---
+
+## Overview
+
+`RemoteCompute` allows clients to send computation tasks to a remote service
+using one of two transport protocols:
+
+- `fetch`: HTTP POST requests
+- `websocket`: Persistent WebSocket connection
+
+Each task must be known to the client (optionally restricted via `canRunTasks`)
+and supported by the server.
+
+---
+
+## Client-Side Usage
+
+### 1. Using `fetch` Transport
+
+```ts
+import { createRemoteCompute } from '@hybrid-compute/remote';
+
+const remote = createRemoteCompute({
+  transport: 'fetch',
+  endpoint: 'https://api.example.com/compute',
+  canRunTasks: ['generatePDF']
+});
+
+const result = await remote.runTask('generatePDF', {
+  content: 'Hello, world!'
+});
+console.log(result);
+```
+
+### 2. Using `websocket` Transport
+
+```ts
+import { createRemoteCompute } from '@hybrid-compute/remote';
+
+const remote = createRemoteCompute({
+  transport: 'websocket',
+  endpoint: 'wss://api.example.com/ws',
+  canRunTasks: ['summarizeText']
+});
+
+const result = await remote.runTask('summarizeText', {
+  text: 'This is a long text...'
+});
+console.log(result);
+```
+
+---
+
+## Backend Implementation
+
+### 1. Backend for Fetch (Node.js/Express)
+
+```ts
+import express from 'express';
+const app = express();
+app.use(express.json());
+
+const handlers = {
+  generatePDF: async ({ content }) => {
+    // simulate PDF generation
+    return `PDF with content: ${content}`;
+  }
+};
+
+app.post('/compute', async (req, res) => {
+  const { task, input } = req.body;
+  try {
+    if (!handlers[task]) throw new Error('Unknown task');
+    const result = await handlers[task](input);
+    res.json({ result });
+  } catch (error) {
+    res.json({ error: error.message });
+  }
+});
+
+app.listen(3000);
+```
+
+### 2. Backend for WebSocket (Node.js/ws)
+
+```ts
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+
+const handlers = {
+  summarizeText: async ({ text }) => {
+    return `Summary: ${text.slice(0, 20)}...`;
+  }
+};
+
+wss.on('connection', (ws) => {
+  ws.on('message', async (message) => {
+    const { task, input, id } = JSON.parse(message.toString());
+    try {
+      if (!handlers[task]) throw new Error('Unknown task');
+      const result = await handlers[task](input);
+      ws.send(JSON.stringify({ id, result }));
+    } catch (error) {
+      ws.send(JSON.stringify({ id, error: error.message }));
+    }
+  });
+});
+```
+
+---
+
+## Best Practices
+
+- Validate task names on both ends
+- Enforce authentication and authorization for remote compute endpoints
+- In WebSocket mode, monitor socket health and auto-reconnect if needed
+- Always wrap remote responses with task `id` for proper correlation
+
+---
+
+## Troubleshooting
+
+| Issue                           | Solution                                                        |
+| ------------------------------- | --------------------------------------------------------------- |
+| `WebSocket not connected` error | Ensure WebSocket is open before sending messages                |
+| Task not found                  | Confirm the task name is registered and listed in `canRunTasks` |
+| JSON parse error                | Ensure backend and client speak the same message protocol       |
+
+## References
+
+- [MDN: fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)
+- [MDN: WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+- [WebSocket on NPM](https://www.npmjs.com/package/ws)

package/docs/testing.md

@@ -0,0 +1,132 @@
+# RemoteCompute Test Harness & CURL Examples
+
+This guide provides a simple test harness and `curl` commands to validate that
+your remote backend endpoints (both fetch and websocket) are working correctly.
+
+## Table of Contents<!-- omit from toc -->
+
+- [RemoteCompute Test Harness \& CURL Examples](#remotecompute-test-harness--curl-examples)
+  - [HTTP `fetch` Test Harness (Node.js)](#http-fetch-test-harness-nodejs)
+    - [File: `test-fetch.js`](#file-test-fetchjs)
+    - [CURL Test: `fetch`](#curl-test-fetch)
+  - [WebSocket Test Harness (Node.js)](#websocket-test-harness-nodejs)
+    - [File: `test-websocket.js`](#file-test-websocketjs)
+    - [WebSocket Manual Testing (via `wscat`)](#websocket-manual-testing-via-wscat)
+  - [What to Verify](#what-to-verify)
+  - [Security Tip](#security-tip)
+
+---
+
+## HTTP `fetch` Test Harness (Node.js)
+
+### File: `test-fetch.js`
+
+```js
+const taskName = 'generatePDF';
+const input = { content: 'Hello, PDF World!' };
+
+async function run() {
+  const res = await fetch('http://localhost:3000/compute', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ task: taskName, input })
+  });
+
+  const json = await res.json();
+  console.log('Response:', json);
+}
+
+run().catch(console.error);
+```
+
+### CURL Test: `fetch`
+
+```bash
+curl -X POST http://localhost:3000/compute \
+  -H "Content-Type: application/json" \
+  -d '{"task": "generatePDF", "input": { "content": "Hello from CURL" }}'
+```
+
+Expected output:
+
+```json
+{ "result": "PDF with content: Hello from CURL" }
+```
+
+## WebSocket Test Harness (Node.js)
+
+### File: `test-websocket.js`
+
+```js
+import WebSocket from 'ws';
+
+const socket = new WebSocket('ws://localhost:8080');
+const taskId = 1;
+
+socket.onopen = () => {
+  socket.send(
+    JSON.stringify({
+      task: 'summarizeText',
+      input: {
+        text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+      },
+      id: taskId
+    })
+  );
+};
+
+socket.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('WS response:', data);
+  socket.close();
+};
+
+socket.onerror = (err) => {
+  console.error('WebSocket error:', err);
+};
+```
+
+### WebSocket Manual Testing (via `wscat`)
+
+You can use `wscat` from the terminal:
+
+```bash
+npm install -g wscat
+wscat -c ws://localhost:8080
+```
+
+Once connected, send this JSON payload:
+
+```json
+{
+  "task": "summarizeText",
+  "input": { "text": "WebSocket test with a longer text to summarize" },
+  "id": 42
+}
+```
+
+Expected response:
+
+```json
+{
+  "id": 42,
+  "result": "Summary: WebSocket test with..."
+}
+```
+
+## What to Verify
+
+| Test              | Expected                                        |
+| ----------------- | ----------------------------------------------- |
+| fetch POST        | JSON response with `"result"` or `"error"`      |
+| WebSocket send    | JSON message with matching `"id"` and result    |
+| Unregistered task | `"error": "Unknown task"`                       |
+| Missing input     | backend should throw or return error gracefully |
+
+## Security Tip
+
+In production, always validate:
+
+- Origin and authentication headers
+- Rate limits
+- Schema of incoming requests (e.g. using Zod or Yup)

package/eslint.config.mjs

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

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hybrid-compute/remote",
+  "version": "0.0.1",
+  "description": "Remote compute backend using fetch or WebSocket transport for distributed task execution.",
+  "keywords": [
+    "remote",
+    "compute",
+    "websocket",
+    "fetch",
+    "transport",
+    "distributed",
+    "json-rpc",
+    "http",
+    "cloud",
+    "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__/remote.spec.ts

@@ -0,0 +1,176 @@
+import test, { describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRemoteCompute, RemoteCompute } from '..';
+globalThis.fetch = async (
+  input: RequestInfo | URL,
+  init?: RequestInit
+): Promise<Response> => {
+  const body = JSON.parse((init?.body as string) ?? '{}');
+
+  const isError = body.task === 'fail';
+
+  return {
+    ok: !isError,
+    status: isError ? 400 : 200,
+    headers: new Headers(),
+    redirected: false,
+    statusText: isError ? 'Bad Request' : 'OK',
+    type: 'basic',
+    url: String(input),
+    clone: function () {
+      return this;
+    },
+    body: null,
+    bodyUsed: true,
+    arrayBuffer: async () => new ArrayBuffer(0),
+    blob: async () => new Blob(),
+    formData: async () => new FormData(),
+    text: async () =>
+      JSON.stringify(
+        isError
+          ? { error: 'Task failed' }
+          : { result: `Result for ${body.task}` }
+      ),
+    json: async () =>
+      isError ? { error: 'Task failed' } : { result: `Result for ${body.task}` }
+  } as Response;
+};
+
+describe('RemoteCompute', () => {
+  test('fetch transport returns result from remote', async () => {
+    const compute = new RemoteCompute({
+      transport: 'fetch',
+      endpoint: 'https://api.example.com/compute'
+    });
+
+    const result = await compute.runTask('echo', { message: 'hi' });
+    assert.equal(result, 'Result for echo');
+  });
+
+  test('fetch transport throws on error response', async () => {
+    const compute = new RemoteCompute({
+      transport: 'fetch',
+      endpoint: 'https://api.example.com/compute'
+    });
+
+    await assert.rejects(() => compute.runTask('fail', {}), /Task failed/);
+  });
+
+  test('canRun returns true if task is allowed', () => {
+    const compute = new RemoteCompute({
+      transport: 'fetch',
+      endpoint: '/compute',
+      canRunTasks: ['foo', 'bar']
+    });
+
+    assert.equal(compute.canRun('foo'), true);
+    assert.equal(compute.canRun('baz'), false);
+  });
+
+  test('canRun returns true if canRunTasks is undefined', () => {
+    const compute = new RemoteCompute({
+      transport: 'fetch',
+      endpoint: '/compute'
+    });
+
+    assert.equal(compute.canRun('anything'), true);
+  });
+
+  test(
+    'WebSocket transport sends and resolves a message',
+    { timeout: 200 },
+    async () => {
+      const OriginalWebSocket = globalThis.WebSocket;
+      let sentData = '';
+
+      class MockWebSocket {
+        public readyState = WebSocket.OPEN;
+        public onmessage: ((event: MessageEvent) => void) | null = null;
+
+        constructor(public url: string) {}
+
+        send(data: string) {
+          sentData = data;
+          const { id } = JSON.parse(data);
+          const fakeResponse = { id, result: 'websocket-result' };
+          setTimeout(() => {
+            this.onmessage?.({
+              data: JSON.stringify(fakeResponse)
+            } as MessageEvent);
+          }, 10);
+        }
+      }
+
+      // @ts-expect-error override native WebSocket
+      globalThis.WebSocket = MockWebSocket;
+
+      try {
+        const compute = new RemoteCompute({
+          transport: 'websocket',
+          endpoint: 'wss://example.com/ws'
+        });
+
+        // Wait a tick before calling runTask (mimics real socket delay)
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        const result = await compute.runTask('test', { foo: 1 });
+        assert.equal(result, 'websocket-result');
+      } finally {
+        globalThis.WebSocket = OriginalWebSocket;
+      }
+    }
+  );
+
+  test('WebSocket rejects if not connected', async () => {
+    const OriginalWebSocket = globalThis.WebSocket;
+
+    class MockWebSocket {
+      public readyState = 3; // WebSocket.CLOSED
+      public onmessage: ((event: MessageEvent) => void) | null = null;
+
+      constructor(public url: string) {
+        console.log('[MOCK] MockWebSocket constructor called');
+      }
+
+      send() {
+        console.log('[MOCK] send() should not be called');
+      }
+    }
+
+    // @ts-expect-error override
+    globalThis.WebSocket = MockWebSocket;
+
+    try {
+      const compute = new RemoteCompute({
+        transport: 'websocket',
+        endpoint: 'wss://example.com/ws'
+      });
+
+      const resultPromise = compute.runTask('any', {});
+      await assert.rejects(resultPromise, /WebSocket not connected/);
+    } finally {
+      globalThis.WebSocket = OriginalWebSocket;
+    }
+  });
+
+  test('runTask() manually rejects for testing', async () => {
+    const compute = {
+      runTask: () => Promise.reject(new Error('WebSocket not connected'))
+    } as unknown as RemoteCompute;
+
+    await assert.rejects(
+      () => compute.runTask('x', {}),
+      /WebSocket not connected/
+    );
+  });
+});
+describe('createRemoteCompute', () => {
+  test('returns instance of RemoteCompute', () => {
+    const instance = createRemoteCompute({
+      transport: 'fetch',
+      endpoint: '/compute'
+    });
+
+    assert.ok(instance instanceof RemoteCompute);
+  });
+});

package/src/index.ts

@@ -0,0 +1,145 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ComputeBackendInterface } from '@hybrid-compute/core';
+
+import { RemoteComputeOptionsInterface, RemoteTransportType } from './types.js';
+
+export * from './types.js';
+
+/**
+ * RemoteCompute is a backend that delegates compute tasks to a remote API
+ * using either HTTP requests (fetch) or a persistent WebSocket connection.
+ *
+ * It supports bidirectional communication, which is useful for low-latency
+ * or streaming scenarios using WebSocket, or traditional stateless interaction
+ * using fetch.
+ *
+ * @remarks
+ * WebSocket-based transport allows concurrent request handling via an internal
+ * request/response map using `id`. This is useful when running multiple tasks in parallel.
+ *
+ * Fetch transport is simpler and more interoperable with typical REST APIs.
+ *
+ * @example Fetch transport
+ * ```ts
+ * const remote = new RemoteCompute({
+ *   transport: 'fetch',
+ *   endpoint: 'https://api.example.com/compute',
+ *   canRunTasks: ['translateText']
+ * });
+ *
+ * const result = await remote.runTask('translateText', { text: 'hello' });
+ * ```
+ *
+ * @example WebSocket transport
+ * ```ts
+ * const remote = new RemoteCompute({
+ *   transport: 'websocket',
+ *   endpoint: 'wss://api.example.com/ws',
+ *   canRunTasks: ['analyzeSentiment']
+ * });
+ *
+ * const result = await remote.runTask('analyzeSentiment', { text: 'It works!' });
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/fetch
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+ */
+export class RemoteCompute implements ComputeBackendInterface {
+  private transport: RemoteTransportType;
+  private endpoint: string;
+  private canRunSet: Set<string>;
+  private socket?: WebSocket;
+  private pending = new Map<
+    number,
+    {
+      resolve: (value: any | PromiseLike<any>) => void;
+      reject: (value: any | PromiseLike<any>) => void;
+    }
+  >();
+  private nextId = 1;
+
+  /**
+   * Initializes the remote compute backend.
+   *
+   * @param options - Transport type and endpoint configuration.
+   */
+  constructor(options: RemoteComputeOptionsInterface) {
+    this.transport = options.transport;
+    this.endpoint = options.endpoint;
+    this.canRunSet = new Set(options.canRunTasks ?? []);
+
+    if (this.transport === 'websocket') {
+      this.socket = new WebSocket(this.endpoint);
+
+      this.socket.onmessage = (event: MessageEvent) => {
+        const { id, result, error } = JSON.parse(event.data);
+
+        if (error) this.pending.get(id)?.reject(error);
+        else this.pending.get(id)?.resolve(result);
+
+        this.pending.delete(id);
+      };
+    }
+  }
+
+  /**
+   * Determines if this backend is allowed to handle the given task.
+   *
+   * @param taskName - Name of the task.
+   * @returns `true` if task is permitted, or if no restrictions are set.
+   */
+  canRun(taskName: string): boolean {
+    return this.canRunSet.size === 0 || this.canRunSet.has(taskName);
+  }
+
+  /**
+   * Executes the specified task using remote communication.
+   *
+   * @typeParam Input - The input data structure expected by the task.
+   * @typeParam Output - The output structure returned by the task.
+   *
+   * @param taskName - Name of the remote task.
+   * @param input - Input data to send.
+   * @returns A promise resolving to the result from the server.
+   */
+  async runTask<Input, Output>(
+    taskName: string,
+    input: Input
+  ): Promise<Output> {
+    const id = this.nextId++;
+
+    if (this.transport === 'fetch') {
+      const response = await fetch(this.endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ task: taskName, input })
+      });
+      const { result, error } = await response.json();
+
+      if (error) throw new Error(error);
+
+      return result;
+    }
+
+    return new Promise<Output>((resolve, reject) => {
+      if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+        reject(new Error('WebSocket not connected'));
+
+        return;
+      }
+
+      this.pending.set(id, { resolve, reject });
+      this.socket.send(JSON.stringify({ task: taskName, input, id }));
+    });
+  }
+}
+
+/**
+ * Factory to create a RemoteCompute instance with given options.
+ *
+ * @param options - Remote connection configuration.
+ * @returns Instance of RemoteCompute.
+ */
+export function createRemoteCompute(options: RemoteComputeOptionsInterface) {
+  return new RemoteCompute(options);
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents the communication method used by the `RemoteCompute` backend
+ * to interact with a remote server.
+ *
+ * - `'fetch'`: Sends HTTP POST requests for each task.
+ * - `'websocket'`: Maintains a persistent WebSocket connection for bi-directional messaging.
+ *
+ * @example
+ * ```ts
+ * const transport: RemoteTransportType = 'fetch';
+ * ```
+ */
+export type RemoteTransportType = 'fetch' | 'websocket';
+
+/**
+ * Configuration options for initializing a `RemoteCompute` backend.
+ *
+ * @property transport - The transport mechanism to use (`fetch` or `websocket`).
+ * @property endpoint - The server URL for handling task requests.
+ * @property canRunTasks - An optional list of task names this backend can handle. If omitted, it is assumed the backend can attempt all tasks.
+ *
+ * @example
+ * ```ts
+ * const options: RemoteComputeOptionsInterface = {
+ *   transport: 'websocket',
+ *   endpoint: 'wss://api.example.com/ws',
+ *   canRunTasks: ['resizeImage', 'generatePDF']
+ * };
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/fetch
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+ */
+export interface RemoteComputeOptionsInterface {
+  transport: RemoteTransportType;
+  endpoint: string;
+  canRunTasks?: 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" }]
+}