@bernierllc/nevar-evaluator

Evaluates condition trees against a flat context using an operator registry for the Nevar rules engine.

Installation

npm install @bernierllc/nevar-evaluator

Usage

import { evaluate, resolveField } from '@bernierllc/nevar-evaluator';
import type { OperatorLookup } from '@bernierllc/nevar-evaluator';
import type { ConditionGroup } from '@bernierllc/nevar-types';

// Any object implementing OperatorLookup (e.g. OperatorRegistry from nevar-operator-registry)
const operators: OperatorLookup = {
  has: (name) => name === 'gte',
  evaluate: (name, field, target) => (field as number) >= (target as number),
};

const tree: ConditionGroup = {
  operator: 'AND',
  conditions: [
    { field: 'user.age', op: 'gte', value: 18 },
  ],
};

const result = evaluate(tree, { user: { age: 21 } }, operators);
// result.matched === true
// result.trace === [{ field: 'user.age', op: 'gte', expected: 18, actual: 21, matched: true }]

// Resolve a dot-path field from a nested object
const value = resolveField({ user: { name: 'Alice' } }, 'user.name');
// 'Alice'

API

evaluate(tree, context, operators)

Recursively evaluates a condition tree (AND / OR / NOT groups) against a context object. Returns a boolean match result and a trace of every condition evaluated.

Parameters:

• tree: ConditionGroup - The root condition group to evaluate
• context: Record<string, unknown> - Key-value context to evaluate against
• operators: OperatorLookup - Operator lookup for resolving and evaluating operators

Returns: EvaluationResult with matched: boolean and trace: EvaluationTrace[]

Throws: NevarEvaluationError if an unknown operator is encountered.

resolveField(context, fieldPath)

Resolves a dot-notation field path against a context object. Returns undefined if any segment is missing.

Parameters:

• context: Record<string, unknown> - The context object
• fieldPath: string - Dot-notation path (e.g. "user.name")

Returns: unknown - The resolved value or undefined

OperatorLookup (type)

Interface for looking up and evaluating operators. Decouples the evaluator from a specific operator registry implementation.

• evaluate(name: string, fieldValue: unknown, targetValue: unknown): boolean
• has(name: string): boolean

Integration Documentation

Logger Integration

This package does not integrate with @bernierllc/logger. As a core package, logger integration is optional and not included by default. Consumers should handle logging at the service layer.

NeverHub Integration

This package does not integrate with @bernierllc/neverhub-adapter. As a core package, NeverHub integration is not applicable. NeverHub registration should be handled by service-layer packages that compose this package.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.