Neuron-JS vs JsonLogic / json-logic-js

JsonLogic is a compact, portable JSON predicate format. It is a strong fit when a decision is mostly a boolean expression and cross-language portability matters. Neuron-JS fits when that predicate grows into a TypeScript-owned business decision with named vocabulary, validation, execution output, and explanation traces.

Fast answer

Use Neuron-JS when the rule is part of an application workflow: validate the JSON, execute a deterministic decision, run approved actions, and explain what happened.

Use JsonLogic when you need a compact, language-portable predicate and the output is primarily true or false.

Decision matrix

Need	Neuron-JS	JsonLogic / json-logic-js
JSON representation	Yes	Yes
Predicate-only decisions	Possible	Strong fit
Cross-language portability	JavaScript/TypeScript package focus	Strong ecosystem fit
Named registry components	Yes	Custom operators/project-owned
Actions after conditions	Yes	Not the core model
Schema validation before runtime	Built in	Project-owned
Explanation traces	Built in	Project-owned
Best fit	Validated business workflows and decisions	Portable boolean logic

Choose Neuron-JS when

• The decision needs conditions and approved actions, not only a boolean predicate.
• TypeScript code owns the rule vocabulary and extension points.
• AI-generated rules need schema validation before execution.
• Support, audit, or tests need explanation traces.
• The rule is stored, versioned, reviewed, or changed through a governance process.

Choose JsonLogic when

• The rule is a compact boolean expression.
• Cross-language compatibility is more important than TypeScript registry ergonomics.
• You already have JsonLogic rules and custom operators that are stable.
• The decision does not need Neuron-JS actions, lifecycle hooks, or explanation contracts.

Migration guide

Migrate when a predicate has become product logic that needs ownership, validation, and explainability.

Before: JsonLogic predicate

{
  "and": [
    { ">=": [{ "var": "cart.total" }, 100] },
    { "==": [{ "var": "customer.tier" }, "gold"] }
  ]
}

After: Neuron-JS decision script

{
  "id": "gold-cart-eligibility",
  "rules": [
    {
      "id": "cart-over-threshold",
      "type": "simple_rule",
      "options": {},
      "conditions": [
        {
          "id": "cart-total-check",
          "type": "compare_two_numbers",
          "options": {},
          "params": [
            { "id": "cart-total", "name": "op1", "type": "simple_number", "value": "125", "options": {} },
            { "id": "operator", "name": "comp", "type": "comparator", "value": ">=", "options": {} },
            { "id": "minimum", "name": "op2", "type": "simple_number", "value": "100", "options": {} }
          ]
        }
      ],
      "actions": [
        {
          "id": "eligibility-score",
          "type": "add_two_numbers",
          "options": {},
          "params": [
            { "id": "base-score", "name": "op1", "type": "simple_number", "value": "1", "options": {} },
            { "id": "tier-score", "name": "op2", "type": "simple_number", "value": "1", "options": {} }
          ]
        }
      ]
    }
  ]
}

Validate and explain the migrated rule

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

const context = {
  messages: [],
  state: { cart: { total: 125 }, customer: { tier: 'gold' } },
};

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

if (!scriptValidation.ok || !contextValidation.ok) {
  throw new Error('Invalid migrated rule input');
}

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

Migration checklist

• Separate boolean predicates from actions and side effects.
• Replace anonymous operator trees with named conditions and actions.
• Preserve edge cases for missing values, nulls, strings, and number coercion.
• Add tests that compare JsonLogic results to Neuron-JS outputs during the migration window.
• Validate with validateScript(script) before execution.
• Use explainExecution({ script, result }) to document rule behavior for reviewers.

Related docs

• Comparison hub
• Schemas, validation, and explainability
• Eligibility check example
• llms.txt