@bonsae/nrg 0.18.4 → 0.19.0

package/README.md

@@ -13,41 +13,25 @@
 
 Build Node-RED nodes with Vue 3, TypeScript, JSON Schema validations, Vite and Vitest.
 
-## Package Exports
-
-| Export | Description |
-| --- | --- |
-| `@bonsae/nrg` | Root entry — `defineRuntimeSettings` |
-| `@bonsae/nrg/server` | Server node classes, schema utilities, validation (`IONode`, `ConfigNode`, `defineIONode`, `defineConfigNode`, `defineModule`, `SchemaType`, `defineSchema`, `Infer`) |
-| `@bonsae/nrg/client` | Client-side registration (`registerTypes`, `defineNode`, `useFormNode`, `Infer`) |
-| `@bonsae/nrg/vite` | Vite plugin for building and developing Node-RED packages |
-| `@bonsae/nrg/test/server/unit` | Server unit test helpers (`createNode`, `createRED`, `MockRED`) |
-| `@bonsae/nrg/test/server/unit/config` | Server unit test default vitest config (`defaultConfig`) |
-| `@bonsae/nrg/test/client/unit` | Client unit test mocks (`createRED`, `createJQuery`, `useFormNode`) |
-| `@bonsae/nrg/test/client/unit/config` | Client unit test default vitest config (`defaultConfig`) |
-| `@bonsae/nrg/test/client/unit/setup` | Setup file that installs `RED` and `$` mocks on `window` |
-| `@bonsae/nrg/test/client/component` | Client component test helpers (`createNode`, `createRED`, `createJQuery`, `useFormNode`) |
-| `@bonsae/nrg/test/client/component/config` | Client component test default vitest config (`defaultConfig`) |
-| `@bonsae/nrg/test/client/component/setup` | Setup file that installs `RED` and `$` mocks on `window` with Vue i18n |
-| `@bonsae/nrg/test/client/e2e` | Browser E2E test helpers (`NodeRedEditor`, `NodeRedField`, `setup`, `teardown`) |
-| `@bonsae/nrg/tsconfig/base.json` | Base TypeScript configuration |
-| `@bonsae/nrg/tsconfig/core/server.json` | Core server source tsconfig |
-| `@bonsae/nrg/tsconfig/core/client.json` | Core client source tsconfig |
-| `@bonsae/nrg/tsconfig/test/server/unit.json` | Server unit test tsconfig |
-| `@bonsae/nrg/tsconfig/test/client/unit.json` | Client unit test tsconfig |
-| `@bonsae/nrg/tsconfig/test/client/component.json` | Client component test tsconfig |
-| `@bonsae/nrg/tsconfig/test/client/e2e.json` | Client E2E test tsconfig |
-
 ## Quick Start
 
 ```bash
-# In your Node-RED package project
 pnpm add @bonsae/nrg
-pnpm add -D vite vue
+pnpm add -D vite vue node-red
 ```
 
 > `vite` and `vue` are dev dependencies because they are only needed at build time. Vue is included as a dependency of nrg and served automatically at runtime.
 
+### Node-RED Resolution
+
+The vite plugin needs a Node-RED instance for the dev server. It resolves it in this order:
+
+1. **`runtime.version`** — if specified in the plugin config, downloads that exact version via `npx` (overrides any locally installed version)
+2. **Local `node_modules`** — if `node-red` is installed as a dependency, it is used directly (fastest)
+3. **Fallback** — downloads the latest `node-red` via `npx`
+
+Installing `node-red` as a dev dependency is recommended for fast, reliable dev server startup across all platforms (especially Windows). If you need a specific version (e.g., a beta), set `runtime.version` in the plugin config instead.
+
 **vite.config.ts**
 
 ```typescript
@@ -153,13 +137,13 @@ pnpm add -D vitest
 
 Optional peer dependencies:
 
-| Package | When to install |
-| --- | --- |
-| `@vitest/browser-playwright` | Component tests (Playwright browser provider for Vitest) |
-| `playwright` | Component tests or E2E tests (direct `import` in test files) |
-| `vitest-browser-vue` | Component tests (`render` helper for Vue components) |
-| `@vitest/coverage-v8` | Coverage with `--coverage` (V8 provider) |
-| `@vitest/coverage-istanbul` | Coverage with `--coverage` (Istanbul provider) |
+| Package                      | When to install                                              |
+| ---------------------------- | ------------------------------------------------------------ |
+| `@vitest/browser-playwright` | Component tests (Playwright browser provider for Vitest)     |
+| `playwright`                 | Component tests or E2E tests (direct `import` in test files) |
+| `vitest-browser-vue`         | Component tests (`render` helper for Vue components)         |
+| `@vitest/coverage-v8`        | Coverage with `--coverage` (V8 provider)                     |
+| `@vitest/coverage-istanbul`  | Coverage with `--coverage` (Istanbul provider)               |
 
 - `@bonsae/nrg/test/server/unit` — server-side unit tests
 - `@bonsae/nrg/test/client/unit` — client-side unit tests (TypeScript logic)
@@ -195,11 +179,14 @@ Test client-side TypeScript logic (validation, utilities) with mocked `RED` and
 import { defineConfig, mergeConfig } from "vitest/config";
 import { defaultConfig } from "@bonsae/nrg/test/client/unit/config";
 
-export default mergeConfig(defaultConfig, defineConfig({
-  test: {
-    include: ["tests/client/unit/**/*.test.ts"],
-  },
-}));
+export default mergeConfig(
+  defaultConfig,
+  defineConfig({
+    test: {
+      include: ["tests/client/unit/**/*.test.ts"],
+    },
+  }),
+);
 ```
 
 ```typescript
@@ -223,11 +210,14 @@ Test your Vue editor components with mocked Node-RED globals. Components that us
 import { defineConfig, mergeConfig } from "vitest/config";
 import { defaultConfig } from "@bonsae/nrg/test/client/component/config";
 
-export default mergeConfig(defaultConfig, defineConfig({
-  test: {
-    include: ["tests/client/component/**/*.test.ts"],
-  },
-}));
+export default mergeConfig(
+  defaultConfig,
+  defineConfig({
+    test: {
+      include: ["tests/client/component/**/*.test.ts"],
+    },
+  }),
+);
 ```
 
 ```typescript
@@ -239,7 +229,10 @@ import MyForm from "../src/client/components/my-form.vue";
 
 describe("MyForm", () => {
   test("renders fields from injected node", async () => {
-    const { provide } = createNode({ name: "test", url: "https://example.com" });
+    const { provide } = createNode({
+      name: "test",
+      url: "https://example.com",
+    });
     const screen = render(MyForm, {
       global: { provide },
     });

package/package.json

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

@@ -280,6 +280,8 @@ var Node = class _Node {
             throw error;
           }
         );
+        createdPromise.catch(() => {
+        });
         node[WIRE_HANDLERS](this, createdPromise);
       },
       {
@@ -288,7 +290,14 @@ var Node = class _Node {
       }
     );
     NodeClass.validateSettings(RED);
-    await Promise.resolve(NodeClass.registered?.(RED));
+    try {
+      await Promise.resolve(NodeClass.registered?.(RED));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      RED.log.error(
+        `Error during registered hook for ${NodeClass.type}: ${message}`
+      );
+    }
   }
   RED;
   node;
@@ -428,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;
@@ -459,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);
@@ -471,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);
@@ -486,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");
@@ -502,7 +529,8 @@ var IONode = class extends Node {
             error: {
               message: errorMsg,
               source: this.#nodeSource()
-            }
+            },
+            [INPUT_KEY]: msg
           });
           if (error instanceof Error) {
             nodeRedNode.error(
@@ -541,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");
@@ -557,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;
@@ -585,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;
@@ -614,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;
@@ -678,7 +754,8 @@ var IONode = class extends Node {
         error: {
           message,
           source: this.#nodeSource()
-        }
+        },
+        [INPUT_KEY]: msg
       });
     }
   }
@@ -1086,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;