You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`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.
14
+
`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.
15
15
16
-
Perfect for dynamic business rules, automation workflows, and cross-application decision logic.
16
+
Use it when hardcoded `if/else` logic is too rigid, but a heavyweight workflow or BPMN platform is too much machinery.
- Examples: planned under `examples/` as `NJS-GROWTH-02`
24
+
- Schemas and validation docs: planned as `NJS-GROWTH-03`
25
+
- AI-readable docs: planned as `NJS-GROWTH-04`
26
+
27
+
---
28
+
29
+
## Why neuron-js?
30
+
31
+
Use `neuron-js` when:
32
+
33
+
- Business rules need to be stored, versioned, audited, or changed without redeploying code.
34
+
- Backend and frontend code need to share the same deterministic rule definitions.
35
+
- AI assistants or workflow tools generate JSON rules that still need developer-owned validation and execution boundaries.
36
+
- Product, pricing, eligibility, routing, or automation decisions change faster than application deployments.
37
+
- A full workflow platform is too heavy, but hardcoded conditional logic is too brittle.
38
+
39
+
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.
console.log(result.value); // 1 (number of rules executed)
109
+
console.log(result.value); // 1 rule executed
110
+
console.log(result.context.messages.map((message) =>message.text)); // includes "Sum result: 15"
90
111
```
91
112
92
113
---
93
114
94
115
## 🧬 Core Concepts
95
116
96
-
### Neuron (The Registry)
97
-
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.
117
+
### Neuron: the registry
118
+
119
+
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.
120
+
121
+
### Synapse: the executor
98
122
99
-
### Synapse (The Executor)
100
-
The `Synapse` is the engine that connects a `Neuron` registry to an `ExecutionScript`. It traverses the logic and manages the flow of the `ExecutionContext`.
123
+
The `Synapse` engine connects a `Neuron` registry with a serializable script and an execution context. It evaluates rules, applies actions, and emits lifecycle hooks.
101
124
102
125
### Rule
126
+
103
127
A Rule is a logical unit containing conditions and actions.
104
-
-**No Conditions**: If a rule has no conditions, it is an **"Always"** rule and will execute its actions on every run.
105
-
-**No Actions**: If a rule has no actions, it will **"Do Nothing"**—it evaluates conditions but performs no operations.
128
+
129
+
-**No Conditions**: the rule is treated as always eligible.
130
+
-**No Actions**: the rule evaluates conditions but performs no operation.
106
131
107
132
### Elements
108
-
-**Action**: An operation to perform (e.g., "SendEmail", "UpdateDatabase").
109
-
-**Condition**: A logical predicate (e.g., "UserIsAdmin", "ValueIsGreaterThanX").
110
-
-**Parameter**: Configurable inputs for elements, enabling reusable logic templates.
133
+
134
+
-**Action**: An operation to perform, such as writing to context, calculating a value, or triggering an approved side effect.
135
+
-**Condition**: A predicate that decides whether a rule should run.
136
+
-**Parameter**: A serializable input for actions and conditions.
111
137
112
138
---
113
139
114
140
## 💾 Execution Context & State
115
141
116
-
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.
142
+
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.
`neuron-js` is a lightweight, extensible, and JSON-serializable execution engine for JavaScript. It allows developers to define complex logic flows (functional scripts) that can be stored in a database, transmitted over the wire, and executed consistently in both Node.js and browser environments.
3
+
`neuron-js` is a lightweight TypeScript rules engine for serializable JSON business rules and deterministic workflow decisions.
4
4
5
-
## The Problem
6
-
Hardcoding business logic often leads to rigid systems that are difficult to update without a full deployment. Workflow engines are often heavy, difficult to integrate, or use proprietary formats.
5
+
It lets teams define logic as structured data, execute that logic through a developer-owned registry, and run the same deterministic rules in Node.js or the browser.
7
6
8
-
## The Solution
9
-
`neuron-js` provides a registry-based approach to execution logic:
10
-
-**Neuron (Registry)**: Stores the definitions of what is possible (Actions, Conditions, Rules, Parameters).
11
-
-**Synapse (Engine)**: Executes specific scripts by coordinating these definitions in a logical flow.
7
+
## The problem
12
8
13
-
By keeping the script format strictly serializable (JSON), `neuron-js` enables:
14
-
-**Dynamic Logic**: Change business rules at runtime without redeploying code.
15
-
-**Portability**: The same logic can run on a backend server or in a client's browser.
16
-
-**Extensibility**: Easily add new capabilities by implementing simple Action or Condition interfaces.
9
+
Hardcoded business logic is fast at first, but it becomes rigid when product, compliance, pricing, routing, eligibility, or workflow rules change often.
17
10
18
-
## Release Classification
19
-
The `0.4.0` release is a **minor capability release**, not a major breaking change.
11
+
Heavy workflow engines solve configurability, but they can add operational weight, proprietary formats, and integration overhead.
12
+
13
+
## The solution
14
+
15
+
`neuron-js` keeps business logic as JSON and executes it through a TypeScript registry.
16
+
17
+
-**Neuron** defines what is allowed: parameters, conditions, actions, and rules.
18
+
-**Synapse** executes a serializable script against an execution context.
19
+
-**ExecutionContext** carries shared state and messages through the run.
20
+
-**Lifecycle hooks** expose script, rule, action, and error events for observability.
21
+
22
+
This gives applications configurable logic without giving up deterministic execution or developer-owned boundaries.
23
+
24
+
## Use neuron-js when
25
+
26
+
- Rules must be stored in a database or versioned in Git.
27
+
- Product teams need configurable logic without redeploying code.
28
+
- AI-generated rules need validation and approved execution boundaries before runtime.
29
+
- Frontend and backend code need to share deterministic decisions.
30
+
- Workflow automation needs a predictable decision node instead of probabilistic LLM branching.
31
+
- A full BPMN/workflow platform is too heavy for the problem.
32
+
33
+
## Do not use neuron-js when
34
+
35
+
- A simple hardcoded condition is clearer and rarely changes.
36
+
- Arbitrary user code execution is required.
37
+
- You need a full BPMN/process orchestration platform.
38
+
- Non-technical users need unrestricted rule authoring without validation, tests, review, and rollback.
39
+
40
+
## Core architecture
41
+
42
+
### Neuron: registry
43
+
44
+
The `Neuron` registry owns the vocabulary of executable elements. By default, it registers built-in parameters, conditions, actions, and rules. Applications can register custom types to expose only approved capabilities.
45
+
46
+
### Synapse: execution engine
47
+
48
+
`Synapse` receives a `Neuron`, a serializable script, and an execution context. It evaluates rules, executes actions, and returns an execution result.
49
+
50
+
### Script
51
+
52
+
A script is a serializable collection of rules. It can be stored, transmitted, reviewed, and versioned as JSON.
53
+
54
+
### Rule
55
+
56
+
A rule combines conditions and actions. Conditions decide whether the rule should run. Actions perform the approved operation.
57
+
58
+
### Context
59
+
60
+
The execution context stores messages and shared state for the run. Actions can return updated context for later rules.
61
+
62
+
### Hooks
63
+
64
+
Lifecycle hooks let applications monitor execution without embedding observability directly into rule definitions.
65
+
66
+
## Release classification
67
+
68
+
The `0.4.0` release is a minor capability release, not a major breaking change.
20
69
21
70
It expands the documented public API, adds extension base classes, makes missing `options` objects safe at runtime, and cleans package output. Existing JSON script behavior remains compatible; the release gives consumers more stable imports and clearer plugin ergonomics.
22
71
23
-
## Key Features
24
-
-**JSON Serializable**: Logic is data.
25
-
-**Shared Context**: State is managed and passed through the execution chain.
26
-
-**Logical Grouping**: Complex AND/OR condition logic is supported out of the box.
27
-
-**Lifecycle Hooks**: Monitor and react to every step of the execution.
0 commit comments