ビジネスルールエンジン

試す

条件を編集すると、文章も判定も説明も同時に変わります。

1. 01

   インストール

   必要なものだけを導入します。エンジンと型定義はランタイム依存ゼロ。ビルダーが別パッケージなのは、ルールを評価するだけのサーバーにReactエディタを送る必要がないからです。

   terminalコピー

   # 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

   ルールを書く

   ルールはただのJSONです。ビルダーがIDと時刻を扱いますが、手で書いても、保存しても、レビューで差分を取っても構いません。

   rules/large-orders.tsコピー

   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

   実行する

   同期的で純粋。レジストリが空から始まるのは、ルールに何を許すかがあなたの選択だからです。結果には判定、アクション、トレースが含まれます。

   rules/run.tsコピー

   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

   読み返す

   すべてのルールは文章になります。ツリーから生成され、決して逆方向に解析されません。まず構造、次に文字列です。

   rules/explain.tsコピー

   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

   独自の演算子を足す

   エンジンができることはすべてプラグインです。登録すればビルダーが提示し、デバッガーが説明し、ルールはJSONのままです。

   rules/registry.tsコピー

   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

   編集できるようにする

   ビジュアルビルダーはプラグインのメタデータだけで動きます。arityが入力欄の数を、acceptsが提示する演算子を決めます。

   app/editor.tsxコピー

   '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

   理由を知る

   デバッガーは判定を決めた行を示し、短絡評価を切ってもう一度実行し、速い経路が飛ばした不具合を明らかにします。

   rules/debug.tsコピー

   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

   保存する

   バージョン管理と復元を備えた単一のストレージ契約。復元は巻き戻しではなく新しいバージョンを書きます。

   rules/storage.tsコピー

   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());

パッケージ構成

各パッケージは必要になった段階で追加されます。使うものだけ導入してください。