@atolljs/node 0.1.3 → 0.1.5

package/dist/http.d.ts

@@ -0,0 +1,212 @@
+import { Server as HttpServer, type IncomingMessage, type RequestListener } from 'node:http';
+import { type Server as NetServer, type Socket } from 'node:net';
+/** Wire id a worker uses to announce an internally-listening HTTP port. */
+export declare const HTTP_PORT = "HTTP_PORT";
+export declare const SOCKET_TRANSFER_SUPPORTED: boolean;
+/** Anything that exposes its workers — WorkerPool is the usual source. */
+export interface WorkerSource {
+    readonly workers: readonly Worker[];
+}
+export interface HttpClusterOptions {
+    /** The pool whose workers serve connections (respawns picked up on read). */
+    pool: WorkerSource;
+    /** Port to listen on. Ignored when `server` is provided. */
+    port?: number;
+    /** Listen host. Ignored when `server` is provided. */
+    host?: string;
+    /**
+     * Bring your own listener — MUST be created with `pauseOnConnect: true`
+     * (e.g. `net.createServer({ pauseOnConnect: true })`) or the main thread
+     * may consume request bytes before the socket is transferred.
+     */
+    server?: NetServer;
+    /**
+     * Connection → worker selection. Defaults to round-robin. Receives the
+     * fresh `pool.workers` snapshot each call, so respawns participate.
+     * Returning undefined destroys the socket. {@link stickyByAddress} is a
+     * ready-made sticky implementation for multi-connection session flows.
+     */
+    route?: (socket: Socket, workers: readonly Worker[]) => Worker | undefined;
+    /** Called once the server is listening. */
+    onListen?: (server: NetServer) => void;
+}
+export interface HttpCluster {
+    /** The listening TCP server (the user's `server` when provided). */
+    server: NetServer;
+    /** Stop accepting; in-flight transferred connections stay with workers. */
+    close(): Promise<void>;
+}
+/**
+ * Main thread: cluster a pool behind one listener — accept connections and
+ * hand each socket to a pool worker. Pairs with the worker-side
+ * {@link serveHttp}:
+ *
+ *   const pool = createNodePool({ worker: () => new Worker(new URL('./api.worker.js', import.meta.url)), sharedMemory, poolSize: 'auto' });
+ *   const cluster = createHttpCluster({ pool, port: 8080 }); // null below Node 26
+ *
+ * Sockets transfer BEFORE any bytes are read — the worker's http.Server does
+ * all parsing. HTTPS termination is not supported here (the TLS handshake
+ * would run on the accept thread); terminate TLS upstream or serve plain
+ * HTTP behind a proxy.
+ *
+ * Returns `null` on runtimes without socket transfer (Node < 26 — see
+ * {@link SOCKET_TRANSFER_SUPPORTED}) after logging a one-line notice, so
+ * callers can write the cluster unconditionally and degrade to gateway-only
+ * behavior without wrapping the call in capability checks.
+ */
+export declare function createHttpCluster(options: HttpClusterOptions): HttpCluster | null;
+/**
+ * Sticky connection routing for {@link createHttpCluster}: every connection
+ * from the same client address lands on the same worker — rendezvous
+ * (highest-random-weight) hashing over `key + slot`, so removing a worker
+ * only remaps ITS clients instead of reshuffling the whole pool.
+ *
+ * A transferred socket pins its whole life to one worker, so a bare
+ * WebSocket connection never needs this — stickiness matters for
+ * multi-connection session flows: socket.io's polling→upgrade sequence,
+ * or an HTTP request that must precede/follow a WS connection on the same
+ * worker. The acceptor can't read headers or cookies, so client address
+ * (nginx ip_hash style) is the strongest key available — supply `key` to
+ * mix in more (e.g. localPort for multi-listener setups).
+ *
+ *   createHttpCluster({ pool, port: 8080, route: stickyByAddress() });
+ */
+export declare function stickyByAddress(key?: (socket: Socket) => string): (socket: Socket, workers: readonly Worker[]) => Worker | undefined;
+export interface ServeHttpOptions {
+    /**
+     * Listen on an internal TCP port and announce it to the parent thread via
+     * a `{ type: HTTP_PORT, port }` message — for the gateway topology where
+     * the main thread parses HTTP and proxies to worker-owned listeners
+     * (works on any Node version, unlike socket transfer). `0` = ephemeral.
+     * The server still accepts transferred sockets either way — `listen` only
+     * adds the internal gateway port.
+     */
+    listen?: number;
+    /** Listen host; defaults to '127.0.0.1' so worker ports stay internal. */
+    host?: string;
+}
+/**
+ * Worker side: serve HTTP with an http.Server owned by this worker. Call it
+ * once in the worker entry, after '@atolljs/node/shim':
+ *
+ *   import '@atolljs/node/shim';
+ *   import { serveHttp } from '@atolljs/node/http';
+ *   import express from 'express';
+ *
+ *   const app = express();          // any (req, res) handler works —
+ *   app.get('/api', (_q, r) => …);  // express/koa .callback()/fastify.server
+ *   serveHttp(app);                 // sockets transferred by createHttpCluster
+ *   serveHttp(app, { listen: 0 });  // internal listener for routeHttpGateway
+ *
+ * Accepts a RequestListener (wrapped in a new http.Server), an existing
+ * http.Server (e.g. `fastify().server` after ready()), or
+ * `{ handler }` / `{ server }`. A no-op on the main thread.
+ */
+export declare function serveHttp(target: RequestListener | HttpServer | {
+    handler?: RequestListener;
+    server?: HttpServer;
+}, options?: ServeHttpOptions): HttpServer;
+export interface WorkerHttpPorts {
+    /** Announced internal listener ports, keyed by worker instance (live map). */
+    readonly ports: ReadonlyMap<Worker, number>;
+    /**
+     * Attach to any new workers in `source.workers` and re-query ones that
+     * haven't announced — call it before resolving routes so respawns (and
+     * announcements that raced the initial attach) are picked up.
+     */
+    refresh(): void;
+    /** Detach all message listeners. */
+    dispose(): void;
+}
+/**
+ * Collect HTTP_PORT announcements from a pool's workers — for the
+ * gateway/proxy topology where workers listen on internal TCP ports.
+ * Announcements are a handshake, not a broadcast: workers that haven't
+ * announced get an HTTP_PORT_QUERY so trackers attached late still learn
+ * their ports.
+ */
+export declare function workerHttpPorts(source: WorkerSource): WorkerHttpPorts;
+export interface ProxyToWorkerOptions {
+    /** The pool whose workers announce internal HTTP ports. */
+    pool: WorkerSource;
+    /** Announcement tracker — from {@link workerHttpPorts} (refreshed per request). */
+    tracker: WorkerHttpPorts;
+    /** Which worker serves this route — a slot index into the live
+     *  `pool.workers` snapshot, or a selector (e.g. round-robin). */
+    worker: number | ((workers: readonly Worker[]) => Worker | undefined);
+    /**
+     * Prefix prepended to `req.url` before forwarding. When mounted via
+     * `app.use('/prefix', mw)` Express has already stripped the mount — set
+     * `to: '/prefix'` to restore it for the worker's routes.
+     */
+    to?: string;
+}
+/**
+ * A mountable RequestListener that proxies to one pool worker's internal
+ * listener — the piece that lets a host framework (Nest, Express, …) house
+ * part of its API inside workers without giving up its own server:
+ *
+ *   const tracker = workerHttpPorts(pool);
+ *   app.use('/api/housed', proxyToWorker({
+ *     pool, tracker, to: '/api/housed',
+ *     worker: (w) => w[i++ % w.length],   // or 0 to pin a slot
+ *   }));
+ */
+export declare function proxyToWorker(options: ProxyToWorkerOptions): RequestListener;
+/**
+ * The upgrade-side sibling of {@link proxyToWorker}: middleware never sees
+ * WebSocket handshakes (Node emits 'upgrade' on the server, bypassing
+ * request listeners), so attach the returned listener to your server:
+ *
+ *   const tracker = workerHttpPorts(pool);
+ *   app.use('/api/housed', proxyToWorker({ pool, tracker, to: '/api/housed', worker }));
+ *   app.getHttpServer().on('upgrade',
+ *     proxyUpgradeToWorker({ pool, tracker, worker })); // full URL — `to` not needed
+ *
+ * Unlike the middleware, an 'upgrade' listener receives the ORIGINAL url
+ * (nothing stripped it), so `to` is a rewrite prefix rather than a mount
+ * restore — usually omit it.
+ */
+export declare function proxyUpgradeToWorker(options: ProxyToWorkerOptions): (req: IncomingMessage, socket: Socket, head: Buffer) => void;
+export interface GatewayRoute {
+    /** URL prefix that owns this route, e.g. '/api/a/'. */
+    prefix: string;
+    /** Which pool worker serves the prefix — a slot index into the live
+     *  `pool.workers` snapshot, or a selector. Respawns are picked up. */
+    worker: number | ((workers: readonly Worker[]) => Worker | undefined);
+    /** Rewrite target prefix — the worker sees `to + url.slice(prefix.length)`.
+     *  Defaults to '/', so `/api/a/x` arrives at the worker as `/x`. */
+    to?: string;
+}
+export interface RouteHttpGatewayOptions {
+    /** The pool whose workers announce internal HTTP ports. */
+    pool: WorkerSource;
+    port?: number;
+    host?: string;
+    /** BYO http.Server (the gateway attaches its request handler). */
+    server?: HttpServer;
+    routes?: GatewayRoute[];
+    /** Everything unmatched runs on the main thread; defaults to 404. */
+    handler?: RequestListener;
+    /**
+     * Fallback for unmatched Upgrade (WebSocket) handshakes — e.g. attach your
+     * own ws server's handler to keep WS routes on the main thread. When
+     * omitted the socket is destroyed, unless another 'upgrade' listener is
+     * registered on the server (then it's left to that listener).
+     */
+    onUpgrade?: (req: IncomingMessage, socket: Socket, head: Buffer) => void;
+    onListen?: (server: HttpServer) => void;
+}
+export interface HttpGateway {
+    server: HttpServer;
+    /** Announced internal listener ports, keyed by worker instance (live map). */
+    ports: ReadonlyMap<Worker, number>;
+    close(): Promise<void>;
+}
+/** Main thread: parse HTTP once and proxy matched prefixes to worker-owned
+ *  listeners — the mixed topology: some routes in worker A, some in worker
+ *  B, the rest served right here. Upgrade (WebSocket) handshakes match the
+ *  same prefix table and are TUNNELED — the handshake is replayed to the
+ *  worker's listener and the two sockets spliced, so frames flow end-to-end
+ *  without the main thread touching them again. */
+export declare function routeHttpGateway(options: RouteHttpGatewayOptions): HttpGateway;

package/dist/http.js

@@ -0,0 +1,261 @@
+// src/http.ts
+import {
+  createServer as createHttpServer,
+  request as httpRequest,
+  Server as HttpServer
+} from "node:http";
+import {
+  connect as netConnect,
+  createServer as createNetServer
+} from "node:net";
+import { isMainThread, parentPort } from "node:worker_threads";
+var HTTP_CONNECTION = "HTTP_CONNECTION";
+var HTTP_PORT = "HTTP_PORT";
+var HTTP_PORT_QUERY = "HTTP_PORT_QUERY";
+var NODE_MAJOR = Number(process.versions.node.split(".")[0]);
+var SOCKET_TRANSFER_SUPPORTED = NODE_MAJOR >= 26;
+function assertSocketTransferSupported() {
+  if (!SOCKET_TRANSFER_SUPPORTED) {
+    throw new Error(
+      `serveHttp (without { listen }) requires Node.js >= 26 for net.Socket transfer across worker_threads (found ${process.versions.node}).`
+    );
+  }
+}
+function createHttpCluster(options) {
+  if (!SOCKET_TRANSFER_SUPPORTED) {
+    console.warn(
+      `[atoll] createHttpCluster skipped \u2014 net.Socket transfer requires Node.js >= 26 (found ${process.versions.node})`
+    );
+    return null;
+  }
+  let cursor = 0;
+  const route = options.route ?? ((_, workers) => workers.length === 0 ? void 0 : workers[cursor++ % workers.length]);
+  const server = options.server ?? createNetServer({ pauseOnConnect: true });
+  server.on("connection", (socket) => {
+    const worker = route(socket, options.pool.workers);
+    if (!worker) {
+      socket.destroy();
+      return;
+    }
+    try {
+      worker.postMessage({ type: HTTP_CONNECTION, socket }, [
+        socket
+      ]);
+    } catch (err) {
+      socket.destroy();
+      server.emit("error", err);
+    }
+  });
+  if (!options.server) {
+    server.listen(options.port ?? 8080, options.host, () => options.onListen?.(server));
+  } else {
+    options.onListen?.(server);
+  }
+  return {
+    server,
+    close: () => new Promise(
+      (resolve, reject) => server.close((err) => err ? reject(err) : resolve())
+    )
+  };
+}
+var fnv1a = (s) => {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+};
+function stickyByAddress(key = (s) => s.remoteAddress ?? "") {
+  return (socket, workers) => {
+    if (workers.length === 0) return void 0;
+    const k = key(socket);
+    let best;
+    let bestScore = -1;
+    workers.forEach((w, i) => {
+      const score = fnv1a(`${k}#${i}`);
+      if (score > bestScore) {
+        bestScore = score;
+        best = w;
+      }
+    });
+    return best;
+  };
+}
+function serveHttp(target, options) {
+  const server = target instanceof HttpServer ? target : typeof target === "function" ? createHttpServer(target) : target.server ?? createHttpServer(target.handler);
+  if (isMainThread || !parentPort) return server;
+  if (options?.listen === void 0) assertSocketTransferSupported();
+  let announcedPort;
+  parentPort.on("message", (msg) => {
+    if (msg?.type === HTTP_CONNECTION && msg.socket) {
+      server.emit("connection", msg.socket);
+      msg.socket.resume();
+    } else if (msg?.type === HTTP_PORT_QUERY && announcedPort !== void 0) {
+      parentPort.postMessage({ type: HTTP_PORT, port: announcedPort });
+    }
+  });
+  if (options?.listen !== void 0) {
+    server.listen(options.listen, options.host ?? "127.0.0.1", () => {
+      const addr = server.address();
+      announcedPort = typeof addr === "object" && addr ? addr.port : 0;
+      parentPort.postMessage({ type: HTTP_PORT, port: announcedPort });
+    });
+  }
+  return server;
+}
+function workerHttpPorts(source) {
+  const ports = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Map();
+  const refresh = () => {
+    for (const w of source.workers) {
+      if (!listeners.has(w)) {
+        const listener = (e) => {
+          const d = e.data;
+          if (d?.type === HTTP_PORT && typeof d.port === "number") ports.set(w, d.port);
+        };
+        listeners.set(w, listener);
+        w.addEventListener("message", listener);
+      }
+      if (!ports.has(w)) {
+        try {
+          w.postMessage({ type: HTTP_PORT_QUERY });
+        } catch {
+        }
+      }
+    }
+  };
+  refresh();
+  return {
+    ports,
+    refresh,
+    dispose: () => {
+      for (const [w, l] of listeners) w.removeEventListener("message", l);
+      listeners.clear();
+    }
+  };
+}
+var forwardToPort = (req, res, port, path) => {
+  const upstream = httpRequest(
+    {
+      host: "127.0.0.1",
+      port,
+      method: req.method,
+      path: path.startsWith("/") ? path : `/${path}`,
+      headers: { ...req.headers, host: `127.0.0.1:${port}` }
+    },
+    (ures) => {
+      res.writeHead(ures.statusCode ?? 502, ures.headers);
+      ures.pipe(res);
+    }
+  );
+  upstream.on("error", () => {
+    if (!res.headersSent) res.writeHead(502);
+    res.end();
+  });
+  req.pipe(upstream);
+};
+function proxyToWorker(options) {
+  return (req, res) => {
+    const port = resolveWorkerPort(options);
+    if (port === void 0) {
+      res.writeHead(503, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "worker not listening yet" }));
+      return;
+    }
+    forwardToPort(req, res, port, (options.to ?? "") + (req.url ?? "/"));
+  };
+}
+var resolveWorkerPort = (options) => {
+  options.tracker.refresh();
+  const workers = options.pool.workers;
+  const worker = typeof options.worker === "number" ? workers[options.worker] : options.worker(workers);
+  return worker ? options.tracker.ports.get(worker) : void 0;
+};
+var tunnelUpgradeToPort = (req, socket, head, port, path) => {
+  const upstream = netConnect({ host: "127.0.0.1", port }, () => {
+    const lines = [`${req.method} ${path} HTTP/${req.httpVersion}`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const key = req.rawHeaders[i];
+      const value = key.toLowerCase() === "host" ? `127.0.0.1:${port}` : req.rawHeaders[i + 1];
+      lines.push(`${key}: ${value}`);
+    }
+    upstream.write(lines.join("\r\n") + "\r\n\r\n");
+    if (head?.length) upstream.write(head);
+    socket.pipe(upstream).pipe(socket);
+  });
+  upstream.on("error", () => socket.destroy());
+  socket.on("error", () => upstream.destroy());
+};
+function proxyUpgradeToWorker(options) {
+  return (req, socket, head) => {
+    const port = resolveWorkerPort(options);
+    if (port === void 0) {
+      socket.destroy();
+      return;
+    }
+    tunnelUpgradeToPort(req, socket, head, port, (options.to ?? "") + (req.url ?? "/"));
+  };
+}
+function routeHttpGateway(options) {
+  const tracker = workerHttpPorts(options.pool);
+  const fallback = options.handler ?? ((_req, res) => res.writeHead(404).end());
+  const server = options.server ?? createHttpServer();
+  const resolveRoute = (url) => {
+    tracker.refresh();
+    const workers = options.pool.workers;
+    const route = options.routes?.find((r) => url.startsWith(r.prefix));
+    const worker = route ? typeof route.worker === "number" ? workers[route.worker] : route.worker(workers) : void 0;
+    return { route, port: worker ? tracker.ports.get(worker) : void 0 };
+  };
+  server.on("request", (req, res) => {
+    const url = req.url ?? "/";
+    const { route, port } = resolveRoute(url);
+    if (!route) {
+      fallback(req, res);
+      return;
+    }
+    if (port === void 0) {
+      res.writeHead(503, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "worker not listening yet" }));
+      return;
+    }
+    forwardToPort(req, res, port, (route.to ?? "/") + url.slice(route.prefix.length));
+  });
+  server.on("upgrade", (req, socket, head) => {
+    const url = req.url ?? "/";
+    const { route, port } = resolveRoute(url);
+    if (!route || port === void 0) {
+      if (options.onUpgrade) {
+        options.onUpgrade(req, socket, head);
+      } else if (server.listenerCount("upgrade") <= 1) {
+        socket.destroy();
+      }
+      return;
+    }
+    tunnelUpgradeToPort(req, socket, head, port, (route.to ?? "/") + url.slice(route.prefix.length));
+  });
+  if (!options.server) {
+    server.listen(options.port ?? 8080, options.host, () => options.onListen?.(server));
+  } else {
+    options.onListen?.(server);
+  }
+  return {
+    server,
+    ports: tracker.ports,
+    close: () => new Promise(
+      (resolve, reject) => server.close((err) => err ? reject(err) : resolve())
+    )
+  };
+}
+export {
+  HTTP_PORT,
+  SOCKET_TRANSFER_SUPPORTED,
+  createHttpCluster,
+  proxyToWorker,
+  proxyUpgradeToWorker,
+  routeHttpGateway,
+  serveHttp,
+  stickyByAddress,
+  workerHttpPorts
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { NodeWorkerAdapter, createNodeWorker } from './worker.js';
+export type { WorkerErrorEvent } from './worker.js';
+export { createNodePool } from './pool.js';
+export type { NodePoolConfig } from './pool.js';
+export { bindSharedBuffer, withSharedBuffer } from './sharedBuffer.js';

package/dist/index.js

@@ -0,0 +1,127 @@
+import {
+  WorkerPool,
+  bindSharedMemories
+} from "./chunk-EEME4TDI.js";
+
+// src/worker.ts
+import { Worker as NodeWorker } from "node:worker_threads";
+var NodeWorkerAdapter = class {
+  constructor(worker) {
+    this.worker = worker;
+  }
+  worker;
+  listeners = /* @__PURE__ */ new Map();
+  postMessage(message, transferList) {
+    if (transferList === void 0) {
+      this.worker.postMessage(message);
+    } else {
+      this.worker.postMessage(message, transferList);
+    }
+  }
+  terminate() {
+    void this.worker.terminate();
+  }
+  addEventListener(type, handler) {
+    let map = this.listeners.get(handler);
+    if (!map) this.listeners.set(handler, map = /* @__PURE__ */ new Map());
+    if (type === "message") {
+      const wrapped = (data) => handler({ data });
+      map.set("message", wrapped);
+      this.worker.on("message", wrapped);
+    } else {
+      const onError = (error) => handler({ type: "error", message: error.message, error });
+      const onExit = (code) => {
+        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, handler) {
+    const map = this.listeners.get(handler);
+    if (!map) return;
+    const events = 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);
+  }
+};
+function createNodeWorker(source, options) {
+  const worker = source instanceof NodeWorker ? source : new NodeWorker(source, options);
+  return new NodeWorkerAdapter(worker);
+}
+
+// src/pool.ts
+import { Worker as NodeWorker2 } from "node:worker_threads";
+var toWorker = (w) => w instanceof NodeWorker2 ? createNodeWorker(w) : w;
+function createNodePool(config) {
+  const { workerFile, worker, createWorker, ...rest } = config;
+  const file = workerFile ?? (typeof worker === "function" ? void 0 : worker);
+  const factory = createWorker ?? (typeof worker === "function" ? () => toWorker(worker()) : void 0);
+  return new WorkerPool({
+    ...rest,
+    createWorker: factory ?? (() => {
+      if (!file) {
+        throw new Error("createNodePool requires worker, workerFile or createWorker.");
+      }
+      return createNodeWorker(file);
+    })
+  });
+}
+
+// src/sharedBuffer.ts
+import { isMainThread, parentPort, workerData } from "node:worker_threads";
+var SHARED_BUFFER = "SHARED_BUFFER";
+function withSharedBuffer(spawn, buffer) {
+  return () => {
+    const worker = spawn();
+    const shared = typeof buffer === "function" ? buffer() : buffer;
+    worker.postMessage({ type: SHARED_BUFFER, buffer: shared });
+    return worker;
+  };
+}
+function bindSharedBuffer(timeoutMs = 1e4) {
+  const fromWorkerData = workerData?.buffer;
+  if (fromWorkerData) {
+    bindSharedMemories(fromWorkerData);
+    return Promise.resolve(fromWorkerData);
+  }
+  if (isMainThread || !parentPort) {
+    return Promise.reject(new Error("bindSharedBuffer() must be called inside a worker"));
+  }
+  const port = parentPort;
+  return new Promise((resolve, reject) => {
+    const onMessage = (msg) => {
+      if (msg?.type !== SHARED_BUFFER) return;
+      clearTimeout(timer);
+      port.off("message", onMessage);
+      if (!msg.buffer) {
+        reject(new Error("bindSharedBuffer(): the producing side sent an empty buffer"));
+        return;
+      }
+      bindSharedMemories(msg.buffer);
+      resolve(msg.buffer);
+    };
+    const timer = setTimeout(() => {
+      port.off("message", onMessage);
+      reject(new Error(`bindSharedBuffer(): no shared buffer arrived within ${timeoutMs}ms`));
+    }, timeoutMs);
+    port.on("message", onMessage);
+  });
+}
+export {
+  NodeWorkerAdapter,
+  bindSharedBuffer,
+  createNodePool,
+  createNodeWorker,
+  withSharedBuffer
+};

package/dist/pool.d.ts

@@ -0,0 +1,32 @@
+import { Worker as NodeWorker } from 'node:worker_threads';
+import { WorkerPool, type SharedSpec, type TaskMap, type WorkerPoolConfig } from '@atolljs/core';
+/**
+ * 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;
+}
+/**
+ * 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 declare function createNodePool<S extends SharedSpec, T extends TaskMap>(config: NodePoolConfig<S, T>): WorkerPool<S, T>;