@bonsae/nrg 0.1.0

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

@@ -0,0 +1,255 @@
+import type { Schema } from "../schemas/types";
+import { type RED } from "../../server/types";
+import type {
+  ConfigNodeContext,
+  IONodeContext,
+  NodeConfig,
+  NodeCredentials,
+  TypedInput,
+  NodeSettings,
+} from "./types";
+import { validator } from "../validator";
+import { setupConfigProxy } from "./utils";
+
+abstract class Node<TConfig = any, TCredentials = any, TSettings = any> {
+  public static readonly type: string;
+  public static readonly category: "config" | string;
+  public static readonly configSchema?: Schema;
+  public static readonly credentialsSchema?: Schema;
+  public static readonly settingsSchema?: Schema;
+
+  private static _cachedSettings: any = null;
+
+  public static registered?(RED: RED): void | Promise<void>;
+
+  /** @internal */
+  public static _registered?(RED: RED): void | Promise<void>;
+
+  /** @internal */
+  public static _settings(): NodeSettings | undefined {
+    if (!this.settingsSchema) return;
+
+    const settings: NodeSettings = {};
+    const prefix = this.type.replace(/-./g, (x) => x[1].toUpperCase());
+    for (const [key, prop] of Object.entries(this.settingsSchema.properties)) {
+      const settingKey = prefix + key.charAt(0).toUpperCase() + key.slice(1);
+      settings[settingKey] = {
+        value: prop.default,
+        exportable: prop.exportable ?? false,
+      };
+    }
+    return settings;
+  }
+
+  // NOTE:
+  public static validateSettings(RED: RED): void {
+    if (!this.settingsSchema) return;
+
+    RED.log.info("Validating settings");
+    const prefix = this.type.replace(/-./g, (x) => x[1].toUpperCase());
+    const properties = this.settingsSchema.properties;
+    const settings: Record<string, unknown> = {};
+
+    for (const key of Object.keys(properties)) {
+      const settingKey = prefix + key.charAt(0).toUpperCase() + key.slice(1);
+      const value = RED.settings[settingKey];
+
+      if (value !== undefined) {
+        settings[key] = value;
+      }
+    }
+
+    // NOTE: assign defaults manually to avoid ajv errors for non json types (eg. Function, Constructor)
+    for (const [key, prop] of Object.entries(properties) as [string, any][]) {
+      if (settings[key] === undefined) {
+        // NOTE: here I need to use _default when it is a non validatable type (eg. Function, Constructor...)
+        const defaultValue = prop.default ?? prop._default;
+        if (defaultValue !== undefined) {
+          settings[key] = defaultValue;
+        }
+      }
+    }
+
+    validator.validate(settings, this.settingsSchema, {
+      cacheKey: this.settingsSchema.$id || `${this.type}:settings`,
+      throwOnError: true,
+    });
+
+    this._cachedSettings = settings;
+
+    RED.log.info("Settings are valid");
+  }
+  protected readonly RED: RED;
+  protected readonly node: any;
+  protected readonly context!: ConfigNodeContext | IONodeContext;
+  public readonly config!: NodeConfig<TConfig>;
+
+  private readonly timers = new Set<NodeJS.Timeout>();
+  private readonly intervals = new Set<NodeJS.Timeout>();
+
+  constructor(
+    RED: RED,
+    node: any,
+    config: NodeConfig<TConfig>,
+    credentials: NodeCredentials<TCredentials>,
+  ) {
+    this.RED = RED;
+    this.node = node;
+
+    const constructor = this.constructor as typeof Node;
+    if (constructor.configSchema) {
+      this.log("Validating configs");
+      const configResult = validator.validate(
+        config,
+        constructor.configSchema,
+        {
+          cacheKey:
+            constructor.configSchema.$id ||
+            `${constructor.type}:configs-schema`,
+          throwOnError: false,
+        },
+      );
+      if (!configResult.valid && configResult.errors?.length) {
+        this.warn(
+          `Config validation errors: ${configResult.errors.map((e) => `${e.instancePath} ${e.message}`).join("; ")}`,
+        );
+      }
+    }
+    (this as any).config = setupConfigProxy(RED, config);
+
+    if (constructor.credentialsSchema && credentials) {
+      this.log("Validating credentials");
+      const credResult = validator.validate(
+        credentials,
+        constructor.credentialsSchema,
+        {
+          cacheKey:
+            constructor.credentialsSchema.$id ||
+            `${constructor.type}:credentials-schema`,
+          throwOnError: false,
+        },
+      );
+      if (!credResult.valid && credResult.errors?.length) {
+        this.warn(
+          `Credentials validation errors: ${credResult.errors.map((e) => `${e.instancePath} ${e.message}`).join("; ")}`,
+        );
+      }
+    }
+  }
+
+  public i18n(key: string, substitutions?: Record<string, string>): string {
+    const nodeType = (this.constructor as typeof Node).type;
+    return this.RED._(`${nodeType}.${key}`, substitutions);
+  }
+
+  public setTimeout(fn: () => void, ms: number): NodeJS.Timeout {
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      fn();
+    }, ms);
+    this.timers.add(timer);
+    return timer;
+  }
+
+  public setInterval(fn: () => void, ms: number): NodeJS.Timeout {
+    const interval = setInterval(fn, ms);
+    this.intervals.add(interval);
+    return interval;
+  }
+
+  public clearTimeout(timer: NodeJS.Timeout): void {
+    clearTimeout(timer);
+    this.timers.delete(timer);
+  }
+
+  public clearInterval(interval: NodeJS.Timeout): void {
+    clearInterval(interval);
+    this.intervals.delete(interval);
+  }
+
+  public created?(): void | Promise<void>;
+  public closed?(removed?: boolean): void | Promise<void>;
+
+  // NOTE: typing msg isnt necessary in this case
+  public resolveTypedInput<T = any>(
+    typedInput: TypedInput,
+    msg?: Record<string, any>,
+  ): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.RED.util.evaluateNodeProperty(
+        typedInput.value,
+        typedInput.type,
+        this.node,
+        msg,
+        (error: Error | null, result: any) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+
+          // NOTE: some references might have not been written with the nrg framework
+          // TODO: type with NodeRedNode for nodes that don't have types
+          if (typedInput.type === "node" && result) {
+            resolve((result._node ?? result) as T);
+            return;
+          }
+
+          resolve(result as T);
+        },
+      );
+    });
+  }
+  // NOTE: used by the registered function. Had to be a different one to avoid calling the parent's closed again
+  /** @internal */
+  public async _closed(removed?: boolean) {
+    try {
+      await Promise.resolve(this.closed?.(removed));
+    } finally {
+      this.log("clearing timers and intervals");
+      this.timers.forEach((t) => clearTimeout(t));
+      this.intervals.forEach((i) => clearInterval(i));
+      this.timers.clear();
+      this.intervals.clear();
+      this.log("timers and intervals cleared");
+    }
+  }
+
+  public on(event: string, callback: (...args: any[]) => void) {
+    this.node.on(event, callback);
+  }
+
+  public log(msg: any) {
+    this.node.log(msg);
+  }
+
+  public warn(message: string) {
+    this.node.warn(message);
+  }
+
+  public error(message: string, msg?: any) {
+    this.node.error(message, msg);
+  }
+
+  public get id(): string {
+    return this.node.id;
+  }
+
+  public get name(): string | undefined {
+    return this.node.name;
+  }
+
+  public get z(): string | undefined {
+    return this.node.z;
+  }
+
+  public get credentials(): NodeCredentials<TCredentials> | undefined {
+    return this.node.credentials;
+  }
+
+  public get settings(): TSettings {
+    const constructor = this.constructor as typeof Node;
+    return (constructor._cachedSettings as TSettings) ?? ({} as TSettings);
+  }
+}
+
+export { Node };

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

@@ -0,0 +1,28 @@
+import type { Static } from "@sinclair/typebox";
+import type {
+  NodeConfig,
+  NodeCredentials,
+  NodeContextScope,
+  NodeContextStore,
+} from "../../../server/nodes/types";
+import type { ConfigNodeConfigSchema } from "../../schemas";
+
+type ConfigNodeContextScope = Exclude<NodeContextScope, "flow">;
+
+type ConfigNodeConfig<TConfig = any> = NodeConfig<TConfig> &
+  Static<typeof ConfigNodeConfigSchema>;
+
+type ConfigNodeCredentials<TCredentials = any> = NodeCredentials<TCredentials>;
+
+type ConfigNodeContext = {
+  (scope: ConfigNodeContextScope, store?: string): NodeContextStore;
+  node: NodeContextStore;
+  global: NodeContextStore;
+};
+
+export {
+  ConfigNodeConfig,
+  ConfigNodeContext,
+  ConfigNodeCredentials,
+  ConfigNodeContextScope,
+};

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

@@ -0,0 +1,3 @@
+export * from "./node";
+export * from "./io-node";
+export * from "./config-node";

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

@@ -0,0 +1,37 @@
+import type { Static } from "@sinclair/typebox";
+import type { IONodeConfigSchema } from "../../schemas";
+import type {
+  NodeConfig,
+  NodeCredentials,
+  NodeContextStore,
+  NodeContextScope,
+} from "../../../server/nodes/types";
+
+type IONodeContextScope = NodeContextScope;
+
+type IONodeConfig<TConfig = any> = NodeConfig<TConfig> &
+  Static<typeof IONodeConfigSchema> & {
+    validateInput?: boolean;
+    validateOutput?: boolean;
+  };
+
+type IONodeCredentials<TCredentials = any> = NodeCredentials<TCredentials>;
+
+type IONodeStatus =
+  | { fill?: "red" | "green"; shape?: "dot" | "string"; text?: string }
+  | string;
+
+type IONodeContext = {
+  (scope: IONodeContextScope, store?: string): NodeContextStore;
+  node: NodeContextStore;
+  flow: NodeContextStore;
+  global: NodeContextStore;
+};
+
+export {
+  IONodeConfig,
+  IONodeContext,
+  IONodeContextScope,
+  IONodeCredentials,
+  IONodeStatus,
+};

package/src/core/server/nodes/types/node.ts

@@ -0,0 +1,41 @@
+import type { Static } from "@sinclair/typebox";
+import type { NodeConfigSchema, TTypedInput } from "../../schemas";
+import type { RED } from "../../../server/types";
+
+type NodeContextScope = "node" | "flow" | "global";
+
+interface NodeContextStore {
+  get<T = any>(key: string): Promise<T>;
+  set<T = any>(key: string, value: T): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+type NodeConstructor<T = any> = (new (...args: any[]) => T) & {
+  type: string;
+  registered?(RED: RED): void | Promise<void>;
+};
+
+type NodeConfig<TConfig = any> = TConfig & Static<typeof NodeConfigSchema>;
+
+type NodeCredentials<TCredentials = any> = TCredentials;
+
+interface NodeSetting<T = any> {
+  value: T;
+  exportable?: boolean;
+}
+
+type NodeSettings = Record<string, NodeSetting>;
+
+// TODO: move this somewhere else
+type TypedInput = Static<TTypedInput>;
+
+export {
+  NodeConfig,
+  NodeContextStore,
+  NodeContextScope,
+  NodeConstructor,
+  NodeCredentials,
+  NodeSetting,
+  NodeSettings,
+  TypedInput,
+};

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

@@ -0,0 +1,83 @@
+import type { ResolveNodeRefs } from "../schemas/types";
+import type { RED, NodeRedContextStore } from "../types";
+import type { NodeContextStore } from "./types";
+
+function setupContext(
+  context: NodeRedContextStore,
+  store?: string,
+): NodeContextStore {
+  return {
+    get: (key) =>
+      new Promise((resolve, reject) =>
+        context.get(key, store, (error, value) =>
+          error ? reject(error) : resolve(value),
+        ),
+      ),
+
+    set: (key, value) =>
+      new Promise((resolve, reject) =>
+        context.set(key, value, store, (error) =>
+          error ? reject(error) : resolve(),
+        ),
+      ),
+
+    keys: () =>
+      new Promise((resolve, reject) =>
+        context.keys(store, (error, k) => (error ? reject(error) : resolve(k))),
+      ),
+  };
+}
+
+function setupConfigProxy<T extends object>(
+  RED: RED,
+  config: T,
+): ResolveNodeRefs<T> {
+  // NOTE: must not proxy its own id or parents ids
+  const SKIP_PROPS = new Set(["id", "_id", "_users"]);
+
+  const createProxy = <O extends object>(obj: O): any => {
+    return new Proxy(obj, {
+      get(target: any, prop: string | symbol): any {
+        if (typeof prop === "symbol") {
+          return target[prop];
+        }
+
+        if (SKIP_PROPS.has(prop)) {
+          return target[prop];
+        }
+
+        const value = target[prop];
+
+        if (typeof value === "string" && value.length > 0) {
+          // NOTE: using the instance provided by the user instead of node-red's internal one
+          const node = RED.nodes.getNode(value)?._node;
+          return node || value;
+        }
+
+        if (Array.isArray(value)) {
+          return value.map((item) => {
+            if (typeof item === "string") {
+              // NOTE: using the instance provided by the user instead of node-red's internal one
+              const node = RED.nodes.getNode(item)?._node;
+              return node || item;
+            }
+            if (item && typeof item === "object") {
+              return createProxy(item);
+            }
+            return item;
+          });
+        }
+
+        if (value && typeof value === "object") {
+          return createProxy(value);
+        }
+
+        return value;
+      },
+    });
+  };
+
+  return createProxy(config) as ResolveNodeRefs<T>;
+}
+
+export { setupConfigProxy, setupContext };

package/src/core/server/schemas/base.ts

@@ -0,0 +1,66 @@
+import { TYPED_INPUT_TYPES } from "../../constants";
+import { SchemaType } from "./type";
+
+const NodeConfigSchema = SchemaType.Object({
+  id: SchemaType.String(),
+  type: SchemaType.String(),
+  name: SchemaType.String(),
+  z: SchemaType.Optional(SchemaType.String()),
+});
+
+const ConfigNodeConfigSchema = SchemaType.Object({
+  ...NodeConfigSchema.properties,
+  _users: SchemaType.Array(SchemaType.String()),
+});
+
+const IONodeConfigSchema = SchemaType.Object({
+  ...NodeConfigSchema.properties,
+  wires: SchemaType.Array(
+    SchemaType.Array(SchemaType.String(), { default: [] }),
+    {
+      default: [[]],
+    },
+  ),
+  x: SchemaType.Number(),
+  y: SchemaType.Number(),
+  g: SchemaType.Optional(SchemaType.String()),
+});
+
+const TypedInputSchema = SchemaType.Object(
+  {
+    value: SchemaType.Union(
+      [
+        SchemaType.String(),
+        SchemaType.Number(),
+        SchemaType.Boolean(),
+        SchemaType.Null(),
+      ],
+      {
+        description: "The actual value entered or selected.",
+        default: "",
+      },
+    ),
+    type: SchemaType.Union(
+      TYPED_INPUT_TYPES.map((type) => SchemaType.Literal(type)),
+      {
+        description:
+          "The type of the value (string, number, message property, etc.)",
+        default: "str",
+      },
+    ),
+  },
+  {
+    description: "Represents a Node-RED TypedInput value and its type.",
+    default: {
+      type: "str",
+      value: "",
+    },
+  },
+);
+
+export {
+  ConfigNodeConfigSchema,
+  IONodeConfigSchema,
+  NodeConfigSchema,
+  TypedInputSchema,
+};

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

@@ -0,0 +1,3 @@
+export * from "./base";
+export * from "./type";
+export type * from "./types";

package/src/core/server/schemas/type.ts

@@ -0,0 +1,95 @@
+import type {
+  TSchema,
+  TProperties,
+  SchemaOptions,
+  ObjectOptions,
+} from "@sinclair/typebox";
+import type { Schema } from "./types";
+import { Type as BaseType, Kind } from "@sinclair/typebox";
+import { TypedInputSchema } from "./base";
+import type { TNodeRef, TTypedInput } from "./types";
+import { isJSONType } from "ajv/dist/compile/rules";
+
+function NodeRef<T extends new (...args: any[]) => any>(
+  nodeClass: T,
+  options?: SchemaOptions,
+): TNodeRef<InstanceType<T>> {
+  return {
+    ...SchemaType.String({
+      description:
+        options?.description || `Reference to ${(nodeClass as any).type}`,
+      format: "node-id",
+    }),
+    "node-type": (nodeClass as any).type,
+    ...options,
+    [Kind]: "NodeRef",
+  } as unknown as TNodeRef<InstanceType<T>>;
+}
+
+function TypedInput(options?: SchemaOptions): TTypedInput {
+  return {
+    ...TypedInputSchema,
+    ...options,
+    [Kind]: "TypedInput",
+  } as unknown as TTypedInput;
+}
+
+const SchemaType = Object.assign({}, BaseType, {
+  NodeRef,
+  TypedInput,
+});
+
+function markNonValidatable<T extends TSchema>(schema: T): T {
+  const type = (schema as any).type;
+
+  const hasInvalidType =
+    type !== undefined &&
+    (Array.isArray(type) ? !type.every(isJSONType) : !isJSONType(type));
+
+  // NOTE: if the type is non serializable, like Functions or Constructor, we must skip validation and avoid applying defaults
+  if (hasInvalidType) {
+    (schema as any)["skip-validation"] = true;
+
+    if ((schema as any).default !== undefined) {
+      (schema as any)._default = (schema as any).default;
+      delete (schema as any).default;
+    }
+
+    // NOTE: delete type to avoid the following error during validation => Error registering node types: Error: type must be JSONType or JSONType[]: Function
+    delete (schema as any).type;
+  }
+
+  if (schema.properties) {
+    for (const prop of Object.values(schema.properties)) {
+      markNonValidatable(prop as TSchema);
+    }
+  }
+
+  if (schema.items) {
+    markNonValidatable(schema.items as TSchema);
+  }
+
+  if (schema.anyOf) {
+    schema.anyOf.forEach((s) => markNonValidatable(s as TSchema));
+  }
+
+  if (schema.allOf) {
+    schema.allOf.forEach((s) => markNonValidatable(s as TSchema));
+  }
+
+  if (schema.oneOf) {
+    schema.oneOf.forEach((s) => markNonValidatable(s as TSchema));
+  }
+
+  return schema;
+}
+
+function defineSchema<T extends TProperties>(
+  properties: T,
+  options: ObjectOptions & { $id: string },
+): Schema<T> {
+  const schema = SchemaType.Object(properties, options);
+  return markNonValidatable(schema) as Schema<T>;
+}
+
+export { SchemaType, defineSchema };

package/src/core/server/schemas/types/index.ts

@@ -0,0 +1,73 @@
+import type {
+  Kind,
+  TSchema,
+  TObject,
+  TProperties,
+  Static,
+} from "@sinclair/typebox";
+import type { TYPED_INPUT_TYPES } from "../../../constants";
+
+interface TNodeRef<T = any> extends TSchema {
+  [Kind]: "NodeRef";
+  static: T;
+  type: "string";
+  "node-type"?: string;
+}
+
+type ResolveNodeRefs<T> =
+  T extends TNodeRef<infer N>
+    ? N
+    : T extends (...args: any[]) => any
+      ? T
+      : T extends Array<infer Item>
+        ? ResolveNodeRefs<Item>[]
+        : T extends object
+          ? { [K in keyof T]: ResolveNodeRefs<T[K]> }
+          : T;
+
+type Infer<T extends TSchema> = ResolveNodeRefs<Static<T>>;
+
+type TypedInputType = (typeof TYPED_INPUT_TYPES)[number];
+
+interface TTypedInput extends TSchema {
+  [Kind]: "TypedInput";
+  static: {
+    value: string | number | boolean | null;
+    type: TypedInputType;
+  };
+}
+
+declare module "@sinclair/typebox" {
+  interface SchemaOptions {
+    exportable?: boolean;
+  }
+}
+
+interface Schema<T extends TProperties = TProperties> extends TObject<T> {
+  $id: string;
+}
+
+export { Infer, ResolveNodeRefs, TNodeRef, TTypedInput };
+export type { Schema };
+export type {
+  TSchema,
+  TObject,
+  TProperties,
+  TString,
+  TNumber,
+  TBoolean,
+  TArray,
+  TUnion,
+  TIntersect,
+  TLiteral,
+  TEnum,
+  TRecord,
+  TTuple,
+  TOptional,
+  TNull,
+  TInteger,
+  TRef,
+  TConst,
+  TFunction,
+  SchemaOptions,
+} from "@sinclair/typebox";