@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/records-query.js

@@ -0,0 +1,780 @@
+/**
+ * What a `db` read means, apart from where its rows are stored (15 §10.4, 18-record-search-index): the
+ * rows a page script and `ctx.api.db` see (`RowOut`, one `SlotOut` per field), what a `where`,
+ * `orderBy`, `after` / `skip` / `take` and `select` do to them, what a read may not say, and which of its
+ * conditions an index answers. The platform's reader (services `slot/page/records.ts`) loads its
+ * candidate rows from the database and applies these; the runtime's page unit tests
+ * (`testing.ts`) load them from the test's data and apply the same functions.
+ */
+import { getCompiledTable, getTableField } from '../slot/compile-schema.js';
+import { isRowTimeKey } from '../slot/schema.js';
+export const RECORDS_LIMITS = {
+    /** Rows one call may reach through its anchor or the index, before any other filter. */
+    rowsPerCall: 500,
+    /** `findMany` without `take`. */
+    defaultTake: 100,
+    /** `skip`: further on, page with `after`. */
+    maxSkip: 1_000,
+    /** Values of one `in` / `notIn`. */
+    listValues: 500,
+    /** `count` counts up to this many; more answer this. */
+    countCap: 10_000,
+    /** Rows read by one reader (a page run; one `ctx.api.db` call). */
+    rowsPerRun: 5_000,
+    /**
+     * Stored row data (its JSON, UTF-8 bytes) one batch of calls may read (one `ctx.api.db` call, one
+     * sandbox slice), and one reader: what keeps a read from filling this process's memory, checked
+     * before the rows are loaded (34 §8).
+     */
+    bytesPerCall: 10 * 1024 * 1024,
+    bytesPerRun: 32 * 1024 * 1024,
+    /** One statement of a read, in milliseconds: past it the read fails as `query_timeout` (34 §8). */
+    statementMs: 3_000,
+    includeDepth: 3,
+};
+export class RecordsQueryError extends Error {
+    code;
+    constructor(message, code = 'invalid_read') {
+        super(message);
+        this.code = code;
+        this.name = 'RecordsQueryError';
+    }
+}
+export function limitExceeded(message) {
+    return new RecordsQueryError(message, 'limit_exceeded');
+}
+export const COMBINATORS = new Set(['AND', 'OR', 'NOT']);
+/** Prisma's list filters, on a way back (`relatedName`). */
+export const WAY_BACK_FILTERS = new Set(['some', 'every', 'none']);
+/** What an `include` of a way back may say of its rows. */
+export const RELATION_INCLUDE_KEYS = new Set(['where', 'orderBy', 'skip', 'take', 'include']);
+/** A `multi_select`'s filters, as Prisma's scalar lists (27 §3.2). */
+const LIST_OPERATORS = ['has', 'hasSome', 'hasEvery', 'isEmpty'];
+const OPERATORS = new Set(['equals', 'in', 'notIn', 'not', 'lt', 'lte', 'gt', 'gte', 'startsWith', 'mode', 'state', ...LIST_OPERATORS]);
+/** Searching inside a text: no index serves it on millions of rows, so `db` has none (34 §10). */
+const SEARCH_OPERATORS = new Set(['contains', 'endsWith']);
+/**
+ * Refuses `contains` / `endsWith` as an operator anywhere in a where (under AND / OR / NOT, a `not`, a
+ * relation's filter), saying what to write instead; before anything is read, whatever path the read
+ * takes. A field may be named `contains`: the where's own keys are fields, only a condition's are
+ * operators.
+ */
+export function refuseSearch(tableName, where, path = 'where') {
+    if (!isPlainObject(where))
+        return;
+    for (const [key, value] of Object.entries(where)) {
+        const at = `${path}.${key}`;
+        if (COMBINATORS.has(key)) {
+            if (Array.isArray(value))
+                value.forEach((part, i) => refuseSearch(tableName, part, `${at}[${i}]`));
+            else
+                refuseSearch(tableName, value, at);
+        }
+        else {
+            refuseSearchOperators(tableName, value, at);
+        }
+    }
+}
+/** A field's condition: its operators, and the where inside a `not` or a relation's filter. */
+function refuseSearchOperators(tableName, cond, path) {
+    if (!isPlainObject(cond))
+        return;
+    for (const [op, operand] of Object.entries(cond)) {
+        if (SEARCH_OPERATORS.has(op)) {
+            throw new RecordsQueryError(`records.${tableName}: ${path}.${op} is not supported: find by startsWith (mode: 'insensitive' for any case) or an exact field (a phone, an email, a code); or read the rows narrowed another way and look inside the text in code`);
+        }
+        if (op === 'not')
+            refuseSearchOperators(tableName, operand, `${path}.not`);
+        else if (op === 'is' || op === 'isNot' || WAY_BACK_FILTERS.has(op))
+            refuseSearch(tableName, operand, `${path}.${op}`);
+    }
+}
+/** The fields of a read's conditions and order that are index entries (not row times): their dictionary ids are needed. */
+export function indexedFieldsOf(conditions, order) {
+    return [...conditions.filter((cond) => !cond.row).map((cond) => cond.field), ...(order && !order.row ? [order.field] : [])];
+}
+/**
+ * The conditions of a where that pin it to some rows (top level and top-level AND): `id` or a ref
+ * field equal to / in some ids (15 §10.6.1).
+ */
+export function findAnchors(table, where) {
+    const out = [];
+    const visit = (w) => {
+        for (const [field, cond] of Object.entries(w)) {
+            if (field === 'AND') {
+                for (const part of asArray(cond))
+                    if (isPlainObject(part))
+                        visit(part);
+                continue;
+            }
+            const def = getTableField(table, field);
+            if (field !== 'id' && !def?.ref)
+                continue;
+            const ids = anchorIds(cond);
+            if (ids)
+                out.push({ field, ids });
+        }
+    };
+    visit(where);
+    // `id` first: the primary key is the narrowest; then refs.
+    return out.sort((a, b) => (a.field === 'id' ? 0 : 1) - (b.field === 'id' ? 0 : 1));
+}
+function anchorIds(cond) {
+    if (typeof cond === 'string')
+        return [cond];
+    if (!isPlainObject(cond))
+        return null;
+    const c = cond;
+    if (typeof c.equals === 'string')
+        return [c.equals];
+    if (Array.isArray(c.in) && c.in.every((v) => typeof v === 'string'))
+        return c.in;
+    return null;
+}
+export function relationFilters(table, where) {
+    const out = [];
+    const visit = (w) => {
+        if (!isPlainObject(w))
+            return;
+        for (const [field, cond] of Object.entries(w)) {
+            if (COMBINATORS.has(field)) {
+                for (const part of asArray(cond))
+                    visit(part);
+                continue;
+            }
+            const ref = getTableField(table, field)?.ref;
+            if (ref && isPlainObject(cond) && ('is' in cond || 'isNot' in cond)) {
+                const c = cond;
+                out.push({ field, target: ref.table, sub: [c.is, c.isNot].filter((w) => w !== undefined && w !== null) });
+            }
+        }
+    };
+    visit(where);
+    return out;
+}
+/** `some` / `every` / `none` on a way back (Prisma's list filters): over the rows pointing at `row`. */
+function matchWayBack(context, tableName, row, relation, cond) {
+    const keys = isPlainObject(cond) ? Object.keys(cond) : [];
+    if (keys.length === 0 || keys.some((key) => !WAY_BACK_FILTERS.has(key))) {
+        throw new RecordsQueryError(`records.${tableName}: where.${relation.name} takes some / every / none`);
+    }
+    const c = cond;
+    const rows = context.related.get(relatedKey(tableName, relation.name))?.get(row.id) ?? [];
+    const hit = (where) => (child) => matches(context, relation.table, child, where);
+    if ('some' in c && !rows.some(hit(c.some)))
+        return false;
+    if ('every' in c && !rows.every(hit(c.every)))
+        return false;
+    if ('none' in c && rows.some(hit(c.none)))
+        return false;
+    return true;
+}
+/** The ways back a `where` filters by (top level and inside AND / OR / NOT), with their sub-wheres. */
+export function wayBackFilters(tableName, where, relationOf) {
+    const out = [];
+    const visit = (w) => {
+        if (!isPlainObject(w))
+            return;
+        for (const [key, cond] of Object.entries(w)) {
+            if (COMBINATORS.has(key)) {
+                for (const part of asArray(cond))
+                    visit(part);
+                continue;
+            }
+            const relation = key === 'id' || isRowTimeKey(key) ? undefined : relationOf(tableName, key);
+            if (!relation || !isPlainObject(cond))
+                continue;
+            out.push({ relation, sub: [...WAY_BACK_FILTERS].map((op) => cond[op]).filter((sub) => sub !== undefined && sub !== null) });
+        }
+    };
+    visit(where);
+    return out;
+}
+export function relatedKey(tableName, name) {
+    return `${tableName}\u0000${name}`;
+}
+export function matches(context, tableName, row, where) {
+    if (where === undefined || where === null)
+        return true;
+    if (!isPlainObject(where))
+        throw new RecordsQueryError(`records.${tableName}: where must be an object`);
+    const table = getCompiledTable(context.schema, tableName);
+    for (const [field, cond] of Object.entries(where)) {
+        if (cond === undefined)
+            continue;
+        if (field === 'AND') {
+            if (!asArray(cond).every((part) => matches(context, tableName, row, part)))
+                return false;
+            continue;
+        }
+        if (field === 'OR') {
+            if (!asArray(cond).some((part) => matches(context, tableName, row, part)))
+                return false;
+            continue;
+        }
+        if (field === 'NOT') {
+            if (asArray(cond).some((part) => matches(context, tableName, row, part)))
+                return false;
+            continue;
+        }
+        if (field === 'id') {
+            if (!matchValue(row.id, cond, tableName, field))
+                return false;
+            continue;
+        }
+        if (isRowTimeKey(field)) {
+            const { same, order } = comparisonOf('datetime');
+            if (!matchValue(row[field] ?? null, cond, tableName, field, same, order))
+                return false;
+            continue;
+        }
+        const def = getTableField(table, field);
+        if (!def) {
+            const relation = context.relationOf(tableName, field);
+            if (!relation)
+                throw new RecordsQueryError(`records.${tableName}: where.${field} is not a field of this table`);
+            if (!matchWayBack(context, tableName, row, relation, cond))
+                return false;
+            continue;
+        }
+        const slot = row[field];
+        if (def.ref && isPlainObject(cond) && ('is' in cond || 'isNot' in cond)) {
+            const c = cond;
+            const target = typeof slot.value === 'string' ? context.targets.get(slot.value) : undefined;
+            if ('is' in c) {
+                if (c.is === null ? target !== undefined : !target || !matches(context, def.ref.table, target, c.is))
+                    return false;
+            }
+            if ('isNot' in c) {
+                if (c.isNot === null ? target === undefined : target && matches(context, def.ref.table, target, c.isNot))
+                    return false;
+            }
+            continue;
+        }
+        // A date or time compares as the instant it names, as the field index does (18-record-search-index
+        // §4.6); a phone / email operand is already in stored form (normalizeWhereValues).
+        const { same, order } = comparisonOf(def.dataType);
+        if (isPlainObject(cond) && 'state' in cond) {
+            const { state, ...rest } = cond;
+            if (!matchValue(slot.state, state, tableName, `${field}.state`))
+                return false;
+            if (Object.keys(rest).length > 0 && !matchValue(slot.value, rest, tableName, field, same, order))
+                return false;
+            continue;
+        }
+        if (!matchValue(slot.value, cond, tableName, field, same, order))
+            return false;
+    }
+    return true;
+}
+/**
+ * Prisma scalar filter: a plain value is `equals`; `null` matches an empty field. `same` is how
+ * equality (`equals` / `in` / `notIn`) compares: as JSON, or an identifier normalized.
+ */
+function matchValue(value, cond, tableName, field, same = equal, order = compare) {
+    if (!isPlainObject(cond))
+        return same(value, cond);
+    const { mode } = cond;
+    if (mode !== undefined && mode !== 'insensitive' && mode !== 'default') {
+        throw new RecordsQueryError(`records.${tableName}: where.${field}.mode is 'insensitive' or 'default'`);
+    }
+    // `mode: 'insensitive'`: strings compare lower-cased, as Prisma does.
+    if (mode === 'insensitive') {
+        const fold = (v) => (typeof v === 'string' ? v.toLowerCase() : Array.isArray(v) ? v.map(fold) : v);
+        const { mode: _, ...ops } = cond;
+        const folded = Object.fromEntries(Object.entries(ops).map(([op, operand]) => [op, op === 'not' ? operand : fold(operand)]));
+        return matchValue(fold(value), folded, tableName, field, same, order);
+    }
+    for (const [op, operand] of Object.entries(cond)) {
+        if (!OPERATORS.has(op))
+            throw new RecordsQueryError(`records.${tableName}: where.${field}.${op} is not supported`);
+        switch (op) {
+            case 'mode':
+                break;
+            case 'equals':
+                if (!same(value, operand))
+                    return false;
+                break;
+            case 'in':
+                if (!asArray(operand).some((v) => same(value, v)))
+                    return false;
+                break;
+            case 'notIn':
+                if (asArray(operand).some((v) => same(value, v)))
+                    return false;
+                break;
+            case 'not':
+                if (matchValue(value, operand, tableName, field, same, order))
+                    return false;
+                break;
+            case 'lt':
+            case 'lte':
+            case 'gt':
+            case 'gte': {
+                if (value === null || value === undefined || operand === null || operand === undefined)
+                    return false;
+                const c = order(value, operand);
+                if (op === 'lt' && !(c < 0))
+                    return false;
+                if (op === 'lte' && !(c <= 0))
+                    return false;
+                if (op === 'gt' && !(c > 0))
+                    return false;
+                if (op === 'gte' && !(c >= 0))
+                    return false;
+                break;
+            }
+            case 'startsWith':
+                if (typeof value !== 'string' || !value.startsWith(String(operand)))
+                    return false;
+                break;
+            case 'has':
+            case 'hasSome':
+            case 'hasEvery':
+            case 'isEmpty': {
+                // A multi_select's list; an empty field is no list (it has nothing and is not "none of them").
+                if (!Array.isArray(value))
+                    return false;
+                const items = asArray(operand);
+                if (op === 'has' && !value.some((v) => same(v, operand)))
+                    return false;
+                if (op === 'hasSome' && !items.some((o) => value.some((v) => same(v, o))))
+                    return false;
+                if (op === 'hasEvery' && !items.every((o) => value.some((v) => same(v, o))))
+                    return false;
+                if (op === 'isEmpty' && (value.length === 0) !== (operand === true))
+                    return false;
+                break;
+            }
+            case 'state':
+                throw new RecordsQueryError(`records.${tableName}: where.${field}.state goes on the field, not inside an operator`);
+        }
+    }
+    return true;
+}
+function equal(a, b) {
+    if (b === null)
+        return a === null || a === undefined;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * How values of a field type compare: a `date` / `datetime` as the instant it names (`…00.000Z` and
+ * `…00Z` are one time; an offset counts; `YYYY` / `YYYY-MM` at their start), as the field index
+ * compares them; a value that is not one compares as text. Everything else as JSON / text.
+ */
+function comparisonOf(dataType) {
+    if (dataType !== 'date' && dataType !== 'datetime')
+        return { same: equal, order: compare };
+    const instant = (v) => (typeof v === 'string' ? indexValueOf(dataType, v)?.valueTime?.getTime() : undefined);
+    return {
+        same: (a, b) => {
+            if (b === null || a === null || a === undefined)
+                return equal(a, b);
+            const ia = instant(a);
+            const ib = instant(b);
+            return ia !== undefined && ib !== undefined ? ia === ib : equal(a, b);
+        },
+        order: (a, b) => {
+            const ia = instant(a);
+            const ib = instant(b);
+            return ia !== undefined && ib !== undefined ? ia - ib : compare(a, b);
+        },
+    };
+}
+function compare(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+export function orderKeys(table, orderBy) {
+    if (orderBy === undefined || orderBy === null)
+        return [];
+    return asArray(orderBy).flatMap((entry) => {
+        if (!isPlainObject(entry))
+            throw new RecordsQueryError('records: orderBy is { field: "asc" | "desc" } or an array of those');
+        return Object.entries(entry).map(([field, dir]) => {
+            const system = field === 'id' || isRowTimeKey(field);
+            const def = system ? undefined : getTableField(table, field);
+            if (!system && !def)
+                throw new RecordsQueryError(`records: orderBy.${field} is not a field`);
+            if (dir !== 'asc' && dir !== 'desc')
+                throw new RecordsQueryError(`records: orderBy.${field} is "asc" or "desc"`);
+            const order = def ? comparisonOf(def.dataType).order : isRowTimeKey(field) ? comparisonOf('datetime').order : compare;
+            return { field, sign: dir === 'asc' ? 1 : -1, order, ...(def ? { def } : {}) };
+        });
+    });
+}
+function placeOf(keys, row) {
+    const values = keys.map(({ field }) => (field === 'id' || isRowTimeKey(field) ? row[field] : row[field]?.value));
+    return { values, created: Date.parse(row.createdAt ?? '') || 0, id: row.id };
+}
+/** The read's total order: the keys, empty values last either way; then creation, then id. */
+function comparePlaces(keys, a, b) {
+    for (const [i, { sign, order }] of keys.entries()) {
+        const va = a.values[i];
+        const vb = b.values[i];
+        const ea = va === null || va === undefined;
+        const eb = vb === null || vb === undefined;
+        if (ea || eb) {
+            if (ea !== eb)
+                return ea ? 1 : -1;
+            continue;
+        }
+        const c = order(va, vb);
+        if (c !== 0)
+            return c * sign;
+    }
+    return a.created - b.created || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+/** Rows in the read's order; without keys, as they come (creation order). */
+export function orderRows(keys, rows) {
+    if (keys.length === 0)
+        return rows;
+    return rows
+        .map((row) => ({ row, place: placeOf(keys, row) }))
+        .sort((a, b) => comparePlaces(keys, a.place, b.place))
+        .map(({ row }) => row);
+}
+/**
+ * `orderBy` as the database can order: null without one, the field when it is one indexed field or a
+ * row time; undefined when it cannot (several keys, `id`, a field not indexed).
+ */
+export function indexOrder(table, orderBy) {
+    if (orderBy === undefined || orderBy === null)
+        return null;
+    const entries = (Array.isArray(orderBy) ? orderBy : [orderBy]).flatMap((entry) => isPlainObject(entry) ? Object.entries(entry) : [['', '']]);
+    if (entries.length !== 1)
+        return undefined;
+    const [field, dir] = entries[0];
+    if (isRowTimeKey(field))
+        return dir === 'asc' || dir === 'desc' ? { field, dataType: 'datetime', desc: dir === 'desc', row: true } : undefined;
+    const def = field === 'id' ? undefined : getTableField(table, field);
+    if (!def || def.ref || def.dataType === 'text' || def.dataType === 'multi_select' || def.dataType === 'contact_schedule' || (dir !== 'asc' && dir !== 'desc'))
+        return undefined;
+    return { field, dataType: def.dataType, desc: dir === 'desc' };
+}
+/** Rows in the read's order, paged: from strictly after `place`, then `skip`, then `take`. */
+export function pageRows(keys, rows, place, args) {
+    let start = 0;
+    if (place) {
+        start = rows.findIndex((row) => comparePlaces(keys, placeOf(keys, row), place) > 0);
+        if (start < 0)
+            return [];
+    }
+    const skip = skipOf(args.skip);
+    const take = optionalCount(args.take, 'take') ?? RECORDS_LIMITS.defaultTake;
+    if (take > RECORDS_LIMITS.rowsPerCall)
+        throw limitExceeded(`records: take is at most ${RECORDS_LIMITS.rowsPerCall}`);
+    return rows.slice(start + skip, start + skip + take);
+}
+/**
+ * `after`: the place a page starts after, read off a row as the reader returned it (normally the last
+ * of the page before). Taken by value, never looked up: its id only breaks ties, so a row since deleted,
+ * changed or of another tenant is only a place and discloses nothing. It needs the row's `id` and
+ * `createdAt`, and its value of each order key: `updatedAt`, or the field's slot (`{ value }`, a null
+ * value for none). A field's value must be of its type ({@link fitsField}): one the index cannot hold
+ * would otherwise place as "no value" in SQL and compare as text in memory.
+ */
+export function afterOf(tableName, keys, args) {
+    if (args.cursor !== undefined) {
+        throw new RecordsQueryError(`records.${tableName}: cursor is now after: pass the last row read (after: rows.at(-1)) to read the rows after it`);
+    }
+    const after = args.after;
+    if (after === undefined)
+        return undefined;
+    if (!isPlainObject(after))
+        throw new RecordsQueryError(`records.${tableName}: after is a row as read (the last row of the page before)`);
+    if (!isUuid(after.id))
+        throw new RecordsQueryError(`records.${tableName}: after needs the row's id`);
+    const created = typeof after.createdAt === 'string' ? Date.parse(after.createdAt) : NaN;
+    if (Number.isNaN(created))
+        throw new RecordsQueryError(`records.${tableName}: after needs createdAt (ISO 8601), as the row was read`);
+    const id = after.id.toLowerCase();
+    const values = keys.map(({ field, def }) => {
+        if (field === 'id')
+            return id;
+        if (isRowTimeKey(field)) {
+            const time = after[field];
+            if (typeof time !== 'string' || Number.isNaN(Date.parse(time))) {
+                throw new RecordsQueryError(`records.${tableName}: after needs ${field} (ISO 8601), as the row was read: the read is ordered by it`);
+            }
+            return time;
+        }
+        const slot = after[field];
+        if (!isPlainObject(slot))
+            throw new RecordsQueryError(`records.${tableName}: after needs ${field}: the read is ordered by it; keep it in select`);
+        const value = slot.value ?? null;
+        if (value !== null && def && !fitsField(def, value)) {
+            throw new RecordsQueryError(`records.${tableName}: after.${field} holds ${shownValue(value)}, not ${typeNameOf(def)}: ${field} is a ${def.ref ? 'ref' : def.dataType} field; pass the row as read (a null value for none)`);
+        }
+        return value;
+    });
+    return { values, created, id };
+}
+/**
+ * Whether `value` is one of `def`'s type, as `after`'s value of an order key: on a field the index
+ * holds, exactly what its entry can hold (`indexValueOf`, as the database orders by it), so the SQL and
+ * in-memory reads take the same places; on any other (read in memory only), the shape its rows carry.
+ */
+function fitsField(def, value) {
+    if (def.ref)
+        return typeof value === 'string';
+    switch (def.dataType) {
+        case 'text':
+            return typeof value === 'string';
+        case 'multi_select':
+            return Array.isArray(value) && value.every((item) => typeof item === 'string');
+        case 'contact_schedule':
+            return isPlainObject(value);
+        default:
+            return indexValueOf(def.dataType, value) !== null;
+    }
+}
+/** What {@link fitsField} takes, in words. */
+function typeNameOf(def) {
+    if (def.ref)
+        return 'an id';
+    switch (def.dataType) {
+        case 'number':
+            return 'a number';
+        case 'boolean':
+            return 'a boolean';
+        case 'date':
+            return 'a date (YYYY-MM-DD, YYYY-MM or YYYY)';
+        case 'datetime':
+            return 'a date and time (ISO 8601)';
+        case 'multi_select':
+            return 'a list of options';
+        case 'contact_schedule':
+            return 'a contact schedule';
+        default:
+            return 'a string';
+    }
+}
+/** A value in a message: a scalar as written (cut short), a list or an object by its kind. */
+function shownValue(value) {
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'an object';
+    const text = typeof value === 'string' ? JSON.stringify(value) : String(value);
+    return text.length > 40 ? `${text.slice(0, 37)}...` : text;
+}
+export function skipOf(value) {
+    const skip = optionalCount(value, 'skip') ?? 0;
+    if (skip > RECORDS_LIMITS.maxSkip)
+        throw limitExceeded(`records: skip is at most ${RECORDS_LIMITS.maxSkip}; page further with after`);
+    return skip;
+}
+/** Every `in` / `notIn` of a where (and its AND / OR / NOT, way-back and `is` filters) within `listValues`. */
+export function checkListSizes(tableName, where) {
+    if (Array.isArray(where)) {
+        for (const part of where)
+            checkListSizes(tableName, part);
+        return;
+    }
+    if (!isPlainObject(where))
+        return;
+    for (const [key, value] of Object.entries(where)) {
+        if ((key === 'in' || key === 'notIn') && Array.isArray(value) && value.length > RECORDS_LIMITS.listValues) {
+            throw limitExceeded(`records.${tableName}: ${key} takes at most ${RECORDS_LIMITS.listValues} values`);
+        }
+        checkListSizes(tableName, value);
+    }
+}
+export function optionalCount(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new RecordsQueryError(`records: ${name} is a whole number ≥ 0`);
+    }
+    return value;
+}
+export function selectFields(tableName, table, row, select) {
+    if (select === undefined || select === null)
+        return row;
+    if (!isPlainObject(select))
+        throw new RecordsQueryError(`records.${tableName}: select must be an object`);
+    // The id and the row's times always come.
+    const out = { id: row.id, ...(row.createdAt ? { createdAt: row.createdAt, updatedAt: row.updatedAt } : {}) };
+    for (const [field, on] of Object.entries(select)) {
+        if (!on || field === 'id' || isRowTimeKey(field))
+            continue;
+        if (!getTableField(table, field))
+            throw new RecordsQueryError(`records.${tableName}: select.${field} is not a field`);
+        out[field] = row[field];
+    }
+    // The ways back `include`d stay: `select` picks among the fields.
+    for (const [key, value] of Object.entries(row))
+        if (Array.isArray(value))
+            out[key] = value;
+    return out;
+}
+export function toSlot(table, id, field, value) {
+    const stored = value.state !== 'empty';
+    return {
+        value: value.value ?? null,
+        state: value.state,
+        reason: value.reason ?? null,
+        updatedAt: stored && value.updatedAt ? new Date(value.updatedAt).toISOString() : null,
+        ref: { table, id, field },
+    };
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(value) {
+    return typeof value === 'string' && UUID.test(value);
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------------------------
+// The field index: which fields it holds, a value's index columns, and the conditions it answers.
+const PROJECTED_TYPES = new Set(['string', 'select', 'time', 'phone', 'email', 'number', 'boolean', 'date', 'datetime']);
+/** The fields of one table's definition that go to the index. */
+export function tableIndexedFields(fields) {
+    const out = new Map();
+    for (const [fieldName, field] of Object.entries(fields)) {
+        if (fieldName === 'id')
+            continue;
+        const def = field;
+        if (def.ref || !def.dataType || !PROJECTED_TYPES.has(def.dataType))
+            continue;
+        out.set(fieldName, { dataType: def.dataType, unique: def.unique === true });
+    }
+    return out;
+}
+/** A stored value's index columns; null when it has none to index (empty, or not of its type). */
+export function indexValueOf(dataType, value) {
+    if (value === null || value === undefined)
+        return null;
+    const none = { valueText: null, valueNum: null, valueTime: null };
+    switch (dataType) {
+        case 'string':
+        case 'select':
+        // `HH:mm`, zero-padded: ordered as text is ordered in time (27 §4).
+        case 'time':
+        case 'phone':
+        case 'email':
+            return typeof value === 'string' ? { ...none, valueText: value } : null;
+        case 'boolean':
+            return typeof value === 'boolean' ? { ...none, valueText: String(value) } : null;
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? { ...none, valueNum: value } : null;
+        case 'date': {
+            // `YYYY` / `YYYY-MM` index at the start of their span.
+            if (typeof value !== 'string')
+                return null;
+            const [year, month = '01', day = '01'] = value.split('-');
+            const time = new Date(`${year}-${month}-${day}T00:00:00.000Z`);
+            return Number.isNaN(time.getTime()) ? null : { ...none, valueTime: time };
+        }
+        case 'datetime': {
+            if (typeof value !== 'string')
+                return null;
+            const time = new Date(value);
+            return Number.isNaN(time.getTime()) ? null : { ...none, valueTime: time };
+        }
+        default:
+            return null;
+    }
+}
+const INDEX_OPERATORS = new Set(['equals', 'in', 'lt', 'lte', 'gt', 'gte', 'startsWith', 'mode']);
+/** What a condition on a row time can say in SQL: it is an instant. */
+const TIME_OPERATORS = new Set(['equals', 'in', 'lt', 'lte', 'gt', 'gte']);
+/** Why a condition cannot start a query on its own (it can still narrow one another condition starts). */
+function cannotStart(cond) {
+    if ('startsWith' in cond.ops && String(cond.ops.startsWith).length === 0)
+        return `where.${cond.field}.startsWith is empty`;
+    return null;
+}
+/**
+ * The conditions of a where the database can answer (top level and top-level AND): on indexed fields
+ * and row times. And whether they are the whole where (nothing else to check in memory). A condition
+ * on a field that is not indexed, an empty value, `not`, `notIn`, `state`, `OR` and `NOT` are left to
+ * the in-memory filter.
+ */
+export function indexConditions(table, where) {
+    const fields = tableIndexedFields(table.fields);
+    const conditions = [];
+    let whole = true;
+    const visit = (w) => {
+        for (const [field, cond] of Object.entries(w)) {
+            if (cond === undefined)
+                continue;
+            if (field === 'AND') {
+                for (const part of Array.isArray(cond) ? cond : [cond]) {
+                    if (isPlainObject(part))
+                        visit(part);
+                    else
+                        whole = false;
+                }
+                continue;
+            }
+            if (isRowTimeKey(field)) {
+                const ops = indexOps(cond);
+                if (!ops || !Object.keys(ops).every((op) => TIME_OPERATORS.has(op))) {
+                    whole = false;
+                    continue;
+                }
+                conditions.push({ field, dataType: 'datetime', ops, insensitive: false, row: true });
+                continue;
+            }
+            const indexed = fields.get(field);
+            const ops = indexed ? indexOps(cond) : null;
+            if (!indexed || !ops) {
+                whole = false;
+                continue;
+            }
+            const { mode, ...rest } = ops;
+            conditions.push({ field, dataType: indexed.dataType, ops: rest, insensitive: mode === 'insensitive' });
+        }
+    };
+    visit(where);
+    return { conditions, whole };
+}
+/** A condition's operators when the index can answer all of them; null otherwise. */
+function indexOps(cond) {
+    if (cond === null)
+        return null;
+    if (!isPlainObject(cond))
+        return { equals: cond };
+    const ops = cond;
+    const keys = Object.keys(ops);
+    if (keys.length === 0 || !keys.every((op) => INDEX_OPERATORS.has(op)))
+        return null;
+    if (ops.mode !== undefined && ops.mode !== 'insensitive' && ops.mode !== 'default')
+        return null;
+    if (keys.every((op) => op === 'mode'))
+        return null;
+    for (const [op, operand] of Object.entries(ops)) {
+        if (op === 'mode')
+            continue;
+        if (operand === null || operand === undefined)
+            return null;
+        if (op === 'in' && (!Array.isArray(operand) || operand.some((v) => v === null)))
+            return null;
+    }
+    return ops;
+}
+/** The conditions that can start a query; when none can, why. */
+export function startableConditions(conditions) {
+    const candidates = conditions.filter((cond) => !cannotStart(cond));
+    return { candidates, why: candidates.length > 0 ? null : (conditions.map(cannotStart).find((why) => why !== null) ?? null) };
+}
+/**
+ * Why a `where` with no anchor (`id` or a ref field equal to / in some ids) cannot be read: no condition
+ * on an indexed field or a row time starts it. Null when one does. The platform's reader and the page
+ * unit tests refuse the same reads, with this message.
+ */
+export function unstartableWhy(tableName, table, where) {
+    const { conditions } = indexConditions(table, where);
+    const { candidates, why } = startableConditions(conditions);
+    if (candidates.length > 0)
+        return null;
+    const indexed = Object.entries(table.fields).filter(([name, def]) => name !== 'id' && !def.ref && def.dataType !== 'text' && def.dataType !== 'multi_select' && def.dataType !== 'contact_schedule');
+    return `records.${tableName}: ${why ? `${why}; ` : ''}the where needs id or a ref field equal to / in some ids, or a condition on a field (${indexed.map(([name]) => name).join(', ') || 'none'}): equals, in, lt / lte / gt / gte or startsWith; or on createdAt / updatedAt: equals, in, lt / lte / gt / gte`;
+}
+//# sourceMappingURL=records-query.js.map