A pluggable, serializable rules engine for functional programming rulesets.
neuron-js is a lightweight, extensible rules engine designed to execute functional programming logic for other applications in a strictly serializable format. It uses a registry-based architecture—using Neuron for component management and Synapse as the execution engine—allowing you to build, store, and run complex functional rulesets that remain pure JSON.
Perfect for dynamic business rules, automation workflows, and cross-application decision logic.
- 🛠 Pluggable Architecture: Easily register custom Actions, Conditions, and Parameters.
- 📦 JSON Serializable: Logic scripts are pure JSON, perfect for database storage or remote transmission.
- ⚡ Modern Toolchain: Built with Node 24, TypeScript, Biome, and Vitest.
- 🌓 Dual-Module Support: Native ESM and CommonJS support via
tshy. - 🪝 Lifecycle Hooks: Comprehensive hook system for monitoring and side-effect management.
yarn add @sebasoft/neuron-js
# or
npm install @sebasoft/neuron-jsimport { Neuron, Synapse } from '@sebasoft/neuron-js';
// 1. Initialize the registry
const neuron = new Neuron();
// 2. Setup the engine
const synapse = new Synapse(neuron);
// 3. Define your logic script (JSON-serializable)
const script = {
id: 'hello-script',
rules: [
{
id: 'rule-1',
type: 'simple_rule',
options: {},
conditions: [
{
id: 'is-positive',
type: 'compare_two_numbers',
params: [
{ name: 'op1', type: 'simple_number', value: '10' },
{ name: 'comp', type: 'comparator', value: '>' },
{ name: 'op2', type: 'simple_number', value: '0' }
]
}
],
actions: [
{
id: 'add-log',
type: 'add_two_numbers',
params: [
{ name: 'op1', type: 'simple_number', value: '5' },
{ name: 'op2', type: 'simple_number', value: '5' }
]
}
]
}
]
};
// 4. Execute
const context = { messages: [], state: {} };
const result = synapse.execute(script, context);
console.log(result.isSuccessful()); // true
console.log(result.value); // 1 (number of rules executed)The Neuron acts as the central hub where all element types (Actions, Conditions, Parameters, Rules) are registered. It ensures the runtime knows how to instantiate any element defined in your scripts.
The Synapse is the engine that connects a Neuron registry to an ExecutionScript. It traverses the logic and manages the flow of the ExecutionContext.
A Rule is a logical unit containing conditions and actions.
- No Conditions: If a rule has no conditions, it is an "Always" rule and will execute its actions on every run.
- No Actions: If a rule has no actions, it will "Do Nothing"—it evaluates conditions but performs no operations.
- Action: An operation to perform (e.g., "SendEmail", "UpdateDatabase").
- Condition: A logical predicate (e.g., "UserIsAdmin", "ValueIsGreaterThanX").
- Parameter: Configurable inputs for elements, enabling reusable logic templates.
The ExecutionContext is a shared state object that persists throughout the entire execution of a script. It allows Actions and Conditions to communicate and share data.
interface ExecutionContext {
messages: { type: string; text: string }[];
state: Record<string, any>;
}Actions can read from the context and return an updated context to pass information to subsequent rules.
// Example: An action that stores a value in the state
execute(context: ExecutionContext): ExecutionResult {
const newState = { ...context.state, lastCalculation: 42 };
return new ExecutionResult(true, { ...context, state: newState });
}We use a modern toolchain for high performance and developer ergonomics:
- Linting & Formatting: Biome
- Testing: Vitest
- Build: tshy
- Runtime: Node.js 24+
yarn test # Run test suite
yarn lint # Check for linting issues
yarn build # Generate ESM/CJS bundlesMIT © SebaSOFT