Business Rules Engine

Try it

Edit any condition. The sentence, the verdict and the explanation follow as you type.

1. 01

   Install

   Take only what you use. The engine and its vocabulary have zero runtime dependencies; the builder is a separate package because a server that only evaluates rules should not ship a React editor.

   terminalCopy

   # the engine and its vocabulary
   pnpm add @adysre/rules-core @adysre/rules-types
   
   # the visual builder, when you want one
   pnpm add @adysre/rules-ui @adysre/rules-react @adysre/rules-theme

2. 02

   Write a rule

   A rule is plain JSON. The builders handle ids and timestamps, but nothing stops you writing the object by hand, storing it, diffing it in review or generating it from somewhere else.

   rules/large-orders.tsCopy

   import { all, condition, field, literal, rule } from '@adysre/rules-core';
   
   // A rule is plain JSON. The builders exist so ids and timestamps are handled
   // for you, but nothing stops you writing the object by hand.
   const largeOrders = rule({
     name: 'Large orders from new customers need approval',
     kind: 'validation',
     when: all([
       condition({
         left: field('order.total'),
         operator: 'greaterThan',
         args: [literal(1000)],
       }),
     ]),
     then: [{ id: 'a_hold', type: 'requireApproval' }],
   });

3. 03

   Run it

   Synchronous and pure. The registry starts empty because what rules may do is your choice; pass the built-ins for the usual set. The result carries the verdict, the actions and the trace.

   rules/run.tsCopy

   import { builtinPlugins, createContext, createRegistry, evaluateRule } from '@adysre/rules-core';
   
   // The registry starts EMPTY: what rules may do is your choice. Pass the
   // built-ins for the usual twenty-seven operators and twenty-three functions.
   const registry = createRegistry(builtinPlugins);
   
   const outcome = evaluateRule(registry, largeOrders, createContext(order));
   
   outcome.verdict;      // 'matched' | 'unmatched' | 'skipped' | 'errored'
   outcome.actions;      // what to do — the engine never does it for you
   outcome.trace;        // every node that ran, and what it concluded

4. 04

   Read it back

   Every rule renders as a sentence, generated from the tree and never parsed back into it. Structure comes first, so a UI can highlight the field being edited rather than reformatting prose.

   rules/explain.tsCopy

   import { describeRule } from '@adysre/rules-renderer';
   
   describeRule(largeOrders, { plugins: registry }).text;
   // When order total is greater than 1,000
   // Then require approval
   
   // Structure first, text second: `.lines` gives typed segments, so a UI can
   // highlight the field being edited or colour the condition that decided it.

5. 05

   Add your own operator

   Everything the engine can do is a plugin. Register one and the builder offers it, the debugger explains it, and your rules stay plain JSON. An operator that cannot answer throws rather than returning false.

   rules/registry.tsCopy

   import { createRegistry, builtinPlugins, RuleError } from '@adysre/rules-core';
   import type { OperatorPlugin } from '@adysre/rules-types';
   
   // Your own operator. The builder picks it up, the debugger explains it, and
   // your rules stay plain JSON — no change to the engine.
   const withinBusinessHours: OperatorPlugin = {
     id: 'withinBusinessHours',
     labelKey: 'operators.withinBusinessHours',
     arity: 0,
     accepts: ['date'],
     evaluate: (left) => {
       if (typeof left !== 'string') {
         // Not `false`: a broken comparison must not look like a failed one.
         throw new RuleError('type_mismatch', 'withinBusinessHours needs a date.');
       }
       const hour = new Date(left).getHours();
       return hour >= 9 && hour < 17;
     },
   };
   
   const registry = createRegistry(builtinPlugins, { operators: [withinBusinessHours] });

6. 06

   Let people edit it

   The visual builder is driven entirely by the plugin metadata: arity decides how many value boxes appear, accepts decides which operators a field is offered. Pass sample data and it runs the rule as you type.

   app/editor.tsxCopy

   'use client';
   
   import { RuleBuilder } from '@adysre/rules-ui';
   
   export function Editor({ rule, onChange }) {
     return (
       <RuleBuilder
         rule={rule}
         registry={registry}
         sample={sampleOrder}   // runs the rule as you type
         onChange={onChange}
       />
     );
   }

7. 07

   Find out why

   The debugger names the row that decided the verdict, and runs the rule a second time with short-circuiting off to surface faults the fast path stepped over.

   rules/debug.tsCopy

   import { debugRule } from '@adysre/rules-devtools';
   
   const session = debugRule(registry, largeOrders, createContext(order));
   
   session.decision;                  // which row decided, or that several did
   session.comparison.hiddenErrors;   // faults a short circuit stepped over

8. 08

   Keep it

   One storage contract with versioning and restore. A restore writes a new version rather than rewinding, and any adapter you write can be checked against the same suite the built-in ones pass.

   rules/storage.tsCopy

   import { createMemoryStorage, runStorageConformance } from '@adysre/rules-storage';
   
   const storage = createMemoryStorage();
   await storage.save(largeOrders);          // version 1
   await storage.restore(largeOrders.id, 1); // a NEW version holding version 1
   
   // Writing your own adapter? Check it against the same contract:
   const results = await runStorageConformance(() => createMyAdapter());

The packages

Each one lands with the phase that gives it something to do. Install only what you use.