@bonsae/nrg-runtime 0.38.0 → 0.39.0

package/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/sdk/lib/runtime.ts
 var runtime_exports = {};
 __export(runtime_exports, {
+  Channels: () => Channels,
   ConfigNode: () => ConfigNode,
   IONode: () => IONode,
   Kind: () => import_typebox3.Kind,
@@ -43,13 +44,20 @@ __export(runtime_exports, {
 });
 module.exports = __toCommonJS(runtime_exports);
 
-// src/sdk/lib/server/nodes/symbols.ts
+// src/sdk/lib/server/symbols/node.ts
 var NRG_SETUP_CLOSE_HANDLER = Symbol.for("nrg.setupCloseHandler");
 var NRG_SETUP_INPUT_HANDLER = Symbol.for("nrg.setupInputHandler");
 var NRG_NODE = Symbol.for("nrg.node");
 var NRG_CONFIG_NODE = Symbol.for("nrg.configNode");
 var NRG_PORTS = Symbol.for("nrg.ports");
 
+// src/sdk/lib/server/symbols/channels-store.ts
+var NRG_PROTECTED_CHANNEL = Symbol.for("nrg.protectedChannel");
+var NRG_PRIVATE_CHANNEL = Symbol.for("nrg.privateChannel");
+var NRG_MODULE_PRIVATE_CHANNEL = Symbol.for(
+  "nrg.modulePrivateChannel"
+);
+
 // src/sdk/lib/shared/errors.ts
 var NrgError = class _NrgError extends Error {
   constructor(message) {
@@ -61,6 +69,7 @@ var NrgError = class _NrgError extends Error {
 
 // src/sdk/lib/server/module.ts
 function defineModule(definition) {
+  const packagePrivateChannel = Symbol("nrg.package.private");
   for (const NodeClass of definition.nodes) {
     if (!NodeClass[NRG_NODE]) {
       const name = NodeClass?.name || String(NodeClass);
@@ -68,6 +77,7 @@ function defineModule(definition) {
         `defineModule: "${name}" is not an nrg node class \u2014 extend IONode/ConfigNode.`
       );
     }
+    NodeClass[NRG_MODULE_PRIVATE_CHANNEL] = packagePrivateChannel;
   }
   return definition;
 }
@@ -249,44 +259,108 @@ var ValidationError = class _ValidationError extends Error {
   }
 };
 
-// src/sdk/lib/server/validation.ts
-function initValidator(RED) {
-  if (RED.validator) return;
-  const nrg = {
-    validator: new Validator({
-      customKeywords: [
-        {
-          keyword: "x-nrg-skip-validation",
-          schemaType: "boolean",
-          valid: true
-        },
-        {
-          keyword: "x-nrg-node-type",
-          type: "string",
-          validate: (schemaValue, dataValue) => {
-            if (!dataValue) return true;
-            const node = RED.nodes.getNode(dataValue);
-            return node?.type === schemaValue;
-          }
-        }
-      ],
-      customFormats: {
-        "node-id": /^[a-zA-Z0-9-_]+$/
-      }
-    })
-  };
-  Object.defineProperty(RED, "_nrg", {
-    value: nrg,
-    writable: false,
-    enumerable: false,
-    configurable: false
-  });
-  Object.defineProperty(RED, "validator", {
-    get: () => nrg.validator,
-    enumerable: false,
-    configurable: false
+// src/sdk/lib/server/channels-store.ts
+var ASSIGN_MESSAGE = "Cannot assign to a message channel. Channel data is written on send \u2014 `send(port, value, { protected, private })`. The `msg[Channels]` accessor is read + delete only (e.g. `delete msg[Channels].private.x`).";
+var ChannelStore = class {
+  #byMsgid = /* @__PURE__ */ new Map();
+  #ttlMs;
+  #sweepMs;
+  #sweeper;
+  constructor(options = {}) {
+    this.#ttlMs = options.ttlMs ?? 5 * 6e4;
+    this.#sweepMs = options.sweepMs ?? 6e4;
+  }
+  #channel(msgid, partition, create) {
+    let entry = this.#byMsgid.get(msgid);
+    if (!entry) {
+      if (!create) return void 0;
+      entry = { lastTouched: Date.now(), partitions: /* @__PURE__ */ new Map() };
+      this.#byMsgid.set(msgid, entry);
+      this.#ensureSweeper();
+    } else {
+      entry.lastTouched = Date.now();
+    }
+    let channel = entry.partitions.get(partition);
+    if (!channel && create) {
+      channel = /* @__PURE__ */ new Map();
+      entry.partitions.set(partition, channel);
+    }
+    return channel;
+  }
+  /** Merge a producer's `{ … }` bag into a channel (send's protected/private args). */
+  merge(msgid, partition, data) {
+    const channel = this.#channel(msgid, partition, true);
+    for (const [key, value] of Object.entries(data)) channel.set(key, value);
+  }
+  get(msgid, partition, key) {
+    return this.#channel(msgid, partition, false)?.get(key);
+  }
+  set(msgid, partition, key, value) {
+    this.#channel(msgid, partition, true).set(key, value);
+  }
+  has(msgid, partition, key) {
+    return this.#channel(msgid, partition, false)?.has(key) ?? false;
+  }
+  /** Remove one entry — framework bookkeeping only; the resource owns release. */
+  delete(msgid, partition, key) {
+    this.#channel(msgid, partition, false)?.delete(key);
+  }
+  keys(msgid, partition) {
+    return [...this.#channel(msgid, partition, false)?.keys() ?? []];
+  }
+  #ensureSweeper() {
+    if (this.#sweeper) return;
+    this.#sweeper = setInterval(() => this.#sweep(), this.#sweepMs);
+    this.#sweeper.unref?.();
+  }
+  #sweep() {
+    const now = Date.now();
+    for (const [msgid, entry] of this.#byMsgid) {
+      if (now - entry.lastTouched > this.#ttlMs) this.#byMsgid.delete(msgid);
+    }
+    if (this.#byMsgid.size === 0 && this.#sweeper) {
+      clearInterval(this.#sweeper);
+      this.#sweeper = void 0;
+    }
+  }
+};
+function channelProxy(store, msgid, partition) {
+  if (msgid == null) {
+    return new Proxy(/* @__PURE__ */ Object.create(null), {
+      get: () => void 0,
+      set: () => {
+        throw new NrgError(ASSIGN_MESSAGE);
+      },
+      deleteProperty: () => true,
+      has: () => false,
+      ownKeys: () => [],
+      getOwnPropertyDescriptor: () => void 0
+    });
+  }
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get: (_t, key) => typeof key === "string" ? store.get(msgid, partition, key) : void 0,
+    // Assignment is a misuse — channels are written on send, not by mutating the
+    // incoming message. Throw loudly rather than silently writing a second path.
+    set: () => {
+      throw new NrgError(ASSIGN_MESSAGE);
+    },
+    deleteProperty: (_t, key) => {
+      if (typeof key === "string") store.delete(msgid, partition, key);
+      return true;
+    },
+    has: (_t, key) => typeof key === "string" ? store.has(msgid, partition, key) : false,
+    ownKeys: () => store.keys(msgid, partition),
+    getOwnPropertyDescriptor: (_t, key) => typeof key === "string" && store.has(msgid, partition, key) ? {
+      enumerable: true,
+      configurable: true,
+      writable: false,
+      value: store.get(msgid, partition, key)
+    } : void 0
   });
 }
+function packageChannel(nodeClass) {
+  return nodeClass[NRG_MODULE_PRIVATE_CHANNEL] ?? NRG_PRIVATE_CHANNEL;
+}
 
 // src/sdk/lib/server/api/assets.ts
 var import_node_path = __toESM(require("node:path"), 1);
@@ -320,6 +394,51 @@ function initRoutes(RED) {
   initAssetsRoutes(RED.httpAdmin);
 }
 
+// src/sdk/lib/server/init.ts
+function initValidator(RED) {
+  if (RED.validator) return;
+  const validator = new Validator({
+    customKeywords: [
+      {
+        keyword: "x-nrg-skip-validation",
+        schemaType: "boolean",
+        valid: true
+      },
+      {
+        keyword: "x-nrg-node-type",
+        type: "string",
+        validate: (schemaValue, dataValue) => {
+          if (!dataValue) return true;
+          const node = RED.nodes.getNode(dataValue);
+          return node?.type === schemaValue;
+        }
+      }
+    ],
+    customFormats: {
+      "node-id": /^[a-zA-Z0-9-_]+$/
+    }
+  });
+  Object.defineProperty(RED, "validator", {
+    get: () => validator,
+    enumerable: false,
+    configurable: false
+  });
+}
+function initChannelStore(RED) {
+  if (RED.channelStore) return;
+  const channelStore = new ChannelStore();
+  Object.defineProperty(RED, "channelStore", {
+    get: () => channelStore,
+    enumerable: false,
+    configurable: false
+  });
+}
+function init(RED) {
+  initValidator(RED);
+  initChannelStore(RED);
+  initRoutes(RED);
+}
+
 // src/sdk/lib/shared/schemas/utils.ts
 function getCredentialsFromSchema(schema) {
   if (!schema?.properties) return void 0;
@@ -416,8 +535,7 @@ async function registerType(RED, NodeClass) {
 function registerTypes(nodes) {
   const fn = Object.assign(
     async function(RED) {
-      initValidator(RED);
-      initRoutes(RED);
+      init(RED);
       try {
         RED.log.info("Registering node types in series");
         for (const NodeClass of nodes) {
@@ -788,18 +906,22 @@ function setupContext(context, store) {
   return { get, set, keys, update, increment };
 }
 
+// src/sdk/lib/server/nodes/types/ports.ts
+var Channels = Symbol.for("nrg.channels");
+
 // src/sdk/lib/server/nodes/io-node.ts
 var import_node_async_hooks = require("node:async_hooks");
 var RETURN_PROPERTY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 var INPUT_KEY = "input";
 var SOURCE_KEY = "source";
+var MSGID_KEY = "_msgid";
 var RESERVED_RETURN_PROPERTIES = /* @__PURE__ */ new Set([
   SOURCE_KEY,
   INPUT_KEY,
   "error",
   "complete",
   "status",
-  "_msgid"
+  MSGID_KEY
 ]);
 var IONode = class _IONode extends Node {
   static align;
@@ -892,7 +1014,10 @@ var IONode = class _IONode extends Node {
             this.#sendToPort("complete", {
               ...result !== void 0 ? { complete: result } : {},
               [SOURCE_KEY]: this.#nodeSource(),
-              [INPUT_KEY]: msg
+              [INPUT_KEY]: msg,
+              // Runs after input() resolved (outside the ALS scope), so inherit
+              // the incoming `_msgid` explicitly to keep the lineage id intact.
+              ...this.#sourceMsgid(msg)
             });
           }
           done();
@@ -915,7 +1040,10 @@ var IONode = class _IONode extends Node {
                   ...stack ? { stack } : {}
                 },
                 [SOURCE_KEY]: this.#nodeSource(),
-                [INPUT_KEY]: msg
+                [INPUT_KEY]: msg,
+                // Runs in the catch (outside the ALS scope), so inherit the
+                // incoming `_msgid` explicitly to keep the lineage id intact.
+                ...this.#sourceMsgid(msg)
               });
               this.node.error(errorMsg);
             }
@@ -945,20 +1073,65 @@ var IONode = class _IONode extends Node {
         this.node.log("Input is valid");
       }
     }
+    this.#setupChannels(msg);
     return await _IONode.#invocation.run(
       store,
       () => Promise.resolve(this.input(msg))
     );
   }
-  send(msg) {
-    const multi = this.#baseOutputs > 1 && Array.isArray(msg);
-    const values = multi ? msg.slice(0, this.#baseOutputs) : [msg];
-    const out = values.map((m, port) => {
-      if (m == null) return m;
-      this.#validatePort(m, port);
-      return this.#wrapOutgoing(m, this.#resolveContextMode(port), port);
+  /**
+   * Add the `[Channels]` accessor to the incoming message. SYMBOL-keyed, so it can
+   * never collide with an author's own message fields and is already invisible to
+   * JSON / `Object.keys` / the debug panel (the `enumerable: false` keeps it out of
+   * a symbol-aware clone too). Reading `msg[Channels]` yields `{ protected, private }`
+   * — proxies over the channel store keyed by the message's `_msgid`, `private`
+   * partitioned by this node's package. A core function node gets the bare message
+   * and has no accessor — the channels are structurally invisible to the flow author.
+   *
+   * Mutates `msg` in place (the caller already holds it as `TInput`). A non-object
+   * message (never produced by real Node-RED, which always delivers an object) is
+   * left untouched.
+   */
+  #setupChannels(msg) {
+    if (msg == null || typeof msg !== "object") return;
+    const store = this.RED.channelStore;
+    const pkg = packageChannel(this.constructor);
+    Object.defineProperty(msg, Channels, {
+      configurable: true,
+      enumerable: false,
+      get() {
+        const msgid = this._msgid;
+        return {
+          protected: channelProxy(store, msgid, NRG_PROTECTED_CHANNEL),
+          private: channelProxy(store, msgid, pkg)
+        };
+      }
     });
-    this.#deliver(out);
+  }
+  /**
+   * Merge the `protected`/`private` args into this message's channels. Keyed by the
+   * outgoing `_msgid`: an input-triggered send inherits it; a source send (no
+   * invocation) mints one and stamps it on the outgoing frames so a downstream
+   * node reads the same channel. Contributions are STICKY — they persist for the
+   * message's journey, so a middle node's plain `send()` keeps them alive.
+   */
+  #writeChannels(protectedData, privateData, out) {
+    if (!protectedData && !privateData) return;
+    const existing = _IONode.#invocation.getStore()?.inputMsg?.[MSGID_KEY];
+    const msgid = existing ?? this.RED.util.generateId();
+    if (!existing) {
+      for (const m of out) {
+        if (m && typeof m === "object") {
+          const rec = m;
+          if (rec[MSGID_KEY] === void 0) rec[MSGID_KEY] = msgid;
+        }
+      }
+    }
+    const store = this.RED.channelStore;
+    if (protectedData) store.merge(msgid, NRG_PROTECTED_CHANNEL, protectedData);
+    if (privateData) {
+      store.merge(msgid, packageChannel(this.constructor), privateData);
+    }
   }
   #deliver(out) {
     const send = _IONode.#invocation.getStore()?.send;
@@ -1058,13 +1231,43 @@ var IONode = class _IONode extends Node {
     const key = this.#returnPropertyKey(port);
     const input = _IONode.#invocation.getStore()?.inputMsg ?? {};
     const source = this.#outputSource(port);
-    const frame = (msg) => Object.keys(msg).length ? { [key]: value, [SOURCE_KEY]: source, [INPUT_KEY]: msg } : { [key]: value, [SOURCE_KEY]: source };
-    if (mode === "reset") return { [key]: value, [SOURCE_KEY]: source };
-    if (mode === "trace") return frame(input);
+    const frame = (msg) => this.#withMsgid(
+      Object.keys(msg).length ? { [key]: value, [SOURCE_KEY]: source, [INPUT_KEY]: msg } : { [key]: value, [SOURCE_KEY]: source }
+    );
+    if (mode === "reset")
+      return this.#withMsgid({ [key]: value, [SOURCE_KEY]: source });
+    if (mode === "trace") return frame({ ...input });
     const lastOnly = { ...input };
     delete lastOnly[INPUT_KEY];
     return frame(lastOnly);
   }
+  /**
+   * Preserve Node-RED's message-lineage id: a node's output inherits the
+   * `_msgid` of the message it is processing (Node-RED assigns a fresh one only
+   * when absent — see `Node.prototype.send`). Copying it onto every outgoing
+   * message — in every context mode and on every port — stops the id forking at
+   * each hop, which would otherwise break the message-flow debugger, Catch/
+   * Complete grouping, and any `_msgid`-based correlation. Reads the current
+   * invocation's input; a send outside any input() call (e.g. a source node)
+   * has none, so nothing is stamped and Node-RED assigns one as usual.
+   */
+  #withMsgid(frame) {
+    const msgid = _IONode.#invocation.getStore()?.inputMsg?.[MSGID_KEY];
+    return msgid !== void 0 ? { ...frame, [MSGID_KEY]: msgid } : frame;
+  }
+  /**
+   * The source message's `_msgid` as a spreadable frame fragment — for the
+   * built-in complete/error auto-emits, which run AFTER `input()` has resolved,
+   * i.e. OUTSIDE the invocation ALS scope, so {@link #withMsgid} (which reads the
+   * scope) can't recover it. Stamping it here keeps the lifecycle frame on the
+   * SAME lineage id as the data-port emits, so Catch/Complete grouping and any
+   * `_msgid` correlation still work. `{}` when the source carries none (a source
+   * node) — Node-RED then assigns one, exactly as {@link #withMsgid} documents.
+   */
+  #sourceMsgid(src) {
+    const id = src?.[MSGID_KEY];
+    return typeof id === "string" ? { [MSGID_KEY]: id } : {};
+  }
   /**
    * Provenance stamped on every data-port output under `msg.source`: the
    * producing node plus the port the message was sent on (with the named-port
@@ -1108,32 +1311,51 @@ var IONode = class _IONode extends Node {
    * framework and cannot be sent to directly. Use `this.status()` for status,
    * throw an error or call `this.error()` for the error port, and the complete
    * port is sent automatically on successful input processing.
+   *
+   * The optional `channels` argument writes off-the-wire data to the message's
+   * channel store (keyed by its `_msgid`): `protected` targets the package-shared
+   * partition, `private` this package's own. It is reachable downstream via
+   * `msg[Channels]` and never rides the serialized message. A single object (not
+   * positional args) so new channels stay additive.
    */
-  sendToPort(port, msg) {
+  send(port, msg, channels) {
     if (port === "error" || port === "complete" || port === "status") {
       throw new NrgError(
-        `sendToPort("${port}") is not allowed. Built-in ports are managed by the framework.`
+        `send("${port}") is not allowed. Built-in ports are managed by the framework.`
       );
     }
+    if (typeof port === "number") {
+      if (!Number.isInteger(port) || port < 0) {
+        throw new NrgError(
+          `send(${port}) \u2014 a numeric output port must be a non-negative integer index.`
+        );
+      }
+      if (port >= this.#baseOutputs && port < this.#totalOutputs) {
+        throw new NrgError(
+          `send(${port}) targets a framework-managed built-in port slot (error/complete/status).` + (this.#baseOutputs > 0 ? ` Send to a base output port (0..${this.#baseOutputs - 1}),` : ` Send to a base output port,`) + ` or use this.status() / this.error().`
+        );
+      }
+    }
     const portIndex = typeof port === "number" ? port : this.#getNamedPortIndex(port);
     if (typeof port === "string" && portIndex === null) {
       const keys = this.#namedPortKeys();
       throw new NrgError(
-        keys && keys.length ? `sendToPort("${port}") \u2014 unknown output port. Valid named ports: ${keys.map((n) => `"${n}"`).join(", ")}.` : `sendToPort("${port}") \u2014 this node has no named output ports. Declare named ports with a Port<T> record in the node's Output generic, or send to a numeric port index.`
+        keys && keys.length ? `send("${port}") \u2014 unknown output port. Valid named ports: ${keys.map((n) => `"${n}"`).join(", ")}.` : `send("${port}") \u2014 this node has no named output ports. Declare named ports with a Port<T> record in the node's Output generic, or send to a numeric port index.`
       );
     }
     const idx = portIndex ?? 0;
     if (msg == null) {
-      this.#sendToPort(port, msg);
+      this.#sendToPort(port, msg, channels);
       return;
     }
     this.#validatePort(msg, idx);
     this.#sendToPort(
       port,
-      this.#wrapOutgoing(msg, this.#resolveContextMode(idx), idx)
+      this.#wrapOutgoing(msg, this.#resolveContextMode(idx), idx),
+      channels
     );
   }
-  #sendToPort(port, msg) {
+  #sendToPort(port, msg, channels) {
     let portIndex;
     if (typeof port === "number") {
       portIndex = port;
@@ -1147,8 +1369,11 @@ var IONode = class _IONode extends Node {
       }
     }
     const out = new Array(this.#totalOutputs);
-    out[portIndex] = msg;
-    this.node.send(out);
+    out[portIndex] = msg !== null && typeof msg === "object" ? this.#withMsgid(msg) : msg;
+    if (channels?.protected || channels?.private) {
+      this.#writeChannels(channels.protected, channels.private, out);
+    }
+    this.#deliver(out);
   }
   /** The declared named output ports (from the injected `Output`-generic
    * topology's `Port<T>` record), or null when the node has none (a
@@ -1497,6 +1722,7 @@ function defineSchema(properties, options) {
 var import_typebox3 = require("@sinclair/typebox");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Channels,
   ConfigNode,
   IONode,
   Kind,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg-runtime",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "The runtime for Node-RED nodes built with @bonsae/nrg — node base classes, schemas, AJV validator, and the editor client. Carries no build tooling.",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",