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, n8n, and LangGraph scenarios - 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 and inspectability artifacts first. Benchmark result claims remain blocked until the benchmark harness emits real measured output with claims_allowed: true.
- Benchmark methodology and result contract:
docs/benchmarks/methodology.md - Explainability proof metadata and alt text:
docs/benchmarks/assets/generated/explainability-trace-diagram.md - Visual proof system and publication guardrails:
docs/benchmarks/visual-proof-system.md - Playground README demo capture spec:
docs/playground/readme-demo-capture.md
- 🛠 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.
- 🪝 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"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 n8n and LangGraph workflow automation recipes - JSON Schemas, validation, and explain output:
docs/schemas-validation-explainability.md - Benchmark methodology, visual proof, and playground capture specifications:
docs/benchmarks/anddocs/playground/readme-demo-capture.md - 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