fix: align public api and docs

Author: SebaSOFT

docs/concepts/implementation-examples.md

@@ -1,59 +1,58 @@
 # Implementation Examples
 
-This page provides practical examples of how to implement the core interfaces of `neuron-js` to build a custom rules engine tailored to your domain.
+This page shows how to implement the core extension points of `neuron-js` with the current public API.
+
+The script boundary stays JSON-friendly: rules, actions, conditions, and parameters are arrays with explicit `options` objects. For plugin ergonomics, the abstract action and condition base classes transform the parameter array into a name-keyed `Map`, so plugin code can use `this.params.get('name')`.
 
 ## 1. Condition Implementation
-Conditions are logical predicates. They should be stateless and only depend on their parameters and the current `ExecutionContext`.
+
+Conditions are logical predicates. They should be stateless and depend only on their parameters and the current `ExecutionContext`.
 
 ```typescript
-import { AbstractCondition, ExecutionResult, ExecutionContext } from '@sebasoft/neuron-js';
+import { AbstractCondition, ExecutionResult, type ExecutionContext } from '@sebasoft/neuron-js';
 
 /**
- * Checks if the current hour in the context state matches a target.
+ * Checks if the current hour in the context state matches a target period.
  */
 export class TimeOfDayCondition extends AbstractCondition {
-  static TYPE = 'is_time_of_day';
+  static readonly TYPE = 'is_time_of_day';
 
-  async execute(context: ExecutionContext): Promise<ExecutionResult<boolean>> {
-    // 1. Resolve parameters (e.g., "morning", "afternoon")
-    const targetPeriod = this.params.get('period').getValue(context);
-    
-    // 2. Access state from context
+  execute(context: ExecutionContext): ExecutionResult<boolean> {
+    const targetPeriod = this.params.get('period')?.getValue(context);
     const currentHour = context.state.systemTime.getHours();
-    
+
     let isMatch = false;
     if (targetPeriod === 'morning') isMatch = currentHour >= 6 && currentHour < 12;
     if (targetPeriod === 'afternoon') isMatch = currentHour >= 12 && currentHour < 18;
 
-    // 3. Return result (Condition value is boolean)
-    return new ExecutionResult(isMatch, context, isMatch);
+    return new ExecutionResult(true, context, isMatch);
   }
 }
 ```
 
 ## 2. Action Implementation
-Actions perform side effects or mutate the context state. They are only triggered if the Rule's conditions pass.
+
+Actions perform side effects or return an updated context. They are only triggered if the rule's conditions pass.
 
 ```typescript
-import { AbstractAction, ExecutionResult, ExecutionContext } from '@sebasoft/neuron-js';
+import { AbstractAction, ExecutionResult, MessageType, type ExecutionContext } from '@sebasoft/neuron-js';
 
 /**
  * Adds a customized audit message to the context.
  */
 export class AuditLogAction extends AbstractAction {
-  static TYPE = 'audit_log';
+  static readonly TYPE = 'audit_log';
 
-  async execute(context: ExecutionContext): Promise<ExecutionResult<void>> {
-    const messageTemplate = this.params.get('template').getValue(context);
+  execute(context: ExecutionContext): ExecutionResult<void> {
+    const messageTemplate = this.params.get('template')?.getValue(context);
     const user = context.state.user.name;
 
-    // Mutate the context by adding a new message
     const nextContext = {
       ...context,
       messages: [
         ...context.messages,
-        { type: 'info', text: `${user}: ${messageTemplate}` }
-      ]
+        { type: MessageType.INFO, text: `${user}: ${messageTemplate}` },
+      ],
     };
 
     return new ExecutionResult(true, nextContext);
@@ -62,126 +61,165 @@ export class AuditLogAction extends AbstractAction {
 ```
 
 ## 3. Parameter Implementation
-Parameters resolve values. They can be static (hardcoded in JSON) or dynamic (resolving paths in state or environment variables).
+
+Parameters resolve values. They can be static, dynamic from context, or backed by another source.
 
 ```typescript
-import { AbstractParameter, ExecutionContext } from '@sebasoft/neuron-js';
+import { AbstractParameter, type ExecutionContext } from '@sebasoft/neuron-js';
 
 /**
  * Resolves a value from an environment variable.
  */
 export class EnvVarParameter extends AbstractParameter<string> {
-  static TYPE = 'env_var';
+  static readonly TYPE = 'env_var';
 
-  getValue(context: ExecutionContext): string | null {
-    // Parameters can use their 'value' property as the key
-    const envKey = this.value; 
-    return process.env[envKey] || this.defaultValue || null;
+  getValue(_context: ExecutionContext): string | null {
+    const envKey = this.value;
+    return envKey ? process.env[envKey] ?? this.defaultValue ?? null : this.defaultValue ?? null;
   }
 }
 ```
 
 ## 4. Context Implementation
-While `ExecutionContext` is a flexible interface, you should define a strict schema for your application's state to ensure type safety in your plugins.
+
+`ExecutionContext` is intentionally flexible. Define a stricter application-level context for your own plugins.
 
 ```typescript
+import type { ExecutionContext } from '@sebasoft/neuron-js';
+
 export interface MyAppContext extends ExecutionContext {
   state: {
     user: { id: string; name: string; loyalty: number };
-    cart: { items: any[]; total: number };
+    cart: { items: unknown[]; total: number };
     systemTime: Date;
   };
 }
 ```
 
 ## 5. Putting It All Together
-The following example shows how to register these custom plugins and execute a script that uses them.
+
+The following example registers custom plugins and executes a JSON-serializable script.
 
 ```typescript
 import { Neuron, Synapse } from '@sebasoft/neuron-js';
 
-// 1. Initialize Registry and register plugins
 const registry = new Neuron();
 registry.registerCondition(TimeOfDayCondition.TYPE, TimeOfDayCondition);
 registry.registerAction(AuditLogAction.TYPE, AuditLogAction);
 registry.registerParameter(EnvVarParameter.TYPE, EnvVarParameter);
 
-// 2. Create the Engine
 const engine = new Synapse(registry);
 
-// 3. Define Logic (JSON)
 const script = {
   id: 'morning-greeting',
-  rules: [{
-    id: 'greet-rule',
-    type: 'simple_rule',
-    conditions: [
-      { 
-        type: 'is_time_of_day', 
-        params: [{ name: 'period', type: 'simple_string', value: 'morning' }] 
-      }
-    ],
-    actions: [
-      { 
-        type: 'audit_log', 
-        params: [{ name: 'template', type: 'simple_string', value: 'Good morning!' }] 
-      }
-    ]
-  }]
+  rules: [
+    {
+      id: 'greet-rule',
+      type: 'simple_rule',
+      options: {},
+      conditions: [
+        {
+          id: 'morning-condition',
+          type: 'is_time_of_day',
+          options: {},
+          params: [
+            {
+              id: 'period-param',
+              name: 'period',
+              type: 'simple_string',
+              value: 'morning',
+              options: {},
+            },
+          ],
+        },
+      ],
+      actions: [
+        {
+          id: 'audit-action',
+          type: 'audit_log',
+          options: {},
+          params: [
+            {
+              id: 'template-param',
+              name: 'template',
+              type: 'simple_string',
+              value: 'Good morning!',
+              options: {},
+            },
+          ],
+        },
+      ],
+    },
+  ],
 };
 
-// 4. Run it
 const context: MyAppContext = {
   state: {
     user: { id: '1', name: 'Alice', loyalty: 10 },
     cart: { items: [], total: 0 },
-    systemTime: new Date() // Suppose it's 9:00 AM
+    systemTime: new Date(),
   },
-  messages: []
+  messages: [],
 };
 
 const result = engine.execute(script, context);
-console.log(result.context.messages); // [{ type: 'info', text: 'Alice: Good morning!' }]
+console.log(result.context.messages);
 ```
 
 ## 6. Logical Grouping (AND/OR)
+
 `neuron-js` uses a "Sum of Products" approach to logic. Conditions are grouped into blocks.
-- **AND**: All conditions within a block must be true.
-- **OR**: If any block is true, the entire rule evaluates to true.
+
+- **AND**: all conditions within a block must be true.
+- **OR**: if any block is true, the entire rule evaluates to true.
 
 ### How to trigger OR
-Setting `orCondition: true` on a condition starts a **new block**. This new block is joined to the previous block with an `OR` operator.
+
+Setting `orCondition: true` on a condition's `options` starts a new block. This new block is joined to the previous block with an `OR` operator.
 
 ### Example: (A AND B) OR (C AND D)
+
 ```json
 {
-  "id": "complex-logic",
+  "id": "complex-rule",
+  "type": "simple_rule",
+  "options": {},
+  "actions": [],
   "conditions": [
-    { "id": "A", "type": "is_gold_member" },
-    { "id": "B", "type": "has_high_balance" },
-    { 
-      "id": "C", 
-      "type": "is_new_user", 
-      "options": { "orCondition": true } 
+    { "id": "A", "type": "is_gold_member", "options": {}, "params": [] },
+    { "id": "B", "type": "has_high_balance", "options": {}, "params": [] },
+    {
+      "id": "C",
+      "type": "is_new_user",
+      "options": { "orCondition": true },
+      "params": []
     },
-    { "id": "D", "type": "has_promo_code" }
+    { "id": "D", "type": "has_promo_code", "options": {}, "params": [] }
   ]
 }
 ```
-**Evaluation Logic**: `(A && B) || (C && D)`
+
+Evaluation logic: `(A && B) || (C && D)`
 
 ## 7. Condition Inversion (NOT)
-Any condition can be negated by setting `inverted: true` in its options. This is handled by the runtime, so your plugin implementation doesn't need to worry about it.
+
+Any condition can be negated by setting `inverted: true` in its `options`. This is handled by the runtime, so plugin implementations do not need special inversion logic.
 
 ```json
 {
-  "id": "not-blocked",
+  "id": "not-blocked-rule",
+  "type": "simple_rule",
+  "options": {},
+  "actions": [],
   "conditions": [
-    { 
-      "type": "is_user_blocked", 
-      "options": { "inverted": true } 
+    {
+      "id": "not-blocked",
+      "type": "is_user_blocked",
+      "options": { "inverted": true },
+      "params": []
     }
   ]
 }
 ```
-**Evaluation Logic**: `!is_user_blocked`
+
+Evaluation logic: `!is_user_blocked`

package.json

@@ -13,7 +13,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "tshy",
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tshy",
     "dev": "vitest",
     "test": "vitest run",
     "lint": "biome check .",

src/abstracts/AbstractAction.ts

@@ -0,0 +1,34 @@
+import type { Neuron } from "../index.js";
+import type { ActionOptions } from "../interfaces/Action.js";
+import type { ParameterInterface } from "../interfaces/Parameter.js";
+import type { ExecutionContext } from "../types/ExecutionContext.js";
+import { AbstractElement } from "./AbstractElement.js";
+
+export abstract class AbstractAction<
+  TOptions extends ActionOptions = ActionOptions,
+> extends AbstractElement<TOptions> {
+  public readonly params: Map<
+    string,
+    { getValue(context: ExecutionContext): unknown | null }
+  >;
+
+  constructor(
+    id: string,
+    type: string,
+    public readonly rawParams: ParameterInterface[],
+    options: TOptions,
+    protected readonly neuron: Neuron,
+  ) {
+    super(id, type, options);
+    this.params = neuron.createParameterMap(rawParams);
+  }
+
+  toJSON(): object {
+    return {
+      id: this.id,
+      type: this.type,
+      params: this.rawParams,
+      options: this.options,
+    };
+  }
+}

src/abstracts/AbstractCondition.ts

@@ -0,0 +1,34 @@
+import type { Neuron } from "../index.js";
+import type { ConditionOptions } from "../interfaces/Condition.js";
+import type { ParameterInterface } from "../interfaces/Parameter.js";
+import type { ExecutionContext } from "../types/ExecutionContext.js";
+import { AbstractElement } from "./AbstractElement.js";
+
+export abstract class AbstractCondition<
+  TOptions extends ConditionOptions = ConditionOptions,
+> extends AbstractElement<TOptions> {
+  public readonly params: Map<
+    string,
+    { getValue(context: ExecutionContext): unknown | null }
+  >;
+
+  constructor(
+    id: string,
+    type: string,
+    public readonly rawParams: ParameterInterface[],
+    options: TOptions,
+    protected readonly neuron: Neuron,
+  ) {
+    super(id, type, options);
+    this.params = neuron.createParameterMap(rawParams);
+  }
+
+  toJSON(): object {
+    return {
+      id: this.id,
+      type: this.type,
+      params: this.rawParams,
+      options: this.options,
+    };
+  }
+}