@bonsae/nrg 0.18.5 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.18.5",
+  "version": "0.19.0",
   "description": "NRG framework — build Node-RED nodes with Vue 3, TypeScript, and JSON Schema",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",

package/server/index.cjs

@@ -437,10 +437,14 @@ var Node = class _Node {
 };
 
 // src/core/server/nodes/io-node.ts
+var RETURN_PROPERTY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var INPUT_KEY = "input";
 var IONode = class extends Node {
   static align;
   static color;
   static inputSchema;
+  // outputsSchema accepts any schema shape: with returnProperty the raw sent
+  // value is validated, and results are frequently non-objects.
   static outputsSchema;
   static validateInput = false;
   static validateOutput = false;
@@ -468,6 +472,12 @@ var IONode = class extends Node {
     return keys.length;
   }
   #send;
+  /**
+   * Most recent input message — the spread base for returnProperty wrapping. Not
+   * cleared after input() so late async sends merge with the last received
+   * message.
+   */
+  #currentInputMsg;
   context;
   constructor(RED, node, config, credentials) {
     super(RED, node, config, credentials);
@@ -480,6 +490,12 @@ var IONode = class extends Node {
     fn.flow = setupContext(context.flow);
     fn.global = setupContext(context.global);
     this.context = fn;
+    const returnPropertyKey = this.#returnPropertyKey();
+    if (!RETURN_PROPERTY_PATTERN.test(returnPropertyKey)) {
+      throw new NrgError(
+        `Invalid returnProperty key "${returnPropertyKey}" in ${this.constructor.type} \u2014 it must be a valid JavaScript identifier (letters, digits, _, $; not starting with a digit)`
+      );
+    }
   }
   [WIRE_HANDLERS](nodeRedNode, createdPromise) {
     super[WIRE_HANDLERS](nodeRedNode, createdPromise);
@@ -495,12 +511,14 @@ var IONode = class extends Node {
         }
         try {
           nodeRedNode.log("Calling input");
+          this.#currentInputMsg = msg;
           await Promise.resolve(this.#input(msg, send));
           this.#sendToPort("complete", {
             ...msg,
             complete: {
               source: this.#nodeSource()
-            }
+            },
+            [INPUT_KEY]: msg
           });
           done();
           nodeRedNode.log("Input processed");
@@ -511,7 +529,8 @@ var IONode = class extends Node {
             error: {
               message: errorMsg,
               source: this.#nodeSource()
-            }
+            },
+            [INPUT_KEY]: msg
           });
           if (error instanceof Error) {
             nodeRedNode.error(
@@ -550,8 +569,9 @@ var IONode = class extends Node {
       this.#send = void 0;
     }
   }
-  send(msg) {
+  send(msg, contextMode = "nest") {
     const NodeClass = this.constructor;
+    const sendsValue = this.baseOutputs <= 1;
     const shouldValidateOutput = this.config.validateOutput ?? NodeClass.validateOutput;
     if (shouldValidateOutput && NodeClass.outputsSchema) {
       this.log("Validating output");
@@ -566,7 +586,7 @@ var IONode = class extends Node {
           });
         }
       } else if (isSchemaLike(rawSchema)) {
-        if (Array.isArray(msg)) {
+        if (Array.isArray(msg) && !sendsValue) {
           const msgs = msg;
           for (let i = 0; i < msgs.length; i++) {
             if (msgs[i] == null) continue;
@@ -594,13 +614,57 @@ var IONode = class extends Node {
       }
       this.log("Output is valid");
     }
-    const out = Array.isArray(msg) ? msg.slice(0, this.baseOutputs) : msg;
+    const truncated = Array.isArray(msg) && !sendsValue ? msg.slice(0, this.baseOutputs) : msg;
+    const out = Array.isArray(truncated) && !sendsValue ? truncated.map(
+      (m) => m == null ? m : this.#wrapOutgoing(m, contextMode)
+    ) : truncated == null ? truncated : this.#wrapOutgoing(truncated, contextMode);
     if (this.#send) {
       this.#send(out);
     } else {
       this.node.send(out);
     }
   }
+  /**
+   * Resolves the active return key. `null` = the node did not declare
+   * `returnProperty` in its configSchema, so its code owns the outgoing message
+   * shape (no wrapping).
+   */
+  /**
+   * Every node has a return property — `"output"` by default. Declaring
+   * `SchemaType.ReturnProperty()` in the configSchema doesn't create it; it
+   * only exposes the key to the flow author so they can override it in the
+   * editor (and lets the node pick a different default). So `this.send(x)`
+   * always means "x is the value at the return key", never "x is the whole
+   * outgoing message".
+   */
+  #returnPropertyKey() {
+    const NodeClass = this.constructor;
+    const declared = NodeClass.configSchema?.properties?.returnProperty;
+    const configured = this.config.returnProperty;
+    if (typeof configured === "string" && configured.trim()) {
+      return configured.trim();
+    }
+    if (declared && typeof declared.default === "string" && declared.default) {
+      return declared.default;
+    }
+    return "output";
+  }
+  /**
+   * Merges a sent value into the incoming message at the returnProperty key so
+   * upstream message properties propagate. A fresh base is built per call so
+   * multi-port sends never share an object.
+   */
+  #wrapOutgoing(value, mode = "nest") {
+    const key = this.#returnPropertyKey();
+    const input = this.#currentInputMsg ?? {};
+    if (mode === "reset") {
+      return { [key]: value };
+    }
+    if (mode === "carry") {
+      return { ...input, [key]: value };
+    }
+    return { ...input, [key]: value, [INPUT_KEY]: input };
+  }
   // --- Built-in port management ---
   get baseOutputs() {
     return this.constructor.outputs ?? 0;
@@ -623,13 +687,16 @@ var IONode = class extends Node {
    * throw an error or call `this.error()` for the error port, and the complete
    * port is sent automatically on successful input processing.
    */
-  sendToPort(port, msg) {
+  sendToPort(port, msg, contextMode = "nest") {
     if (port === "error" || port === "complete" || port === "status") {
       throw new NrgError(
         `sendToPort("${port}") is not allowed. Built-in ports are managed by the framework.`
       );
     }
-    this.#sendToPort(port, msg);
+    this.#sendToPort(
+      port,
+      msg == null ? msg : this.#wrapOutgoing(msg, contextMode)
+    );
   }
   #sendToPort(port, msg) {
     let portIndex;
@@ -687,7 +754,8 @@ var IONode = class extends Node {
         error: {
           message,
           source: this.#nodeSource()
-        }
+        },
+        [INPUT_KEY]: msg
       });
     }
   }
@@ -1095,9 +1163,18 @@ function TypedInput2(options) {
     [import_typebox2.Kind]: "TypedInput"
   };
 }
+function ReturnProperty(options) {
+  return import_typebox2.Type.String({
+    description: "Message property that receives this node's result. The rest of the incoming message is propagated unchanged, and the prior message is kept under `input`.",
+    pattern: "^[A-Za-z_$][A-Za-z0-9_$]*$",
+    default: "output",
+    ...options
+  });
+}
 var SchemaType = Object.assign({}, import_typebox2.Type, {
   NodeRef,
-  TypedInput: TypedInput2
+  TypedInput: TypedInput2,
+  ReturnProperty
 });
 function markNonValidatable(schema) {
   const type = schema.type;