AI-friendly TypeScript rules engine for serializable JSON business rules and deterministic workflow decisions.
neuron-js lets teams define business rules and workflow decisions as pure JSON, execute them deterministically in Node.js or the browser, and extend the rule vocabulary with TypeScript actions, conditions, parameters, rules, and lifecycle hooks.
Use it when hardcoded if/else logic is too rigid, but a heavyweight workflow or BPMN platform is too much machinery.
- Documentation: https://sebasoft.github.io/neuron-js/
- npm: https://www.npmjs.com/package/@sebasoft/neuron-js
- GitHub: https://github.com/SebaSOFT/neuron-js
- Examples:
examples/with pricing, eligibility, workflow-routing, a generic decision-runtime example, n8n, and LangGraph scenarios - Decision runtime concept:
docs/concepts/decision-runtime.md - Agentic decision architecture:
docs/concepts/agentic-decision-architecture.md - Schemas and validation docs:
docs/schemas-validation-explainability.md - AI-readable docs:
docs/ai-coding-assistants.md,docs/public/llms.txt, and the officialneuron-jsAI skill - Comparison and migration guides:
docs/comparisons/for json-rules-engine, JsonLogic, node-rules, and if/else migrations - Workflow automation recipes:
docs/integrations/for n8n deterministic routing and LangGraph decision nodes - Proof assets:
docs/benchmarks/methodology.mdfor the benchmark contract anddocs/benchmarks/assets/generated/explainability-trace-diagram.mdfor the inspectable trace diagram
Use neuron-js when:
- Business rules need to be stored, versioned, audited, or changed without redeploying code.
- Backend and frontend code need to share the same deterministic rule definitions.
- AI assistants or workflow tools generate JSON rules that still need developer-owned validation and execution boundaries.
- Product, pricing, eligibility, routing, or automation decisions change faster than application deployments.
- A full workflow platform is too heavy, but hardcoded conditional logic is too brittle.
Do not use neuron-js when a simple hardcoded condition is clearer and rarely changes, when arbitrary user code execution is required, or when you need a full BPMN/process orchestration platform.
Neuron-JS proof material is published as methodology, measured benchmarks, and inspectability artifacts. Benchmark numbers come from a real actual_benchmark harness run only — reproduce them with yarn benchmark.
Measured throughput, cold-start, bundle-size, validation, and explanation overhead across the pricing, eligibility, and workflow-routing scenarios, compared against json-rules-engine, json-logic-js, a hand-coded TypeScript baseline, and rule-engine-js. See the full charts, results table, and provenance:
- Benchmark results (charts + data + provenance):
docs/benchmarks/results.md - Reproduce locally:
yarn benchmarkthenyarn benchmark:charts - Raw measured output:
benchmarks/results/latest.actual.json
- Benchmark methodology (how each metric is measured):
docs/benchmarks/methodology.md - AI-rule safety (why AI-drafted rules need validation):
docs/benchmarks/ai-rule-safety.md - Proof overview and explainability diagram:
docs/benchmarks/
- 🛠 Pluggable TypeScript registry: Register custom Actions, Conditions, Parameters, and Rules.
- 📦 JSON business rules: Store, transmit, version, and audit logic as serializable JSON.
- ⚡ Deterministic execution: Run predictable workflow and business decisions in Node.js or the browser.
- 🧾 Pure decision runtime: Evaluate a caller-defined context snapshot against a declared
DecisionDefinition, validate before execution, return a schema-valid outcome, and keep side effects outside the runtime. - 🪝 Lifecycle hooks: Monitor script, rule, action, and error events around execution.
- 🌓 Dual-module support: Native ESM and CommonJS bundles via
tshy.
yarn add @sebasoft/neuron-js
# or
npm install @sebasoft/neuron-jsimport { Neuron, Synapse } from '@sebasoft/neuron-js';
const neuron = new Neuron();
const synapse = new Synapse(neuron);
const script = {
id: 'pricing-decision',
rules: [
{
id: 'vip-discount-rule',
type: 'simple_rule',
options: {},
conditions: [
{
id: 'minimum-order-value',
type: 'compare_two_numbers',
options: {},
params: [
{ id: 'order-total', name: 'op1', type: 'simple_number', value: '125', options: {} },
{ id: 'comparison', name: 'comp', type: 'comparator', value: '>', options: {} },
{ id: 'threshold', name: 'op2', type: 'simple_number', value: '100', options: {} }
]
}
],
actions: [
{
id: 'calculate-discount',
type: 'add_two_numbers',
options: {},
params: [
{ id: 'base-discount', name: 'op1', type: 'simple_number', value: '10', options: {} },
{ id: 'vip-bonus', name: 'op2', type: 'simple_number', value: '5', options: {} }
]
}
]
}
]
};
const context = { messages: [], state: {} };
const result = synapse.execute(script, context);
console.log(result.isSuccessful()); // true
console.log(result.value); // 1 rule executed
console.log(result.context.messages.map((message) => message.text)); // includes "Sum result: 15"For pure decisions, use the opt-in evaluateDecision API instead of treating mutable workflow execution as a decision contract. A DecisionDefinition declares the context schema, outcome schema, approved component manifest, and executable script. The runtime validates the caller context before any component executes, evaluates against a cloned immutable snapshot, validates the produced outcome, and returns a receipt for review or replay.
The decision runtime is domain-neutral: application-specific meanings belong inside the successful outcome object, while engine status remains one of succeeded, invalid_context, no_decision, or execution_failed. Neuron-JS does not fetch context, persist receipts, call external services, run LLMs, trigger workflow side effects, or provide a CLI/MCP/UI for this profile.
Runnable example: examples/generic-decision-runtime/. For agentic systems, see docs/concepts/agentic-decision-architecture.md: LLM extraction is advisory, the host resolves canonical Decision Context, Neuron-JS evaluates an approved DecisionDefinition, and host-only side-effect routing consumes receipt-backed results.
The Neuron registry knows which parameter, condition, action, and rule types are available. Applications keep control of this registry so generated or stored JSON can only use developer-approved capabilities.
The Synapse engine connects a Neuron registry with a serializable script and an execution context. It evaluates rules, applies actions, and emits lifecycle hooks.
A Rule is a logical unit containing conditions and actions.
- No Conditions: the rule is treated as always eligible.
- No Actions: the rule evaluates conditions but performs no operation.
- Action: An operation to perform, such as writing to context, calculating a value, or triggering an approved side effect.
- Condition: A predicate that decides whether a rule should run.
- Parameter: A serializable input for actions and conditions.
The ExecutionContext is a shared state object that persists through script execution. Actions and conditions can read from it, and actions can return updated context for later rules.
interface ExecutionContext {
messages: { type: string; text: string }[];
state: Record<string, any>;
}The current public surface includes installation, positioning, core concepts, runtime architecture, and runnable examples.
Available adoption assets:
- Runnable examples:
examples/including the generic decision runtime plus n8n and LangGraph workflow automation recipes - Decision runtime concept:
docs/concepts/decision-runtime.md - Agentic decision architecture:
docs/concepts/agentic-decision-architecture.md - JSON Schemas, validation, and explain output:
docs/schemas-validation-explainability.md - Measured benchmarks, methodology, and AI-rule-safety proof:
docs/benchmarks/ - Comparison and migration guides:
docs/comparisons/for choosing and migrating from json-rules-engine, JsonLogic, node-rules, and hand-written if/else - AI-readable docs:
docs/ai-coding-assistants.md,docs/public/llms.txt,docs/public/llms-full.txt, anddocs/public/skills/neuron-js/SKILL.md
We use a modern toolchain for high-signal development:
- Linting & Formatting: Biome
- Testing: Vitest
- Build: tshy
- Runtime: Node.js 24+
yarn test # Run test suite
yarn lint # Check linting and formatting
yarn examples # Build and verify runnable examples
yarn build # Generate ESM/CJS bundles
yarn docs:build # Build API docs and VitePress siteMIT © SebaSOFT