Blog/wwwroot/jsonql-js/evaluate.js 12.6 K · 387 lines · raw · history

1 import { SqlEvaluationError } from './errors.js';
2 import { builtins } from './functions.js';
3 import { isAggregateName } from './aggregates.js';
4
5 /**
6 * Evaluates a parsed expression AST against a JSON context object.
7 *
8 * Implements SQL three-valued logic: comparisons and arithmetic against `null`
9 * propagate `null` rather than throwing or coercing, except `IS [NOT] NULL`
10 * which always returns a real boolean.
11 *
12 * @param {import('./parser.js').Expr} node
13 * @param {Record<string, any>} context
14 * @param {{functions?: Record<string, (...args: any[]) => any>}} [options]
15 * @returns {any}
16 */
17 export function evaluate(node, context, options = {}) {
18 const functions = { ...builtins, ...uppercaseKeys(options.functions) };
19 return evalNode(node, context, functions);
20 }
21
22 /**
23 * @param {import('./parser.js').Expr} node
24 * @param {Record<string, any>} ctx
25 * @param {Record<string, (...args: any[]) => any>} functions
26 * @returns {any}
27 */
28 function evalNode(node, ctx, functions) {
29 switch (node.type) {
30 case 'Literal':
31 return node.value;
32 case 'ArrayLiteral':
33 return node.elements.map((e) => evalNode(e, ctx, functions));
34 case 'ObjectLiteral': {
35 /** @type {Record<string, any>} */
36 const out = {};
37 for (const prop of node.properties) {
38 out[prop.key] = evalNode(prop.value, ctx, functions);
39 }
40 return out;
41 }
42 case 'Identifier':
43 case 'Member':
44 case 'Index':
45 case 'Unnest':
46 return evalPathish(node, ctx, functions).value;
47 case 'Call':
48 return evalCall(node, ctx, functions);
49 case 'Negate': {
50 const v = evalNode(node.expr, ctx, functions);
51 if (v === null) return null;
52 if (typeof v !== 'number') throw new SqlEvaluationError(`Cannot negate ${typeName(v)}`);
53 return -v;
54 }
55 case 'Not': {
56 const v = evalNode(node.expr, ctx, functions);
57 if (v === null) return null;
58 if (typeof v !== 'boolean') throw new SqlEvaluationError(`NOT requires a boolean, got ${typeName(v)}`);
59 return !v;
60 }
61 case 'Logical':
62 return evalLogical(node, ctx, functions);
63 case 'Comparison':
64 return evalComparison(node, ctx, functions);
65 case 'IsNull': {
66 const v = evalNode(node.expr, ctx, functions);
67 const isNull = v === null;
68 return node.negate ? !isNull : isNull;
69 }
70 case 'Like':
71 return evalLike(node, ctx, functions);
72 case 'InList':
73 return evalInList(node, ctx, functions);
74 case 'InArray':
75 return evalInArray(node, ctx, functions);
76 case 'Binary':
77 return evalBinary(node, ctx, functions);
78 case 'Star':
79 throw new SqlEvaluationError('* is not a value; it is only valid as COUNT(*)');
80 default:
81 throw new SqlEvaluationError(`Unknown AST node type: ${/** @type {any} */ (node).type}`);
82 }
83 }
84
85 /**
86 * Path expressions (`Identifier`/`Member`/`Index`/`Unnest`) thread a `mapped` flag: once an
87 * `[]` unnest is hit, every subsequent `.prop`/`[i]` in the chain maps over the resulting array
88 * instead of applying to it directly (e.g. `items[].sku` -> `items.map(i => i.sku)`).
89 * @param {import('./parser.js').Expr} node
90 * @param {Record<string, any>} ctx
91 * @param {Record<string, (...args: any[]) => any>} functions
92 * @returns {{value: any, mapped: boolean}}
93 */
94 function evalPathish(node, ctx, functions) {
95 switch (node.type) {
96 case 'Identifier': {
97 const v = ctx == null ? null : ctx[node.name];
98 return { value: v === undefined ? null : v, mapped: false };
99 }
100 case 'Member': {
101 const base = evalPathish(node.object, ctx, functions);
102 if (base.mapped) {
103 const arr = Array.isArray(base.value) ? base.value : [];
104 return { value: arr.map((item) => memberGet(item, node.property)), mapped: true };
105 }
106 return { value: memberGet(base.value, node.property), mapped: false };
107 }
108 case 'Index': {
109 const base = evalPathish(node.object, ctx, functions);
110 const idx = evalNode(node.index, ctx, functions);
111 if (base.mapped) {
112 const arr = Array.isArray(base.value) ? base.value : [];
113 return { value: arr.map((item) => indexGet(item, idx)), mapped: true };
114 }
115 return { value: indexGet(base.value, idx), mapped: false };
116 }
117 case 'Unnest': {
118 const base = evalPathish(node.object, ctx, functions);
119 if (base.mapped) {
120 const arr = Array.isArray(base.value) ? base.value : [];
121 const flattened = arr.flatMap((v) => {
122 if (v === null || v === undefined) return [];
123 if (Array.isArray(v)) return v;
124 throw new SqlEvaluationError('Cannot unnest a non-array value');
125 });
126 return { value: flattened, mapped: true };
127 }
128 if (base.value === null || base.value === undefined) return { value: [], mapped: true };
129 if (!Array.isArray(base.value)) throw new SqlEvaluationError('Cannot unnest a non-array value');
130 return { value: base.value, mapped: true };
131 }
132 default:
133 return { value: evalNode(node, ctx, functions), mapped: false };
134 }
135 }
136
137 /** @param {any} obj @param {string} prop */
138 function memberGet(obj, prop) {
139 if (obj === null || obj === undefined) return null;
140 if (typeof obj !== 'object' || Array.isArray(obj)) return null;
141 const v = obj[prop];
142 return v === undefined ? null : v;
143 }
144
145 /** @param {any} obj @param {any} idx */
146 function indexGet(obj, idx) {
147 if (obj === null || obj === undefined || idx === null) return null;
148 if (Array.isArray(obj)) {
149 if (typeof idx !== 'number' || !Number.isInteger(idx)) {
150 throw new SqlEvaluationError('Array index must be an integer');
151 }
152 const i = idx < 0 ? obj.length + idx : idx;
153 const v = obj[i];
154 return v === undefined ? null : v;
155 }
156 if (typeof obj === 'object') {
157 if (typeof idx !== 'string') throw new SqlEvaluationError('Object index must be a string');
158 const v = obj[idx];
159 return v === undefined ? null : v;
160 }
161 return null;
162 }
163
164 /**
165 * @param {import('./parser.js').LogicalNode} node
166 * @param {Record<string, any>} ctx
167 * @param {Record<string, (...args: any[]) => any>} functions
168 */
169 function evalLogical(node, ctx, functions) {
170 const left = evalNode(node.left, ctx, functions);
171 if (node.op === 'AND') {
172 if (left === false) return false;
173 const right = evalNode(node.right, ctx, functions);
174 if (right === false) return false;
175 if (left === null || right === null) return null;
176 return true;
177 }
178 if (left === true) return true;
179 const right = evalNode(node.right, ctx, functions);
180 if (right === true) return true;
181 if (left === null || right === null) return null;
182 return false;
183 }
184
185 /**
186 * @param {import('./parser.js').ComparisonNode} node
187 * @param {Record<string, any>} ctx
188 * @param {Record<string, (...args: any[]) => any>} functions
189 */
190 function evalComparison(node, ctx, functions) {
191 const l = evalNode(node.left, ctx, functions);
192 const r = evalNode(node.right, ctx, functions);
193 if (l === null || r === null) return null;
194 switch (node.op) {
195 case '=':
196 return deepEqual(l, r);
197 case '!=':
198 return !deepEqual(l, r);
199 case '<':
200 case '>':
201 case '<=':
202 case '>=':
203 requireOrderable(l, r, node.op);
204 if (node.op === '<') return l < r;
205 if (node.op === '>') return l > r;
206 if (node.op === '<=') return l <= r;
207 return l >= r;
208 default:
209 throw new SqlEvaluationError(`Unknown comparison operator: ${node.op}`);
210 }
211 }
212
213 /** @param {any} l @param {any} r @param {string} op */
214 function requireOrderable(l, r, op) {
215 const bothNumbers = typeof l === 'number' && typeof r === 'number';
216 const bothStrings = typeof l === 'string' && typeof r === 'string';
217 if (!bothNumbers && !bothStrings) {
218 throw new SqlEvaluationError(`Cannot compare ${typeName(l)} and ${typeName(r)} with ${op}`);
219 }
220 }
221
222 /**
223 * @param {import('./parser.js').LikeNode} node
224 * @param {Record<string, any>} ctx
225 * @param {Record<string, (...args: any[]) => any>} functions
226 */
227 function evalLike(node, ctx, functions) {
228 const v = evalNode(node.expr, ctx, functions);
229 const pattern = evalNode(node.pattern, ctx, functions);
230 if (v === null || pattern === null) return null;
231 if (typeof v !== 'string' || typeof pattern !== 'string') {
232 throw new SqlEvaluationError('LIKE requires string operands');
233 }
234 const matched = likeToRegExp(pattern).test(v);
235 return node.negate ? !matched : matched;
236 }
237
238 /** @param {string} pattern */
239 function likeToRegExp(pattern) {
240 let re = '';
241 for (const ch of pattern) {
242 if (ch === '%') re += '.*';
243 else if (ch === '_') re += '.';
244 else re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
245 }
246 return new RegExp(`^${re}$`, 's');
247 }
248
249 /**
250 * @param {import('./parser.js').InListNode} node
251 * @param {Record<string, any>} ctx
252 * @param {Record<string, (...args: any[]) => any>} functions
253 */
254 function evalInList(node, ctx, functions) {
255 const v = evalNode(node.expr, ctx, functions);
256 if (v === null) return null;
257 let sawNull = false;
258 for (const itemNode of node.items) {
259 const item = evalNode(itemNode, ctx, functions);
260 if (item === null) {
261 sawNull = true;
262 continue;
263 }
264 if (deepEqual(v, item)) return !node.negate;
265 }
266 if (sawNull) return null;
267 return node.negate;
268 }
269
270 /**
271 * @param {import('./parser.js').InArrayNode} node
272 * @param {Record<string, any>} ctx
273 * @param {Record<string, (...args: any[]) => any>} functions
274 */
275 function evalInArray(node, ctx, functions) {
276 const v = evalNode(node.expr, ctx, functions);
277 const arr = evalNode(node.array, ctx, functions);
278 if (v === null || arr === null) return null;
279 if (!Array.isArray(arr)) throw new SqlEvaluationError('IN requires an array value');
280 let sawNull = false;
281 for (const item of arr) {
282 if (item === null) {
283 sawNull = true;
284 continue;
285 }
286 if (deepEqual(v, item)) return !node.negate;
287 }
288 if (sawNull) return null;
289 return node.negate;
290 }
291
292 /**
293 * @param {import('./parser.js').BinaryNode} node
294 * @param {Record<string, any>} ctx
295 * @param {Record<string, (...args: any[]) => any>} functions
296 */
297 function evalBinary(node, ctx, functions) {
298 const l = evalNode(node.left, ctx, functions);
299 const r = evalNode(node.right, ctx, functions);
300 if (node.op === '||') {
301 if (l === null || r === null) return null;
302 return stringify(l) + stringify(r);
303 }
304 if (l === null || r === null) return null;
305 if (typeof l !== 'number' || typeof r !== 'number') {
306 throw new SqlEvaluationError(`Operator ${node.op} requires numbers, got ${typeName(l)} and ${typeName(r)}`);
307 }
308 switch (node.op) {
309 case '+':
310 return l + r;
311 case '-':
312 return l - r;
313 case '*':
314 return l * r;
315 case '/':
316 if (r === 0) throw new SqlEvaluationError('Division by zero');
317 return l / r;
318 case '%':
319 if (r === 0) throw new SqlEvaluationError('Division by zero');
320 return l % r;
321 default:
322 throw new SqlEvaluationError(`Unknown operator: ${node.op}`);
323 }
324 }
325
326 /** @param {any} v */
327 function stringify(v) {
328 return typeof v === 'string' ? v : JSON.stringify(v);
329 }
330
331 /**
332 * @param {import('./parser.js').CallNode} node
333 * @param {Record<string, any>} ctx
334 * @param {Record<string, (...args: any[]) => any>} functions
335 */
336 function evalCall(node, ctx, functions) {
337 const fn = functions[node.name.toUpperCase()];
338 if (typeof fn !== 'function') {
339 // Aggregates are folded away by the query layer before evaluation, so one
340 // reaching here means it was used outside SELECT/HAVING/ORDER BY.
341 if (isAggregateName(node.name)) {
342 throw new SqlEvaluationError(
343 `${node.name.toUpperCase()} is an aggregate function; it can only be used in a query's SELECT, HAVING or ORDER BY clause`,
344 );
345 }
346 throw new SqlEvaluationError(`Unknown function: ${node.name}`);
347 }
348 const args = node.args.map((a) => evalNode(a, ctx, functions));
349 return fn(...args);
350 }
351
352 /** @param {any} a @param {any} b */
353 function deepEqual(a, b) {
354 if (a === b) return true;
355 if (Array.isArray(a) && Array.isArray(b)) {
356 if (a.length !== b.length) return false;
357 return a.every((v, i) => deepEqual(v, b[i]));
358 }
359 if (isPlainObject(a) && isPlainObject(b)) {
360 const ak = Object.keys(a);
361 const bk = Object.keys(b);
362 if (ak.length !== bk.length) return false;
363 return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
364 }
365 return false;
366 }
367
368 /** @param {any} v */
369 function isPlainObject(v) {
370 return typeof v === 'object' && v !== null && !Array.isArray(v);
371 }
372
373 /** @param {any} v */
374 function typeName(v) {
375 if (v === null) return 'null';
376 if (Array.isArray(v)) return 'array';
377 return typeof v;
378 }
379
380 /** @param {Record<string, any>|undefined} obj */
381 function uppercaseKeys(obj) {
382 if (!obj) return {};
383 /** @type {Record<string, any>} */
384 const out = {};
385 for (const [k, v] of Object.entries(obj)) out[k.toUpperCase()] = v;
386 return out;
387 }