# neuron-js: AI-friendly TypeScript rules engine

`neuron-js` is a lightweight TypeScript rules engine for serializable JSON business rules and deterministic workflow decisions.

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.

## The problem

Hardcoded business logic is fast at first, but it becomes rigid when product, compliance, pricing, routing, eligibility, or workflow rules change often.

Heavy workflow engines solve configurability, but they can add operational weight, proprietary formats, and integration overhead.

## The solution

`neuron-js` keeps business logic as JSON and executes it through a TypeScript registry.
It is the ideal complement for creating programmable execution flows and incorporating AI into rule engines: AI-generated decisions are validated, normalized, and fed into a deterministic Neuron-JS boundary before any side effect occurs.

- **Neuron** defines what is allowed: parameters, conditions, actions, and rules.
- **Synapse** executes a serializable script against an execution context.
- **ExecutionContext** carries shared state and messages through the run.
- **Lifecycle hooks** expose script, rule, action, and error events for observability.

This gives applications configurable logic without giving up deterministic execution or developer-owned boundaries.

## Use neuron-js when

- Rules must be stored in a database or versioned in Git.
- Product teams need configurable logic without redeploying code.
- AI-generated rules need validation and approved execution boundaries before runtime.
- Frontend and backend code need to share deterministic decisions.
- Workflow automation needs a predictable decision node instead of probabilistic LLM branching.
- A full BPMN/workflow platform is too heavy for the problem.

## Do not use neuron-js when

- A simple hardcoded condition is clearer and rarely changes.
- Arbitrary user code execution is required.
- You need a full BPMN/process orchestration platform.
- Non-technical users need unrestricted rule authoring without validation, tests, review, and rollback.

## Core architecture

### Neuron: registry

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.

### Synapse: execution engine

`Synapse` receives a `Neuron`, a serializable script, and an execution context. It evaluates rules, executes actions, and returns an execution result.

### Script

A script is a serializable collection of rules. It can be stored, transmitted, reviewed, and versioned as JSON.

### Rule

A rule combines conditions and actions. Conditions decide whether the rule should run. Actions perform the approved operation.

### Context

The execution context stores messages and shared state for the run. Actions can return updated context for later rules.

### Hooks

Lifecycle hooks let applications monitor execution without embedding observability directly into rule definitions.

## Release classification

The `0.7.5` source release is a patch release, not a breaking change.

It standardizes the CI toolchain on Node 24: GitHub Actions upgraded to `actions/checkout` v7 and `actions/setup-node` v7, `changesets/action` migrated to v2 with explicit `github-token` and `push-git-tags`, and the OIDC publish script emits ndjson git-tag events. Rule-engine behavior is unchanged; existing JSON scripts and the public API remain compatible.

The release version stated here describes the repository source and its Git tag. Published package availability is a separate npm-registry fact; verify the registry before representing a source release as installable from npm.

## Current and planned adoption assets

Available now:

- npm package: `@sebasoft/neuron-js`
- GitHub repository: <https://github.com/SebaSOFT/neuron-js>
- Documentation site: <https://sebasoft.github.io/neuron-js/>
- Core concepts and use-case documentation in this site
- Runnable examples: [Runnable Examples](/use-cases/runnable-examples)
- JSON Schemas, validation, and explain output: [Schemas, validation, and explainability](/schemas-validation-explainability)
- AI-readable docs: [AI coding assistants](/ai-coding-assistants), [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt), and the official [Neuron-JS AI skill](/skills/neuron-js/SKILL.md)
- Workflow automation recipes: [Integrations](/integrations/) for n8n deterministic routing and LangGraph decision nodes

Planned next:

- Benchmark, playground, and visual proof assets: `NJS-GROWTH-07`

## Key features

- **JSON Serializable**: Logic is data that can be stored, transmitted, and audited.
- **Shared Context**: State and messages pass through the execution chain.
- **Logical Grouping**: AND/OR condition logic is supported by the rule model.
- **Lifecycle Hooks**: Observe execution at script, rule, action, and error boundaries.
- **Type Safe**: Built with TypeScript for a robust developer experience.