⚙️ Ruleset Engine

A tiny (≈ 1 KB gzipped), zero-dependency TypeScript library for evaluating rule trees expressed as JSON-serializable data.

import { RulesetEngine } from 'ruleset-engine';

const rules = [
  'all',
  { fact: 'age', op: 'gte', value: 18 },
  { fact: 'country', op: 'eq', value: 'AM' }
] as const;

const engine = new RulesetEngine(rules);

engine.evaluate({ age: 21, country: 'AM' }); // → true

✨ Features

| Feature | Notes | | ---------------------------- |--------------------------------------------------------------------------------------| | Declarative rules | Compose predicates with all, any, not_all, and not_any—no code in your data. | | Rich operator set | eq, gt, gte, lt, lte, in, has, and regex out of the box. | | String-template look-ups | Reference dynamic data with {{ path.to.value }} placeholders. | | TypeScript-first | Fully typed API—all rules are validated at compile time. | | Runtime-agnostic | Works in Node, Bun, Deno, or directly in the browser (IIFE/UMD/ESM). |

📦 Install

# ESM / Node ≥18
npm i ruleset-engine
# or
yarn add ruleset-engine
# or
pnpm add ruleset-engine

Via CDN (UMD):

<script src="https://cdn.jsdelivr.net/npm/ruleset-engine/dist-cdn/index.umd.js"></script>
<script>
  const engine = new RulesetEngine(...);
  /* … */
</script>

🚀 Quick start

import { RulesetEngine, Ruleset } from 'ruleset-engine';

const discountRules: Ruleset = [
  'any',
  ['all',
    { fact: 'user.segment', op: 'eq', value: 'vip' },
    { fact: 'order.total', op: 'gte', value: 100 }
  ],
  { fact: 'coupon', op: 'eq', value: 'SUMMER25' }
];

const engine = new RulesetEngine(discountRules);

engine.evaluate({
  user: { segment: 'vip' },
  order: { total: 130 },
  coupon: null
}); // → true

📚 Rule syntax

type Conjunction = 'all' | 'any' | 'not_all' | 'not_any';

type Operator =
  | 'eq'    // strict equality
  | 'gt'    // >
  | 'gte'   // ≥
  | 'lt'    // <
  | 'lte'   // ≤
  | 'in'    // left ∈ right[]
  | 'has'   // right ⊂ left[]
  | 'regex' // RegExp test

type Predicate = { fact: string; op: Operator; value: unknown };

export type Ruleset = Predicate | [Conjunction, ...Ruleset[]];

String-template values

If value is a string wrapped in {{ }}, it is resolved against the current fact set at evaluation time:

{ fact: 'order.total', op: 'gt', value: '{{ user.maxSpend }}' }

🔌 Extending operators

Need a custom operator? Just derive your own class:

class ExtEngine extends RulesetEngine {
  protected override test(p: Predicate, f: Record<string, unknown>) {
    if (p.op === 'startsWith') {
      const L = this.factValue(p.fact, f);
      const R = String(this.tpl(p.value, f));
      return String(L).startsWith(R);
    }
    return super.test(p, f);
  }
}

🛠 API

| Method | Description | | ----------------------------- | ---------------------------------------------------------------------------------------- | | new RulesetEngine(rules) | Create an engine instance. rules is any valid Ruleset. | | .evaluate(facts, [ruleset]) | Evaluate ruleset (defaults to the root) against a facts object. Returns boolean. |