Initial version of @reactodia/worker-proxy library

Author: AlexeyMz

.editorconfig

@@ -0,0 +1,16 @@
+# http://editorconfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+
+[*.{js,jsx,ts,tsx}]
+indent_style = space
+indent_size = 4
+
+[*.json]
+indent_style = space
+indent_size = 4

.gitignore

@@ -0,0 +1,8 @@
+/node_modules
+/dist
+/*.sh
+/*.bat
+/*.tgz
+.vscode/
+
+*.log

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to the project will be documented in this document.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.1.0]
+- Initial release with:
+  * Ref-counted worker proxy: `refCountedWorker()` function and `RefCountedWorker` interface.
+  * Worker proxy protocol: `connectWorker()` function and `WorkerConstructor`, `WorkerObject`, `WorkerCall`, `WorkerCallSuccess`, `WorkerCallError` types.
+
+[0.1.0]: https://github.com/reactodia/worker-proxy/commits/v0.1.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexey Morozov
+
+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.

README.md

@@ -0,0 +1,169 @@
+# Reactodia Worker Proxy [![npm version](https://badge.fury.io/js/@reactodia%2Fworker-proxy.svg)](https://badge.fury.io/js/@reactodia%2Fworker-proxy)
+
+`@reactodia/worker-proxy` is a TypeScript/JavaScript library for the browser that makes it easy to run background tasks with dedicated [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Worker) with automatic connection lifecycle and transparently mapped worker logic via [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) objects.
+
+## Installation
+
+Install with:
+```sh
+npm install --save @reactodia/worker-proxy
+```
+
+## Quick example
+
+`calc.worker.ts` module:
+```ts
+import { connectWorker } from '@reactodia/worker-proxy/protocol';
+
+// Define a class with methods which return Promise
+// with results to the worker caller side:
+class Calculator {
+    constructor(options: {
+        precision: number;
+    }) { ... }
+
+    add(a: number, b: number): Promise<number> {
+        ...
+    }
+}
+
+// Setup communication protocol with the worker caller 
+connectWorker(Calculator);
+```
+
+`using-calc.ts` module:
+```ts
+import { refCountedWorker } from '@reactodia/worker-proxy';
+import type { Calculator } from './calc.worker.ts';
+
+// Create a ref-counted worker definition
+const calcWorker = refCountedWorker<typeof Calculator>(
+  () => new Worker(
+    new URL('./calc.worker.js', import.meta.url)
+  ),
+  [{ calcPrecision: 2 }]
+);
+
+// Get a proxy and connect to the worker
+const calculator = calcWorker.acquire();
+// Call a worker method
+const sum1 = await calculator.add(2, 3);
+const sum2 = await calculator.add(10, 20);
+// Release the worker when its no longer needed
+calcWorker.release();
+```
+
+### Using Web Workers from a React component
+
+Although the library does not expose a built-in hook to use workers from a React component to avoid dependencies, it should be trivial to define a simple hook like this:
+
+```ts
+import type { RefCountedWorker } from '@reactodia/worker-proxy';
+
+function useWorker<T>(worker: RefCountedWorker<T>): T {
+    React.useEffect(() => {
+        worker.acquire();
+        return () => worker.release();
+    }, [worker]);
+    return worker.getProxy();
+}
+```
+
+Then it can be used in a component this way:
+
+```ts
+import { refCountedWorker } from '@reactodia/worker-proxy';
+import type { Calculator } from './calc.worker.ts';
+
+const CalcWorker = refCountedWorker<typeof Calculator>(
+  () => new Worker(
+    new URL('./calc.worker.js', import.meta.url)
+  ),
+  [{ calcPrecision: 2 }]
+);
+
+function MyComponent() {
+    const calculator = useWorker(CalcWorker);
+    ...
+}
+```
+
+## API
+
+The library has the following exports:
+
+### Main entry point `@reactodia/worker-proxy`
+
+#### `refCountedWorker<T>(factory, constructorArgs)` function
+
+Creates a ref-counted [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker) definition which automatically manages the lifecycle of a worker (create, connect, disconnect) and exposes it behind a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object implementing the same interface as the mapped worker.
+
+Parameters:
+* `factory`: `() => Worker` - callback to construct a Worker instance on demand
+* `constructorArgs`: `ConstructorParameters<T>` - constructor arguments to initialize the worker with its connected class constructor before any other calls
+
+Returns: `RefCountedWorker<WorkerObject<InstanceType<T>>>`
+
+#### `RefCountedWorker<T>` interface
+
+```ts
+export interface RefCountedWorker<T> {
+    /**
+     * Returns an lifecycle state of the connected Worker instance.
+     */
+    getState(): 'disconnected' | 'blocked' | 'ready' | 'connecting' | 'connected';
+    /**
+     * Returns a cached Proxy instance to transparently call the worker logic.
+     *
+     * Important: calls to the proxy will be resolved only after `acquire()`
+     * method have been called at least once.
+     */
+    getProxy(): T;
+    /**
+     * Increments a ref-count and connects to the worker if needed.
+     */
+    acquire(): T;
+    /**
+     * Decrements a ref-count and disconnects from the worker if ref-count is zero.
+     */
+    release(): void;
+}
+```
+
+### Protocol entry point `@reactodia/worker-proxy/protocol`
+
+#### `connectWorker(factory: WorkerConstructor)` function
+
+Establishes a specific connection protocol between the callee (worker) and external caller (which created a worker via `new Worker(...)` constructor).
+
+The protocol assumes the worker exposes an RPC-like interface via a `class` where every public method returns a `Promise`. This interface is transparently mapped from the caller to the worker via messages.
+
+The communication protocol is defined in terms of messages to be sent with `postMessage()` and received with `onmessage` from withing the worker.
+The worker expect the first message to be a `WorkerCall` with `method === "constructor"` to create an instance of the connected class.
+
+Here are the exported definitions for the message types:
+
+```ts
+export interface WorkerCall {
+    readonly type: 'call';
+    readonly id: number;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+
+export interface WorkerCallSuccess {
+    readonly type: 'success';
+    readonly id: number;
+    readonly result: unknown;
+}
+
+export interface WorkerCallError {
+    readonly type: 'error';
+    readonly id: number;
+    readonly error: unknown;
+}
+```
+
+## License
+
+The library is distributed under MIT license, see [LICENSE](./LICENSE).