|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [#5322] Empty combinators reduce to their boolean identities in the |
| 5 | + * analytics filter normalizer — `{$and: []}` = TRUE, `{$or: []}` = FALSE — |
| 6 | + * matching the five `FILTER_LOGIC_CASES` backends row for row. Together with |
| 7 | + * the `{}` / `{$not: {}}` identities #5325 already gave this module, the |
| 8 | + * boolean algebra over the combinators is now complete. |
| 9 | + * |
| 10 | + * # The history this file flips |
| 11 | + * |
| 12 | + * Until the 2026-08-04 #5322 ruling, `buildNode` REFUSED the empty arrays. |
| 13 | + * Its error message argued the opposite position, verbatim: |
| 14 | + * |
| 15 | + * > `"$and" requires a non-empty array. An empty combinator has no defensible |
| 16 | + * > reading — dropping it widens the query, and treating it as "match |
| 17 | + * > nothing" silently empties a chart.` |
| 18 | + * |
| 19 | + * "Treating it as match nothing" is exactly what #5134 ruled for `$or: []` |
| 20 | + * and what `driver-sql` / `driver-memory` / `formula` / `driver-sqlite-wasm` |
| 21 | + * / `driver-mongodb` (#5239) implement. The ruling took the reduction because |
| 22 | + * only a reduction can evaluate a NESTED tree (a rejection must first reduce |
| 23 | + * to decide whether `$and: []` inside a `$or` branch is an error — which |
| 24 | + * concedes the point), and because `{$or: []}` = zero rows is fail-closed |
| 25 | + * where it matters: a scope whose disjunct list loops to zero items hides |
| 26 | + * every row rather than widening to the whole table. The loud authoring-time |
| 27 | + * rejection of the literal spellings lives on as #5330 (publish/lint), not as |
| 28 | + * runtime behavior. |
| 29 | + * |
| 30 | + * # What deliberately did NOT loosen |
| 31 | + * |
| 32 | + * Non-array `$and`/`$or` still throws (this file), as do non-object branches |
| 33 | + * and non-object `$not` operands (pinned in |
| 34 | + * `filter-normalizer-not-null-safe.test.ts`): reduction makes `null` ("no |
| 35 | + * constraint") a meaningful verdict, so silently mapping junk to it would let |
| 36 | + * a malformed disjunct ABSORB its `$or` and widen the query — the exact |
| 37 | + * failure mode the old error message feared, reachable only through the |
| 38 | + * lenient path. |
| 39 | + * |
| 40 | + * Row-level conformance for the four ruled shapes lives in the shared table |
| 41 | + * (`filter-logic-conformance.ts`), executed against a real SQLite engine by |
| 42 | + * `native-sql-filter-logic-conformance.test.ts` and |
| 43 | + * `read-scope-sql-conformance.test.ts`. This file pins the TREE the |
| 44 | + * normalizer produces and the seam where the ObjectQL engine path receives |
| 45 | + * the boolean constant. |
| 46 | + */ |
| 47 | + |
| 48 | +import { describe, it, expect } from 'vitest'; |
| 49 | +import { DatasetSchema } from '@objectstack/spec/ui'; |
| 50 | + |
| 51 | +import { |
| 52 | + normalizeAnalyticsFilterTree, |
| 53 | + collectFilterLeaves, |
| 54 | +} from '../strategies/filter-normalizer.js'; |
| 55 | +import { AnalyticsService } from '../analytics-service.js'; |
| 56 | + |
| 57 | +const tree = (where: unknown) => normalizeAnalyticsFilterTree({ where }); |
| 58 | + |
| 59 | +const FALSE_NODE = { kind: 'const', value: false }; |
| 60 | +const TRUE_NODE = { kind: 'const', value: true }; |
| 61 | + |
| 62 | +describe('[#5322] buildNode reduces empty combinators to boolean identities', () => { |
| 63 | + it('`{$and: []}` is TRUE — no constraint', () => { |
| 64 | + expect(tree({ $and: [] })).toBeNull(); |
| 65 | + }); |
| 66 | + |
| 67 | + it('`{$or: []}` is FALSE — the zero-row constant', () => { |
| 68 | + expect(tree({ $or: [] })).toEqual(FALSE_NODE); |
| 69 | + }); |
| 70 | + |
| 71 | + it('`$not` negates the REDUCED operand, in both directions', () => { |
| 72 | + expect(tree({ $not: { $and: [] } })).toEqual(FALSE_NODE); // NOT TRUE ≡ FALSE |
| 73 | + expect(tree({ $not: { $or: [] } })).toEqual(TRUE_NODE); // NOT FALSE ≡ TRUE |
| 74 | + }); |
| 75 | + |
| 76 | + it('an empty-combinator branch carries its identity into the enclosing combinator', () => { |
| 77 | + // A `{$and: []}` disjunct is TRUE and ABSORBS the whole `$or` — collapsing |
| 78 | + // to the surviving branches instead is the narrowing #5325 fixed for the |
| 79 | + // literal `{}` disjunct. |
| 80 | + expect(tree({ $or: [{ a: 'x' }, { $and: [] }] })).toBeNull(); |
| 81 | + // A `{$or: []}` conjunct is FALSE; the compiled conjunction carries the |
| 82 | + // constant (row-set: zero rows — pinned via SQL in the conformance suite). |
| 83 | + expect(JSON.stringify(tree({ $and: [{ a: 'x' }, { $or: [] }] }))).toContain('"value":false'); |
| 84 | + expect(JSON.stringify(tree({ a: 'x', $or: [] }))).toContain('"value":false'); |
| 85 | + }); |
| 86 | + |
| 87 | + it('the FALSE constant touches no member', () => { |
| 88 | + expect(collectFilterLeaves(tree({ $or: [] }))).toEqual([]); |
| 89 | + expect(collectFilterLeaves(tree({ $and: [{ $or: [] }] }))).toEqual([]); |
| 90 | + }); |
| 91 | + |
| 92 | + it('non-array `$and`/`$or` still throws — #5322 loosened only the EMPTY array', () => { |
| 93 | + expect(() => tree({ $and: 'x' })).toThrow(/requires an array/); |
| 94 | + expect(() => tree({ $or: { a: 1 } })).toThrow(/requires an array/); |
| 95 | + }); |
| 96 | +}); |
| 97 | + |
| 98 | +// ── The engine-path seam: FALSE reaches ObjectQL as a real zero-row filter ── |
| 99 | + |
| 100 | +const dataset = DatasetSchema.parse({ |
| 101 | + name: 'incidents', |
| 102 | + label: 'Incidents', |
| 103 | + object: 'incident', |
| 104 | + dimensions: [{ name: 'severity', field: 'severity', type: 'string' }], |
| 105 | + measures: [{ name: 'incident_count', aggregate: 'count' }], |
| 106 | +}); |
| 107 | + |
| 108 | +const ROWS: Array<{ severity: string }> = [ |
| 109 | + { severity: 'high' }, |
| 110 | + { severity: 'high' }, |
| 111 | + { severity: 'low' }, |
| 112 | +]; |
| 113 | + |
| 114 | +/** |
| 115 | + * Stand-in for `engine.aggregate`, mirroring how a driver receives the |
| 116 | + * filter: `{$not: {}}` — the spelling `filterNodeToCondition` uses for the |
| 117 | + * FALSE constant, because `formula` and `driver-memory` already pin it as the |
| 118 | + * zero-row filter (#5134) — matches nothing, and an absent/empty filter |
| 119 | + * matches everything. |
| 120 | + */ |
| 121 | +function makeEngine(captured: Array<{ filter?: Record<string, unknown> }>) { |
| 122 | + const matches = (row: Record<string, unknown>, cond: Record<string, unknown>): boolean => |
| 123 | + Object.entries(cond).every(([key, value]) => { |
| 124 | + if (key === '$and') return (value as Record<string, unknown>[]).every((c) => matches(row, c)); |
| 125 | + if (key === '$or') return (value as Record<string, unknown>[]).some((c) => matches(row, c)); |
| 126 | + if (key === '$not') return !matches(row, value as Record<string, unknown>); |
| 127 | + return row[key] === value; |
| 128 | + }); |
| 129 | + return async ( |
| 130 | + _object: string, |
| 131 | + options: { groupBy?: string[]; filter?: Record<string, unknown> }, |
| 132 | + ): Promise<Array<Record<string, unknown>>> => { |
| 133 | + captured.push({ filter: options.filter }); |
| 134 | + const filtered = ROWS.filter((row) => matches(row, options.filter ?? {})); |
| 135 | + return [{ incident_count: filtered.length }]; |
| 136 | + }; |
| 137 | +} |
| 138 | + |
| 139 | +describe('[#5322] the ObjectQL path hands the engine the constant, not silence', () => { |
| 140 | + it('`{$or: []}` arrives as the zero-row `{$not: {}}` and counts zero rows', async () => { |
| 141 | + const captured: Array<{ filter?: Record<string, unknown> }> = []; |
| 142 | + const svc = new AnalyticsService({ |
| 143 | + queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }), |
| 144 | + executeAggregate: makeEngine(captured), |
| 145 | + }); |
| 146 | + |
| 147 | + const result = await svc.queryDataset!(dataset, { |
| 148 | + measures: ['incident_count'], |
| 149 | + runtimeFilter: { $or: [] }, |
| 150 | + }); |
| 151 | + |
| 152 | + // The constant reached the engine as a real zero-row condition — NOT as an |
| 153 | + // absent filter, which every driver reads as "every row". |
| 154 | + expect(captured).toHaveLength(1); |
| 155 | + expect(JSON.stringify(captured[0].filter)).toContain('"$not":{}'); |
| 156 | + expect(result.rows).toEqual([{ incident_count: 0 }]); |
| 157 | + }); |
| 158 | + |
| 159 | + it('`{$and: []}` arrives as no constraint and counts every row', async () => { |
| 160 | + const captured: Array<{ filter?: Record<string, unknown> }> = []; |
| 161 | + const svc = new AnalyticsService({ |
| 162 | + queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }), |
| 163 | + executeAggregate: makeEngine(captured), |
| 164 | + }); |
| 165 | + |
| 166 | + const result = await svc.queryDataset!(dataset, { |
| 167 | + measures: ['incident_count'], |
| 168 | + runtimeFilter: { $and: [] }, |
| 169 | + }); |
| 170 | + |
| 171 | + expect(JSON.stringify(captured[0].filter ?? {})).not.toContain('$and'); |
| 172 | + expect(result.rows).toEqual([{ incident_count: 3 }]); |
| 173 | + }); |
| 174 | + |
| 175 | + it('a `{$and: []}` disjunct absorbs its `$or` instead of narrowing to the other branch', async () => { |
| 176 | + const captured: Array<{ filter?: Record<string, unknown> }> = []; |
| 177 | + const svc = new AnalyticsService({ |
| 178 | + queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }), |
| 179 | + executeAggregate: makeEngine(captured), |
| 180 | + }); |
| 181 | + |
| 182 | + const result = await svc.queryDataset!(dataset, { |
| 183 | + measures: ['incident_count'], |
| 184 | + runtimeFilter: { $or: [{ severity: 'high' }, { $and: [] }] }, |
| 185 | + }); |
| 186 | + |
| 187 | + // Narrowing to `severity = high` would count 2 — the #5297/#5325 seam. |
| 188 | + expect(JSON.stringify(captured[0].filter ?? {})).not.toContain('severity'); |
| 189 | + expect(result.rows).toEqual([{ incident_count: 3 }]); |
| 190 | + }); |
| 191 | +}); |
0 commit comments