@atolljs/node 0.1.3 → 0.1.5

package/dist/redis.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Redis persistence for shared-memory contracts — the shared-memory analog
+ * of NestJS's Redis WebSocket adapter. The SharedArrayBuffer stays the
+ * synchronous source of truth on this thread (the contract's read/write
+ * surface can't be async); the adapter mirrors field regions to a Redis hash
+ * so state survives restarts, and optionally replicates writes across
+ * processes through a pub/sub channel.
+ *
+ * Layout in Redis:
+ *   {key}:{name}              hash — member = field path, value = base64 bytes
+ *   {key}:{name}:ops          channel — { src, path, b64 } per dirty field
+ *
+ * Change detection is the version-counter block every write already bumps
+ * (Atomics), polled on `syncIntervalMs` — no instrumentation of the hot
+ * write path. Remote applies bump the local version too, so `observe()`/
+ * waitAsync watchers fire exactly as they do for local writes.
+ *
+ * The client surface is intentionally minimal (base64 strings, hset/hgetall)
+ * — ioredis and node-redis both satisfy it directly; `publish` is only used
+ * when replication is enabled.
+ */
+import { type SharedMemory, type SharedSpec } from '@atolljs/core';
+/** The hash commands the adapter needs — ioredis and node-redis both fit. */
+export interface RedisHashClient {
+    hset(key: string, field: string, value: string): Promise<unknown>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    publish?(channel: string, message: string): Promise<unknown>;
+}
+/**
+ * Normalized pub/sub surface — node-redis's `client.subscribe(ch, listener)`
+ * matches directly; wrap an ioredis connection with `ioRedisSubscriber`.
+ */
+export interface RedisSubscriber {
+    subscribe(channel: string, onMessage: (channel: string, message: string) => void): unknown;
+    unsubscribe?(channel: string): unknown;
+}
+/** Wrap an ioredis connection in the normalized subscriber surface. */
+export declare const ioRedisSubscriber: (client: {
+    subscribe(channel: string): unknown;
+    unsubscribe?(channel: string): unknown;
+    on(event: 'message', cb: (channel: string, message: string) => void): unknown;
+}) => RedisSubscriber;
+export interface RedisMemoryAdapterOptions {
+    client: RedisHashClient;
+    /** Hash key root — the contract lives at `${key}:${name}`. Default 'atoll:mem'. */
+    key?: string;
+    /** Contract namespace under the key root. Default 'default'. */
+    name?: string;
+    /** Version-diff poll cadence — dirty fields flush at most this often. Default 100ms. */
+    syncIntervalMs?: number;
+    /** Restrict persistence to a subset of field paths. */
+    fields?: string[];
+    /**
+     * A second Redis connection subscribed to `${key}:${name}:ops` — enables
+     * cross-process replication. Each instance publishes its dirty fields;
+     * subscribers apply the bytes into their own buffer and bump the local
+     * version counter so local observers fire. Last write wins per field.
+     */
+    subscriber?: RedisSubscriber;
+    /** Echo guard — defaults to pid + random. Override for deterministic tests. */
+    instanceId?: string;
+}
+export interface RedisMemoryPersistence {
+    /** Resolves when initial restore + subscriber attach complete. */
+    readonly ready: Promise<void>;
+    /** Flush dirty fields now — also runs automatically on the poll interval. */
+    flush(): Promise<number>;
+    /** Final flush, unsubscribe, and stop the poll timer. */
+    stop(): Promise<void>;
+}
+/**
+ * Attach Redis persistence to a bound (or soon-bound) shared-memory contract.
+ * `ready` resolves once state has been restored INTO the local buffer —
+ * workers that bind afterwards see the restored state, and version bumps
+ * wake observers on this thread.
+ */
+export declare function persistSharedMemory<S extends SharedSpec>(memory: SharedMemory<S>, options: RedisMemoryAdapterOptions): RedisMemoryPersistence;
+/**
+ * Pool-config form — the `persistence` option shape for `createNodePool` /
+ * `AtollModule.registerPool`. Nest's `app.useWebSocketAdapter()` analog:
+ *
+ *   persistence: redisMemoryAdapter(redis, { name: 'incidents' })
+ */
+export declare function redisMemoryAdapter(client: RedisHashClient, options?: Omit<RedisMemoryAdapterOptions, 'client'>): (memory: SharedMemory) => RedisMemoryPersistence;

package/dist/redis.js

@@ -0,0 +1,136 @@
+import {
+  scoped
+} from "./chunk-EEME4TDI.js";
+
+// src/redis.ts
+var log = scoped("redis-mem");
+var ioRedisSubscriber = (client) => ({
+  subscribe: (channel, onMessage) => {
+    client.on("message", (c, m) => {
+      if (c === channel) onMessage(c, m);
+    });
+    return client.subscribe(channel);
+  },
+  unsubscribe: (channel) => client.unsubscribe?.(channel)
+});
+function persistSharedMemory(memory, options) {
+  const { client, subscriber } = options;
+  const key = `${options.key ?? "atoll:mem"}:${options.name ?? "default"}`;
+  const channel = `${key}:ops`;
+  const intervalMs = options.syncIntervalMs ?? 100;
+  const instanceId = options.instanceId ?? `${process.pid}:${Math.random().toString(36).slice(2, 8)}`;
+  let buffer;
+  let regions = [];
+  const lastSeen = /* @__PURE__ */ new Map();
+  let timer;
+  let stopped = false;
+  let flushing = Promise.resolve(0);
+  const b64encode = (u8) => Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength).toString("base64");
+  const b64decode = (s) => new Uint8Array(Buffer.from(s, "base64"));
+  const fieldRegion = (path) => regions.find((r) => r.path === path);
+  const applyRemote = (path, b64) => {
+    const region = fieldRegion(path);
+    if (!region) return;
+    const bytes = b64decode(b64);
+    if (bytes.byteLength !== region.byteLength) {
+      log.warn(`"${path}": remote field is ${bytes.byteLength}B but the contract reserves ${region.byteLength}B \u2014 skipped`);
+      return;
+    }
+    new Uint8Array(buffer, region.byteOffset, region.byteLength).set(bytes);
+    if (region.version) {
+      Atomics.add(region.version.view, region.version.index, 1);
+      Atomics.notify(region.version.view, region.version.index);
+      lastSeen.set(path, Atomics.load(region.version.view, region.version.index));
+    }
+  };
+  const flush = async () => {
+    if (stopped) return 0;
+    let dirty = 0;
+    for (const region of regions) {
+      const current = region.version ? Atomics.load(region.version.view, region.version.index) : 0;
+      if (lastSeen.get(region.path) === current) continue;
+      lastSeen.set(region.path, current);
+      dirty++;
+      const b64 = b64encode(new Uint8Array(buffer, region.byteOffset, region.byteLength));
+      await client.hset(key, region.path, b64);
+      if (subscriber) {
+        await client.publish?.(
+          channel,
+          JSON.stringify({ src: instanceId, path: region.path, b64 })
+        );
+      }
+    }
+    return dirty;
+  };
+  const restore = async () => {
+    const all = await client.hgetall(key) ?? {};
+    let restored = 0;
+    for (const [path, b64] of Object.entries(all)) {
+      applyRemote(path, b64);
+      restored++;
+    }
+    if (restored) log.info(`restored ${restored} field(s) from ${key}`);
+  };
+  const ready = new Promise((resolve, reject) => {
+    memory.onBound(() => {
+      buffer = memory.buffer;
+      regions = memory.fields().filter((f) => !options.fields || options.fields.includes(f.path)).map((f) => ({ ...f, version: memory.connector(f.path)._version }));
+      for (const r of regions) {
+        if (r.version) {
+          lastSeen.set(r.path, Atomics.load(r.version.view, r.version.index));
+        }
+      }
+      (async () => {
+        await restore();
+        if (subscriber) {
+          await subscriber.subscribe(channel, (_ch, message) => {
+            try {
+              const msg = JSON.parse(message);
+              if (msg.src === instanceId || !msg.path || !msg.b64) return;
+              applyRemote(msg.path, msg.b64);
+            } catch (e) {
+              log.warn("malformed replication message", e);
+            }
+          });
+        }
+        if (stopped) return;
+        timer = setInterval(() => {
+          flushing = flushing.then(flush).catch((e) => {
+            log.warn("flush failed", e);
+            return 0;
+          });
+        }, intervalMs);
+        timer.unref?.();
+      })().then(resolve, reject);
+    });
+  });
+  return {
+    ready,
+    // Serialize manual flushes behind the interval's — concurrent hset on
+    // the same members is pointless churn.
+    flush: () => flushing = flushing.then(flush).catch(() => 0),
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      if (timer) clearInterval(timer);
+      await subscriber?.unsubscribe?.(channel);
+      await flushing.catch(() => 0);
+      stopped = false;
+      try {
+        await flush();
+      } catch (e) {
+        log.warn("final flush failed", e);
+      } finally {
+        stopped = true;
+      }
+    }
+  };
+}
+function redisMemoryAdapter(client, options = {}) {
+  return (memory) => persistSharedMemory(memory, { ...options, client });
+}
+export {
+  ioRedisSubscriber,
+  persistSharedMemory,
+  redisMemoryAdapter
+};

package/dist/sharedBuffer.d.ts

@@ -0,0 +1,16 @@
+import type { Worker as NodeWorker } from 'node:worker_threads';
+/**
+ * Main thread: wraps a worker factory so each spawned worker receives a
+ * shared buffer over its message channel. The buffer may be a thunk —
+ * evaluated per spawn, so respawned workers get it too. An unresolved
+ * buffer still posts (empty), so the worker fails loudly instead of hanging.
+ */
+export declare function withSharedBuffer<W extends Worker | NodeWorker>(spawn: () => W, buffer: SharedArrayBuffer | (() => SharedArrayBuffer | undefined)): () => W;
+/**
+ * Worker side: resolve this worker's shared buffer and bind every defined
+ * contract to it (the same call the worker bootstrap makes on INIT_MEMORY).
+ * Checks `workerData.buffer` first — the manual channel — then waits for the
+ * message {@link withSharedBuffer} posts. Rejects on an empty buffer or after
+ * `timeoutMs` so misconfigurations surface instead of hanging.
+ */
+export declare function bindSharedBuffer(timeoutMs?: number): Promise<SharedArrayBuffer>;

package/dist/shim.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shim.js

@@ -0,0 +1,5 @@
+// src/shim.ts
+import { isMainThread, parentPort } from "node:worker_threads";
+if (!isMainThread && parentPort) {
+  globalThis.self = parentPort;
+}

package/dist/worker.d.ts

@@ -0,0 +1,46 @@
+import { Worker as NodeWorker } from 'node:worker_threads';
+export interface WorkerErrorEvent {
+    type: 'error';
+    message: string;
+    error?: unknown;
+}
+/**
+ * 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 declare class NodeWorkerAdapter {
+    private readonly worker;
+    private readonly listeners;
+    constructor(worker: NodeWorker);
+    postMessage(message: unknown, transferList?: unknown[]): void;
+    terminate(): void;
+    addEventListener(type: 'message', handler: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'error', handler: (event: WorkerErrorEvent) => void): void;
+    removeEventListener(type: 'message', handler: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'error', handler: (event: WorkerErrorEvent) => void): void;
+}
+/**
+ * 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 declare function createNodeWorker(source: string | URL | NodeWorker, options?: ConstructorParameters<typeof NodeWorker>[1]): Worker;

package/package.json

@@ -1,24 +1,40 @@
 {
   "name": "@atolljs/node",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Node runtime adapter — node:worker_threads pools, no framework",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts",
-    "./http": "./src/http.ts",
-    "./redis": "./src/redis.ts",
-    "./shim": "./src/shim.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "default": "./dist/redis.js"
+    },
+    "./shim": {
+      "types": "./dist/shim.d.ts",
+      "default": "./dist/shim.js"
+    }
   },
   "files": [
-    "src"
+    "src",
+    "dist"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build-lib.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.3"
+    "@atolljs/core": "0.1.5"
   },
   "repository": {
     "type": "git",