@ctserv/rule-evaluator 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# @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
+
+```bash
+npm install @ctserv/rule-evaluator
+```
+
+Local development from FormBuilder:
+
+```bash
+npm install ../Rules\ Evaluator
+```
+
+## Usage
+
+```js
+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:
+
+```js
+// 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:
+
+```bash
+node debug/evaluate-nested-or-and.js
+```
+
+## Operators
+
+`==`, `!=`, `>`, `>=`, `<`, `<=`
+
+Ordering ops use numeric comparison when both sides are finite numbers; otherwise lexicographic string comparison.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ctserv/rule-evaluator",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "Evaluate FormBuilder logic rule conditions from JSON (nested AND/OR groups)",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "formbuilder",
+    "rules",
+    "evaluator"
+  ],
+  "license": "UNLICENSED"
+}

package/src/constants.js

@@ -0,0 +1,15 @@
+export const OPS = ["==", "!=", ">", ">=", "<", "<="];
+
+export const MATCH_MODES = ["all", "any"];
+
+export const GROUP_OPS = ["and", "or"];
+
+export const NODE_TYPES = ["group", "condition"];
+
+export const VALID_ACTIONS = new Set([
+  "disable",
+  "enable",
+  "hide",
+  "show",
+  "resetDefault",
+]);

package/src/evaluate.js

@@ -0,0 +1,110 @@
+import {
+  hasCompleteConditionsInTree,
+  normalizeEnableWhen,
+  normalizeRules,
+} from "./normalize.js";
+
+const NUMERIC_OPS = new Set([">", ">=", "<", "<="]);
+
+export function defaultGetComparableValue(fieldMeta, rawValue) {
+  if (fieldMeta?.type === "select") return rawValue?.value ?? "";
+  if (fieldMeta?.type === "checkbox") {
+    return rawValue === true ? "true" : "false";
+  }
+
+  return rawValue ?? "";
+}
+
+export function compareOp(op, left, right) {
+  const lNum = Number(left);
+  const rNum = Number(right);
+  const canNum = Number.isFinite(lNum) && Number.isFinite(rNum);
+
+  if (NUMERIC_OPS.has(op) && canNum) {
+    if (op === ">") return lNum > rNum;
+    if (op === ">=") return lNum >= rNum;
+    if (op === "<") return lNum < rNum;
+    if (op === "<=") return lNum <= rNum;
+  }
+
+  const lStr = String(left ?? "");
+  const rStr = String(right ?? "");
+
+  if (op === "==") return lStr === rStr;
+  if (op === "!=") return lStr !== rStr;
+  if (op === ">") return lStr > rStr;
+  if (op === ">=") return lStr >= rStr;
+  if (op === "<") return lStr < rStr;
+  if (op === "<=") return lStr <= rStr;
+
+  return false;
+}
+
+function evaluateCondition(condition, values, fieldLookup, getComparableValue) {
+  const fieldName = condition.field;
+  const fieldMeta = fieldLookup?.[fieldName];
+  const rawValue = values?.[fieldName];
+  const actual = getComparableValue(fieldMeta, rawValue);
+
+  return compareOp(condition.op, actual, condition.value);
+}
+
+function evaluateTreeNode(node, values, fieldLookup, getComparableValue) {
+  if (node.type === "condition") {
+    return evaluateCondition(node, values, fieldLookup, getComparableValue);
+  }
+
+  if (node.type === "group") {
+    const children = node.children || [];
+    if (children.length === 0) return false;
+
+    if (node.op === "or") {
+      return children.some((child) =>
+        evaluateTreeNode(child, values, fieldLookup, getComparableValue),
+      );
+    }
+
+    return children.every((child) =>
+      evaluateTreeNode(child, values, fieldLookup, getComparableValue),
+    );
+  }
+
+  return false;
+}
+
+function resolveEnableWhenTree(rules) {
+  if (!rules || typeof rules !== "object") return null;
+
+  if (rules.enableWhen !== undefined) {
+    return normalizeEnableWhen(rules.enableWhen);
+  }
+
+  return normalizeEnableWhen(rules);
+}
+
+/**
+ * @param {object|null} rules - Full rules object or enableWhen tree/flat JSON
+ * @param {object} values - Runtime values keyed by field name
+ * @param {object} [options]
+ * @param {Record<string, object>} [options.fieldLookup]
+ * @param {(fieldMeta: object|undefined, rawValue: unknown) => any} [options.getComparableValue]
+ * @returns {boolean}
+ */
+export function evaluateConditions(rules, values, options = {}) {
+  if (rules == null) return false;
+
+  const tree = resolveEnableWhenTree(rules);
+  if (!tree || !hasCompleteConditionsInTree(tree)) return false;
+
+  const fieldLookup = options.fieldLookup ?? {};
+  const getComparableValue =
+    options.getComparableValue ?? defaultGetComparableValue;
+
+  return evaluateTreeNode(tree, values, fieldLookup, getComparableValue);
+}
+
+export function hasCompleteConditions(rules) {
+  const normalized = normalizeRules(rules);
+  if (!normalized?.enableWhen) return false;
+  return hasCompleteConditionsInTree(normalized.enableWhen);
+}

package/src/format.js

@@ -0,0 +1,100 @@
+import { normalizeEnableWhen, normalizeRules } from "./normalize.js";
+
+function resolveEnableWhen(rules) {
+  if (!rules || typeof rules !== "object") return null;
+
+  if (rules.enableWhen !== undefined) {
+    return normalizeEnableWhen(rules.enableWhen);
+  }
+
+  return normalizeEnableWhen(rules);
+}
+
+function formatConditionValue(value, quoteValues) {
+  const text = value ?? "";
+  if (!quoteValues) return String(text);
+  return `"${String(text)}"`;
+}
+
+function formatCondition(condition, options) {
+  const { quoteValues = true } = options;
+  const value = formatConditionValue(condition.value, quoteValues);
+  return `${condition.field} ${condition.op} ${value}`;
+}
+
+function formatGroupJoiner(op, options) {
+  const { joinerAnd = " AND ", joinerOr = " OR " } = options;
+  return op === "or" ? joinerOr : joinerAnd;
+}
+
+function formatTreeNode(node, options) {
+  if (!node) return null;
+
+  if (node.type === "condition") {
+    return formatCondition(node, options);
+  }
+
+  if (node.type !== "group") return null;
+
+  const joiner = formatGroupJoiner(node.op, options);
+  const { wrapNestedGroups = true } = options;
+  const parts = (node.children || [])
+    .map((child) => {
+      const text = formatTreeNode(child, options);
+      if (!text) return null;
+      if (wrapNestedGroups && child.type === "group") return `(${text})`;
+      return text;
+    })
+    .filter(Boolean);
+
+  if (parts.length === 0) return null;
+  if (parts.length === 1) return parts[0];
+  return parts.join(joiner);
+}
+
+/**
+ * Format rules (or enableWhen only) as a textual AND/OR expression.
+ *
+ * @param {object|null} rules - Full rules object, enableWhen tree/flat JSON, or normalized rules
+ * @param {object} [options]
+ * @param {boolean} [options.quoteValues=true] - Wrap condition values in double quotes
+ * @param {string} [options.joinerAnd=" AND "] - Joiner for and groups
+ * @param {string} [options.joinerOr=" OR "] - Joiner for or groups
+ * @param {boolean} [options.wrapNestedGroups=true] - Wrap nested groups in parentheses
+ * @returns {string|null} Expression such as `(age > "18" AND country == "US") OR vip == "true"`
+ */
+export function formatConditionsExpression(rules, options = {}) {
+  const tree = resolveEnableWhen(rules);
+  if (!tree) return null;
+  return formatTreeNode(tree, options);
+}
+
+/**
+ * Format the full rules object including action when present.
+ *
+ * Example: `Disable this field when (age > "18" AND country == "US") OR vip == "true"`
+ *
+ * @param {object|null} rules
+ * @param {object} [options]
+ * @param {string} [options.targetLabel="this field"] - Label used in action prefix
+ * @returns {string|null}
+ */
+export function formatRulesExpression(rules, options = {}) {
+  const normalized = normalizeRules(rules);
+  if (!normalized) return null;
+
+  const expression = formatConditionsExpression(normalized.enableWhen, options);
+  if (!expression) return null;
+
+  const { targetLabel = "this field" } = options;
+  const action = normalized.action ?? "disable";
+
+  if (action === "hide") return `Hide ${targetLabel} when ${expression}`;
+  if (action === "show") return `Show ${targetLabel} when ${expression}`;
+  if (action === "enable") return `Enable ${targetLabel} when ${expression}`;
+  if (action === "resetDefault") {
+    return `Reset ${targetLabel} to default when ${expression}`;
+  }
+
+  return `Disable ${targetLabel} when ${expression}`;
+}

package/src/index.js

@@ -0,0 +1,31 @@
+export {
+  OPS,
+  MATCH_MODES,
+  GROUP_OPS,
+  NODE_TYPES,
+  VALID_ACTIONS,
+} from "./constants.js";
+
+export {
+  normalizeRules,
+  normalizeEnableWhen,
+  normalizeTreeNode,
+  sanitizeRules,
+  isCompleteCondition,
+  countCompleteConditions,
+  hasCompleteConditionsInTree,
+} from "./normalize.js";
+
+export {
+  evaluateConditions,
+  hasCompleteConditions,
+  compareOp,
+  defaultGetComparableValue,
+} from "./evaluate.js";
+
+export { validateEnableWhenTree } from "./validate.js";
+
+export {
+  formatConditionsExpression,
+  formatRulesExpression,
+} from "./format.js";

package/src/normalize.js

@@ -0,0 +1,191 @@
+import { GROUP_OPS, VALID_ACTIONS } from "./constants.js";
+
+function matchToGroupOp(match) {
+  return match === "any" ? "or" : "and";
+}
+
+function legacyGroupOp(enableWhen) {
+  const legacyAll = Array.isArray(enableWhen.all) ? enableWhen.all : [];
+  const legacyAny = Array.isArray(enableWhen.any) ? enableWhen.any : [];
+
+  if (legacyAny.length > 0 && legacyAll.length === 0) {
+    return { op: "or", items: legacyAny };
+  }
+
+  return { op: "and", items: legacyAll };
+}
+
+export function isCompleteCondition(node) {
+  return Boolean(node?.field && node?.op);
+}
+
+function normalizeCondition(node) {
+  if (!node || typeof node !== "object") return null;
+  if (!isCompleteCondition(node)) return null;
+
+  return {
+    type: "condition",
+    field: node.field,
+    op: node.op,
+    value: node.value ?? "",
+  };
+}
+
+function normalizeGroupNode(node) {
+  if (!node || typeof node !== "object" || node.type !== "group") return null;
+
+  const op = node.op === "or" ? "or" : "and";
+  const children = (Array.isArray(node.children) ? node.children : [])
+    .map(normalizeTreeNode)
+    .filter(Boolean);
+
+  if (children.length === 0) return null;
+
+  return { type: "group", op, children };
+}
+
+export function normalizeTreeNode(node) {
+  if (!node || typeof node !== "object") return null;
+
+  if (node.type === "group") return normalizeGroupNode(node);
+  if (node.type === "condition") return normalizeCondition(node);
+
+  if (node.field !== undefined) {
+    return normalizeCondition({ type: "condition", ...node });
+  }
+
+  return null;
+}
+
+/** Normalize enableWhen JSON (tree, flat, or legacy) to an internal group tree. */
+export function normalizeEnableWhen(enableWhen) {
+  if (!enableWhen || typeof enableWhen !== "object") return null;
+
+  if (enableWhen.type === "group") {
+    return normalizeGroupNode(enableWhen);
+  }
+
+  if (Array.isArray(enableWhen.conditions)) {
+    const op = matchToGroupOp(enableWhen.match === "any" ? "any" : "all");
+    const children = enableWhen.conditions
+      .map((condition) => normalizeCondition({ type: "condition", ...condition }))
+      .filter(Boolean);
+
+    if (children.length === 0) return null;
+
+    return { type: "group", op, children };
+  }
+
+  const { op, items } = legacyGroupOp(enableWhen);
+  const children = items
+    .map((condition) => normalizeCondition({ type: "condition", ...condition }))
+    .filter(Boolean);
+
+  if (children.length === 0) return null;
+
+  return { type: "group", op, children };
+}
+
+function migrateLegacyAction(rules) {
+  if (rules.action && VALID_ACTIONS.has(rules.action)) {
+    return rules.action;
+  }
+  if (rules.whenMet === "disable") return "disable";
+  return "disable";
+}
+
+function extractRulesObject(rules) {
+  if (!rules || typeof rules !== "object") return null;
+
+  if (rules.enableWhen !== undefined) {
+    return rules;
+  }
+
+  if (
+    rules.type === "group" ||
+    rules.match !== undefined ||
+    rules.conditions !== undefined ||
+    rules.all !== undefined ||
+    rules.any !== undefined
+  ) {
+    return { enableWhen: rules };
+  }
+
+  return null;
+}
+
+/** Normalize legacy, flat, and nested shapes to a canonical rules object. */
+export function normalizeRules(rules) {
+  const source = extractRulesObject(rules);
+  if (!source) return null;
+
+  const enableWhen = normalizeEnableWhen(source.enableWhen);
+  if (!enableWhen) return null;
+
+  const normalized = { enableWhen };
+
+  if (source.action !== undefined || source.whenMet !== undefined) {
+    normalized.action = migrateLegacyAction(source);
+  }
+
+  return normalized;
+}
+
+export function countCompleteConditions(node) {
+  if (!node) return 0;
+
+  if (node.type === "condition") {
+    return isCompleteCondition(node) ? 1 : 0;
+  }
+
+  if (node.type === "group") {
+    return (node.children || []).reduce(
+      (total, child) => total + countCompleteConditions(child),
+      0,
+    );
+  }
+
+  return 0;
+}
+
+export function hasCompleteConditionsInTree(node) {
+  return countCompleteConditions(node) > 0;
+}
+
+export function sanitizeTreeNode(node) {
+  if (!node) return null;
+
+  if (node.type === "condition") {
+    return normalizeCondition(node);
+  }
+
+  if (node.type === "group") {
+    const op = GROUP_OPS.includes(node.op) ? node.op : "and";
+    const children = (node.children || [])
+      .map(sanitizeTreeNode)
+      .filter(Boolean);
+
+    if (children.length === 0) return null;
+
+    return { type: "group", op, children };
+  }
+
+  return null;
+}
+
+/** Strip incomplete nodes; return null if nothing valid remains. */
+export function sanitizeRules(rules) {
+  const normalized = normalizeRules(rules);
+  if (!normalized) return null;
+
+  const enableWhen = sanitizeTreeNode(normalized.enableWhen);
+  if (!enableWhen) return null;
+
+  const sanitized = { enableWhen };
+
+  if (normalized.action !== undefined) {
+    sanitized.action = normalized.action;
+  }
+
+  return sanitized;
+}

package/src/validate.js

@@ -0,0 +1,84 @@
+import { GROUP_OPS, NODE_TYPES, OPS } from "./constants.js";
+import { isCompleteCondition } from "./normalize.js";
+
+function validateConditionNode(node, errors, path) {
+  if (node.type !== "condition") {
+    errors.push(`${path}: expected type "condition"`);
+    return;
+  }
+
+  if (!node.field) {
+    errors.push(`${path}: condition missing field`);
+  }
+
+  if (!node.op) {
+    errors.push(`${path}: condition missing op`);
+  } else if (!OPS.includes(node.op)) {
+    errors.push(`${path}: unsupported op "${node.op}"`);
+  }
+}
+
+function validateGroupNode(node, errors, path) {
+  if (node.type !== "group") {
+    errors.push(`${path}: expected type "group"`);
+    return;
+  }
+
+  if (!GROUP_OPS.includes(node.op)) {
+    errors.push(`${path}: group op must be "and" or "or"`);
+  }
+
+  if (!Array.isArray(node.children) || node.children.length === 0) {
+    errors.push(`${path}: group must have at least one child`);
+    return;
+  }
+
+  node.children.forEach((child, index) => {
+    validateTreeNode(child, errors, `${path}.children[${index}]`);
+  });
+}
+
+function validateTreeNode(node, errors, path = "enableWhen") {
+  if (!node || typeof node !== "object") {
+    errors.push(`${path}: expected object`);
+    return;
+  }
+
+  if (!NODE_TYPES.includes(node.type)) {
+    errors.push(`${path}: unknown node type "${node.type}"`);
+    return;
+  }
+
+  if (node.type === "condition") {
+    validateConditionNode(node, errors, path);
+    return;
+  }
+
+  validateGroupNode(node, errors, path);
+}
+
+/**
+ * Validate a normalized tree-shaped enableWhen node.
+ * Returns { valid: boolean, errors: string[] }.
+ */
+export function validateEnableWhenTree(enableWhen) {
+  const errors = [];
+
+  if (!enableWhen || typeof enableWhen !== "object") {
+    return { valid: false, errors: ["enableWhen must be an object"] };
+  }
+
+  if (enableWhen.type === "group") {
+    validateTreeNode(enableWhen, errors);
+  } else if (Array.isArray(enableWhen.conditions)) {
+    enableWhen.conditions.forEach((condition, index) => {
+      if (!isCompleteCondition(condition)) {
+        errors.push(`enableWhen.conditions[${index}]: incomplete condition`);
+      }
+    });
+  } else {
+    errors.push('enableWhen must be a group tree or flat "conditions" list');
+  }
+
+  return { valid: errors.length === 0, errors };
+}