@sebasoft/neuron-js 0.3.0 → 0.5.0

package/examples/eligibility-check/run.ts

@@ -0,0 +1,128 @@
+import {
+  ExecutionResult,
+  MessageType,
+  Neuron,
+  Synapse,
+  type ActionOptions,
+  type ExecutionContext,
+  type ParameterInterface,
+} from "../../dist/esm/index.js";
+import expectedOutput from "./expected-output.json" with { type: "json" };
+import input from "./input.json" with { type: "json" };
+import script from "./rules.json" with { type: "json" };
+
+function readStatePath(context: ExecutionContext, path: string): unknown {
+  return path.split(".").reduce<unknown>((current, segment) => {
+    if (current && typeof current === "object" && segment in current) {
+      return (current as Record<string, unknown>)[segment];
+    }
+    return undefined;
+  }, context.state);
+}
+
+class StateNumberParameter {
+  static readonly TYPE = "state_number";
+
+  readonly id: string;
+  readonly type: string;
+  readonly name: string;
+  readonly value: string;
+  readonly options: Record<string, unknown>;
+
+  constructor(
+    id: string,
+    type: string,
+    name: string,
+    value: string,
+    options: Record<string, unknown>,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.name = name;
+    this.value = value;
+    this.options = options;
+  }
+
+  getValue(context: ExecutionContext): number | null {
+    const value = readStatePath(context, this.value);
+    return typeof value === "number" ? value : null;
+  }
+}
+
+class SetDecisionAction {
+  static readonly TYPE = "set_decision";
+
+  readonly id: string;
+  readonly type: string;
+  private readonly params: ParameterInterface[];
+  readonly options: ActionOptions;
+  private readonly neuron: Neuron;
+
+  constructor(
+    id: string,
+    type: string,
+    params: ParameterInterface[],
+    options: ActionOptions,
+    neuron: Neuron,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.params = params;
+    this.options = options;
+    this.neuron = neuron;
+  }
+
+  execute(context: ExecutionContext): ExecutionResult<string | null> {
+    const decisionParam = this.params.find((param) => param.name === "decision");
+    if (!decisionParam) {
+      return new ExecutionResult(false, context, null, ["Missing decision parameter"]);
+    }
+
+    const ParamCtor = this.neuron.getParameter(decisionParam.type);
+    const decision = ParamCtor
+      ? new ParamCtor(decisionParam.id, decisionParam.type, decisionParam.name, decisionParam.value, decisionParam.options, decisionParam.defaultValue).getValue(context)
+      : null;
+
+    if (typeof decision !== "string") {
+      return new ExecutionResult(false, context, null, ["Invalid decision value"]);
+    }
+
+    const nextContext: ExecutionContext = {
+      ...context,
+      messages: [
+        ...context.messages,
+        { type: MessageType.INFO, text: `Eligibility decision: ${decision}` },
+      ],
+      state: {
+        ...context.state,
+        eligibility: { eligible: decision === "approved", decision },
+      },
+    };
+
+    return new ExecutionResult(true, nextContext, decision);
+  }
+}
+
+const neuron = new Neuron();
+neuron.registerParameter(StateNumberParameter.TYPE, StateNumberParameter);
+neuron.registerAction(SetDecisionAction.TYPE, SetDecisionAction);
+
+const result = new Synapse(neuron).execute(script, input as ExecutionContext);
+const eligibility = result.context.state.eligibility as
+  | { eligible?: boolean; decision?: string }
+  | undefined;
+const actual = {
+  ok: result.isSuccessful(),
+  rulesExecuted: result.value,
+  eligible: eligibility?.eligible,
+  decision: eligibility?.decision,
+  messages: result.context.messages.map((message) => message.text),
+};
+
+if (JSON.stringify(actual) !== JSON.stringify(expectedOutput)) {
+  console.error(JSON.stringify({ expected: expectedOutput, actual }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify(actual, null, 2));
+

package/examples/pricing-rules/README.md

@@ -0,0 +1,31 @@
+# Pricing Rules Example
+
+Run a pricing decision from serializable JSON. The rule checks the cart subtotal from `input.json`, applies a VIP discount from `rules.json`, and verifies the final context against `expected-output.json`.
+
+## Run
+
+From the repository root:
+
+```bash
+yarn build
+node examples/pricing-rules/run.ts
+```
+
+Expected summary:
+
+```json
+{
+  "ok": true,
+  "rulesExecuted": 1,
+  "finalTotal": 105,
+  "discountAmount": 20,
+  "messages": ["Applied 16% discount: -20"]
+}
+```
+
+## Files
+
+- `rules.json` — the serializable Neuron-JS script.
+- `input.json` — the execution context used by the script.
+- `expected-output.json` — the checked output summary.
+- `run.ts` — registers the example vocabulary, executes the script, and fails if output differs.

package/examples/pricing-rules/expected-output.json

@@ -0,0 +1,7 @@
+{
+  "ok": true,
+  "rulesExecuted": 1,
+  "finalTotal": 105,
+  "discountAmount": 20,
+  "messages": ["Applied 16% discount: -20"]
+}

package/examples/pricing-rules/input.json

@@ -0,0 +1,7 @@
+{
+  "messages": [],
+  "state": {
+    "cart": { "subtotal": 125, "currency": "USD" },
+    "customer": { "segment": "vip" }
+  }
+}

package/examples/pricing-rules/rules.json

@@ -0,0 +1,32 @@
+{
+  "id": "pricing-rules-demo",
+  "rules": [
+    {
+      "id": "vip-order-discount",
+      "type": "simple_rule",
+      "options": {},
+      "conditions": [
+        {
+          "id": "minimum-cart-subtotal",
+          "type": "compare_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "cart-subtotal", "name": "op1", "type": "state_number", "value": "cart.subtotal", "options": {} },
+            { "id": "comparison", "name": "comp", "type": "comparator", "value": ">=", "options": {} },
+            { "id": "discount-threshold", "name": "op2", "type": "simple_number", "value": "100", "options": {} }
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "id": "apply-vip-discount",
+          "type": "apply_discount",
+          "options": {},
+          "params": [
+            { "id": "discount-percent", "name": "percent", "type": "simple_number", "value": "16", "options": {} }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/pricing-rules/run.ts

@@ -0,0 +1,136 @@
+import {
+  ExecutionResult,
+  MessageType,
+  Neuron,
+  Synapse,
+  type ActionOptions,
+  type ExecutionContext,
+  type ParameterInterface,
+} from "../../dist/esm/index.js";
+import expectedOutput from "./expected-output.json" with { type: "json" };
+import input from "./input.json" with { type: "json" };
+import script from "./rules.json" with { type: "json" };
+
+function readStatePath(context: ExecutionContext, path: string): unknown {
+  return path.split(".").reduce<unknown>((current, segment) => {
+    if (current && typeof current === "object" && segment in current) {
+      return (current as Record<string, unknown>)[segment];
+    }
+    return undefined;
+  }, context.state);
+}
+
+class StateNumberParameter {
+  static readonly TYPE = "state_number";
+
+  readonly id: string;
+  readonly type: string;
+  readonly name: string;
+  readonly value: string;
+  readonly options: Record<string, unknown>;
+
+  constructor(
+    id: string,
+    type: string,
+    name: string,
+    value: string,
+    options: Record<string, unknown>,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.name = name;
+    this.value = value;
+    this.options = options;
+  }
+
+  getValue(context: ExecutionContext): number | null {
+    const value = readStatePath(context, this.value);
+    return typeof value === "number" ? value : null;
+  }
+}
+
+class ApplyDiscountAction {
+  static readonly TYPE = "apply_discount";
+
+  readonly id: string;
+  readonly type: string;
+  private readonly params: ParameterInterface[];
+  readonly options: ActionOptions;
+  private readonly neuron: Neuron;
+
+  constructor(
+    id: string,
+    type: string,
+    params: ParameterInterface[],
+    options: ActionOptions,
+    neuron: Neuron,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.params = params;
+    this.options = options;
+    this.neuron = neuron;
+  }
+
+  execute(context: ExecutionContext): ExecutionResult<number | null> {
+    const percentParam = this.params.find((param) => param.name === "percent");
+    if (!percentParam) {
+      return new ExecutionResult(false, context, null, ["Missing percent parameter"]);
+    }
+
+    const ParamCtor = this.neuron.getParameter(percentParam.type);
+    const percent = ParamCtor
+      ? new ParamCtor(percentParam.id, percentParam.type, percentParam.name, percentParam.value, percentParam.options, percentParam.defaultValue).getValue(context)
+      : null;
+    const subtotal = readStatePath(context, "cart.subtotal");
+
+    if (typeof subtotal !== "number" || typeof percent !== "number") {
+      return new ExecutionResult(false, context, null, ["Invalid discount input"]);
+    }
+
+    const discountAmount = Math.round(subtotal * (percent / 100));
+    const finalTotal = subtotal - discountAmount;
+    const nextContext: ExecutionContext = {
+      ...context,
+      messages: [
+        ...context.messages,
+        { type: MessageType.INFO, text: `Applied ${percent}% discount: -${discountAmount}` },
+      ],
+      state: {
+        ...context.state,
+        cart: {
+          ...(context.state.cart as Record<string, unknown>),
+          discountPercent: percent,
+          discountAmount,
+          finalTotal,
+        },
+      },
+    };
+
+    return new ExecutionResult(true, nextContext, finalTotal);
+  }
+}
+
+const neuron = new Neuron();
+neuron.registerParameter(StateNumberParameter.TYPE, StateNumberParameter);
+neuron.registerAction(ApplyDiscountAction.TYPE, ApplyDiscountAction);
+
+const result = new Synapse(neuron).execute(script, input as ExecutionContext);
+const cart = result.context.state.cart as
+  | { finalTotal?: number; discountAmount?: number }
+  | undefined;
+const actual = {
+  ok: result.isSuccessful(),
+  rulesExecuted: result.value,
+  finalTotal: cart?.finalTotal,
+  discountAmount: cart?.discountAmount,
+  messages: result.context.messages.map((message) => message.text),
+};
+
+if (JSON.stringify(actual) !== JSON.stringify(expectedOutput)) {
+  console.error(JSON.stringify({ expected: expectedOutput, actual }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify(actual, null, 2));
+

package/examples/workflow-routing/README.md

@@ -0,0 +1,31 @@
+# Workflow Routing Example
+
+Run a deterministic workflow-routing decision from JSON. The rule checks ticket priority from `input.json` and routes high-priority work to the escalation lane.
+
+## Run
+
+From the repository root:
+
+```bash
+yarn build
+node examples/workflow-routing/run.ts
+```
+
+Expected summary:
+
+```json
+{
+  "ok": true,
+  "rulesExecuted": 1,
+  "route": "escalation",
+  "slaHours": 4,
+  "messages": ["Workflow route: escalation within 4h"]
+}
+```
+
+## Files
+
+- `rules.json` — the serializable Neuron-JS script.
+- `input.json` — the execution context used by the script.
+- `expected-output.json` — the checked output summary.
+- `run.ts` — registers the example vocabulary, executes the script, and fails if output differs.

package/examples/workflow-routing/expected-output.json

@@ -0,0 +1,7 @@
+{
+  "ok": true,
+  "rulesExecuted": 1,
+  "route": "escalation",
+  "slaHours": 4,
+  "messages": ["Workflow route: escalation within 4h"]
+}

package/examples/workflow-routing/input.json

@@ -0,0 +1,6 @@
+{
+  "messages": [],
+  "state": {
+    "ticket": { "id": "SUP-1001", "priority": 9, "channel": "enterprise" }
+  }
+}

package/examples/workflow-routing/rules.json

@@ -0,0 +1,33 @@
+{
+  "id": "workflow-routing-demo",
+  "rules": [
+    {
+      "id": "route-critical-ticket",
+      "type": "simple_rule",
+      "options": {},
+      "conditions": [
+        {
+          "id": "priority-threshold",
+          "type": "compare_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "ticket-priority", "name": "op1", "type": "state_number", "value": "ticket.priority", "options": {} },
+            { "id": "comparison", "name": "comp", "type": "comparator", "value": ">=", "options": {} },
+            { "id": "critical-threshold", "name": "op2", "type": "simple_number", "value": "8", "options": {} }
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "id": "assign-escalation-route",
+          "type": "set_route",
+          "options": {},
+          "params": [
+            { "id": "route-name", "name": "route", "type": "simple_string", "value": "escalation", "options": {} },
+            { "id": "sla-hours", "name": "slaHours", "type": "simple_number", "value": "4", "options": {} }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/workflow-routing/run.ts

@@ -0,0 +1,130 @@
+import {
+  ExecutionResult,
+  MessageType,
+  Neuron,
+  Synapse,
+  type ActionOptions,
+  type ExecutionContext,
+  type ParameterInterface,
+} from "../../dist/esm/index.js";
+import expectedOutput from "./expected-output.json" with { type: "json" };
+import input from "./input.json" with { type: "json" };
+import script from "./rules.json" with { type: "json" };
+
+function readStatePath(context: ExecutionContext, path: string): unknown {
+  return path.split(".").reduce<unknown>((current, segment) => {
+    if (current && typeof current === "object" && segment in current) {
+      return (current as Record<string, unknown>)[segment];
+    }
+    return undefined;
+  }, context.state);
+}
+
+class StateNumberParameter {
+  static readonly TYPE = "state_number";
+
+  readonly id: string;
+  readonly type: string;
+  readonly name: string;
+  readonly value: string;
+  readonly options: Record<string, unknown>;
+
+  constructor(
+    id: string,
+    type: string,
+    name: string,
+    value: string,
+    options: Record<string, unknown>,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.name = name;
+    this.value = value;
+    this.options = options;
+  }
+
+  getValue(context: ExecutionContext): number | null {
+    const value = readStatePath(context, this.value);
+    return typeof value === "number" ? value : null;
+  }
+}
+
+class SetRouteAction {
+  static readonly TYPE = "set_route";
+
+  readonly id: string;
+  readonly type: string;
+  private readonly params: ParameterInterface[];
+  readonly options: ActionOptions;
+  private readonly neuron: Neuron;
+
+  constructor(
+    id: string,
+    type: string,
+    params: ParameterInterface[],
+    options: ActionOptions,
+    neuron: Neuron,
+  ) {
+    this.id = id;
+    this.type = type;
+    this.params = params;
+    this.options = options;
+    this.neuron = neuron;
+  }
+
+  private resolveParam(context: ExecutionContext, name: string): unknown {
+    const param = this.params.find((item) => item.name === name);
+    if (!param) return null;
+    const ParamCtor = this.neuron.getParameter(param.type);
+    return ParamCtor
+      ? new ParamCtor(param.id, param.type, param.name, param.value, param.options, param.defaultValue).getValue(context)
+      : null;
+  }
+
+  execute(context: ExecutionContext): ExecutionResult<string | null> {
+    const route = this.resolveParam(context, "route");
+    const slaHours = this.resolveParam(context, "slaHours");
+
+    if (typeof route !== "string" || typeof slaHours !== "number") {
+      return new ExecutionResult(false, context, null, ["Invalid route input"]);
+    }
+
+    const nextContext: ExecutionContext = {
+      ...context,
+      messages: [
+        ...context.messages,
+        { type: MessageType.INFO, text: `Workflow route: ${route} within ${slaHours}h` },
+      ],
+      state: {
+        ...context.state,
+        workflow: { route, slaHours },
+      },
+    };
+
+    return new ExecutionResult(true, nextContext, route);
+  }
+}
+
+const neuron = new Neuron();
+neuron.registerParameter(StateNumberParameter.TYPE, StateNumberParameter);
+neuron.registerAction(SetRouteAction.TYPE, SetRouteAction);
+
+const result = new Synapse(neuron).execute(script, input as ExecutionContext);
+const workflow = result.context.state.workflow as
+  | { route?: string; slaHours?: number }
+  | undefined;
+const actual = {
+  ok: result.isSuccessful(),
+  rulesExecuted: result.value,
+  route: workflow?.route,
+  slaHours: workflow?.slaHours,
+  messages: result.context.messages.map((message) => message.text),
+};
+
+if (JSON.stringify(actual) !== JSON.stringify(expectedOutput)) {
+  console.error(JSON.stringify({ expected: expectedOutput, actual }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify(actual, null, 2));
+

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sebasoft/neuron-js",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "Pluggable and extensible execution runtime for functional logic.",
+  "description": "AI-friendly TypeScript rules engine for serializable JSON business rules and deterministic workflow decisions.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SebaSOFT/neuron-js.git"
@@ -13,9 +13,10 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "tshy",
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tshy",
     "dev": "vitest",
     "test": "vitest run",
+    "examples": "yarn build && node examples/pricing-rules/run.ts && node examples/eligibility-check/run.ts && node examples/workflow-routing/run.ts",
     "lint": "biome check .",
     "format": "biome format --write .",
     "prepare": "yarn build",
@@ -48,6 +49,8 @@
   "files": [
     "dist",
     "src",
+    "schemas",
+    "examples",
     "!src/**/*.test.ts",
     "README.md",
     "LICENSE"
@@ -66,5 +69,29 @@
         "default": "./dist/commonjs/index.js"
       }
     }
-  }
+  },
+  "keywords": [
+    "rules-engine",
+    "rule-engine",
+    "json-rules",
+    "business-rules",
+    "decision-engine",
+    "json-logic",
+    "workflow-automation",
+    "typescript",
+    "javascript",
+    "nodejs",
+    "browser",
+    "ai-agents",
+    "llm",
+    "mcp",
+    "deterministic",
+    "functional-programming",
+    "validation",
+    "feature-flags",
+    "policy-engine",
+    "authorization",
+    "n8n",
+    "langgraph"
+  ]
 }

package/schemas/execution-context.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sebasoft.github.io/neuron-js/schemas/execution-context.schema.json",
+  "title": "Neuron-JS Execution Context",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["messages", "state"],
+  "properties": {
+    "messages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "text"],
+        "properties": {
+          "type": { "enum": ["debug", "info", "warn", "error"] },
+          "text": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "state": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/execution-output.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sebasoft.github.io/neuron-js/schemas/execution-output.schema.json",
+  "title": "Neuron-JS Execution Output",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["ok", "rulesExecuted", "messages"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "rulesExecuted": { "type": ["number", "null"] },
+    "messages": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}