uniworker 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,164 @@
+# UniWorker
+
+A lightweight, type-safe library for communicating with [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) via proxied function calls.
+
+UniWorker lets you call functions inside a Web Worker as if they were local, abstracting away `postMessage` / `addEventListener` boilerplate entirely. It's inspired by [Comlink](https://github.com/GoogleChromeLabs/comlink), while being simpler, more limited in scope, and significantly faster.
+
+## Features
+
+- **Fully typed** — proxy methods preserve the original function signatures
+- **Three calling modes** — fire-and-forget, awaited, and proxy-creating
+- **Transferable support** — transfer `ArrayBuffer`, `OffscreenCanvas`, `ImageBitmap`, etc.
+- **Mock proxy** — run the same code synchronously on the main thread for testing or fallback
+- **Zero dependencies**
+- **~1 KB** minified + gzipped
+
+## Install
+
+```bash
+npm install uniworker
+```
+
+## Quick Start
+
+### 1. Define worker code (`my-worker.ts`)
+
+```ts
+import { expose } from "uniworker";
+
+expose((name: string) => {
+  // The initializer function runs once when init() is called.
+  // It returns an object whose methods become available on the proxy.
+  return {
+    greet(greeting: string) {
+      return `${greeting}, ${name}!`;
+    },
+    add(a: number, b: number) {
+      return a + b;
+    },
+  };
+});
+```
+
+### 2. Use from the main thread (`main.ts`)
+
+```ts
+import { init, WorkerProxy } from "uniworker";
+
+// Type describing the initializer function (matches the expose() argument)
+type MyWorkerInit = (name: string) => {
+  greet(greeting: string): string;
+  add(a: number, b: number): number;
+};
+
+const worker = new Worker(new URL("./my-worker.ts", import.meta.url), {
+  type: "module",
+});
+
+const proxy = await init<MyWorkerInit>({ worker }, "World");
+
+// Fire-and-forget (returns void, does not wait)
+proxy.greet("Hello");
+
+// Await the return value
+const message = await proxy.await.greet("Hello");
+console.log(message); // "Hello, World!"
+
+const sum = await proxy.await.add(2, 3);
+console.log(sum); // 5
+```
+
+## API
+
+### `expose(initializer)`
+
+Call inside a Web Worker script. `initializer` is a function that receives arguments passed from `init()` and returns an object whose methods are exposed to the main thread.
+
+```ts
+expose((canvas: OffscreenCanvas) => {
+  const ctx = canvas.getContext("2d")!;
+  return {
+    drawRect(x: number, y: number, w: number, h: number) {
+      ctx.fillRect(x, y, w, h);
+    },
+  };
+});
+```
+
+### `init<T>(options, ...args): Promise<WorkerProxy<ReturnType<T>>>`
+
+Call on the main thread to initialize the worker and get a typed proxy.
+
+**Options:**
+| Option | Type | Description |
+|----------|------|-------------|
+| `worker` | `Worker` | The Web Worker instance |
+| `transfer` | `Transfer` | Optional array of transferable objects to send with the init call |
+
+```ts
+const canvas = document.createElement("canvas");
+const offscreen = canvas.transferControlToOffscreen();
+
+const proxy = await init<MyWorkerInit>(
+  { worker, transfer: [offscreen] },
+  offscreen
+);
+```
+
+### `WorkerProxy<T>`
+
+The proxy object returned by `init()`. It provides three ways to call each exposed method:
+
+| Mode | Syntax | Returns | Description |
+|------|--------|---------|-------------|
+| Fire-and-forget | `proxy.method(args)` | `void` | Fastest. Sends message, doesn't wait for a result. |
+| Awaited | `proxy.await.method(args)` | `Promise<T>` | Sends message and resolves with the return value. |
+| Create proxy | `proxy.createProxy.method(args)` | `Promise<WorkerProxy<T>>` | Like `await`, but the return value is itself wrapped in a new proxy. Useful for factory functions that return objects with their own methods. |
+
+#### Transferring data
+
+Use `.transfer()` before calling a method to transfer ownership of objects:
+
+```ts
+proxy.transfer([imageBitmap]).drawImage(imageBitmap);
+
+// Also works with await
+const result = await proxy.transfer([buffer]).await.process(buffer);
+```
+
+### `createMockProxy<T>(obj): WorkerProxy<T>`
+
+Creates a synchronous mock proxy that wraps a plain object with the same interface as `WorkerProxy`. Useful for:
+
+- **Testing** without spinning up real workers
+- **Fallback** when Web Workers are unavailable
+- **Isomorphic code** that should work with or without a worker
+
+```ts
+import { createMockProxy, WorkerProxy } from "uniworker";
+
+const impl = {
+  greet(name: string) {
+    return `Hello, ${name}!`;
+  },
+};
+
+const proxy = createMockProxy(impl);
+
+// Same interface as worker proxy
+proxy.greet("World");                          // fire-and-forget (sync)
+const msg = await proxy.await.greet("World");  // "Hello, World!"
+```
+
+## How It Works
+
+1. **`expose()`** registers the initializer and listens for messages in the worker.
+2. **`init()`** sends the init arguments to the worker, which runs the initializer and returns a mapping of method names to internal IDs.
+3. The main-thread proxy translates method calls into `postMessage` calls using these IDs.
+4. For `await` calls, a return handler is registered and resolved when the worker posts back the result.
+
+The protocol is a simple positional array format (`[fnID, returnID, proxy, ...args]`), avoiding serialization overhead of structured objects.
+
+## License
+
+[MIT](./LICENSE) © Whimsical, Inc.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export type Transfer = (OffscreenCanvas | Transferable)[];
+type Fn = (...args: any) => any;
+type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+type PromisifyFn<T extends Fn> = (...args: Parameters<T>) => Promisify<ReturnType<T>>;
+type AsyncProperty<T> = T extends Fn ? PromisifyFn<T> : undefined;
+type Async<T> = {
+    [P in keyof T]: AsyncProperty<T[P]>;
+};
+type Voidify<T> = T extends Fn ? (...args: Parameters<T>) => void : void;
+type NoReturn<T> = {
+    [P in keyof T]: Voidify<T[P]>;
+};
+type InitFn = (...args: any) => object;
+type WorkerInstance<T> = T;
+type WorkerProxyAsync<T> = Async<WorkerInstance<T>>;
+type WorkerProxySendOnly<T> = NoReturn<WorkerInstance<T>>;
+type CreateProxyPromisifyInitFn<T extends InitFn> = (...args: Parameters<T>) => Promisify<WorkerProxy<ReturnType<T>>>;
+type CreateProxyAsyncProperty<T> = T extends InitFn ? CreateProxyPromisifyInitFn<T> : undefined;
+type CreateProxyAsync<T> = {
+    [P in keyof T]: CreateProxyAsyncProperty<T[P]>;
+};
+type CreateProxy<T> = CreateProxyAsync<WorkerInstance<T>>;
+type WorkerProxyWithAwaitAndCreateProxy<T> = WorkerProxySendOnly<T> & {
+    await: WorkerProxyAsync<T>;
+    createProxy: CreateProxy<T>;
+};
+export type WorkerProxy<T extends object> = WorkerProxyWithAwaitAndCreateProxy<T> & {
+    transfer(transfers: (OffscreenCanvas | Transferable)[]): WorkerProxyWithAwaitAndCreateProxy<T>;
+};
+export declare function expose(workerInitializer: (...args: any[]) => any): void;
+export declare function init<T extends InitFn>({ worker, transfer, }: {
+    worker: Worker;
+    transfer?: Transfer;
+}, ...args: Parameters<T>): Promise<WorkerProxy<ReturnType<T>>>;
+export declare function createMockProxy<T extends {
+    [k: string]: any;
+}>(obj: T): WorkerProxy<T>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,133 @@
+const InitWorkerID = 0;
+export function expose(workerInitializer) {
+    let nextFnID = InitWorkerID + 1;
+    const fns = new Map();
+    function registerFn(fn) {
+        const id = nextFnID++;
+        fns.set(id, fn);
+        return id;
+    }
+    function createProxyMappings(obj) {
+        return Object.keys(obj)
+            .filter((key) => typeof obj[key] === "function")
+            .map((key) => {
+            const fn = obj[key];
+            const id = registerFn(fn);
+            return [key, id];
+        });
+    }
+    fns.set(InitWorkerID, workerInitializer);
+    addEventListener("message", (ev) => {
+        if (!ev || !ev.data) {
+            return;
+        }
+        const [id, returnID, proxy, ...args] = ev.data;
+        const fn = fns.get(id);
+        if (fn == null) {
+            console.warn("Function is not registered:", ...ev.data);
+            return;
+        }
+        const returnValue = fn(...args);
+        if (returnID != null) {
+            // If the return value is a promise, resolve it before posting the op return. For non promise values
+            // resolve will be a synchronous operation.
+            Promise.resolve(returnValue).then((returnValue) => {
+                if (proxy) {
+                    returnValue = createProxyMappings(returnValue);
+                }
+                const returnMessage = [returnID, returnValue];
+                postMessage(returnMessage);
+            });
+        }
+    });
+}
+function createProxy(mappings, adapter) {
+    const client = {
+        await: {},
+        createProxy: {},
+    };
+    function registerFn([fnName, fnID]) {
+        client[fnName] = (...args) => adapter.callWorkerFn(fnID, args);
+        client.await[fnName] = (...args) => adapter.callWorkerFnAwait(fnID, false, args);
+        client.createProxy[fnName] = (...args) => adapter.callWorkerFnAwait(fnID, true, args);
+    }
+    mappings.forEach(registerFn);
+    client.transfer = (transfer) => {
+        adapter.setCurrentTransfer(transfer);
+        return client;
+    };
+    return client;
+}
+export async function init({ worker, transfer, }, ...args) {
+    let nextReturnID = 0;
+    const returnHandlers = new Map();
+    let adapter = new (class {
+        constructor() {
+            // Initialize with transfer to be used for init function:
+            this.currentTransfer = transfer || [];
+        }
+        setCurrentTransfer(transfer) {
+            this.currentTransfer.length = 0;
+            if (transfer) {
+                this.currentTransfer.push(...transfer);
+            }
+        }
+        callWorkerFn(id, args) {
+            const message = [id, null, false, ...args];
+            worker.postMessage(message, this.currentTransfer);
+            this.setCurrentTransfer(null);
+        }
+        callWorkerFnAwait(id, proxy, args) {
+            return new Promise((resolve) => {
+                const returnID = nextReturnID++;
+                returnHandlers.set(returnID, (returnValue) => {
+                    if (proxy) {
+                        returnValue = createProxy(returnValue, this);
+                    }
+                    resolve(returnValue);
+                });
+                const message = [id, returnID, proxy, ...args];
+                worker.postMessage(message, this.currentTransfer);
+                this.setCurrentTransfer(null);
+            });
+        }
+    })();
+    worker.addEventListener("message", (ev) => {
+        if (!ev || !ev.data || !Array.isArray(ev.data)) {
+            return;
+        }
+        const [returnID, returnValue] = ev.data;
+        const returnHandler = returnHandlers.get(returnID);
+        if (returnHandler == null) {
+            console.warn("Return handler is not registered for:", ...ev.data);
+            return;
+        }
+        returnHandlers.delete(returnID);
+        returnHandler(returnValue);
+    });
+    return await adapter.callWorkerFnAwait(InitWorkerID, true, args);
+}
+export function createMockProxy(obj) {
+    const proxy = new (class {
+        constructor() {
+            this.await = {};
+            this.createProxy = {};
+        }
+        transfer(_) {
+            return this;
+        }
+    })();
+    Object.keys(obj)
+        .filter((key) => typeof obj[key] === "function")
+        .forEach((key) => {
+        proxy[key] = obj[key];
+        proxy.await[key] = function (...args) {
+            return Promise.resolve(obj[key](...args));
+        };
+        proxy.createProxy[key] = function (...args) {
+            return Promise.resolve(createMockProxy(obj[key](...args)));
+        };
+    });
+    return proxy;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "uniworker",
+  "version": "1.0.0",
+  "description": "A lightweight, type-safe library for communicating with Web Workers via proxied function calls",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "web-worker",
+    "worker",
+    "proxy",
+    "typed",
+    "comlink",
+    "postmessage",
+    "transferable",
+    "offscreencanvas"
+  ],
+  "author": "Whimsical, Inc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WhimsicalCode/uniworker.git"
+  },
+  "homepage": "https://github.com/WhimsicalCode/uniworker#readme",
+  "bugs": {
+    "url": "https://github.com/WhimsicalCode/uniworker/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,203 @@
+export type Transfer = (OffscreenCanvas | Transferable)[];
+
+type Fn = (...args: any) => any;
+type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+type PromisifyFn<T extends Fn> = (...args: Parameters<T>) => Promisify<ReturnType<T>>;
+type AsyncProperty<T> = T extends Fn ? PromisifyFn<T> : undefined;
+type Async<T> = { [P in keyof T]: AsyncProperty<T[P]> };
+type Voidify<T> = T extends Fn ? (...args: Parameters<T>) => void : void;
+type NoReturn<T> = { [P in keyof T]: Voidify<T[P]> };
+
+type InitFn = (...args: any) => object;
+
+type WorkerInstance<T> = T;
+type WorkerProxyAsync<T> = Async<WorkerInstance<T>>;
+type WorkerProxySendOnly<T> = NoReturn<WorkerInstance<T>>;
+
+type CreateProxyPromisifyInitFn<T extends InitFn> = (...args: Parameters<T>) => Promisify<WorkerProxy<ReturnType<T>>>;
+type CreateProxyAsyncProperty<T> = T extends InitFn ? CreateProxyPromisifyInitFn<T> : undefined;
+type CreateProxyAsync<T> = { [P in keyof T]: CreateProxyAsyncProperty<T[P]> };
+type CreateProxy<T> = CreateProxyAsync<WorkerInstance<T>>;
+
+type WorkerProxyWithAwaitAndCreateProxy<T> = WorkerProxySendOnly<T> & {
+  await: WorkerProxyAsync<T>;
+  createProxy: CreateProxy<T>;
+};
+
+export type WorkerProxy<T extends object> = WorkerProxyWithAwaitAndCreateProxy<T> & {
+  transfer(transfers: (OffscreenCanvas | Transferable)[]): WorkerProxyWithAwaitAndCreateProxy<T>;
+};
+
+type FnID = number;
+type FnReturnID = number;
+type FnCallMessage = [id: FnID, returnID: FnReturnID | null, proxy: boolean, ...args: any[]];
+type FnReturnMessage = [id: FnReturnID, value: any];
+type FnReturnHandler = (value: any) => void;
+type FnName = string;
+type ProxyMappings = [FnName, FnID][];
+
+const InitWorkerID: FnID = 0;
+
+export function expose(workerInitializer: (...args: any[]) => any) {
+  let nextFnID = InitWorkerID + 1;
+  const fns = new Map<FnID, Fn>();
+
+  function registerFn(fn: Fn) {
+    const id = nextFnID++;
+    fns.set(id, fn);
+    return id;
+  }
+
+  function createProxyMappings(obj: { [k: string]: any }): ProxyMappings {
+    return Object.keys(obj)
+      .filter((key) => typeof obj[key] === "function")
+      .map((key) => {
+        const fn: Fn = obj[key];
+        const id = registerFn(fn);
+        return [key, id];
+      });
+  }
+
+  fns.set(InitWorkerID, workerInitializer);
+
+  addEventListener("message", (ev: MessageEvent) => {
+    if (!ev || !ev.data) {
+      return;
+    }
+    const [id, returnID, proxy, ...args] = ev.data as FnCallMessage;
+    const fn = fns.get(id);
+    if (fn == null) {
+      console.warn("Function is not registered:", ...ev.data);
+      return;
+    }
+    const returnValue = fn(...args);
+    if (returnID != null) {
+      // If the return value is a promise, resolve it before posting the op return. For non promise values
+      // resolve will be a synchronous operation.
+      Promise.resolve(returnValue).then((returnValue) => {
+        if (proxy) {
+          returnValue = createProxyMappings(returnValue);
+        }
+        const returnMessage: FnReturnMessage = [returnID, returnValue];
+        postMessage(returnMessage);
+      });
+    }
+  });
+}
+
+interface WorkerAdapter {
+  setCurrentTransfer(transfer: Transfer | null): void;
+
+  callWorkerFn(id: FnID, args: any[]): void;
+
+  callWorkerFnAwait(id: FnID, proxy: boolean, args: any[]): Promise<any>;
+}
+
+function createProxy(mappings: ProxyMappings, adapter: WorkerAdapter) {
+  const client: { [k: string]: any } = {
+    await: {},
+    createProxy: {},
+  };
+
+  function registerFn([fnName, fnID]: [FnName, FnID]) {
+    client[fnName] = (...args: any[]) => adapter.callWorkerFn(fnID, args);
+    client.await[fnName] = (...args: any[]) => adapter.callWorkerFnAwait(fnID, false, args);
+    client.createProxy[fnName] = (...args: any[]) => adapter.callWorkerFnAwait(fnID, true, args);
+  }
+
+  mappings.forEach(registerFn);
+
+  client.transfer = (transfer: Transfer) => {
+    adapter.setCurrentTransfer(transfer);
+    return client;
+  };
+
+  return client;
+}
+
+export async function init<T extends InitFn>(
+  {
+    worker,
+    transfer,
+  }: {
+    worker: Worker;
+    transfer?: Transfer;
+  },
+  ...args: Parameters<T>
+): Promise<WorkerProxy<ReturnType<T>>> {
+  let nextReturnID = 0;
+  const returnHandlers = new Map<FnReturnID, FnReturnHandler>();
+
+  let adapter: WorkerAdapter = new (class {
+    // Initialize with transfer to be used for init function:
+    currentTransfer = transfer || [];
+
+    setCurrentTransfer(transfer: Transfer | null): void {
+      this.currentTransfer.length = 0;
+      if (transfer) {
+        this.currentTransfer.push(...transfer);
+      }
+    }
+
+    callWorkerFn(id: FnID, args: any[]): void {
+      const message: FnCallMessage = [id, null, false, ...args];
+      worker.postMessage(message, this.currentTransfer);
+      this.setCurrentTransfer(null);
+    }
+
+    callWorkerFnAwait(id: FnID, proxy: boolean, args: any[]): Promise<any> {
+      return new Promise((resolve) => {
+        const returnID = nextReturnID++;
+        returnHandlers.set(returnID, (returnValue) => {
+          if (proxy) {
+            returnValue = createProxy(returnValue, this);
+          }
+          resolve(returnValue);
+        });
+        const message: FnCallMessage = [id, returnID, proxy, ...args];
+        worker.postMessage(message, this.currentTransfer);
+        this.setCurrentTransfer(null);
+      });
+    }
+  })();
+
+  worker.addEventListener("message", (ev: MessageEvent) => {
+    if (!ev || !ev.data || !Array.isArray(ev.data)) {
+      return;
+    }
+    const [returnID, returnValue] = ev.data as FnReturnMessage;
+    const returnHandler = returnHandlers.get(returnID);
+    if (returnHandler == null) {
+      console.warn("Return handler is not registered for:", ...ev.data);
+      return;
+    }
+    returnHandlers.delete(returnID);
+    returnHandler(returnValue);
+  });
+
+  return await adapter.callWorkerFnAwait(InitWorkerID, true, args);
+}
+
+export function createMockProxy<T extends { [k: string]: any }>(obj: T): WorkerProxy<T> {
+  const proxy: { [k: string]: any } = new (class {
+    transfer(_: any) {
+      return this;
+    }
+    await: { [k: string]: any } = {};
+    createProxy: { [k: string]: any } = {};
+  })();
+
+  Object.keys(obj)
+    .filter((key) => typeof obj[key] === "function")
+    .forEach((key) => {
+      proxy[key] = obj[key];
+      proxy.await[key] = function (...args: any[]) {
+        return Promise.resolve(obj[key](...args));
+      };
+      proxy.createProxy[key] = function (...args: any[]) {
+        return Promise.resolve(createMockProxy(obj[key](...args)));
+      };
+    });
+
+  return proxy as WorkerProxy<T>;
+}