@ctserv/rule-evaluator

Evaluate FormBuilder logic rule conditions from JSON. Returns a boolean — whether the expression is satisfied at runtime.

Pure JavaScript. No React. No DOM. Runs in Node and browser bundlers.

Install

npm install @ctserv/rule-evaluator

Local development from FormBuilder:

npm install ../Rules\ Evaluator

Usage

import {
  evaluateConditions,
  normalizeRules,
  hasCompleteConditions,
} from "@ctserv/rule-evaluator";

const rules = {
  enableWhen: {
    type: "group",
    op: "or",
    children: [
      {
        type: "group",
        op: "and",
        children: [
          { type: "condition", field: "age", op: ">", value: "18" },
          { type: "condition", field: "country", op: "==", value: "US" },
        ],
      },
      { type: "condition", field: "vip", op: "==", value: "true" },
    ],
  },
  action: "disable",
};

const values = { age: "25", country: { value: "US" }, vip: false };

const met = evaluateConditions(rules, values, {
  fieldLookup: {
    age: { type: "inputNumeric" },
    country: { type: "select" },
    vip: { type: "checkbox" },
  },
});

Flat and legacy shapes are normalized internally:

// flat
{ match: "all", conditions: [...] }

// legacy
{ all: [...] }  // or { any: [...] }

API

| Function | Description | |----------|-------------| | evaluateConditions(rules, values, options?) | Returns boolean | | normalizeRules(rules) | Canonical tree-shaped rules object | | hasCompleteConditions(rules) | At least one complete field + op condition | | sanitizeRules(rules) | Strip incomplete nodes; null if nothing valid |

Options

• fieldLookup — map of field name → metadata (type, etc.)
• getComparableValue(fieldMeta, rawValue) — override for type-aware comparisons (dateTime, richEdit, fileUpload)

Default comparable values

| Field type | Comparable | |------------|------------| | inputText, inputNumeric, radioGroup | raw scalar / string | | select | rawValue.value | | checkbox | "true" or "false" | | dateTime, richEdit, fileUpload | use injected getComparableValue |

Debugging

Example scripts live in debug/. Open any file, set breakpoints, then run Debug current file from .vscode/launch.json.

| File | What it exercises | |------|-------------------| | debug/evaluate-flat-and.js | Flat AND rules | | debug/evaluate-flat-or.js | Flat OR rules | | debug/evaluate-nested-or-and.js | Nested OR with inner AND | | debug/evaluate-legacy-all.js | Legacy all[] shape | | debug/evaluate-field-types.js | Select, checkbox, numeric, case sensitivity | | debug/normalize-rules.js | Normalization and sanitize |

Shared helpers: debug/_shared.js.

Or run from terminal:

node debug/evaluate-nested-or-and.js

Operators

==, !=, >, >=, <, <=

Ordering ops use numeric comparison when both sides are finite numbers; otherwise lexicographic string comparison.