wirejs-web-worker 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+## ⚠️ Experimental Alpha ⚠️
+
+An experimental utility for type safe Web Workers.
+
+```
+npm i wirejs-web-worker
+```
+
+For example, create code you want to run as a worker in a `my-worker` sub-package:
+
+```
+src/
+	my-app-code.ts
+
+my-worker/
+	src/index.ts    <-- here
+	package.json
+
+package.json
+```
+
+### `my-worker/src/index.ts`
+
+Let's just count up to *some number* and report on progress every 50ms.
+
+```typescript
+import { SingleWorker } from 'wirejs-web-worker';
+
+export const worker = SingleWorker({
+	async count(
+		upTo: number,
+		options?: { tick?: (pct: number) => void }
+	) {
+		let lastUpdate = new Date();
+		options?.tick?.(0);
+		let c = 0;
+		for (let i = 0; i < upTo; i++) {
+			let current = new Date();
+			if (current.getTime() - lastUpdate.getTime() > 50) {
+				options?.tick?.(i / upTo);
+				lastUpdate = current;
+			}
+			c++;
+		}
+		options?.tick?.(1);
+		return c;
+	}
+});
+```
+
+### `src/my-app-code.ts`
+
+The page will just need to import `worker` from the `my-worker` sub-package and call `worker.count()`. 
+
+```typescript
+import { html, hydrate, text } from 'wirejs-dom/v2';
+import { Main } from '../layouts/main.js';
+import { worker } from 'my-worker';
+
+async function App() {
+	return html`<div id='app'>
+		<h4>Web Worker Demo</h4>
+		<div>${text('status', '...')}</div>
+		<div>Web Worker output: ${text('output', '...')}</div>
+	</div>`.onadd(async self => {
+		console.log('starting web worker');
+		self.data.output = (await worker.count(256_000_000, {
+			tick: pct => self.data.status = `${Math.floor(pct * 100)} % complete.`
+		})).toString();
+	});
+}
+
+export async function generate() {
+	return Main({
+		pageTitle: 'Welcome!',
+		content: await App()
+	})
+}
+
+hydrate('app', App as any);
+```
+
+In this example, we pass a function to the worker (the `tick` callback). An adapter is injected by `wirejs-web-worker` *during the build* that takes care of creating the necessary lookup tables, message passing, and garbage cleanup jobs on both ends of the pipe.
+
+(The overarching framework for this example yet another experimental project. 😅)
+
+### `my-worker/package.json`
+
+To make this work, the worker sub-package must built using the `wirejs-web-worker` build script, and the sub-package exports must be explicitly set:
+
+```json
+{
+	"name": "my-worker",
+	"private": true,
+	"type": "module",
+	"exports": {
+		"types": "./src/index.ts",
+		"default": "./dist/index.js"
+	},
+	"scripts": {
+		"prebuild": "wirejs-web-worker-build",
+		"start": "wirejs-scripts watch src npm run prebuild"
+	}
+}
+```
+
+This example builds during the `prebuild` stage to ensure it is ready for the main package's `build` step &mdash; assuming we're using vanilla workspaces and don't have luxury of dependency-aware build sequencing.
+
+### `package.json`
+
+An example top-level `package.json` using vanilla workspaces:
+
+```json
+{
+	"name": "sample-app",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"workspaces": [
+		"src",
+		"web-worker"
+	],
+	"dependencies": {
+		"wirejs-dom": "^1.0.41",
+		"wirejs-web-worker": "^1.0.0"
+	},
+	"devDependencies": {
+		"wirejs-scripts": "^3.0.101",
+		"typescript": "^5.7.3"
+	},
+	"scripts": {
+		"prebuild": "npm run prebuild --workspaces --if-present",
+		"prestart": "npm run prestart --workspaces --if-present",
+		"start": "wirejs-scripts ws-run-parallel start",
+		"build": "npm run build --workspaces --if-present"
+	}
+}
+```
+
+In this example, `build` and `prebuild` are run across all workspaces. `src` is treated as a sub-package that contains its own `build` steps. `start` runs all workspace `start` scripts in parallel. All of this ensure the web worker is built and ready when the `src` code needs it.
+
+Your `package.json` will probably look different, especially if you're using a build management tool that builds in a dependency-aware manner.
+
+Either way, the end result is magic. 🪄
+
+## ⚠️ Known Limitations ⚠️
+
+1. Only a single export is supported per worker package.
+1. Worker pools are not yet supported.
+1. Type-validation on workers is limited.
+1. Behavior is undefined when exporting non-worker from a worker package.
+1. No built-in mechanism for killing a worker.
+
+In addition to these known limitations, this code has only been lightly tested and is still experimental.

package/build.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import { build } from 'esbuild';
+import { randomUUID } from 'crypto';
+import { cwd } from 'process';
+
+const clientContainer = /* typescript */ `
+import { proxyWorker } from 'wirejs-web-worker';
+const workerBundle = "__WORKER_CODE__";
+export const worker = proxyWorker(workerBundle);
+`;
+
+async function main() {
+	const PREBUILD_NAME = `./dist/client.${randomUUID()}.ts`;
+
+	const serverBuild = await build({
+		entryPoints: ['./src/index.ts'],
+		format: 'iife',
+		bundle: true,
+		write: false
+	});
+
+	const clientSource = clientContainer
+		.replace(
+			'"__WORKER_CODE__"',
+			JSON.stringify(serverBuild.outputFiles[0].text)
+		)
+	;
+
+	await fs.promises.mkdir(`${cwd()}/dist`, { recursive: true });
+	await fs.promises.writeFile(PREBUILD_NAME, clientSource);
+
+	await build({
+		entryPoints: [PREBUILD_NAME],
+		format: 'esm',
+		bundle: true,
+		outfile: './dist/index.js'
+	});
+
+	await fs.promises.unlink(PREBUILD_NAME);
+}
+
+main();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export declare function messageHandler(send: typeof postMessage, callables: any): (message: any) => Promise<void>;
+export declare function proxyWorker(workerBundle: string): any;
+export declare function SingleWorker<const T extends Record<string, (...args: any) => Promise<any> | void>>(callables: T): T;

package/dist/index.js

@@ -0,0 +1,220 @@
+function isRequest(o) {
+    return (typeof o === 'object'
+        && o.__type === 'request');
+}
+;
+function isCallbackRequest(o) {
+    return (typeof o === 'object'
+        && o.__type === 'callbackRequest');
+}
+;
+function isCallbackDescriptor(o) {
+    return (typeof o === 'object'
+        && o.__type === 'callback');
+}
+;
+function isResponse(o) {
+    return (typeof o === 'object'
+        && o.__type === 'response');
+}
+;
+function isGarbageCollection(o) {
+    return (typeof o === 'object'
+        && o.__type === 'garbage');
+}
+;
+/**
+ * Callbacks the local context has exposed to the remote context.
+ *
+ * When the remote context detects that it no longer needs one of these,
+ * it will send a message letting this side of the wire know to remove the
+ * callback so it can be garbage collected. (Assuming nothing else is also
+ * using it!)
+ */
+const callbackFunctions = new Map();
+/**
+ * Callbacks the remote context has exposed to the local context.
+ *
+ * The functions these descriptor ID's map to are ingested directly by the
+ * concerned code in the local scope. Hence, when local code no longer needs
+ * the callback, the referenced function can be garbage collected. We can
+ * then detect which descriptors are no longer needed and inform the other
+ * side of the wire that it can delete the functions.
+ */
+const callbackDescriptors = new Map();
+/**
+ * Requests the local context has made to the remote context.
+ */
+const requests = new Map();
+/**
+ * Creates a callable function for a callback that lives on the other
+ * side of the wire.
+ *
+ * @param callback
+ * @returns
+ */
+function createCallbackFunction(callback) {
+    const f = (...args) => {
+        return new Promise((resolve, reject) => {
+            const requestId = crypto.randomUUID();
+            requests.set(requestId, { resolve, reject });
+            postMessage({
+                __type: 'callbackRequest',
+                requestId,
+                args: dehydrateCallbacks(args),
+                target: callback.callbackId,
+            });
+        });
+    };
+    callbackDescriptors.set(callback.callbackId, new WeakRef(f));
+    return f;
+}
+/**
+ * Creates a callback descriptor to send over the wire to the other side,
+ * indicating to the other side that there is an invocable function waiting
+ * for it here.
+ *
+ * @param f
+ */
+function createCallbackDescriptor(f) {
+    const callbackId = crypto.randomUUID();
+    callbackFunctions.set(callbackId, f);
+    return {
+        __type: 'callback',
+        callbackId
+    };
+}
+/**
+ * Copies the object, replacing callbacks descriptors with callback functions
+ * that know how to invoke them over the wire.
+ *
+ * @param o
+ * @returns
+ */
+function hydrateCallbacks(o) {
+    if (isCallbackDescriptor(o)) {
+        return createCallbackFunction(o);
+    }
+    else if (!o) {
+        return o;
+    }
+    else if (Array.isArray(o)) {
+        const copied = [];
+        for (let i = 0; i < o.length; i++) {
+            copied[i] = hydrateCallbacks(o[i]);
+        }
+        return copied;
+    }
+    else if (typeof o === 'object') {
+        const copied = {};
+        for (const [k, v] of Object.entries(o)) {
+            copied[k] = hydrateCallbacks(v);
+        }
+        return copied;
+    }
+    return o;
+}
+/**
+ * Copies the object, replacing callbacks with descriptors.
+ *
+ * @param o
+ */
+function dehydrateCallbacks(o) {
+    if (typeof o === 'function') {
+        return createCallbackDescriptor(o);
+    }
+    else if (!o) {
+        return o;
+    }
+    else if (Array.isArray(o)) {
+        const copied = [];
+        for (let i = 0; i < o.length; i++) {
+            copied[i] = dehydrateCallbacks(o[i]);
+        }
+        return copied;
+    }
+    else if (typeof o === 'object') {
+        const copied = {};
+        for (const [k, v] of Object.entries(o)) {
+            copied[k] = dehydrateCallbacks(v);
+        }
+        return copied;
+    }
+    return o;
+}
+let garbageCollectionLoop = undefined;
+function ensureGarbageCollectionIsRunning(send) {
+    garbageCollectionLoop = garbageCollectionLoop ?? setInterval(() => {
+        for (const callbackId of Object.keys(callbackDescriptors)) {
+            const ref = callbackDescriptors.get(callbackId);
+            if (!ref.deref) {
+                send({ __type: 'garbage', callbackId });
+            }
+        }
+    }, 1000);
+}
+async function handleRequest(f, requestId, args, respond) {
+    try {
+        const result = dehydrateCallbacks(await f(...hydrateCallbacks(args || [])));
+        respond({ __type: 'response', requestId, result });
+    }
+    catch (error) {
+        respond({ __type: 'response', requestId, error });
+    }
+}
+;
+export function messageHandler(send, callables) {
+    ensureGarbageCollectionIsRunning(send);
+    return async (message) => {
+        const { data } = message;
+        if (isRequest(data)) {
+            handleRequest(callables[data.method], data.requestId, data.args, send);
+        }
+        else if (isCallbackRequest(data)) {
+            handleRequest(callbackFunctions.get(data.target), data.requestId, data.args, send);
+        }
+        else if (isResponse(data)) {
+            const request = requests.get(data.requestId);
+            if (!request)
+                return;
+            const hydratedResult = hydrateCallbacks(data.result);
+            requests.delete(data.requestId);
+            data.error ? request.reject(data.error) : request.resolve(hydratedResult);
+        }
+        else if (isGarbageCollection(data)) {
+            callbackFunctions.delete(data.callbackId);
+        }
+    };
+}
+;
+function buildWorker(workerBundle) {
+    const worker = new Worker(URL.createObjectURL(new Blob([workerBundle], { type: 'text/javascript' })));
+    worker.onmessage = messageHandler((m) => worker?.postMessage(m), {});
+    return worker;
+}
+export function proxyWorker(workerBundle) {
+    let worker;
+    return new Proxy({}, {
+        get(_target, method) {
+            worker = worker ?? buildWorker(workerBundle);
+            return (...args) => {
+                return new Promise((resolve, reject) => {
+                    const requestId = crypto.randomUUID();
+                    requests.set(requestId, { resolve, reject });
+                    worker.postMessage({
+                        __type: 'request',
+                        method,
+                        requestId,
+                        args: dehydrateCallbacks(args)
+                    });
+                });
+            };
+        }
+    });
+}
+;
+export function SingleWorker(callables) {
+    self.onmessage = messageHandler(postMessage, callables);
+    return callables;
+}
+;

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "wirejs-web-worker",
+	"version": "1.0.0",
+	"type": "module",
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"default": "./dist/index.js"
+	},
+	"bin": {
+		"wirejs-web-worker-build": "./build.js"
+	},
+	"scripts": {
+		"build": "tsc"
+	},
+	"devDependencies": {
+		"typescript": "*"
+	},
+	"files": [
+		"package.json",
+		"dist/*",
+		"build.js",
+		"README.md"
+	]
+}