feat: add evaluateWithReason function to return minimal expression that led to true result (#48)

Author: regevbr

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        node-version: [ 18.x, 20.x, 22.x, 24.x ]
+        node-version: [ 20.x, 22.x, 24.x ]
 
     steps:
       - uses: actions/checkout@v5

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+- `yarn install` - Install dependencies
+- `yarn build` - Lint and compile TypeScript
+- `yarn compile` - Compile TypeScript only
+- `yarn test` - Run linting, type tests, and coverage tests
+- `yarn test:unit` - Run unit tests only
+- `yarn test:cover` - Run unit tests with coverage
+- `yarn test:tsd` - Run TypeScript definition tests
+- `yarn lint` - Run TSLint
+- `yarn ci` - Full CI pipeline (lint, compile, type tests, coverage)
+
+Run a single test:
+```sh
+yarn test:unit --grep "test name pattern"
+```
+
+## Architecture
+
+### Two Evaluation Systems
+
+1. **Expression Evaluator** (`src/lib/evaluator.ts`): Evaluates boolean expressions against a context
+   - `evaluate()` - Returns boolean result
+   - `evaluateWithReason()` - Returns `{result, reason}` where reason is the minimal expression that caused the result. For `and`/`or`, reason is always wrapped in array form (e.g., `{or: [reason]}`)
+   - `validate()` - Validates expression structure against a full context
+
+2. **Rule Engine** (`src/lib/engine.ts`): Evaluates rules with conditions and consequences
+   - Rules have a condition (expression) and consequence (message + custom payload)
+   - Can also use rule functions that combine condition checking and consequence in one
+
+### Type System (Critical)
+
+The type system uses `ts-toolbelt` for advanced type manipulation. Generic parameters follow this pattern:
+```typescript
+<Context, FunctionsTable, Ignore, CustomRunOptions>
+```
+
+- **Context**: The object being evaluated against
+- **FunctionsTable**: Custom functions available in expressions
+- **Ignore**: Types to exclude from path extraction (e.g., `Moment`) to avoid TypeScript exhaustion
+- **CustomRunOptions**: User-defined options passed to functions
+
+Key types in `src/types/`:
+- `Expression` - Union type of all valid expression forms (and/or/not/property comparisons/functions)
+- `ValidationContext` - Context with all optional properties required (for validation)
+- `EvaluationResult` - Result of `evaluateWithReason()` with boolean and minimal expression
+
+### Expression Operators
+
+Logical: `and`, `or`, `not`
+Comparison: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `inq`, `nin`, `regexp`, `regexpi`, `exists`
+
+Right-hand side can be: literal value, `{ref: "path"}` to reference context, or math operation `{op, lhs, rhs}`.
+
+## Code Style
+
+- 4-space indentation, single quotes, semicolons required
+- Lines ~140 characters max
+- 100% code coverage required
+- Type tests use TSD in `src/test/types/`
+
+## Node.js Support
+
+Supports Node.js ^20, ^22, or ^24

README.md

@@ -27,7 +27,7 @@ yarn add json-expression-eval
  *Please see tests and examples dir for more usages and examples (under /src)* 
 
 ```typescript
-import {evaluate, Expression, ExpressionHandler, validate, ValidationContext, EvaluatorFuncRunOptions} from 'json-expression-eval';
+import {evaluate, evaluateWithReason, Expression, ExpressionHandler, validate, ValidationContext, EvaluatorFuncRunOptions, EvaluationResult} from 'json-expression-eval';
 import {Moment} from 'moment';
 import moment = require('moment');
 
@@ -139,9 +139,37 @@ const expression: IExampleExpression = {
     await validate<IExampleContext, IExampleFunctionTable, IExampleContextIgnore,
         IExampleCustomEvaluatorFuncRunOptions>(expression, validationContext, functionsTable, {dryRun: true}); // Should not throw
     console.log(await evaluate<IExampleContext, IExampleFunctionTable, IExampleContextIgnore, IExampleCustomEvaluatorFuncRunOptions>(expression, context, functionsTable, {dryRun: true})); // true
+
+    // Example usage 3 - evaluateWithReason returns the minimal expression that led to the result
+    const resultWithReason = await evaluateWithReason<IExampleContext, IExampleFunctionTable, IExampleContextIgnore, IExampleCustomEvaluatorFuncRunOptions>(expression, context, functionsTable, {dryRun: true});
+    console.log(resultWithReason.result); // true
+    console.log(JSON.stringify(resultWithReason.reason)); // {"or":[{"userId":"a@b.com"}]} - the first matching condition in the OR
+
+    // Using ExpressionHandler
+    const handlerResult = await handler.evaluateWithReason(context, {dryRun: true});
+    console.log(handlerResult.result); // true
+    console.log(JSON.stringify(handlerResult.reason)); // {"or":[{"userId":"a@b.com"}]}
 })()
 ```
 
+### evaluateWithReason
+
+The `evaluateWithReason` function evaluates an expression and returns not only the boolean result, but also the minimal sub-expression that led to that result. This is useful for debugging and understanding why an expression evaluated to a specific value.
+
+```typescript
+const result: EvaluationResult<...> = await evaluateWithReason(expression, context, functionsTable, runOptions);
+// result.result - boolean: the evaluation result
+// result.reason - Expression: the minimal expression that caused the result
+```
+
+**Behavior:**
+- For `or` expressions that evaluate to `true`: returns `{or: [reason]}` with the first sub-expression that evaluated to `true`
+- For `or` expressions that evaluate to `false`: returns `{or: [reasons...]}` with all sub-expressions (all failed)
+- For `and` expressions that evaluate to `false`: returns `{and: [reason]}` with the first sub-expression that evaluated to `false`
+- For `and` expressions that evaluate to `true`: returns `{and: [reasons...]}` with all sub-expressions (all passed)
+- For `not` expressions: returns `{not: reason}` wrapping the reason from the inner expression
+- For simple property comparisons and function calls: returns the expression itself
+
 ### Expression
 
 There are 4 types of operators you can use (evaluated in that order of precedence):

package.json

@@ -1,11 +1,11 @@
 {
   "name": "json-expression-eval",
-  "version": "8.2.1",
+  "version": "9.0.0",
   "description": "json serializable rule engine / boolean expression evaluator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "engines": {
-    "node": "^18 || ^20 || ^22 || ^24"
+    "node": "^20 || ^22 || ^24"
   },
   "scripts": {
     "test": "yarn lint && yarn test:tsd && yarn test:cover",
@@ -52,7 +52,7 @@
     "@types/chai": "4.3.20",
     "@types/chai-as-promised": "7.1.8",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.10.0",
+    "@types/node": "^24.10.9",
     "@types/underscore": "^1.13.0",
     "chai": "4.5.0",
     "chai-as-promised": "7.1.2",

src/index.ts

@@ -1,5 +1,5 @@
 export * from './types';
-export {evaluate, validate} from './lib/evaluator';
+export {evaluate, validate, evaluateWithReason} from './lib/evaluator';
 export {validateRules, evaluateRules} from './lib/engine';
 export {ExpressionHandler} from './lib/expressionHandler';
 export {RulesEngine} from './lib/rulesEngine';

src/lib/evaluator.ts

@@ -25,7 +25,8 @@ import {
     FunctionsTable,
     ExtendedCompareOp,
     ValidationContext,
-    PropertyCompareOps, Primitive, MathOp
+    PropertyCompareOps, Primitive, MathOp,
+    EvaluationResult
 } from '../types';
 import {
     assertUnreachable,
@@ -155,42 +156,59 @@ async function evaluateCompareOp<C extends Context, Ignore>(expressionValue: Ext
 async function handleAndOp<C extends Context, F extends FunctionsTable<C, CustomEvaluatorFuncRunOptions>,
     Ignore, CustomEvaluatorFuncRunOptions>
 (andExpression: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>[], context: C, functionsTable: F,
- validation: boolean, runOptions: CustomEvaluatorFuncRunOptions): Promise<boolean> {
+ validation: boolean, runOptions: CustomEvaluatorFuncRunOptions)
+    : Promise<EvaluationResult<C, F, Ignore, CustomEvaluatorFuncRunOptions>> {
     if (andExpression.length === 0) {
         throw new Error('Invalid expression - and operator must have at least one expression');
     }
+    const reasons: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>[] = [];
     for (const currExpression of andExpression) {
-        const result = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(currExpression,
-            context, functionsTable, validation, runOptions);
-        if (!validation && !result) {
-            return false;
+        const runResult = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
+            currExpression, context, functionsTable, validation, runOptions);
+        if (!runResult.result && !validation) {
+            // AND fails on first false
+            const reason = {and: [runResult.reason] as const} as
+                Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>;
+            return {result: false, reason};
         }
+        reasons.push(runResult.reason);
     }
-    return true;
+    return {
+        result: true,
+        reason: {and: reasons} as Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>,
+    };
 }
 
 async function handleOrOp<C extends Context, F extends FunctionsTable<C, CustomEvaluatorFuncRunOptions>,
     Ignore, CustomEvaluatorFuncRunOptions>(
         orExpression: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>[],
         context: C, functionsTable: F, validation: boolean, runOptions: CustomEvaluatorFuncRunOptions)
-    : Promise<boolean> {
+    : Promise<EvaluationResult<C, F, Ignore, CustomEvaluatorFuncRunOptions>> {
     if (orExpression.length === 0) {
         throw new Error('Invalid expression - or operator must have at least one expression');
     }
+    const reasons: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>[] = [];
     for (const currExpression of orExpression) {
-        const result = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
+        const runResult = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
             currExpression, context, functionsTable, validation, runOptions);
-        if (!validation && result) {
-            return true;
+        if (runResult.result && !validation) {
+            // OR succeeds on first true
+            const reason = {or: [runResult.reason] as const} as Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>;
+            return {result: true, reason};
         }
+        reasons.push(runResult.reason);
     }
-    return false;
+    return {
+        result: false,
+        reason: {or: reasons} as Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>,
+    };
 }
 
 async function run<C extends Context, F extends FunctionsTable<C, CustomEvaluatorFuncRunOptions>,
     Ignore, CustomEvaluatorFuncRunOptions>(
         expression: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>, context: C,
-        functionsTable: F, validation: boolean, runOptions: CustomEvaluatorFuncRunOptions): Promise<boolean> {
+        functionsTable: F, validation: boolean, runOptions: CustomEvaluatorFuncRunOptions)
+    : Promise<EvaluationResult<C, F, Ignore, CustomEvaluatorFuncRunOptions>> {
     const expressionKeys = objectKeys(expression);
     if (expressionKeys.length !== 1) {
         throw new Error('Invalid expression - too may keys');
@@ -203,24 +221,30 @@ async function run<C extends Context, F extends FunctionsTable<C, CustomEvaluato
         return handleOrOp<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression.or, context,
             functionsTable, validation, runOptions);
     } else if (isNotCompareOp<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression)) {
-        return !(await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression.not, context,
-            functionsTable, validation, runOptions));
+        const innerResult = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
+            expression.not, context, functionsTable, validation, runOptions);
+        return {
+            result: !innerResult.result,
+            reason: {not: innerResult.reason} as Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>,
+        };
     } else if (isFunctionCompareOp<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression,
         functionsTable, expressionKey)) {
-        return functionsTable[expressionKey](expression[expressionKey], context, {
+        const result = await functionsTable[expressionKey](expression[expressionKey], context, {
             custom: runOptions,
             validation,
         });
+        return {result, reason: expression};
     } else {
         const {value: contextValue, exists} = getFromPath(context, expressionKey);
         if (validation && !exists) {
             throw new Error(`Invalid expression - unknown context key ${expressionKey}`);
         }
-        return evaluateCompareOp<C, Ignore>(
+        const result = await evaluateCompareOp<C, Ignore>(
             (expression as PropertyCompareOps<C, Ignore>)
                 [expressionKey as any as keyof PropertyCompareOps<C, Ignore>] as
                 unknown as ExtendedCompareOp<any, any, any>,
             expressionKey, contextValue, context, validation);
+        return {result, reason: expression};
     }
 }
 
@@ -229,8 +253,9 @@ export const evaluate = async <C extends Context, F extends FunctionsTable<C, Cu
         expression: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>, context: C, functionsTable: F
         , runOptions: CustomEvaluatorFuncRunOptions)
     : Promise<boolean> => {
-    return run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression, context,
+    const runResult = await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression, context,
         functionsTable, false, runOptions);
+    return runResult.result;
 };
 
 // Throws in case of validation error. Does not run functions or compare fields
@@ -242,3 +267,12 @@ export const validate = async <C extends Context, F extends FunctionsTable<C, Cu
     await run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(expression,
         validationContext as C, functionsTable, true, runOptions);
 };
+
+export const evaluateWithReason = async <C extends Context, F extends FunctionsTable<C, CustomEvaluatorFuncRunOptions>,
+    Ignore = never, CustomEvaluatorFuncRunOptions = undefined>(
+        expression: Expression<C, F, Ignore, CustomEvaluatorFuncRunOptions>, context: C, functionsTable: F
+        , runOptions: CustomEvaluatorFuncRunOptions)
+    : Promise<EvaluationResult<C, F, Ignore, CustomEvaluatorFuncRunOptions>> => {
+    return run<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
+        expression, context, functionsTable, false, runOptions);
+};

src/lib/expressionHandler.ts

@@ -1,9 +1,10 @@
-import {evaluate, validate} from './evaluator';
+import {evaluate, validate, evaluateWithReason} from './evaluator';
 import {
     Context,
     Expression,
     FunctionsTable,
-    ValidationContext
+    ValidationContext,
+    EvaluationResult
 } from '../types';
 
 export class ExpressionHandler<C extends Context, F extends FunctionsTable<C, CustomEvaluatorFuncRunOptions>,
@@ -24,4 +25,10 @@ export class ExpressionHandler<C extends Context, F extends FunctionsTable<C, Cu
             this.expression, validationContext, this.functionsTable, runOptions);
     }
 
+    public async evaluateWithReason(context: C, runOptions: CustomEvaluatorFuncRunOptions)
+        : Promise<EvaluationResult<C, F, Ignore, CustomEvaluatorFuncRunOptions>> {
+        return evaluateWithReason<C, F, Ignore, CustomEvaluatorFuncRunOptions>(
+            this.expression, context, this.functionsTable, runOptions);
+    }
+
 }