@aglyn/shared-ui-jsx 1.0.0-beta.198 → 1.0.0-beta.199

package/src/lib/const/list-query-plan.js

@@ -0,0 +1,624 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { listFilterDay, listFilterOperators } from "./list-filter.js";
+/** The document id, as a path. */ export const LIST_QUERY_ID_PATH = '__name__';
+/** Firestore's cap on disjunctions — `in` values times `array-contains-any` values. */ export const LIST_QUERY_DISJUNCTIONS = 30;
+/** A very high private-use codepoint: `[p, p + HIGH]` spans every string starting `p`. */ const HIGH = '\uf8ff';
+const csv = (raw)=>raw.split(',').map((entry)=>entry.trim()).filter(Boolean);
+const dayBounds = (raw)=>{
+    const start = listFilterDay(raw);
+    if (Number.isNaN(start.getTime())) return null;
+    const day = new Date(start);
+    day.setHours(0, 0, 0, 0);
+    const end = new Date(day);
+    end.setDate(end.getDate() + 1);
+    return {
+        start: day,
+        end
+    };
+};
+/** The order a range over `path` puts the list in. */ const rangeOrder = (declaration, field, path)=>{
+    const offered = declaration.sorts.find((sort)=>sort.path === path);
+    if (offered) return offered;
+    return {
+        path,
+        direction: (field == null ? void 0 : field.kind) === 'date' ? 'desc' : 'asc'
+    };
+};
+/**
+ * One clause as predicates, or the reason it has none. The same operator
+ * meanings as the AGL-2501 twins (`applyListFilter`, `listFilterConstraints`),
+ * which this replaces for a list that composes clauses.
+ */ function shapeClause(field, input, names) {
+    var _input_value;
+    if (field.windowOnly) return 'this field is not stored where a query can reach it';
+    if (!listFilterOperators(field).includes(input.op)) {
+        return `${input.op} is not something this list can ask of ${field.column}`;
+    }
+    const raw = ((_input_value = input.value) != null ? _input_value : '').trim();
+    const op = input.op;
+    if (op === 'isEmpty') {
+        if (field.presence !== 'nullable') return 'only a field stored as null can be asked for empty';
+        return {
+            filters: [
+                {
+                    path: field.path,
+                    op: '==',
+                    value: null
+                }
+            ]
+        };
+    }
+    if (op === 'isNotEmpty') {
+        if (field.presence === 'always') return 'this field is never empty';
+        return {
+            filters: [
+                {
+                    path: field.path,
+                    op: '!=',
+                    value: null
+                }
+            ],
+            inequality: field.path
+        };
+    }
+    if (field.kind === 'boolean') {
+        if (raw !== 'true' && raw !== 'false') return 'pick true or false';
+        return {
+            filters: [
+                {
+                    path: field.path,
+                    op: '==',
+                    value: raw === 'true'
+                }
+            ]
+        };
+    }
+    if (!raw) return 'no value yet';
+    if (field.keysOf) {
+        if (op !== 'equals' || !/^[A-Za-z0-9_]+$/.test(raw)) return 'pick one of the choices';
+        return {
+            filters: [
+                {
+                    path: `${field.path}.${raw}`,
+                    op: '==',
+                    value: true
+                }
+            ]
+        };
+    }
+    if (field.kind === 'text') {
+        if (op === 'contains' && field.tokensPath) {
+            const token = field.verbatimTokens ? raw : names.token(raw);
+            if (!token) return 'no value yet';
+            return {
+                filters: [
+                    {
+                        path: field.tokensPath,
+                        op: 'array-contains',
+                        value: token
+                    }
+                ],
+                array: true
+            };
+        }
+        if (op === 'equals' && field.lowerPath) {
+            return {
+                filters: [
+                    {
+                        path: field.lowerPath,
+                        op: '==',
+                        value: names.key(raw)
+                    }
+                ]
+            };
+        }
+        if (op === 'equals' && field.presence === 'always' && !field.lowerPath) {
+            return {
+                filters: [
+                    {
+                        path: field.path,
+                        op: '==',
+                        value: raw
+                    }
+                ]
+            };
+        }
+        if (op === 'startsWith' && field.lowerPath) {
+            const key = names.key(raw);
+            return {
+                filters: [
+                    {
+                        path: field.lowerPath,
+                        op: '>=',
+                        value: key
+                    },
+                    {
+                        path: field.lowerPath,
+                        op: '<=',
+                        value: `${key}${HIGH}`
+                    }
+                ],
+                inequality: field.lowerPath
+            };
+        }
+        if (op === 'endsWith' && field.reversedPath) {
+            const key = names.reversed(raw);
+            return {
+                filters: [
+                    {
+                        path: field.reversedPath,
+                        op: '>=',
+                        value: key
+                    },
+                    {
+                        path: field.reversedPath,
+                        op: '<=',
+                        value: `${key}${HIGH}`
+                    }
+                ],
+                inequality: field.reversedPath
+            };
+        }
+        if (op === 'isAnyOf' && field.lowerPath) {
+            const values = csv(raw).map((value)=>names.key(value));
+            if (values.length > LIST_QUERY_DISJUNCTIONS) return `at most ${LIST_QUERY_DISJUNCTIONS} values`;
+            return {
+                filters: [
+                    {
+                        path: field.lowerPath,
+                        op: 'in',
+                        value: values
+                    }
+                ],
+                disjunctions: values.length
+            };
+        }
+        return `${op} is not something this list can ask of ${field.column}`;
+    }
+    if (field.kind === 'id') {
+        if (op === 'equals') return {
+            filters: [
+                {
+                    path: LIST_QUERY_ID_PATH,
+                    op: '==',
+                    value: raw
+                }
+            ]
+        };
+        if (op === 'isAnyOf') {
+            const values = csv(raw);
+            if (values.length > LIST_QUERY_DISJUNCTIONS) return `at most ${LIST_QUERY_DISJUNCTIONS} values`;
+            return {
+                filters: [
+                    {
+                        path: LIST_QUERY_ID_PATH,
+                        op: 'in',
+                        value: values
+                    }
+                ],
+                disjunctions: values.length
+            };
+        }
+        if (op === 'startsWith') {
+            return {
+                filters: [
+                    {
+                        path: LIST_QUERY_ID_PATH,
+                        op: '>=',
+                        value: raw
+                    },
+                    {
+                        path: LIST_QUERY_ID_PATH,
+                        op: '<=',
+                        value: `${raw}${HIGH}`
+                    }
+                ],
+                inequality: LIST_QUERY_ID_PATH
+            };
+        }
+        return `${op} is not something this list can ask of ${field.column}`;
+    }
+    if (field.kind === 'exact') {
+        if (op === 'equals') return {
+            filters: [
+                {
+                    path: field.path,
+                    op: '==',
+                    value: raw
+                }
+            ]
+        };
+        if (op === 'isAnyOf') {
+            const values = csv(raw);
+            if (values.length > LIST_QUERY_DISJUNCTIONS) return `at most ${LIST_QUERY_DISJUNCTIONS} values`;
+            if (field.tokensPath) {
+                // An array field asked "any of these": one array clause.
+                return {
+                    filters: [
+                        {
+                            path: field.tokensPath,
+                            op: 'array-contains-any',
+                            value: values
+                        }
+                    ],
+                    array: true,
+                    disjunctions: values.length
+                };
+            }
+            return {
+                filters: [
+                    {
+                        path: field.path,
+                        op: 'in',
+                        value: values
+                    }
+                ],
+                disjunctions: values.length
+            };
+        }
+        if (op === 'contains' && field.tokensPath) {
+            return {
+                filters: [
+                    {
+                        path: field.tokensPath,
+                        op: 'array-contains',
+                        value: raw
+                    }
+                ],
+                array: true
+            };
+        }
+        return `${op} is not something this list can ask of ${field.column}`;
+    }
+    if (field.kind === 'number') {
+        const value = Number(raw);
+        if (!Number.isFinite(value)) return 'type a number';
+        if (op === '=') return {
+            filters: [
+                {
+                    path: field.path,
+                    op: '==',
+                    value
+                }
+            ]
+        };
+        const comparison = {
+            '!=': '!=',
+            '>': '>',
+            '>=': '>=',
+            '<': '<',
+            '<=': '<='
+        };
+        const found = comparison[op];
+        if (!found) return `${op} is not something this list can ask of ${field.column}`;
+        return {
+            filters: [
+                {
+                    path: field.path,
+                    op: found,
+                    value
+                }
+            ],
+            inequality: field.path
+        };
+    }
+    if (field.kind === 'date') {
+        const day = dayBounds(raw);
+        if (!day) return 'pick a date';
+        // A `…AtMs` field is compared as the number it is stored as.
+        const at = (date)=>field.storedAs === 'millis' ? date.getTime() : date;
+        if (op === 'is') {
+            return {
+                filters: [
+                    {
+                        path: field.path,
+                        op: '>=',
+                        value: at(day.start)
+                    },
+                    {
+                        path: field.path,
+                        op: '<',
+                        value: at(day.end)
+                    }
+                ],
+                inequality: field.path
+            };
+        }
+        const bound = {
+            after: [
+                '>=',
+                day.end
+            ],
+            onOrAfter: [
+                '>=',
+                day.start
+            ],
+            before: [
+                '<',
+                day.start
+            ],
+            onOrBefore: [
+                '<',
+                day.end
+            ]
+        };
+        const found = bound[op];
+        if (!found) return `${op} is not something this list can ask of ${field.column}`;
+        return {
+            filters: [
+                {
+                    path: field.path,
+                    op: found[0],
+                    value: at(found[1])
+                }
+            ],
+            inequality: field.path
+        };
+    }
+    return `${op} is not something this list can ask of ${field.column}`;
+}
+const disjunctionsOf = (filter)=>filter.op === 'in' || filter.op === 'array-contains-any' ? Math.max(1, Array.isArray(filter.value) ? filter.value.length : 1) : 1;
+/**
+ * Every clause and the search, as ONE query — or as much of it as one query
+ * can hold, with the rest refused by name.
+ *
+ * Order of claim: the base (the list's scope) first, then the search, then
+ * the clauses in the order they were added. A clause that would be a second
+ * array clause, a second inequality field or push the disjunctions past
+ * thirty is refused, and the list shows the refusal beside its chip; the
+ * clauses before it stand. The search is claimed before the clauses because
+ * it is the thing a reader typed last and looks at.
+ */ export function planListQuery(declaration, request, names) {
+    var _request_base, _ref, _request_search, _ref1;
+    var _filters_find;
+    const filters = [
+        ...(_request_base = request.base) != null ? _request_base : []
+    ];
+    const served = [];
+    const refused = [];
+    const notices = [];
+    let arrayTaken = filters.some((filter)=>filter.op === 'array-contains' || filter.op === 'array-contains-any');
+    let inequality = (_ref = (_filters_find = filters.find((filter)=>[
+            '!=',
+            '<',
+            '<=',
+            '>',
+            '>='
+        ].includes(filter.op))) == null ? void 0 : _filters_find.path) != null ? _ref : null;
+    let disjunctions = filters.reduce((product, filter)=>product * disjunctionsOf(filter), 1);
+    // The search.
+    let searched = null;
+    const words = ((_request_search = request.search) != null ? _request_search : []).map((word)=>word.trim()).filter(Boolean);
+    if (words.length) {
+        const search = declaration.search;
+        const token = names.token(words.join(' '));
+        if (!search) {
+            refused.push({
+                clause: 'search',
+                reason: 'this list has no search'
+            });
+        } else if (!token) {
+        // Nothing searchable was typed.
+        } else {
+            const scopeAt = filters.findIndex((filter)=>filter.op === 'array-contains-any' || filter.op === 'array-contains');
+            if (scopeAt === -1) {
+                filters.push({
+                    path: search.tokensPath,
+                    op: 'array-contains',
+                    value: token
+                });
+                arrayTaken = true;
+                searched = token;
+            } else if (search.scoped) {
+                // Fold the search into the scope: one array clause answers both.
+                const scope = filters[scopeAt];
+                const scopes = Array.isArray(scope.value) ? scope.value : [
+                    scope.value
+                ];
+                filters.splice(scopeAt, 1, {
+                    path: search.scoped.tokensPath,
+                    op: 'array-contains-any',
+                    value: scopes.map((entry)=>{
+                        var _search_scoped;
+                        return `${String(entry)}${(_search_scoped = search.scoped) == null ? void 0 : _search_scoped.join}${token}`;
+                    })
+                });
+                searched = token;
+            } else {
+                refused.push({
+                    clause: 'search',
+                    reason: 'this list is already narrowed to what you can see, which search cannot combine with'
+                });
+            }
+            if (searched && words.length > 1) {
+                notices.push(`Search matches one word at a time: showing results for "${token}".`);
+            }
+            if (searched && names.key(words[0]).length > names.maxPrefix) {
+                notices.push(`Search reads the first ${names.maxPrefix} letters of a word.`);
+            }
+        }
+    }
+    // The clauses.
+    for (const clause of request.clauses){
+        const field = declaration.fields.find((entry)=>entry.column === clause.field);
+        if (!field) {
+            refused.push({
+                clause,
+                reason: 'this list does not filter by that'
+            });
+            continue;
+        }
+        const shape = shapeClause(field, clause, names);
+        if (typeof shape === 'string') {
+            refused.push({
+                clause,
+                reason: shape
+            });
+            continue;
+        }
+        if (shape.array && arrayTaken) {
+            refused.push({
+                clause,
+                reason: searched ? 'cannot be combined with the search — clear the search to use it' : 'cannot be combined with another "contains" or "any of" filter on a list'
+            });
+            continue;
+        }
+        if (shape.inequality && inequality && shape.inequality !== inequality) {
+            refused.push({
+                clause,
+                reason: 'only one range (dates, numbers, starts with) can apply at a time'
+            });
+            continue;
+        }
+        const product = disjunctions * shape.filters.reduce((total, filter)=>total * disjunctionsOf(filter), 1);
+        if (product > LIST_QUERY_DISJUNCTIONS) {
+            refused.push({
+                clause,
+                reason: `too many values at once (the limit is ${LIST_QUERY_DISJUNCTIONS})`
+            });
+            continue;
+        }
+        filters.push(...shape.filters);
+        served.push(clause);
+        if (shape.array) arrayTaken = true;
+        if (shape.inequality) inequality = shape.inequality;
+        disjunctions = product;
+    }
+    // The order.
+    const asked = request.sort ? declaration.sorts.find((sort)=>{
+        var _request_sort, _request_sort1;
+        return sort.path === ((_request_sort = request.sort) == null ? void 0 : _request_sort.path) && sort.direction === ((_request_sort1 = request.sort) == null ? void 0 : _request_sort1.direction);
+    }) : undefined;
+    const orderBy = inequality ? rangeOrder(declaration, declaration.fields.find((field)=>field.path === inequality || field.lowerPath === inequality || field.reversedPath === inequality), inequality) : (_ref1 = asked != null ? asked : declaration.sorts[0]) != null ? _ref1 : {
+        path: LIST_QUERY_ID_PATH,
+        direction: 'asc'
+    };
+    return {
+        filters,
+        orderBy,
+        served,
+        searched,
+        refused,
+        notices
+    };
+}
+const ORDER = {
+    asc: 'ASCENDING',
+    desc: 'DESCENDING'
+};
+/**
+ * Every composite a declaration's queries can need, under index merging:
+ * one `(predicate field, order)` index per equality or array field and per
+ * order the list can take — its sorts, and the order each range imposes.
+ *
+ * `base` names the scope predicates the list always applies (their paths
+ * and whether they are array clauses), which need their own index per order
+ * like any other equality. Pinned by each list's spec against
+ * `cloud/firebase-firestore.indexes.json`.
+ */ export function listQueryIndexes(declaration, base = []) {
+    const equalities = new Map() // path → is array clause
+    ;
+    const orders = [
+        ...declaration.sorts
+    ];
+    const addOrder = (sort)=>{
+        if (!orders.some((entry)=>entry.path === sort.path && entry.direction === sort.direction)) {
+            orders.push(sort);
+        }
+    };
+    for (const entry of base)equalities.set(entry.path, Boolean(entry.array));
+    if (declaration.search) {
+        equalities.set(declaration.search.tokensPath, true);
+        if (declaration.search.scoped) equalities.set(declaration.search.scoped.tokensPath, true);
+    }
+    for (const field of declaration.fields){
+        if (field.windowOnly) continue;
+        const ops = listFilterOperators(field);
+        const has = (...names)=>names.some((name)=>ops.includes(name));
+        if (field.keysOf) {
+            var _ref;
+            var _declaration_keys;
+            for (const key of (_ref = (_declaration_keys = declaration.keys) == null ? void 0 : _declaration_keys[field.column]) != null ? _ref : []){
+                equalities.set(`${field.path}.${key}`, false);
+            }
+            continue;
+        }
+        if (field.kind === 'text') {
+            if (has('contains') && field.tokensPath) equalities.set(field.tokensPath, true);
+            if (has('equals', 'isAnyOf') && field.lowerPath) equalities.set(field.lowerPath, false);
+            if (has('equals') && !field.lowerPath && field.presence === 'always') equalities.set(field.path, false);
+            if (has('startsWith') && field.lowerPath) addOrder(rangeOrder(declaration, field, field.lowerPath));
+            if (has('endsWith') && field.reversedPath) addOrder(rangeOrder(declaration, field, field.reversedPath));
+        } else if (field.kind === 'exact') {
+            if (has('equals', 'isAnyOf')) equalities.set(field.path, false);
+            if (has('contains', 'isAnyOf') && field.tokensPath) equalities.set(field.tokensPath, true);
+        } else if (field.kind === 'boolean') {
+            equalities.set(field.path, false);
+        } else if (field.kind === 'number') {
+            if (has('=')) equalities.set(field.path, false);
+            if (has('!=', '>', '>=', '<', '<=')) addOrder(rangeOrder(declaration, field, field.path));
+        } else if (field.kind === 'date') {
+            if (has('is', 'after', 'onOrAfter', 'before', 'onOrBefore')) {
+                addOrder(rangeOrder(declaration, field, field.path));
+            }
+        }
+        if (has('isEmpty')) equalities.set(field.path, false);
+        if (has('isNotEmpty')) addOrder(rangeOrder(declaration, field, field.path));
+    }
+    const indexes = [];
+    const seen = new Set();
+    for (const [path, array] of equalities){
+        for (const order of orders){
+            if (order.path === path || order.path === LIST_QUERY_ID_PATH) continue;
+            const index = {
+                fields: [
+                    array ? {
+                        fieldPath: path,
+                        arrayConfig: 'CONTAINS'
+                    } : {
+                        fieldPath: path,
+                        order: 'ASCENDING'
+                    },
+                    {
+                        fieldPath: order.path,
+                        order: ORDER[order.direction]
+                    }
+                ]
+            };
+            const key = JSON.stringify(index);
+            if (!seen.has(key)) {
+                seen.add(key);
+                indexes.push(index);
+            }
+        }
+    }
+    return indexes;
+}
+/**
+ * The composites a declaration needs that an index file does not hold — what
+ * a list's spec asserts is empty, so a declared filter cannot ship without
+ * the index that serves it.
+ */ export function missingListQueryIndexes(file, collectionGroup, needed, queryScope = 'COLLECTION') {
+    const shape = (fields)=>fields.filter((field)=>field.fieldPath !== LIST_QUERY_ID_PATH).map((field)=>{
+            var _field_order;
+            return `${field.fieldPath}:${(_field_order = field.order) != null ? _field_order : field.arrayConfig}`;
+        }).join(',');
+    const present = new Set(file.indexes.filter((index)=>index.collectionGroup === collectionGroup && index.queryScope === queryScope).map((index)=>shape(index.fields)));
+    return needed.filter((index)=>!present.has(shape(index.fields)));
+}
+
+//# sourceMappingURL=list-query-plan.js.map