@sebasoft/neuron-js 0.3.0 → 0.5.0

package/src/index.ts

@@ -11,10 +11,17 @@ import { SimpleRule } from "./plugins/rules/SimpleRule.js";
 import type { ExecutionContext } from "./types/ExecutionContext.js";
 import type { ExecutionResult } from "./types/ExecutionResult.js";
 
+/**
+ * Interface for all executable element instances.
+ */
 export interface IElementInstance {
+  /**
+   * Executes the element logic within the given context.
+   */
   execute(context: ExecutionContext): ExecutionResult<any>;
 }
 
+/** Constructor type for Parameters. */
 export type ParameterConstructor<T = any> = new (
   id: string,
   type: string,
@@ -24,6 +31,7 @@ export type ParameterConstructor<T = any> = new (
   defaultValue?: any,
 ) => IElementInstance & { getValue(context: ExecutionContext): T | null };
 
+/** Constructor type for Actions. */
 export type ActionConstructor = new (
   id: string,
   type: string,
@@ -32,6 +40,7 @@ export type ActionConstructor = new (
   neuron: Neuron,
 ) => IElementInstance;
 
+/** Constructor type for Conditions. */
 export type ConditionConstructor = new (
   id: string,
   type: string,
@@ -40,6 +49,7 @@ export type ConditionConstructor = new (
   neuron: Neuron,
 ) => IElementInstance;
 
+/** Constructor type for Rules. */
 export type RuleConstructor = new (
   id: string,
   type: string,
@@ -48,6 +58,10 @@ export type RuleConstructor = new (
   options: any,
 ) => IElementInstance;
 
+/**
+ * The Neuron class serves as the central component registry for the rules engine.
+ * It manages the availability and instantiation of Parameters, Conditions, Actions, and Rules.
+ */
 export class Neuron {
   private registries = {
     parameters: new Map<string, ParameterConstructor>(),
@@ -56,6 +70,9 @@ export class Neuron {
     rules: new Map<string, RuleConstructor>(),
   };
 
+  /**
+   * Creates a new Neuron instance and registers the default built-in plugins.
+   */
   constructor() {
     this.registerParameter(
       SimpleNumberParameter.TYPE,
@@ -84,35 +101,134 @@ export class Neuron {
     this.registerRule(SimpleRule.TYPE, SimpleRule as any);
   }
 
+  /** Registers a custom parameter type. */
   registerParameter(type: string, ctor: ParameterConstructor) {
     this.registries.parameters.set(type, ctor);
   }
 
+  /** Retrieves a parameter constructor by type. */
   getParameter(type: string): ParameterConstructor | undefined {
     return this.registries.parameters.get(type);
   }
 
+  /**
+   * Converts serializable parameter definitions into a name-keyed Map of parameter instances.
+   *
+   * Plugin authors still receive JSON-friendly arrays at the script boundary, but base
+   * classes can expose a Map for ergonomic `this.params.get("name")` access.
+   */
+  createParameterMap(
+    params: ParameterInterface[],
+  ): Map<
+    string,
+    IElementInstance & { getValue(context: ExecutionContext): unknown | null }
+  > {
+    const parameterMap = new Map<
+      string,
+      IElementInstance & { getValue(context: ExecutionContext): unknown | null }
+    >();
+
+    for (const param of params) {
+      const ParamCtor = this.getParameter(param.type);
+      if (!ParamCtor) {
+        continue;
+      }
+
+      parameterMap.set(
+        param.name,
+        new ParamCtor(
+          param.id,
+          param.type,
+          param.name,
+          param.value,
+          param.options,
+          param.defaultValue,
+        ),
+      );
+    }
+
+    return parameterMap;
+  }
+
+  /** Registers a custom condition type. */
   registerCondition(type: string, ctor: ConditionConstructor) {
     this.registries.conditions.set(type, ctor);
   }
 
+  /** Retrieves a condition constructor by type. */
   getCondition(type: string): ConditionConstructor | undefined {
     return this.registries.conditions.get(type);
   }
 
+  /** Registers a custom action type. */
   registerAction(type: string, ctor: ActionConstructor) {
     this.registries.actions.set(type, ctor);
   }
 
+  /** Retrieves an action constructor by type. */
   getAction(type: string): ActionConstructor | undefined {
     return this.registries.actions.get(type);
   }
 
+  /** Registers a custom rule type. */
   registerRule(type: string, ctor: RuleConstructor) {
     this.registries.rules.set(type, ctor);
   }
 
+  /** Retrieves a rule constructor by type. */
   getRule(type: string): RuleConstructor | undefined {
     return this.registries.rules.get(type);
   }
 }
+
+export { AbstractAction } from "./abstracts/AbstractAction.js";
+export { AbstractCondition } from "./abstracts/AbstractCondition.js";
+export { AbstractElement } from "./abstracts/AbstractElement.js";
+export { AbstractParameter } from "./abstracts/AbstractParameter.js";
+export { AbstractRule } from "./abstracts/AbstractRule.js";
+export type { ExplainExecutionOptions } from "./contracts/explain.js";
+export { explainExecution } from "./contracts/explain.js";
+export type {
+  ExecutionExplanation,
+  ExecutionExplanationEvent,
+  ValidationError,
+  ValidationResult,
+} from "./contracts/validation.js";
+export {
+  summarizeExecutionOutput,
+  validateExecutionContext,
+  validateExecutionExplanation,
+  validateExecutionOutput,
+  validateScript,
+  validateValidationErrors,
+} from "./contracts/validation.js";
+export type { ActionInterface, ActionOptions } from "./interfaces/Action.js";
+export type {
+  ConditionInterface,
+  ConditionOptions,
+} from "./interfaces/Condition.js";
+export type { ElementInterface } from "./interfaces/Element.js";
+export { HookEvents } from "./interfaces/HookEvents.js";
+export type { ParameterInterface } from "./interfaces/Parameter.js";
+export type { RuleInterface, RuleOptions } from "./interfaces/Rule.js";
+export type { ScriptInterface } from "./interfaces/Script.js";
+export { AddTwoNumbersAction } from "./plugins/actions/AddTwoNumbersAction.js";
+export { CompareTwoNumbersCondition } from "./plugins/conditions/CompareTwoNumbersCondition.js";
+export type { Comparator } from "./plugins/parameters/ComparatorParameter.js";
+export { ComparatorParameter } from "./plugins/parameters/ComparatorParameter.js";
+export { SimpleNumberParameter } from "./plugins/parameters/SimpleNumberParameter.js";
+export type {
+  SelectOption,
+  SelectOptions,
+} from "./plugins/parameters/SimpleSelectParameter.js";
+export { SimpleSelectParameter } from "./plugins/parameters/SimpleSelectParameter.js";
+export { SimpleStringParameter } from "./plugins/parameters/SimpleStringParameter.js";
+export { SimpleRule } from "./plugins/rules/SimpleRule.js";
+export { Synapse } from "./Synapse.js";
+export type {
+  ExecutionContext,
+  ExecutionMessage,
+} from "./types/ExecutionContext.js";
+export { MessageType } from "./types/ExecutionContext.js";
+export { ExecutionResult } from "./types/ExecutionResult.js";
+export type { HookEmitter } from "./types/HookEmitter.js";

package/src/interfaces/Action.ts

@@ -1,11 +1,25 @@
 import type { ElementInterface } from "./Element.js";
 import type { ParameterInterface } from "./Parameter.js";
 
+/**
+ * Configuration options for an Action.
+ */
 export interface ActionOptions {
+  /**
+   * Whether the action is disabled and should be skipped during execution.
+   */
   disabled?: boolean;
 }
 
+/**
+ * Represents an operation to be performed when a Rule's conditions are met.
+ *
+ * @template TOptions - The type of configuration options for this action.
+ */
 export interface ActionInterface<TOptions extends ActionOptions = ActionOptions>
   extends ElementInterface<TOptions> {
+  /**
+   * The collection of input parameters required by this action.
+   */
   params: ParameterInterface[];
 }

package/src/interfaces/Condition.ts

@@ -1,14 +1,37 @@
 import type { ElementInterface } from "./Element.js";
 import type { ParameterInterface } from "./Parameter.js";
 
+/**
+ * Configuration options for a Condition.
+ */
 export interface ConditionOptions {
+  /**
+   * If true, this condition is treated as part of an OR group.
+   * By default, conditions are evaluated with AND logic.
+   */
   orCondition?: boolean;
+
+  /**
+   * If true, the result of the condition evaluation is flipped.
+   */
   inverted?: boolean;
+
+  /**
+   * Whether the condition is disabled and should be treated as always true.
+   */
   disabled?: boolean;
 }
 
+/**
+ * Represents a logical predicate used to determine if a Rule should execute its actions.
+ *
+ * @template TOptions - The type of configuration options for this condition.
+ */
 export interface ConditionInterface<
   TOptions extends ConditionOptions = ConditionOptions,
 > extends ElementInterface<TOptions> {
+  /**
+   * The collection of input parameters used to evaluate the condition.
+   */
   params: ParameterInterface[];
 }

package/src/interfaces/Element.ts

@@ -1,5 +1,23 @@
+/**
+ * Represents the base interface for all elements within the rules engine.
+ * Elements are the building blocks of scripts, pulses, actions, conditions, and parameters.
+ *
+ * @template TOptions - The type of configuration options for this element.
+ */
 export interface ElementInterface<TOptions = any> {
+  /**
+   * Unique identifier for the element instance.
+   */
   id: string;
+
+  /**
+   * The registered type name of the element.
+   * This type is used by the Registry (Neuron) to look up the correct implementation.
+   */
   type: string;
+
+  /**
+   * Configuration options specific to this element instance.
+   */
   options: TOptions;
 }

package/src/interfaces/HookEvents.ts

@@ -1,14 +1,30 @@
+/**
+ * Enumeration of all lifecycle events emitted during script execution.
+ * These can be used with a HookEmitter to monitor performance, log data, or handle side effects.
+ */
 export enum HookEvents {
+  /** Emitted when the execution of a script starts. */
   ON_SCRIPT_START = "on_script_start",
+  /** Emitted when a specific rule begins evaluation. */
   ON_RULE_START = "on_rule_start",
+  /** Emitted before a condition starts evaluation. */
   ON_CONDITION_START = "pre_condition_start",
+  /** Emitted before an action starts execution. */
   ON_ACTION_START = "pre_action_start",
+  /** Emitted when a script successfully completes all rules. */
   ON_SCRIPT_END = "pre_script_end",
+  /** Emitted when a rule finishes evaluation (regardless of outcome). */
   ON_RULE_END = "on_rule_end",
+  /** Emitted after a condition evaluation completes. */
   ON_CONDITION_END = "pre_condition_end",
+  /** Emitted after an action execution completes. */
   ON_ACTION_END = "pre_action_end",
+  /** Emitted if an unhandled error occurs during script execution. */
   ON_SCRIPT_ERROR = "on_script_error",
+  /** Emitted if an error occurs while evaluating a specific rule. */
   ON_RULE_ERROR = "on_rule_error",
+  /** Emitted if an error occurs during condition evaluation. */
   ON_CONDITION_ERROR = "on_condition_error",
+  /** Emitted if an error occurs during action execution. */
   ON_ACTION_ERROR = "on_action_error",
 }

package/src/interfaces/Parameter.ts

@@ -1,8 +1,26 @@
 import type { ElementInterface } from "./Element.js";
 
+/**
+ * Represents a configurable input value for Actions and Conditions.
+ * Parameters allow for reusable logic templates by decoupling the implementation from the values.
+ *
+ * @template TValue - The primitive or complex type of the parameter's value.
+ * @template TOptions - The type of configuration options for this parameter.
+ */
 export interface ParameterInterface<TValue = any, TOptions = any>
   extends ElementInterface<TOptions> {
+  /**
+   * The semantic name of the parameter (e.g., "recipient", "threshold").
+   */
   name: string;
+
+  /**
+   * The actual value assigned to the parameter.
+   */
   value: TValue | null;
+
+  /**
+   * An optional fallback value if the primary value is missing or null.
+   */
   defaultValue?: TValue;
 }

package/src/interfaces/Rule.ts

@@ -2,12 +2,36 @@ import type { ActionInterface } from "./Action.js";
 import type { ConditionInterface } from "./Condition.js";
 import type { ElementInterface } from "./Element.js";
 
+/**
+ * Configuration options for a Rule.
+ */
 export interface RuleOptions {
+  /**
+   * Whether the rule is disabled and should be skipped.
+   */
   disabled?: boolean;
 }
 
+/**
+ * Represents a logical unit containing conditions and actions.
+ * A Rule executes its actions only if its conditions evaluate to true.
+ *
+ * - **Empty Conditions**: The rule is considered "Always" and will automatically execute actions.
+ * - **Empty Actions**: The rule will "Do Nothing" (no side effects).
+ *
+ * @template TOptions - The type of configuration options for this rule.
+ */
 export interface RuleInterface<TOptions extends RuleOptions = RuleOptions>
   extends ElementInterface<TOptions> {
+  /**
+   * List of conditions that must be satisfied for the actions to execute.
+   * If empty, actions are always executed.
+   */
   conditions: ConditionInterface[];
+
+  /**
+   * List of actions to perform if the conditions are met.
+   * If empty, the rule has no side effects.
+   */
   actions: ActionInterface[];
 }

package/src/interfaces/Script.ts

@@ -1,6 +1,17 @@
 import type { RuleInterface } from "./Rule.js";
 
+/**
+ * Represents a complete set of rules to be executed by the engine.
+ * The script is the top-level serializable container for all logic.
+ */
 export interface ScriptInterface {
+  /**
+   * Unique identifier for the script.
+   */
   id: string;
+
+  /**
+   * The ordered list of rules that comprise the script's logic.
+   */
   rules: RuleInterface[];
 }

package/src/runtime/ActionRuntime.ts

@@ -18,7 +18,7 @@ export class ActionRuntime {
     let actionsExecuted = 0;
 
     for (const actionItem of this._actions) {
-      if (actionItem.options.disabled) {
+      if (actionItem.options?.disabled) {
         continue;
       }
 

package/src/runtime/ConditionRuntime.ts

@@ -22,14 +22,14 @@ export class ConditionRuntime {
     let groupIndex = 0;
 
     for (const conditionItem of this._conditions) {
-      if (conditionItem.options.disabled) {
+      if (conditionItem.options?.disabled) {
         continue;
       }
 
       this._hookEmitter?.(HookEvents.ON_CONDITION_START, context);
 
       if (
-        conditionItem.options.orCondition &&
+        conditionItem.options?.orCondition &&
         orGroups[groupIndex].length > 0
       ) {
         groupIndex++;
@@ -61,7 +61,7 @@ export class ConditionRuntime {
         return new ExecutionResult(false, context, false, messageList);
       }
 
-      const verdict = conditionItem.options.inverted
+      const verdict = conditionItem.options?.inverted
         ? !conditionResult.value
         : !!conditionResult.value;
 

package/src/runtime/RuleRuntime.ts

@@ -20,7 +20,7 @@ export class RuleRuntime {
     let rulesExecuted = 0;
 
     for (const ruleItem of this._rules) {
-      if (ruleItem.options.disabled) {
+      if (ruleItem.options?.disabled) {
         continue;
       }
 

package/src/types/ExecutionContext.ts

@@ -1,3 +1,6 @@
+/**
+ * Severity levels for execution messages.
+ */
 export enum MessageType {
   DEBUG = "debug",
   INFO = "info",
@@ -5,12 +8,22 @@ export enum MessageType {
   ERROR = "error",
 }
 
+/**
+ * Represents a log message or audit entry generated during execution.
+ */
 export interface ExecutionMessage {
+  /** The severity level of the message. */
   type: MessageType;
+  /** The descriptive text of the message. */
   text: string;
 }
 
+/**
+ * The shared state container that travels through the execution engine.
+ */
 export interface ExecutionContext {
+  /** Accumulation of all messages generated during the current script run. */
   messages: ExecutionMessage[];
+  /** The primary data object being processed and mutated by actions. */
   state: Record<string, any>;
 }

package/src/types/ExecutionResult.ts

@@ -1,6 +1,17 @@
 import type { ExecutionContext } from "./ExecutionContext.js";
 
+/**
+ * Represents the outcome of an execution unit (Script, Rule, Action, or Condition).
+ *
+ * @template TValue - The type of the value produced by the execution (e.g., number of rules for a Script, boolean for a Condition).
+ */
 export class ExecutionResult<TValue = any> {
+  /**
+   * @param success - Whether the execution completed without errors.
+   * @param context - The state of the ExecutionContext after the run.
+   * @param value - The primary output of the execution.
+   * @param messages - Any informational or error messages generated.
+   */
   constructor(
     public readonly success: boolean,
     public readonly context: ExecutionContext,
@@ -8,6 +19,9 @@ export class ExecutionResult<TValue = any> {
     public readonly messages: string[] = [],
   ) {}
 
+  /**
+   * Helper to check if the execution was successful.
+   */
   isSuccessful(): boolean {
     return this.success;
   }

package/src/types/HookEmitter.ts

@@ -1,7 +1,12 @@
 import type { HookEvents } from "../interfaces/HookEvents.js";
 import type { ExecutionContext } from "../types/ExecutionContext.js";
 
+/**
+ * Functional type for lifecycle hook callbacks.
+ */
 export type HookEmitter = (
+  /** The lifecycle event being triggered. */
   event: HookEvents,
+  /** The current state of the execution context. */
   context: ExecutionContext,
 ) => void;

package/dist/commonjs/Synapse.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=Synapse.test.d.ts.map

package/dist/commonjs/Synapse.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Synapse.test.d.ts","sourceRoot":"","sources":["../../src/Synapse.test.ts"],"names":[],"mappings":""}

package/dist/commonjs/Synapse.test.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const index_js_1 = require("./index.js");
-const Synapse_js_1 = require("./Synapse.js");
-(0, vitest_1.test)("Synapse can execute an empty script", () => {
-    const neuron = new index_js_1.Neuron();
-    const synapse = new Synapse_js_1.Synapse(neuron);
-    const context = { messages: [], state: {} };
-    const script = { id: "test", rules: [] };
-    const result = synapse.execute(script, context);
-    (0, vitest_1.expect)(result.isSuccessful()).toBe(true);
-    (0, vitest_1.expect)(result.value).toBe(0);
-});
-//# sourceMappingURL=Synapse.test.js.map

package/dist/commonjs/Synapse.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Synapse.test.js","sourceRoot":"","sources":["../../src/Synapse.test.ts"],"names":[],"mappings":";;AAAA,mCAAsC;AACtC,yCAAoC;AACpC,6CAAuC;AAEvC,IAAA,aAAI,EAAC,qCAAqC,EAAE,GAAG,EAAE;IAC/C,MAAM,MAAM,GAAG,IAAI,iBAAM,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,oBAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAEzC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,IAAA,eAAM,EAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,IAAA,eAAM,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC"}

package/dist/commonjs/index.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=index.test.d.ts.map

package/dist/commonjs/index.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/index.test.ts"],"names":[],"mappings":""}