evaluateExpression

Description#

Evaluate a single FilterExpression against item.

The contract, in resolution order:

1. Unknown field (fieldDef is undefined) - false. The expression references a field the consumer never declared.
2. Unfilled value - true. The user picked a field and an operator but supplied no value (null / undefined / ''), so the row is a no-op that must not exclude every item. Operators whose definition is valueless (builtin isEmpty / isNotEmpty) are exempt and evaluate normally; the registry passed via options.operators extends this exemption to consumer-registered valueless operators.
3. Unknown operator - one console.warn per key in dev mode, then false for every item. An operator that reaches evaluation without a registered definition is a wiring bug, and a loud conservative false beats a silent one.
4. Otherwise the resolved CngxFilterOperatorDef.evaluate runs with the item value, the expression value, and the evaluation context.

Semantics of the builtin definitions:

• eq / neq compare with Object.is identity - no coercion, no case folding.
• contains / startsWith / endsWith require both sides to be strings (anything else is false) and are case-SENSITIVE unless options.caseInsensitive is true, which lowercases both sides.
• gt / gte / lt / lte order numbers, Date instances, and strings (lexicographic). Nullish operands and mixed/unsupported type pairs compare as NaN, so every ordering test on them is false.