Skip to content

index.md

Latest commit

 

History

History
76 lines (58 loc) · 3.44 KB

index.md

File metadata and controls

76 lines (58 loc) · 3.44 KB
Raw

Comparison and migration guides

Use these guides to decide when Neuron-JS is the right TypeScript rules engine, when another rules library is a better fit, and how to migrate safely when JSON rules need validation, explainability, and deterministic execution.

Neuron-JS should not be chosen by default for every conditional. It fits when business logic must become data: stored, versioned, reviewed, generated, validated, executed, and explained.

Fast decision tree

  • Use plain if/else when a condition is simple, local, and rarely changes.
  • Use JsonLogic when you need compact, portable boolean predicates across languages.
  • Use json-rules-engine when you want the established Node.js JSON rules-engine default with facts, events, and priority semantics.
  • Use node-rules when maintaining an older Node.js rules-engine implementation is cheaper than migration.
  • Use Neuron-JS when a TypeScript system needs serializable JSON business rules, developer-owned registry vocabulary, validation before runtime, and explainable execution traces.

Guides

Comparison matrix

Need Neuron-JS json-rules-engine JsonLogic node-rules if/else
Serializable rules Yes Yes Yes Partial No
TypeScript-first extension points Yes Partial No No Native code
Schema validation before runtime Yes Project-owned Project-owned Project-owned Type checker only
Explanation traces Yes Project-owned Project-owned Project-owned Logs/tests only
AI-generated rule safety Strong fit Possible with custom guardrails Possible for predicates Weak fit Poor fit
Best use Auditable JSON business rules and workflow decisions Established JSON rules-engine workflows Portable predicates Existing older rules systems Simple stable conditions

Migration baseline

Every migration should keep this validation-before-execution contract:

import {
  Neuron,
  Synapse,
  explainExecution,
  summarizeExecutionOutput,
  validateExecutionContext,
  validateScript,
} from '@sebasoft/neuron-js';

const scriptValidation = validateScript(script);
const contextValidation = validateExecutionContext(context);

if (!scriptValidation.ok || !contextValidation.ok) {
  throw new Error('Invalid Neuron-JS input');
}

const result = new Synapse(new Neuron()).execute(script, context);
const output = summarizeExecutionOutput(result);
const explanation = explainExecution({ script, result });

Migration checklist

  • Identify the business decision, not only the existing code shape.
  • List the approved parameters, conditions, actions, and rules.
  • Convert the rule into serializable JSON.
  • Validate with validateScript(script).
  • Validate runtime input with validateExecutionContext(context).
  • Execute through Synapse with the application registry.
  • Normalize output with summarizeExecutionOutput(result).
  • Explain the run with explainExecution({ script, result }).
  • Add tests or snapshots for edge cases and approval workflows.

Related docs