@bonsae/nrg 0.1.0

package/src/core/server/index.ts

@@ -0,0 +1,209 @@
+import path from "path";
+import fs from "fs";
+import { getCredentialsFromSchema } from "./utils";
+import { Node } from "./nodes";
+import { type RED } from "./types";
+import { initValidator } from "./validator";
+
+const MIME: Record<string, string> = {
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+};
+
+let _nrgResourcesRegistered = false;
+
+function serveNrgResources(RED: RED): void {
+  if (_nrgResourcesRegistered) return;
+  _nrgResourcesRegistered = true;
+
+  const clientDir = path.resolve(__dirname, "./resources");
+  if (!fs.existsSync(clientDir)) return;
+
+  const httpAdmin = (RED as any).httpAdmin;
+  if (!httpAdmin) return;
+
+  // /nrg/assets/ is not handled by Node-RED's editorApp, so our handler
+  // appended via use() is reached normally without any stack manipulation.
+  httpAdmin.use(function (req: any, res: any, next: any) {
+    const prefix = "/nrg/assets/";
+    if (!(req.path as string).startsWith(prefix)) return next();
+    const reqPath = (req.path as string)
+      .slice(prefix.length)
+      .replace(/\.\./g, "");
+    const filePath = path.resolve(clientDir, reqPath);
+    if (!filePath.startsWith(clientDir)) return next();
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+      return next();
+    const ext = path.extname(filePath);
+    res.setHeader("Content-Type", MIME[ext] ?? "application/octet-stream");
+    fs.createReadStream(filePath).pipe(res);
+  });
+}
+
+type AnyNodeClass = (abstract new (...args: any[]) => Node) &
+  Partial<typeof Node>;
+
+/**
+ * Registers a custom node with Node-RED.
+ *
+ * @param RED - The Node-RED runtime API object
+ * @param NodeClass - A node class extending Node, IONode, or ConfigNode
+ * @throws If NodeClass does not extend Node
+ * @throws If NodeClass.type is not defined
+ */
+async function registerType(RED: RED, NodeClass: AnyNodeClass) {
+  const NC = NodeClass as any;
+  RED.log.debug(`Registering Type: ${NC.type}`);
+  if (!(NC.prototype instanceof Node)) {
+    throw new Error(`${NC.name} must extend IONode or ConfigNode classes`);
+  }
+
+  if (!NC.type) {
+    throw new Error("type must be provided when registering the node");
+  }
+
+  if (NC.color && !/^#[0-9A-Fa-f]{6}$/.test(NC.color)) {
+    throw new Error(
+      `Invalid color for ${NodeClass.type}: ${NC.color} color must be in hex format`,
+    );
+  }
+
+  if (
+    NC.inputs !== undefined &&
+    (!Number.isInteger(NC.inputs) || (NC.inputs != 0 && NC.inputs != 1))
+  ) {
+    throw new Error(
+      `Invalid number of inputs for ${NodeClass.type}: inputs must be 0 or 1`,
+    );
+  }
+
+  if (
+    NC.outputs !== undefined &&
+    (!Number.isInteger(NC.outputs) || NC.outputs < 0)
+  ) {
+    throw new Error(
+      `Invalid number of outputs for ${NodeClass.type}: outputs must be a positive integer`,
+    );
+  }
+
+  RED.nodes.registerType(
+    NC.type,
+    function (this: any, config: any) {
+      RED.nodes.createNode(this, config);
+      const node = new NC(RED, this, config, this.credentials);
+      // NOTE: save node intance inside node-red's node so that the proxy can resolve it lazyly
+      this._node = node;
+
+      // NOTE: created promise must be here because we only want it to start after the whole object creation chain has been completed: child -> IONode -> Node -> IONode -> child -> done
+      const createdPromise = Promise.resolve(node.created?.()).catch(
+        (error: any) => {
+          this.error("Error during created hook: " + error.message);
+          throw error;
+        },
+      );
+
+      this.on(
+        "input",
+        async (
+          msg: unknown,
+          send: (msg: unknown) => void,
+          done: (err?: Error) => void,
+        ) => {
+          try {
+            await createdPromise;
+          } catch {
+            done(new Error("Node failed to initialize"));
+            return;
+          }
+
+          try {
+            this.log("Calling input");
+            await Promise.resolve(node._input(msg, send));
+            done();
+            this.log("Input processed");
+          } catch (error) {
+            if (error instanceof Error) {
+              this.error("Error while processing input: " + error.message, msg);
+              done(error);
+            } else {
+              this.error("Unknown error occurred during input handling", msg);
+              done(new Error("Unknown error during input handling"));
+            }
+          }
+        },
+      );
+
+      this.on(
+        "close",
+        async (removed: boolean, done: (err?: Error) => void) => {
+          try {
+            this.log("Calling closed");
+            await Promise.resolve(node._closed(removed));
+            this.log("Node was closed");
+            done();
+          } catch (error) {
+            if (error instanceof Error) {
+              this.error("Error while closing node: " + error.message);
+              done(error);
+            } else {
+              this.error("Unknown error occurred while closing node");
+              done(new Error("Unknown error occurred while closing node"));
+            }
+          }
+        },
+      );
+    },
+    {
+      credentials: NC.credentialsSchema
+        ? getCredentialsFromSchema(NC.credentialsSchema)
+        : {},
+      settings: NC._settings?.(),
+    },
+  );
+
+  await Promise.resolve(NC._registered?.(RED));
+
+  RED.log.debug(`Type registered: ${NC.type}`);
+}
+
+type NodeRedPackageFunction = ((RED: RED) => Promise<void>) & {
+  nodes: AnyNodeClass[];
+};
+
+/**
+ * Registers multiple node classes with Node-RED.
+ *
+ * Returns a Node-RED package function that Node-RED calls with the RED
+ * runtime object when loading the package.
+ *
+ * @param nodes - Array of node classes to register
+ */
+function registerTypes(nodes: AnyNodeClass[]): NodeRedPackageFunction {
+  const fn = async function (RED: RED) {
+    initValidator(RED);
+    serveNrgResources(RED);
+    try {
+      RED.log.info("Registering node types in series");
+      for (const NodeClass of nodes) {
+        await registerType(RED, NodeClass);
+      }
+      RED.log.info("All node types registered in series");
+    } catch (error) {
+      RED.log.error("Error registering node types:", error);
+      throw error;
+    }
+  };
+  (fn as NodeRedPackageFunction).nodes = nodes;
+  return fn as NodeRedPackageFunction;
+}
+
+export { registerType, registerTypes };
+export { Node, IONode, ConfigNode } from "./nodes";
+export type { RED } from "./types";
+export { SchemaType, defineSchema } from "./schemas";
+export type { Schema, Infer } from "./schemas/types";

package/src/core/server/nodes/config-node.ts

@@ -0,0 +1,67 @@
+import type { RED } from "../../server/types";
+import { Node } from "./node";
+import type {
+  ConfigNodeConfig,
+  ConfigNodeContext,
+  ConfigNodeCredentials,
+} from "./types";
+import { setupContext } from "./utils";
+
+abstract class ConfigNode<
+  TConfig = any,
+  TCredentials = any,
+  TSettings = any,
+> extends Node<TConfig, TCredentials, TSettings> {
+  public static override readonly category: string = "config";
+  declare public readonly config: ConfigNodeConfig<TConfig>;
+
+  protected override readonly context: ConfigNodeContext;
+
+  // NOTE: used by the registered function. Had to be a different one to avoid calling the parent's input again
+  /** @internal */
+  public static override _registered(RED: RED): void | Promise<void> {
+    this.validateSettings(RED);
+    return this.registered?.(RED);
+  }
+
+  constructor(
+    RED: RED,
+    node: any,
+    config: ConfigNodeConfig<TConfig>,
+    credentials: ConfigNodeCredentials<TCredentials>,
+  ) {
+    super(RED, node, config, credentials);
+
+    const context = node.context();
+    const fn = (scope: "node" | "global", store?: string) => {
+      const target = scope === "global" ? context.global : context;
+      return setupContext(target, store);
+    };
+    fn.node = setupContext(context);
+    fn.global = setupContext(context.global);
+
+    this.context = fn as any;
+  }
+
+  get userIds(): string[] {
+    return this.config._users;
+  }
+
+  get users(): Node[] {
+    return this.userIds
+      .map((id) => this.RED.nodes.getNode(id)?._node)
+      .filter((node): node is Node => node != null);
+  }
+
+  getUser<T extends Node = Node>(index: number): T | undefined {
+    const id = this.userIds[index];
+    if (!id) return undefined;
+    return this.RED.nodes.getNode(id)?._node as T | undefined;
+  }
+
+  override get credentials(): ConfigNodeCredentials<TCredentials> | undefined {
+    return this.node.credentials;
+  }
+}
+
+export { ConfigNode };

package/src/core/server/nodes/index.ts

@@ -0,0 +1,4 @@
+export { Node } from "./node";
+export { IONode } from "./io-node";
+export { ConfigNode } from "./config-node";
+export type * from "./types";

package/src/core/server/nodes/io-node.ts

@@ -0,0 +1,178 @@
+import type { Schema } from "../schemas/types";
+import type { RED } from "../../server/types";
+import { validator } from "../validator";
+import { Node } from "./node";
+import type {
+  IONodeContext,
+  IONodeContextScope,
+  IONodeStatus,
+  IONodeConfig,
+  IONodeCredentials,
+} from "./types";
+import { setupContext } from "./utils";
+
+abstract class IONode<
+  TConfig = any,
+  TCredentials = any,
+  TInput = any,
+  TOutput = any,
+  TSettings = any,
+> extends Node<TConfig, TCredentials, TSettings> {
+  public static readonly align?: "left" | "right";
+  public static readonly color: `#${string}`;
+  public static readonly labelStyle?:
+    | "node_label"
+    | "node_label_italic"
+    | string;
+  public static readonly paletteLabel?: string;
+  public static readonly inputs?: number = 0;
+  public static readonly outputs?: number = 0;
+  public static readonly inputLabels?: string | string[];
+  public static readonly outputLabels?: string | string[];
+  public static readonly inputSchema?: Schema;
+  public static readonly outputsSchema?: Schema | Schema[];
+  public static readonly validateInput: boolean = false;
+  public static readonly validateOutput: boolean = false;
+
+  private _send: ((msg: any) => void) | undefined;
+
+  declare public readonly config: IONodeConfig<TConfig>;
+  protected override readonly context: IONodeContext;
+
+  // NOTE: used by the registered function. Had to be a different one to avoid calling the parent's input again
+  /** @internal */
+  public static override _registered(RED: RED): void | Promise<void> {
+    this.validateSettings(RED);
+    return this.registered?.(RED);
+  }
+
+  constructor(
+    RED: RED,
+    node: any,
+    config: IONodeConfig<TConfig>,
+    credentials: IONodeCredentials<TCredentials>,
+  ) {
+    super(RED, node, config, credentials);
+
+    const context = node.context();
+    const fn = (scope: IONodeContextScope, store?: string) => {
+      const target =
+        scope === "global"
+          ? context.global
+          : scope === "flow"
+            ? context.flow
+            : context;
+      return setupContext(target, store);
+    };
+
+    fn.node = setupContext(context);
+    fn.flow = setupContext(context.flow);
+    fn.global = setupContext(context.global);
+
+    this.context = fn as any;
+  }
+
+  public abstract input(msg: TInput): void | Promise<void>;
+
+  // NOTE: used by the registered function. Had to be a different one to avoid calling the parent's input again
+  /** @internal */
+  public async _input(msg: TInput, send: (msg: any) => void) {
+    const NodeClass = this.constructor as typeof IONode;
+    const shouldValidateInput =
+      this.config.validateInput ?? NodeClass.validateInput;
+    if (shouldValidateInput && NodeClass.inputSchema) {
+      this.log("Validating input");
+      validator.validate(msg, NodeClass.inputSchema, {
+        cacheKey: NodeClass.inputSchema.$id || `${NodeClass.type}:input-schema`,
+        throwOnError: true,
+      });
+      this.log("Input is valid");
+    }
+    this._send = send;
+    try {
+      await Promise.resolve(this.input(msg));
+    } finally {
+      this._send = undefined;
+    }
+  }
+
+  public send(msg: TOutput) {
+    const NodeClass = this.constructor as typeof IONode;
+    const shouldValidateOutput =
+      this.config.validateOutput ?? NodeClass.validateOutput;
+    if (shouldValidateOutput && NodeClass.outputsSchema) {
+      this.log("Validating output");
+      const schemas = NodeClass.outputsSchema;
+
+      if (Array.isArray(schemas)) {
+        // Per-port validation: schemas[i] validates msg[i]
+        const msgs = msg as any[];
+        for (let i = 0; i < schemas.length; i++) {
+          if (msgs[i] == null) continue;
+          validator.validate(msgs[i], schemas[i], {
+            cacheKey: schemas[i].$id || `${NodeClass.type}:output-schema:${i}`,
+            throwOnError: true,
+          });
+        }
+      } else if (Array.isArray(msg)) {
+        // Single schema, array of messages: validate each non-null element
+        for (let i = 0; i < (msg as any[]).length; i++) {
+          if ((msg as any[])[i] == null) continue;
+          validator.validate((msg as any[])[i], schemas, {
+            cacheKey: schemas.$id || `${NodeClass.type}:output-schema`,
+            throwOnError: true,
+          });
+        }
+      } else {
+        // Single schema, single message
+        validator.validate(msg, schemas, {
+          cacheKey: schemas.$id || `${NodeClass.type}:output-schema`,
+          throwOnError: true,
+        });
+      }
+      this.log("Output is valid");
+    }
+
+    if (this._send) {
+      this._send(msg);
+    } else {
+      this.node.send(msg);
+    }
+  }
+
+  public status(status: IONodeStatus) {
+    this.node.status(status);
+  }
+
+  public updateWires(wires: string[][]) {
+    this.node.updateWires(wires);
+  }
+
+  public receive(msg: TInput) {
+    this.node.receive(msg);
+  }
+
+  public get x(): number {
+    return this.node.x;
+  }
+
+  public get y(): number {
+    return this.node.y;
+  }
+
+  public get g(): string | undefined {
+    return this.node.g;
+  }
+
+  public get wires(): string[][] {
+    return this.node.wires;
+  }
+
+  public override get credentials():
+    | IONodeCredentials<TCredentials>
+    | undefined {
+    return this.node.credentials;
+  }
+}
+
+export { IONode };