@atolljs/node 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @atolljs/node
+
+`node:worker_threads` runtime adapter for `@atolljs/core` — lets `WorkerPool`
+and `connectWorker` run on Node's Worker (an EventEmitter) instead of the DOM
+surface they expect.
+
+- `createNodePool({ worker, sharedMemory?, tasks?, … })` — `WorkerPool` with the
+  adapter baked in. The `worker:` factory may return a `node:worker_threads.Worker`
+  directly, so `new Worker(new URL('./x.worker.ts', import.meta.url))` stays
+  bundler-detectable.
+- `createNodeWorker(nodeWorker)` / `NodeWorkerAdapter` — wraps a Node Worker for
+  `connectWorker` or a hand-built `WorkerPool`.
+- `@atolljs/node/shim` — worker-side entry shim; imports first and binds
+  `self = parentPort` before `defineWorker`'s bootstrap evaluates.
+
+`SharedArrayBuffer` works in Node with no headers — cross-origin isolation is a
+browser-only requirement.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@atolljs/node",
+  "version": "0.1.0",
+  "description": "Node runtime adapter — node:worker_threads pools, no framework",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./shim": "./src/shim.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@atolljs/core": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwhenry3/atolljs",
+    "directory": "packages/node"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// Node runtime adapter for the Atoll — node:worker_threads pools without a
+// framework. Worker entries must import '@atolljs/node/shim' first.
+export { NodeWorkerAdapter, createNodeWorker } from './worker';
+export type { WorkerErrorEvent } from './worker';
+export { createNodePool } from './pool';
+export type { NodePoolConfig } from './pool';

package/src/pool.ts

@@ -0,0 +1,64 @@
+import { Worker as NodeWorker } from 'node:worker_threads';
+import {
+  WorkerPool,
+  type SharedSpec,
+  type TaskMap,
+  type WorkerPoolConfig,
+} from '@atolljs/core';
+import { createNodeWorker } from './worker';
+
+/**
+ * WorkerPoolConfig for Node: workerUrl is replaced by a worker spec — a
+ * bundled file path, a `new Worker(new URL('./x.worker.ts', import.meta.url))`
+ * factory (webpack/esbuild detect the literal and emit the worker chunk), or
+ * an explicit createWorker for full control.
+ */
+export interface NodePoolConfig<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap>
+  extends Omit<WorkerPoolConfig<S, T>, 'workerUrl' | 'createWorker'> {
+  /** Bundled worker entry (e.g. dist/incidents.worker.js). */
+  workerFile?: string;
+  /**
+   * Worker spec — the preferred form. A path/URL behaves like workerFile; a
+   * factory may return a node:worker_threads Worker (auto-adapted) or a
+   * DOM-style Worker (used as-is):
+   *
+   *   worker: () => new Worker(new URL('./x.worker.ts', import.meta.url))
+   */
+  worker?: string | URL | (() => Worker | NodeWorker);
+  /** Worker factory; defaults to the node:worker_threads adapter. */
+  createWorker?: () => Worker;
+}
+
+/** Adapts whatever the user spawned into the DOM Worker surface the pool needs. */
+const toWorker = (w: Worker | NodeWorker): Worker =>
+  w instanceof NodeWorker ? createNodeWorker(w) : w;
+
+/**
+ * Creates a WorkerPool backed by node:worker_threads. Identical to
+ * `new WorkerPool` except workers default to `new NodeWorker(workerFile)`
+ * wrapped in the EventTarget adapter — usable from any Node program, no
+ * framework required:
+ *
+ *   const pool = createNodePool({ workerFile, sharedMemory, tasks });
+ *   const pool = createNodePool({ worker: () => new Worker(new URL('./w.worker.ts', import.meta.url)), ... });
+ */
+export function createNodePool<S extends SharedSpec, T extends TaskMap>(
+  config: NodePoolConfig<S, T>,
+): WorkerPool<S, T> {
+  const { workerFile, worker, createWorker, ...rest } = config;
+  const file = workerFile ?? (typeof worker === 'function' ? undefined : worker);
+  const factory =
+    createWorker ??
+    (typeof worker === 'function' ? () => toWorker(worker()) : undefined);
+  return new WorkerPool({
+    ...rest,
+    createWorker:
+      factory ??
+      (() => {
+        if (!file) {
+          throw new Error('createNodePool requires worker, workerFile or createWorker.');
+        }
+        return createNodeWorker(file);
+      }),
+  });
+}

package/src/shim.ts

@@ -0,0 +1,11 @@
+// Import this FIRST in a Node worker entry, before workerBootstrap.
+// node:worker_threads has no `self` global — the SDK's worker bootstrap
+// expects a DOM-style `self` carrying onmessage/postMessage, so we bind the
+// worker's parent MessagePort as `self` before the bootstrap module
+// evaluates. ESM/CJS import order guarantees this runs first.
+import { isMainThread, parentPort } from 'node:worker_threads';
+
+// Guarded so an accidental main-thread import is a no-op (parentPort is null).
+if (!isMainThread && parentPort) {
+  (globalThis as { self?: unknown }).self = parentPort;
+}

package/src/worker.ts

@@ -0,0 +1,95 @@
+import { Worker as NodeWorker } from 'node:worker_threads';
+
+export interface WorkerErrorEvent {
+  type: 'error';
+  message: string;
+  error?: unknown;
+}
+type EventHandler = (event: any) => void;
+type NodeEvent = 'message' | 'error' | 'exit';
+
+/**
+ * Adapts node:worker_threads.Worker to the DOM Worker surface that
+ * WorkerPool expects (`postMessage`, `terminate`, add/removeEventListener
+ * with `event.data`). Node's Worker is an EventEmitter — 'message' delivers
+ * the value directly, so handlers get wrapped and tracked by identity so
+ * removeEventListener can detach the exact listener the pool installed.
+ *
+ * 'error' listeners additionally observe a Node 'exit' with code ≠ 0 —
+ * surfaced as `{ type: 'error', message }` so the pool's crash/respawn
+ * path sees silent exits too. `exit(0)` is a clean shutdown, not an error.
+ */
+export class NodeWorkerAdapter {
+  private readonly listeners = new Map<EventHandler, Map<NodeEvent, (...args: any[]) => void>>();
+
+  constructor(private readonly worker: NodeWorker) {}
+
+  postMessage(message: unknown): void {
+    this.worker.postMessage(message);
+  }
+
+  terminate(): void {
+    void this.worker.terminate();
+  }
+
+  addEventListener(type: 'message', handler: (event: { data: unknown }) => void): void;
+  addEventListener(type: 'error', handler: (event: WorkerErrorEvent) => void): void;
+  addEventListener(type: 'message' | 'error', handler: EventHandler): void {
+    let map = this.listeners.get(handler);
+    if (!map) this.listeners.set(handler, (map = new Map()));
+    if (type === 'message') {
+      const wrapped = (data: unknown) => handler({ data });
+      map.set('message', wrapped);
+      this.worker.on('message', wrapped);
+    } else {
+      const onError = (error: Error) =>
+        handler({ type: 'error', message: error.message, error });
+      const onExit = (code: number) => {
+        if (code !== 0) {
+          handler({ type: 'error', message: `worker exited with code ${code}` });
+        }
+      };
+      map.set('error', onError);
+      map.set('exit', onExit);
+      this.worker.on('error', onError);
+      this.worker.on('exit', onExit);
+    }
+  }
+
+  removeEventListener(type: 'message', handler: (event: { data: unknown }) => void): void;
+  removeEventListener(type: 'error', handler: (event: WorkerErrorEvent) => void): void;
+  removeEventListener(type: 'message' | 'error', handler: EventHandler): void {
+    const map = this.listeners.get(handler);
+    if (!map) return;
+    const events: NodeEvent[] = type === 'message' ? ['message'] : ['error', 'exit'];
+    for (const ev of events) {
+      const wrapped = map.get(ev);
+      if (wrapped) {
+        this.worker.off(ev, wrapped);
+        map.delete(ev);
+      }
+    }
+    if (map.size === 0) this.listeners.delete(handler);
+  }
+}
+
+/**
+ * Wraps node:worker_threads.Worker creation. Pass a file/URL to spawn, or an
+ * already-constructed Worker to adapt — the latter enables the
+ * bundler-detectable form in pool configs:
+ *
+ *   createWorker: () => createNodeWorker(
+ *     new NodeWorker(new URL('./my.worker.ts', import.meta.url))
+ *   )
+ *
+ * webpack compiles the referenced entry into its own chunk and rewrites the
+ * URL to the emitted file — the config points at the TS source, never at a
+ * dist filename.
+ */
+export function createNodeWorker(
+  source: string | URL | NodeWorker,
+  options?: ConstructorParameters<typeof NodeWorker>[1],
+): Worker {
+  const worker = source instanceof NodeWorker ? source : new NodeWorker(source, options);
+  return new NodeWorkerAdapter(worker) as unknown as Worker;
+}