@bonsae/nrg 0.16.0 → 0.18.0

package/README.md

@@ -11,8 +11,7 @@
 
 # nrg
 
-Build Node-RED nodes with Vue 3, TypeScript, JSON Schema validations, Vite and Vistest.
-
+Build Node-RED nodes with Vue 3, TypeScript, JSON Schema validations, Vite and Vitest.
 
 ## Package Exports
 
@@ -20,9 +19,21 @@ Build Node-RED nodes with Vue 3, TypeScript, JSON Schema validations, Vite and V
 | --- | --- |
 | `@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`) |
+| `@bonsae/nrg/client` | Client-side registration (`registerTypes`, `defineNode`, `useFormNode`, `Infer`) |
 | `@bonsae/nrg/vite` | Vite plugin for building and developing Node-RED packages |
-| `@bonsae/nrg/tsconfig/*` | Shared TypeScript configurations for consumers |
+| `@bonsae/nrg/test/server/unit` | Server unit test helpers (`createNode`, `createRED`, `MockRED`) |
+| `@bonsae/nrg/test/client/unit` | Client unit test config and mocks (`defaultConfig`, `createRED`, `createJQuery`) |
+| `@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`, `defaultConfig`, `createRED`, `createJQuery`) |
+| `@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
 
@@ -32,7 +43,7 @@ pnpm add @bonsae/nrg
 pnpm add -D vite vue
 ```
 
-> `vite` ane `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.
+> `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.
 
 **vite.config.ts**
 
@@ -55,7 +66,7 @@ export const ConfigsSchema = defineSchema(
     name: SchemaType.String({ default: "" }),
     prefix: SchemaType.String({ default: "hello" }),
   },
-  { $id: "my-node:configs" }
+  { $id: "my-node:configs" },
 );
 ```
 
@@ -95,7 +106,7 @@ type Config = Infer<typeof ConfigsSchema>;
 type Input = Infer<typeof InputSchema>;
 type Output = Infer<typeof OutputSchema>;
 
-export default class MyNode extends IONode<Config, any, Input, Output> {
+export default class MyNode extends IONode<Config, never, Input, Output> {
   static readonly type = "my-node";
   static readonly category = "function";
   static readonly color: `#${string}` = "#ffffff";
@@ -131,16 +142,18 @@ See the [consumer template](https://github.com/AllanOricil/node-red-vue-template
 
 ## Testing
 
-Test your nodes' server-side logic with `@bonsae/nrg/test`:
+NRG provides four test libraries:
 
-```bash
-pnpm add -D vitest
-```
+- `@bonsae/nrg/test/server/unit` — server-side unit tests
+- `@bonsae/nrg/test/client/unit` — client-side unit tests (TypeScript logic)
+- `@bonsae/nrg/test/client/component` — client component tests (Vue + browser)
+- `@bonsae/nrg/test/client/e2e` — browser E2E tests (Playwright)
+
+### Server Unit Tests
 
 ```typescript
-// tests/my-node.test.ts
 import { describe, it, expect } from "vitest";
-import { createNode } from "@bonsae/nrg/test";
+import { createNode } from "@bonsae/nrg/test/server/unit";
 import MyNode from "../src/server/nodes/my-node";
 
 describe("my-node", () => {
@@ -156,18 +169,98 @@ describe("my-node", () => {
 });
 ```
 
-```bash
-npx vitest run
+### Client Unit Tests
+
+Test client-side TypeScript logic (validation, utilities) with mocked `RED` and `$` globals:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { defaultConfig } from "@bonsae/nrg/test/client/unit";
+
+export default defineConfig({
+  test: {
+    ...defaultConfig,
+  },
+});
+```
+
+```typescript
+// tests/client/unit/my-util.test.ts
+import { describe, it, expect } from "vitest";
+import { myUtil } from "../src/client/my-util";
+
+describe("myUtil", () => {
+  it("works with RED globals", () => {
+    expect(myUtil("input")).toBe("expected");
+  });
+});
 ```
 
+### Client Component Tests
+
+Test your Vue editor components with mocked Node-RED globals:
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { playwright } from "@vitest/browser-playwright";
+import vue from "@vitejs/plugin-vue";
+import { defaultConfig } from "@bonsae/nrg/test/client/component";
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    ...defaultConfig,
+    browser: {
+      ...defaultConfig.browser,
+      provider: playwright(),
+    },
+  },
+});
+```
+
+```typescript
+// tests/client/component/my-component.test.ts
+import { describe, test, expect, vi } from "vitest";
+import { render } from "vitest-browser-vue";
+import { createNode } from "@bonsae/nrg/test/client/component";
+import MyComponent from "../src/client/components/my-component.vue";
+
+describe("MyComponent", () => {
+  test("renders with node props", async () => {
+    const { node } = createNode({ name: "test" });
+    const screen = render(MyComponent, {
+      props: { node },
+    });
+    await expect.element(screen.getByText("test")).toBeInTheDocument();
+  });
+
+  test("calls RED.editor API", async () => {
+    const { node, RED } = createNode();
+    render(MyComponent, { props: { node, value: "" } });
+    expect(RED.editor.createEditor).toHaveBeenCalled();
+  });
+});
+```
+
+See the [testing guide](https://bonsaedev.github.io/nrg/guide/testing) for full API reference.
+
 ## Development
 
 ```bash
 pnpm install
-pnpm build          # build all (server CJS, client ESM, vite plugin)
-pnpm typecheck      # type-check server and client
-pnpm lint           # eslint
-pnpm format         # prettier
+pnpm build                        # build all (server, client, vite plugin, test libs)
+pnpm validate                     # type-check + lint + format check
+pnpm validate:tsc                 # type-check all tsconfigs
+pnpm validate:lint                # eslint
+pnpm validate:format              # prettier check
+pnpm test                         # run all tests
+pnpm test:core:server:unit        # server unit tests
+pnpm test:core:client:unit        # client unit tests
+pnpm test:core:client:component   # client component tests
+pnpm test:core:client:e2e         # client E2E tests
+pnpm docs:dev                     # start docs dev server
 ```
 
 ## License

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "NRG framework — build Node-RED nodes with Vue 3, TypeScript, and JSON Schema",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",
   "type": "module",
+  "homepage": "https://bonsaedev.github.io/nrg/",
   "repository": {
     "url": "https://github.com/bonsaedev/nrg",
     "type": "git"
@@ -16,6 +17,19 @@
     "node": ">=20.19",
     "pnpm": ">=10.11.0"
   },
+  "keywords": [
+    "node-red",
+    "vue",
+    "vue3",
+    "typescript",
+    "json-schema",
+    "vite",
+    "vitest",
+    "iot",
+    "automation",
+    "low-code",
+    "framework"
+  ],
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
@@ -33,13 +47,31 @@
       "types": "./types/vite.d.ts",
       "default": "./vite/index.js"
     },
-    "./test": {
-      "types": "./types/test.d.ts",
-      "default": "./test/index.js"
+    "./test/server/unit": {
+      "types": "./types/test-server-unit.d.ts",
+      "default": "./test/server/unit/index.js"
+    },
+    "./test/client/component": {
+      "types": "./types/test-client-component.d.ts",
+      "default": "./test/client/component/index.js"
+    },
+    "./test/client/component/setup": "./test/client/component/setup.js",
+    "./test/client/unit": {
+      "types": "./types/test-client-unit.d.ts",
+      "default": "./test/client/unit/index.js"
+    },
+    "./test/client/unit/setup": "./test/client/unit/setup.js",
+    "./test/client/e2e": {
+      "types": "./types/test-client-e2e.d.ts",
+      "default": "./test/client/e2e/index.js"
     },
     "./tsconfig/base.json": "./tsconfig/base.json",
-    "./tsconfig/client.json": "./tsconfig/client.json",
-    "./tsconfig/server.json": "./tsconfig/server.json"
+    "./tsconfig/core/server.json": "./tsconfig/core/server.json",
+    "./tsconfig/core/client.json": "./tsconfig/core/client.json",
+    "./tsconfig/test/server/unit.json": "./tsconfig/test/server/unit.json",
+    "./tsconfig/test/client/component.json": "./tsconfig/test/client/component.json",
+    "./tsconfig/test/client/unit.json": "./tsconfig/test/client/unit.json",
+    "./tsconfig/test/client/e2e.json": "./tsconfig/test/client/e2e.json"
   },
   "peerDependencies": {
     "vite": "^6.0.0",

package/server/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   ErrorPortSchema: () => ErrorPortSchema,
   IONode: () => IONode,
   Node: () => Node,
+  NodeSourceSchema: () => NodeSourceSchema,
   NrgError: () => NrgError,
   SchemaType: () => SchemaType,
   StatusPortSchema: () => StatusPortSchema,
@@ -449,6 +450,11 @@ var IONode = class extends Node {
           `outputsSchema record key "${key}" in ${this.type} looks numeric. Use descriptive string names (e.g. "success", "failure") to avoid JavaScript object key ordering issues.`
         );
       }
+      if (key === "error" || key === "complete" || key === "status") {
+        throw new NrgError(
+          `outputsSchema record key "${key}" in ${this.type} is reserved for built-in ports. Use a different name (e.g. "failed" instead of "error").`
+        );
+      }
     }
     return keys.length;
   }
@@ -579,10 +585,11 @@ var IONode = class extends Node {
       }
       this.log("Output is valid");
     }
+    const out = Array.isArray(msg) ? msg.slice(0, this.baseOutputs) : msg;
     if (this.#send) {
-      this.#send(msg);
+      this.#send(out);
     } else {
-      this.node.send(msg);
+      this.node.send(out);
     }
   }
   // --- Built-in port management ---
@@ -599,16 +606,20 @@ var IONode = class extends Node {
   }
   /**
    * Send a message to a specific output port by index or name.
-   * Built-in port `"status"` is resolved automatically based on the node's
-   * built-in port configuration.
    * Custom named ports are resolved from `outputsSchema` when it is a record.
    * Numeric indices refer to the base output ports (0-based).
    *
-   * Note: `"error"` and `"complete"` ports are managed by the framework and
-   * cannot be sent to directly. Throw an error to trigger the error port,
-   * and the complete port is sent automatically on successful input processing.
+   * Built-in ports (`"error"`, `"complete"`, `"status"`) are managed by the
+   * 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.
    */
   sendToPort(port, msg) {
+    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);
   }
   #sendToPort(port, msg) {
@@ -652,10 +663,9 @@ var IONode = class extends Node {
       name: this.name
     };
   }
-  status(status, data) {
+  status(status) {
     this.node.status(status);
     this.#sendToPort("status", {
-      ...data,
       status,
       source: this.#nodeSource()
     });
@@ -1185,21 +1195,24 @@ var CompletePortSchema = SchemaType.Object({
   })
 });
 var StatusPortSchema = SchemaType.Object({
-  status: SchemaType.Object({
-    fill: SchemaType.Optional(
-      SchemaType.Union([
-        SchemaType.Literal("red"),
-        SchemaType.Literal("green")
-      ])
-    ),
-    shape: SchemaType.Optional(
-      SchemaType.Union([
-        SchemaType.Literal("dot"),
-        SchemaType.Literal("string")
-      ])
-    ),
-    text: SchemaType.Optional(SchemaType.String())
-  }),
+  status: SchemaType.Union([
+    SchemaType.Object({
+      fill: SchemaType.Optional(
+        SchemaType.Union([
+          SchemaType.Literal("red"),
+          SchemaType.Literal("green")
+        ])
+      ),
+      shape: SchemaType.Optional(
+        SchemaType.Union([
+          SchemaType.Literal("dot"),
+          SchemaType.Literal("string")
+        ])
+      ),
+      text: SchemaType.Optional(SchemaType.String())
+    }),
+    SchemaType.String()
+  ]),
   source: NodeSourceSchema
 });
 
@@ -1214,6 +1227,7 @@ function defineModule(definition) {
   ErrorPortSchema,
   IONode,
   Node,
+  NodeSourceSchema,
   NrgError,
   SchemaType,
   StatusPortSchema,