@bonsae/nrg 0.20.0 → 0.21.0

package/README.md

@@ -130,6 +130,14 @@ export default defineModule({
 
 See the [consumer template](https://github.com/AllanOricil/node-red-vue-template) for a complete example.
 
+### The generated editor form
+
+nrg builds the node's edit dialog from your schema — no HTML or jQuery. Your config fields render first, then a **Ports Settings** section (input/output validation, return key, and per-port [context modes](https://bonsaedev.github.io/nrg/guide/schemas#context-modes)) and a **Lifecycle Ports** section (error / complete / status):
+
+<p align="center">
+  <img alt="nrg generated editor form" src="docs/public/editor-form.png" width="360"/>
+</p>
+
 ## Testing
 
 NRG provides five test libraries and bundles most test infrastructure as direct dependencies. Install `vitest` plus any optional peer dependencies you need:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.20.0",
+  "version": "0.21.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

@@ -443,8 +443,8 @@ 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.
+  // outputsSchema accepts any schema shape: the raw sent value (per port) is
+  // validated, and results are frequently non-objects.
   static outputsSchema;
   static validateInput = false;
   static validateOutput = false;
@@ -473,7 +473,7 @@ var IONode = class extends Node {
   }
   #send;
   /**
-   * Most recent input message — the spread base for returnProperty wrapping. Not
+   * Most recent input message — the spread base for output wrapping. Not
    * cleared after input() so late async sends merge with the last received
    * message.
    */
@@ -490,11 +490,15 @@ 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)`
-      );
+    const outputReturnProperties = this.config.outputReturnProperties;
+    if (outputReturnProperties) {
+      for (const [port, key] of Object.entries(outputReturnProperties)) {
+        if (typeof key === "string" && key.trim() && !RETURN_PROPERTY_PATTERN.test(key.trim())) {
+          throw new NrgError(
+            `Invalid return property "${key}" for output port ${port} in ${this.constructor.type} \u2014 it must be a valid JavaScript identifier (letters, digits, _, $; not starting with a digit)`
+          );
+        }
+      }
     }
   }
   [WIRE_HANDLERS](nodeRedNode, createdPromise) {
@@ -569,55 +573,33 @@ var IONode = class extends Node {
       this.#send = void 0;
     }
   }
-  send(msg, contextMode = "nest") {
-    const NodeClass = this.constructor;
+  send(msg, options) {
     const sendsValue = this.baseOutputs <= 1;
-    const shouldValidateOutput = this.config.validateOutput ?? NodeClass.validateOutput;
-    if (shouldValidateOutput && NodeClass.outputsSchema) {
-      this.log("Validating output");
-      const rawSchema = NodeClass.outputsSchema;
-      if (Array.isArray(rawSchema)) {
-        const msgs = msg;
-        for (let i = 0; i < rawSchema.length; i++) {
-          if (msgs[i] == null) continue;
-          this.RED.validator.validate(msgs[i], rawSchema[i], {
-            cacheKey: rawSchema[i].$id || `${NodeClass.type}:output-schema:${i}`,
-            throwOnError: true
-          });
-        }
-      } else if (isSchemaLike(rawSchema)) {
-        if (Array.isArray(msg) && !sendsValue) {
-          const msgs = msg;
-          for (let i = 0; i < msgs.length; i++) {
-            if (msgs[i] == null) continue;
-            this.RED.validator.validate(msgs[i], rawSchema, {
-              cacheKey: rawSchema.$id || `${NodeClass.type}:output-schema`,
-              throwOnError: true
-            });
-          }
-        } else {
-          this.RED.validator.validate(msg, rawSchema, {
-            cacheKey: rawSchema.$id || `${NodeClass.type}:output-schema`,
-            throwOnError: true
-          });
-        }
-      } else {
-        const schemaArray = Object.values(rawSchema);
-        const msgs = msg;
-        for (let i = 0; i < schemaArray.length; i++) {
-          if (msgs[i] == null) continue;
-          this.RED.validator.validate(msgs[i], schemaArray[i], {
-            cacheKey: schemaArray[i].$id || `${NodeClass.type}:output-schema:${i}`,
-            throwOnError: true
-          });
-        }
-      }
-      this.log("Output is valid");
+    const defaultMode = options?.defaultMode;
+    if (Array.isArray(msg) && !sendsValue) {
+      const slots = msg.slice(0, this.baseOutputs);
+      const out = slots.map((m, port) => {
+        if (m == null) return m;
+        this.#validatePort(m, port);
+        return this.#wrapOutgoing(
+          m,
+          this.#resolveContextMode(port, defaultMode),
+          port
+        );
+      });
+      this.#deliver(out);
+      return;
+    }
+    if (msg == null) {
+      this.#deliver(msg);
+      return;
     }
-    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);
+    this.#validatePort(msg, 0);
+    this.#deliver(
+      this.#wrapOutgoing(msg, this.#resolveContextMode(0, defaultMode), 0)
+    );
+  }
+  #deliver(out) {
     if (this.#send) {
       this.#send(out);
     } else {
@@ -625,45 +607,70 @@ var IONode = class extends Node {
     }
   }
   /**
-   * 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).
+   * Per-port output validation. A port validates when its flow-author flag
+   * (`config.validateOutputs[port]`) — or the node's static `validateOutput`
+   * fallback — is on and a schema exists for that port.
    */
+  #validatePort(value, port) {
+    const NodeClass = this.constructor;
+    const configured = this.config.validateOutputs?.[port];
+    if (!(configured ?? NodeClass.validateOutput)) return;
+    const schema = this.#outputSchemaForPort(port);
+    if (!schema) return;
+    this.log("Validating output");
+    this.RED.validator.validate(value, schema, {
+      cacheKey: schema.$id || `${NodeClass.type}:output-schema:${port}`,
+      throwOnError: true
+    });
+    this.log("Output is valid");
+  }
+  /** Resolves the output schema for a base-output port: array → `[port]`,
+   * record → the port-th value, single schema → itself. */
+  #outputSchemaForPort(port) {
+    const raw = this.constructor.outputsSchema;
+    if (!raw) return void 0;
+    if (Array.isArray(raw)) return raw[port];
+    if (isSchemaLike(raw)) return raw;
+    return Object.values(raw)[port];
+  }
   /**
-   * 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".
+   * The return key for an output port — `"output"` unless a custom one is set
+   * via `outputReturnProperties[port]` (author default and/or flow-author
+   * override, only possible when the node declares `outputReturnProperties`).
+   * `this.send(x)` always means "x is the value at this port's 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;
+  #returnPropertyKey(port) {
+    const configured = this.config.outputReturnProperties?.[port];
     if (typeof configured === "string" && configured.trim()) {
       return configured.trim();
     }
-    if (declared && typeof declared.default === "string" && declared.default) {
-      return declared.default;
-    }
     return "output";
   }
+  /**
+   * Resolves the context mode for a base-output port. Precedence: the flow
+   * author's per-port override (`config.contextModes[port]`) → the node author's
+   * `defaultMode` → `"carry"`.
+   */
+  #resolveContextMode(port, defaultMode) {
+    const configured = this.config.contextModes?.[port];
+    return configured ?? defaultMode ?? "carry";
+  }
   /**
    * 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();
+  #wrapOutgoing(value, mode, port) {
+    const key = this.#returnPropertyKey(port);
     const input = this.#currentInputMsg ?? {};
     if (mode === "reset") {
       return { [key]: value };
     }
-    if (mode === "carry") {
-      return { ...input, [key]: value };
+    if (mode === "trace") {
+      return { ...input, [key]: value, [INPUT_KEY]: input };
     }
-    return { ...input, [key]: value, [INPUT_KEY]: input };
+    return { ...input, [key]: value };
   }
   // --- Built-in port management ---
   get baseOutputs() {
@@ -687,15 +694,17 @@ 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, contextMode = "nest") {
+  sendToPort(port, msg, options) {
     if (port === "error" || port === "complete" || port === "status") {
       throw new NrgError(
         `sendToPort("${port}") is not allowed. Built-in ports are managed by the framework.`
       );
     }
+    const portIndex = typeof port === "number" ? port : this.#getNamedPortIndex(port);
+    const mode = this.#resolveContextMode(portIndex ?? 0, options?.defaultMode);
     this.#sendToPort(
       port,
-      msg == null ? msg : this.#wrapOutgoing(msg, contextMode)
+      msg == null ? msg : this.#wrapOutgoing(msg, mode, portIndex ?? 0)
     );
   }
   #sendToPort(port, msg) {
@@ -1163,18 +1172,21 @@ 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
-  });
+function OutputReturnProperties(options) {
+  return import_typebox2.Type.Record(
+    import_typebox2.Type.Number(),
+    import_typebox2.Type.String({ pattern: "^[A-Za-z_$][A-Za-z0-9_$]*$" }),
+    {
+      description: "Per-port return property, keyed by output port index. A missing entry falls back to `output`.",
+      default: {},
+      ...options
+    }
+  );
 }
 var SchemaType = Object.assign({}, import_typebox2.Type, {
   NodeRef,
   TypedInput: TypedInput2,
-  ReturnProperty
+  OutputReturnProperties
 });
 function markNonValidatable(schema) {
   const type = schema.type;