@bonsae/nrg 0.25.0 → 0.26.0

package/test/server/unit/index.js

@@ -235,9 +235,191 @@ function createNodeRedNode(options = {}) {
   };
 }
 
+// src/core/validator.ts
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import addErrors from "ajv-errors";
+var Validator = class {
+  ajv;
+  constructor(options) {
+    const { customKeywords, customFormats, ...ajvOptions } = options || {};
+    this.ajv = new Ajv({
+      allErrors: true,
+      code: {
+        source: false
+      },
+      coerceTypes: true,
+      removeAdditional: false,
+      strict: false,
+      strictSchema: false,
+      useDefaults: true,
+      validateFormats: true,
+      // NOTE: typebox handles validation via typescript
+      // NOTE: if true, types that are not serializable JSON, like Function, would not work
+      validateSchema: false,
+      verbose: true,
+      ...ajvOptions
+    });
+    addFormats(this.ajv);
+    addErrors(this.ajv);
+    this.addCustomKeywords(customKeywords || []);
+    this.addCustomFormats(customFormats || {});
+  }
+  /**
+   * Add custom keywords to the validator
+   */
+  addCustomKeywords(keywords) {
+    if (!keywords) return;
+    keywords.forEach((keyword) => {
+      this.ajv.addKeyword(keyword);
+    });
+  }
+  /**
+   * Add custom formats to the validator
+   */
+  addCustomFormats(formats) {
+    if (!formats) return;
+    Object.entries(formats).forEach(([name, validator]) => {
+      if (validator instanceof RegExp) {
+        this.ajv.addFormat(name, validator);
+      } else {
+        this.ajv.addFormat(name, { validate: validator });
+      }
+    });
+  }
+  /**
+   * Create a validator function with caching
+   * @param schema - JSON Schema to validate against
+   * @param cacheKey - Optional cache key for reusing validators
+   */
+  createValidator(schema, cacheKey) {
+    if (cacheKey && !schema.$id) {
+      schema.$id = cacheKey;
+    }
+    if (schema.$id) {
+      const cached = this.ajv.getSchema(schema.$id);
+      if (cached) return cached;
+    }
+    const validator = this.ajv.compile(schema);
+    return validator;
+  }
+  /**
+   * Validate data against a schema and return a structured result
+   */
+  validate(data, schema, options) {
+    const validator = this.createValidator(schema, options?.cacheKey);
+    const valid = validator(data);
+    if (!valid) {
+      const errorMessage = this.formatErrors(validator.errors);
+      if (options?.throwOnError) {
+        throw new ValidationError(errorMessage, validator.errors || []);
+      }
+      return {
+        valid: false,
+        errors: validator.errors || void 0,
+        errorMessage
+      };
+    }
+    return {
+      valid: true,
+      data
+    };
+  }
+  /**
+   * Format errors into a human-readable string
+   */
+  formatErrors(errors, options) {
+    if (!errors || errors.length === 0) {
+      return "No errors";
+    }
+    return this.ajv.errorsText(errors, {
+      separator: "; ",
+      dataVar: "data",
+      ...options
+    });
+  }
+  /**
+   * Get detailed error information
+   */
+  getDetailedErrors(errors) {
+    if (!errors || errors.length === 0) return [];
+    return errors.map((error) => ({
+      field: error.instancePath || "/",
+      message: error.message || "Validation failed",
+      keyword: error.keyword,
+      params: error.params,
+      schemaPath: error.schemaPath
+    }));
+  }
+  /**
+   * Add a schema to the validator for reference
+   */
+  addSchema(schema, key) {
+    this.ajv.addSchema(schema, key);
+    return this;
+  }
+  /**
+   * Remove a schema from the validator
+   */
+  removeSchema(key) {
+    this.ajv.removeSchema(key);
+    return this;
+  }
+};
+var ValidationError = class _ValidationError extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+
+// src/core/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-_]+$/,
+        "flow-id": /^[a-f0-9]{16}$/,
+        "topic-path": (data) => /^[a-zA-Z0-9/_-]+$/.test(data)
+      }
+    })
+  };
+  Object.defineProperty(RED, "_nrg", {
+    value: nrg,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+  Object.defineProperty(RED, "validator", {
+    get: () => nrg.validator,
+    enumerable: false,
+    configurable: false
+  });
+}
+
+// src/core/server/nodes/symbols.ts
+var WIRE_HANDLERS = Symbol.for("nrg.wireHandlers");
+
 // src/test/server/unit/index.ts
-import { initValidator } from "@bonsae/nrg-runtime/internal/server";
-import { WIRE_HANDLERS } from "@bonsae/nrg-runtime/internal/server";
 import { Kind } from "@sinclair/typebox";
 function builtinPortIndex(node, name) {
   if (name !== "error" && name !== "complete" && name !== "status") {

package/types/client.d.ts

@@ -228,7 +228,7 @@ export interface TypedInputValue {
 /**
  * Maps a schema's static type to the raw values the editor form holds.
  * The server counterpart (`ResolvedStatic` in server/schemas/types) maps the
- * same brands — shared via core/brands — to resolved runtime values instead.
+ * same brands — shared via core/types — to resolved runtime values instead.
  * - `NodeRef<T>` → `string` (the referenced node's id)
  * - `TypedInput<T>` → `TypedInputValue` (raw value + type pair)
  * - Functions pass through, arrays and objects map recursively

package/types/server.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="./shims/typebox.d.ts" />
 // Generated by dts-bundle-generator v9.5.1
 
-import { Kind, ObjectOptions, SchemaOptions, Static, TArray, TBoolean, TConst, TEnum, TFunction, TInteger, TIntersect, TLiteral, TNull, TNumber, TObject, TOptional, TProperties, TRecord, TRef, TSchema, TString, TTuple, TUnion } from '@sinclair/typebox';
+import { Kind, ObjectOptions, SchemaOptions, Static, StringFormatOption, StringOptions, TArray, TBoolean, TConst, TEnum, TFunction, TInteger, TIntersect, TLiteral, TNull, TNumber, TObject, TOptional, TProperties, TRecord, TRef, TSchema, TString, TTuple, TUnion } from '@sinclair/typebox';
 import { EventEmitter } from 'events';
 import { Express as Express$1 } from 'express';
 import { Http2ServerRequest } from 'http2';
@@ -508,9 +508,14 @@ declare function NodeRef<T extends (new (...args: any[]) => any) & {
 	type: string;
 }>(nodeClass: T, options?: NrgSchemaOptions): TNodeRef<InstanceType<T>>;
 declare function TypedInput$1<T = unknown>(options?: NrgSchemaOptions): TTypedInput<T>;
+type NrgStringFormat = StringFormatOption | "password" | "byte" | "binary" | "url" | "duration" | "iso-time" | "iso-date-time" | "json-pointer-uri-fragment";
+interface NrgStringOptions extends Omit<StringOptions, "format"> {
+	format?: NrgStringFormat;
+}
+declare function NrgString(options?: NrgStringOptions): TString;
 declare function OutputReturnProperties(options?: NrgSchemaOptions & {
 	default?: Record<number, string>;
-}): import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString>;
+}): import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TNumber, TString>;
 declare function OutputContextModes(options?: NrgSchemaOptions & {
 	default?: Record<number, "carry" | "trace" | "reset">;
 }): import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TUnion<[
@@ -530,6 +535,7 @@ declare function OutputContextModes(options?: NrgSchemaOptions & {
  * use {@link NodeRef} / {@link TypedInput} instead. See the Schemas guide.
  */
 export declare const SchemaType: import("@sinclair/typebox").JavaScriptTypeBuilder & {
+	String: typeof NrgString;
 	NodeRef: typeof NodeRef;
 	TypedInput: typeof TypedInput$1;
 	OutputReturnProperties: typeof OutputReturnProperties;

package/types/shims/components.d.ts

@@ -11,13 +11,13 @@ declare module "vue" {
   }
 
   export interface GlobalComponents {
-    NodeRedConfigInput: (typeof import("./client/form/components/node-red-config-input.vue"))["default"];
-    NodeRedEditorInput: (typeof import("./client/form/components/node-red-editor-input.vue"))["default"];
-    NodeRedInputLabel: (typeof import("./client/form/components/node-red-input-label.vue"))["default"];
-    NodeRedInput: (typeof import("./client/form/components/node-red-input.vue"))["default"];
-    NodeRedJsonSchemaForm: (typeof import("./client/form/components/node-red-json-schema-form.vue"))["default"];
-    NodeRedSelectInput: (typeof import("./client/form/components/node-red-select-input.vue"))["default"];
-    NodeRedToggle: (typeof import("./client/form/components/node-red-toggle.vue"))["default"];
-    NodeRedTypedInput: (typeof import("./client/form/components/node-red-typed-input.vue"))["default"];
+    NodeRedConfigInput: (typeof import("./core/client/form/components/node-red-config-input.vue"))["default"];
+    NodeRedEditorInput: (typeof import("./core/client/form/components/node-red-editor-input.vue"))["default"];
+    NodeRedInputLabel: (typeof import("./core/client/form/components/node-red-input-label.vue"))["default"];
+    NodeRedInput: (typeof import("./core/client/form/components/node-red-input.vue"))["default"];
+    NodeRedJsonSchemaForm: (typeof import("./core/client/form/components/node-red-json-schema-form.vue"))["default"];
+    NodeRedSelectInput: (typeof import("./core/client/form/components/node-red-select-input.vue"))["default"];
+    NodeRedToggle: (typeof import("./core/client/form/components/node-red-toggle.vue"))["default"];
+    NodeRedTypedInput: (typeof import("./core/client/form/components/node-red-typed-input.vue"))["default"];
   }
 }

package/types/shims/{client → core/client}/types.d.ts

@@ -1,7 +1,7 @@
 import type { Component, App } from "vue";
 import type { TSchema, Static } from "@sinclair/typebox";
 import type { SchemaObject } from "ajv";
-import type { NodeRefResolved, TypedInputResolved } from "../brands";
+import type { NodeRefResolved, TypedInputResolved } from "../types";
 import type { JsonSchemaObjectExtensions } from "../schema-options";
 export interface NodeStateCredentials {
     [key: string]: any;
@@ -200,7 +200,7 @@ export interface TypedInputValue {
 /**
  * Maps a schema's static type to the raw values the editor form holds.
  * The server counterpart (`ResolvedStatic` in server/schemas/types) maps the
- * same brands — shared via core/brands — to resolved runtime values instead.
+ * same brands — shared via core/types — to resolved runtime values instead.
  * - `NodeRef<T>` → `string` (the referenced node's id)
  * - `TypedInput<T>` → `TypedInputValue` (raw value + type pair)
  * - Functions pass through, arrays and objects map recursively

package/types/shims/core/schema-options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * NRG's JSON Schema vocabulary — the custom keywords the server emits onto
+ * serialized schemas and the client consumes for form rendering and
+ * validation. Shared at the core root (like types.ts) so both planes derive
+ * from one definition instead of drifting copies.
+ */
+export interface JsonSchemaObjectExtensions {
+    format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+    /** expose this settings property to the editor via RED.settings */
+    exportable?: boolean;
+    /** set by SchemaType.NodeRef — the referenced config node type */
+    "x-nrg-node-type"?: string;
+    /** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+    "x-nrg-typed-input"?: boolean;
+    /** set by markNonValidatable — ajv skips this property */
+    "x-nrg-skip-validation"?: boolean;
+    /** form rendering hints consumed by the auto-generated editor form */
+    "x-nrg-form"?: {
+        icon?: string;
+        typedInputTypes?: string[];
+        editorLanguage?: string;
+        toggle?: boolean;
+    };
+}

package/types/shims/schema-options.d.ts

@@ -1,24 +1,24 @@
 /**
  * NRG's JSON Schema vocabulary — the custom keywords the server emits onto
  * serialized schemas and the client consumes for form rendering and
- * validation. Shared at the core root (like brands.ts) so both planes derive
+ * validation. Shared at the core root (like types.ts) so both planes derive
  * from one definition instead of drifting copies.
  */
 export interface JsonSchemaObjectExtensions {
-    format?: "node-id" | "flow-id" | "topic-path" | (string & {});
-    /** expose this settings property to the editor via RED.settings */
-    exportable?: boolean;
-    /** set by SchemaType.NodeRef — the referenced config node type */
-    "x-nrg-node-type"?: string;
-    /** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
-    "x-nrg-typed-input"?: boolean;
-    /** set by markNonValidatable — ajv skips this property */
-    "x-nrg-skip-validation"?: boolean;
-    /** form rendering hints consumed by the auto-generated editor form */
-    "x-nrg-form"?: {
-        icon?: string;
-        typedInputTypes?: string[];
-        editorLanguage?: string;
-        toggle?: boolean;
-    };
+  format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+  /** expose this settings property to the editor via RED.settings */
+  exportable?: boolean;
+  /** set by SchemaType.NodeRef — the referenced config node type */
+  "x-nrg-node-type"?: string;
+  /** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+  "x-nrg-typed-input"?: boolean;
+  /** set by markNonValidatable — ajv skips this property */
+  "x-nrg-skip-validation"?: boolean;
+  /** form rendering hints consumed by the auto-generated editor form */
+  "x-nrg-form"?: {
+    icon?: string;
+    typedInputTypes?: string[];
+    editorLanguage?: string;
+    toggle?: boolean;
+  };
 }

package/types/test-client-component-schemas.d.ts

@@ -0,0 +1,73 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { ProvidedContext } from 'vitest';
+
+interface GlobalSetupContext {
+	provide<K extends keyof ProvidedContext>(key: K, value: ProvidedContext[K]): void;
+}
+/**
+ * A node's schemas, serialized to plain JSON. This is the exact shape the vite
+ * plugin injects into the production editor bundle (`JSON.stringify` of the
+ * TypeBox schema), so component tests validate against the same data the real
+ * form does — with no TypeBox `Kind` symbols or server runtime in the browser.
+ */
+export interface SerializedNodeSchemas {
+	configSchema?: Record<string, unknown>;
+	credentialsSchema?: Record<string, unknown>;
+}
+interface NodeClass {
+	type?: string;
+	configSchema?: unknown;
+	credentialsSchema?: unknown;
+}
+interface Registry {
+	nodes?: NodeClass[];
+}
+/**
+ * Serializes every node in a registry (`defineModule({ nodes })`) to a map
+ * keyed by node `type`. Pure data in, pure data out — runs in Node.
+ */
+export declare function serializeRegistry(registry: Registry | undefined): Record<string, SerializedNodeSchemas>;
+/**
+ * Builds a vitest `globalSetup` that serializes an explicitly-provided node
+ * registry and provides it to component tests. Use this when your registry is
+ * not at the conventional `src/server` entry; otherwise reference the default
+ * export of this module directly from your config.
+ *
+ * @example
+ * ```ts
+ * // tests/client/component/schemas.ts
+ * import { provideSchemas } from "@bonsae/nrg/test/client/component/schemas";
+ * import registry from "../../../src/server";
+ * export default provideSchemas(registry);
+ * ```
+ */
+export declare function provideSchemas(registry: Registry): ({ provide }: GlobalSetupContext) => void;
+/**
+ * Imports a package's node registry from the conventional `src/server` entry.
+ * Resolves the default export (`defineModule({ nodes })`), or the module itself
+ * if it exposes `nodes` directly. Runs in Node, so the server import is safe.
+ *
+ * @param cwd Package root to resolve `src/server/index.ts` against. Defaults to
+ * the working directory (where vitest runs), which is the package root.
+ */
+export declare function loadRegistry(cwd?: string): Promise<Registry>;
+/**
+ * Convention `globalSetup`: serializes the package's node registry — the
+ * default export of `src/server` — and provides every node's schemas as data,
+ * so component tests validate against the real schema WITHOUT value-importing
+ * the server runtime into the browser. `createNode({ type })` reads it back.
+ *
+ * Reference it directly from your vitest config — no per-package file needed:
+ *
+ * ```ts
+ * test: { globalSetup: ["@bonsae/nrg/test/client/component/schemas"] }
+ * ```
+ */
+declare function _default({ provide }: GlobalSetupContext): Promise<void>;
+
+export {
+	_default as default,
+};
+
+export {};

package/types/test-client-component.d.ts

@@ -1,13 +1,125 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { TSchema } from '@sinclair/typebox';
+import { Static, TSchema } from '@sinclair/typebox';
+import { SchemaObject } from 'ajv';
+import { App } from 'vue';
 
-export declare function useFormNode<TConfig extends TSchema = TSchema, TCredentials extends TSchema = TSchema>(): {
-	node: Record<string, any>;
-	schema: Record<string, any>;
-	errors: Record<string, string>;
-};
-type JsonSchemaObject = Record<string, any>;
+interface NodeRefResolved<T = any> {
+	readonly __nrg_node_ref: true;
+	readonly __instance: T;
+}
+interface TypedInputResolved {
+	resolve(...args: any[]): any;
+	value: unknown;
+	type: string;
+}
+interface JsonSchemaObjectExtensions {
+	format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+	/** expose this settings property to the editor via RED.settings */
+	exportable?: boolean;
+	/** set by SchemaType.NodeRef — the referenced config node type */
+	"x-nrg-node-type"?: string;
+	/** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+	"x-nrg-typed-input"?: boolean;
+	/** set by markNonValidatable — ajv skips this property */
+	"x-nrg-skip-validation"?: boolean;
+	/** form rendering hints consumed by the auto-generated editor form */
+	"x-nrg-form"?: {
+		icon?: string;
+		typedInputTypes?: string[];
+		editorLanguage?: string;
+		toggle?: boolean;
+	};
+}
+interface NodeRedNodeButtonDefinition {
+	toggle: string;
+	onclick: () => void;
+	enabled?: () => boolean;
+	visible?: () => boolean;
+}
+interface NodeRedNode {
+	id: string;
+	type: string;
+	name: string;
+	category: string;
+	x: string;
+	y: string;
+	g: string;
+	z: string;
+	credentials: Record<string, any>;
+	_def: {
+		defaults: Record<string, {
+			value: string;
+			type?: string;
+			label?: string;
+			required?: boolean;
+		}>;
+		credentials: Record<string, {
+			value: string;
+			type?: "password" | "text";
+			label?: string;
+			required?: boolean;
+		}>;
+		category: string;
+		color?: string;
+		icon?: string;
+		label?: ((this: NodeRedNode) => string) | string;
+		inputs?: number;
+		outputs?: number;
+		paletteLabel?: ((this: NodeRedNode) => string) | string;
+		labelStyle?: ((this: NodeRedNode) => string) | string;
+		inputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+		outputLabels?: ((this: NodeRedNode, index: number) => string) | string;
+		align?: "left" | "right";
+		button?: NodeRedNodeButtonDefinition;
+	};
+	_newState?: NodeRedNode;
+	_app?: App | null;
+	_: (str: string) => string;
+	/** dynamic port count (base outputs + enabled built-in ports) */
+	outputs?: number;
+	/** injected when the node has an inputSchema */
+	validateInput?: boolean;
+	/** built-in port toggles, present when declared in the configSchema */
+	errorPort?: boolean;
+	completePort?: boolean;
+	statusPort?: boolean;
+	/**
+	 * Per-port output settings, indexed by base-output port. `validateOutputs` is
+	 * injected (empty) when the node has an outputsSchema; `outputReturnProperties`
+	 * and `outputContextModes` are author-declared (SchemaType.*) — present only
+	 * when the node opts into per-port return keys / context modes. Read at
+	 * runtime by IONode.
+	 */
+	validateOutputs?: Record<number, boolean>;
+	outputContextModes?: Record<number, "carry" | "trace" | "reset">;
+	outputReturnProperties?: Record<number, string>;
+	[key: string]: any;
+}
+interface JsonPropertySchema extends JsonSchemaObjectExtensions {
+	type?: string | string[];
+	properties?: Record<string, JsonPropertySchema>;
+	required?: string[];
+	enum?: unknown[];
+	anyOf?: JsonPropertySchema[];
+	const?: unknown;
+	items?: JsonPropertySchema;
+	title?: string;
+	description?: string;
+	default?: unknown;
+}
+interface JsonSchemaObject extends SchemaObject {
+	type: "object";
+	properties?: Record<string, JsonPropertySchema>;
+	required?: string[];
+}
+interface TypedInputValue {
+	value: string;
+	type: string;
+}
+type EditorStatic<T> = T extends NodeRefResolved<any> ? string : T extends TypedInputResolved ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? EditorStatic<I>[] : T extends object ? {
+	[K in keyof T]: EditorStatic<T[K]>;
+} : T;
 export interface MockEditor {
 	getValue(): string;
 	setValue(val: string): void;
@@ -104,6 +216,30 @@ export interface MockRED {
 	settings: MockSettings;
 	notify(message: any, options?: Record<string, any>): MockNotification;
 }
+interface FormNode<TConfig extends TSchema = TSchema, TCredentials extends TSchema = TSchema> {
+	node: NodeRedNode & EditorStatic<Static<TConfig>> & {
+		credentials: EditorStatic<Static<TCredentials>> & Record<string, any>;
+	};
+	schema: Record<string, any>;
+	errors: Record<string, string>;
+}
+/**
+ * Composable that provides typed access to the form node, schema, and errors.
+ * Replaces `defineProps` in custom form components — no props declaration needed.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFormNode } from "@bonsae/nrg/client";
+ * import type { ConfigsSchema, CredentialsSchema } from "../../server/schemas/my-node";
+ *
+ * const { node, errors } = useFormNode<typeof ConfigsSchema, typeof CredentialsSchema>();
+ * node.name      // string — typed from ConfigsSchema
+ * node.credentials.apiKey  // string — typed from CredentialsSchema
+ * </script>
+ * ```
+ */
+export declare function useFormNode<TConfig extends TSchema = TSchema, TCredentials extends TSchema = TSchema>(): FormNode<TConfig, TCredentials>;
 export interface TestNode {
 	id: string;
 	type: string;
@@ -125,6 +261,16 @@ export interface CreateNodeResult {
 	provide: FormProvide;
 }
 export interface CreateNodeOptions {
+	/**
+	 * The node's registered `type`. When set, createNode resolves each schema not
+	 * passed explicitly (configSchema/credentialsSchema) from the map serialized
+	 * by the `schemas` globalSetup — so the test validates against the production
+	 * schema without importing it. Used only for schema lookup; the harness keeps
+	 * its own unique internal node type. Note: this is a reserved options key — a
+	 * raw-shorthand config object that itself carries a `type` field must be
+	 * passed via the explicit `{ configs }` form.
+	 */
+	type?: string;
 	configs?: Record<string, any>;
 	credentials?: Record<string, any>;
 	configSchema?: JsonSchemaObject;