@ganju/utils 0.0.15 → 0.0.17

package/dist/dataCompiler.js

@@ -0,0 +1,730 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSensitiveWrite = exports.tidyArgs = exports.chunkRows = exports.rowsPerInsert = exports.keysetCondition = exports.decodeCursor = exports.encodeCursor = exports.ftsMatch = exports.assertParamCount = exports.compileWhere = exports.resolvePath = exports.fromStored = exports.zoned = exports.zoneOffsetMinutes = exports.toStored = exports.isoSeconds = exports.relationJoin = exports.joinsParams = exports.joinsSql = exports.participantOf = exports.canRead = exports.isScoped = exports.tableFor = exports.visibleTables = exports.accessOf = exports.unknownColumn = exports.columnFor = exports.isSystemColumn = exports.FILTER_OPERATORS = void 0;
+// Turns the structured query and write arguments into SQL with bound values.
+// Identifiers are checked against the database's own schema and quoted;
+// every value a caller sends is a parameter. Pure: the engine runs the SQL.
+const dataIdentifiers_1 = require("./dataIdentifiers");
+const dataDdl_1 = require("./dataDdl");
+const base64_1 = require("./base64");
+const dataTypes_1 = require("./dataTypes");
+exports.FILTER_OPERATORS = [
+    'eq',
+    'ne',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'in',
+    'notIn',
+    'contains',
+    'startsWith',
+    'isNull'
+];
+const SYSTEM_COLUMN_TYPES = {
+    id: 'integer',
+    created_at: 'datetime',
+    updated_at: 'datetime'
+};
+const isSystemColumn = (column) => 'system' in column && column.system === true;
+exports.isSystemColumn = isSystemColumn;
+const columnFor = (table, name) => {
+    if (name in SYSTEM_COLUMN_TYPES) {
+        return { name, type: SYSTEM_COLUMN_TYPES[name], system: true };
+    }
+    return table.columns.find(column => column.name === name);
+};
+exports.columnFor = columnFor;
+const unknownColumn = (table, name) => new dataTypes_1.DataError(`Unknown column "${name}" in ${table.name}. Columns: ${[
+    'id',
+    ...table.columns.map(c => c.name),
+    'created_at',
+    'updated_at'
+].join(', ')}.`, 'invalid');
+exports.unknownColumn = unknownColumn;
+// Access
+const accessOf = (caller, table) => caller.tables && !caller.tables.includes(table.name)
+    ? 'none'
+    : caller.restricted
+        ? table.access
+        : 'full';
+exports.accessOf = accessOf;
+const visibleTables = (schema, caller) => schema.tables.filter(table => dataTypes_1.DATA_ACCESS_RANK[(0, exports.accessOf)(caller, table)] >= 1);
+exports.visibleTables = visibleTables;
+// The table a call names, if the caller may `need` it. A table the caller
+// can't see is reported as unknown, so a hidden table doesn't exist for it.
+const tableFor = (schema, caller, name, need = 'read') => {
+    const table = typeof name === 'string'
+        ? schema.tables.find(t => t.name === name)
+        : undefined;
+    if (!table || dataTypes_1.DATA_ACCESS_RANK[(0, exports.accessOf)(caller, table)] < 1) {
+        const names = (0, exports.visibleTables)(schema, caller).map(t => t.name);
+        throw new dataTypes_1.DataError(typeof name === 'string'
+            ? `Unknown table "${name}". Tables: ${names.join(', ') || '(none)'}.`
+            : `"table" is the name of a table. Tables: ${names.join(', ') || '(none)'}.`, 'not_found');
+    }
+    const access = (0, exports.accessOf)(caller, table);
+    if (dataTypes_1.DATA_ACCESS_RANK[access] < dataTypes_1.DATA_ACCESS_RANK[need]) {
+        const allowed = access === 'read'
+            ? 'read only'
+            : access === 'add'
+                ? 'read and add rows only'
+                : access;
+        throw new dataTypes_1.DataError(`Not allowed: the assistant's access to "${table.name}" is ${allowed}.`, 'forbidden');
+    }
+    return table;
+};
+exports.tableFor = tableFor;
+const isScoped = (caller, table) => Boolean(caller.restricted && table.customerScoped);
+exports.isScoped = isScoped;
+const canRead = (caller, table) => dataTypes_1.DATA_ACCESS_RANK[(0, exports.accessOf)(caller, table)] >= 1;
+exports.canRead = canRead;
+// The customer a scoped call is for. A restricted caller without one would
+// otherwise share a single bucket with every other caller like it.
+const participantOf = (caller) => {
+    if (typeof caller.participantId !== 'string' || !caller.participantId) {
+        throw new dataTypes_1.DataError("This conversation has no customer, so customer-scoped tables can't be used.", 'forbidden');
+    }
+    return caller.participantId;
+};
+exports.participantOf = participantOf;
+const joinsSql = (joins) => [...joins.values()].map(join => join.sql).join(' ');
+exports.joinsSql = joinsSql;
+const joinsParams = (joins) => [...joins.values()].flatMap(join => join.params);
+exports.joinsParams = joinsParams;
+// The related table as the caller may see it: a bot reaches only its own
+// customer's rows of a scoped table, through a label, a filter or a sort just
+// as through a query on that table.
+const relationJoin = (caller, target, alias, on) => {
+    const scoped = (0, exports.isScoped)(caller, target);
+    // No customer: no row of a scoped table is theirs.
+    if (scoped && !caller.participantId) {
+        return { sql: `LEFT JOIN ${(0, dataIdentifiers_1.quoteIdentifier)(target.name)} ${alias} ON 0`, params: [] };
+    }
+    return {
+        sql: `LEFT JOIN ${(0, dataIdentifiers_1.quoteIdentifier)(target.name)} ${alias} ON ${alias}.id = ${on}${scoped ? ` AND ${alias}.participant_id = ?` : ''}`,
+        params: scoped ? [(0, exports.participantOf)(caller)] : []
+    };
+};
+exports.relationJoin = relationJoin;
+// Values
+const isoSeconds = (date) => date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+exports.isoSeconds = isoSeconds;
+const LOCAL_DATETIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?$/;
+// "2026-10-21T15:00:00" with no offset, read as a wall-clock time in
+// `timeZone` (UTC without one). `new Date()` would read it in the server's
+// zone: UTC on Workers, the developer's own zone on a laptop.
+const localDatetime = (value, timeZone) => {
+    const m = LOCAL_DATETIME.exec(value.trim());
+    if (!m)
+        return null;
+    const [year, month, day, hour, minute, second] = m
+        .slice(1, 7)
+        .map(part => Number(part ?? 0));
+    const wall = Date.UTC(year, month - 1, day, hour, minute, second);
+    const check = new Date(wall);
+    if (check.getUTCFullYear() !== year ||
+        check.getUTCMonth() !== month - 1 ||
+        check.getUTCDate() !== day ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59) {
+        return new Date(NaN);
+    }
+    // The offset at the guess, then again at the result, so a time next to a
+    // daylight-saving change lands on the right side of it.
+    let at = wall - (0, exports.zoneOffsetMinutes)(new Date(wall), timeZone) * 60_000;
+    at = wall - (0, exports.zoneOffsetMinutes)(new Date(at), timeZone) * 60_000;
+    return new Date(at);
+};
+const normaliseDatetime = (value, label, timeZone) => {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new dataTypes_1.DataError(`${label}: expected an ISO 8601 date and time.`);
+    }
+    const date = (typeof value === 'string' ? localDatetime(value, timeZone) : null) ??
+        new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new dataTypes_1.DataError(`${label}: "${value}" is not a date and time; use ISO 8601, e.g. 2026-10-19T09:00:00-05:00.`);
+    }
+    return (0, exports.isoSeconds)(date);
+};
+const isRealDate = (value) => {
+    const date = new Date(`${value}T00:00:00Z`);
+    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value);
+};
+const asNumber = (value) => {
+    const n = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof n === 'number' && Number.isFinite(n) ? n : undefined;
+};
+const checkSize = (label, value) => {
+    if (value.length > dataTypes_1.DATA_MAX_VALUE_BYTES) {
+        throw new dataTypes_1.DataError(`${label} is too long (over ${dataTypes_1.DATA_MAX_VALUE_BYTES.toLocaleString('en-US')} characters).`, 'too_large');
+    }
+    return value;
+};
+// Turns a value from a caller into what the column stores, or explains why
+// it can't. `timeZone` is the project's, for datetimes sent without an
+// offset.
+const toStored = (table, column, value, timeZone) => {
+    const label = `${table.name}.${column.name}`;
+    if (value === null || value === undefined) {
+        if (!(0, exports.isSystemColumn)(column) && column.required) {
+            throw new dataTypes_1.DataError(`${label} is required.`);
+        }
+        return null;
+    }
+    switch (column.type) {
+        case 'integer':
+        case 'relation': {
+            const n = typeof value === 'string' && /^-?\d+$/.test(value.trim())
+                ? Number(value)
+                : value;
+            if (typeof n !== 'number' || !Number.isSafeInteger(n)) {
+                const target = (0, exports.isSystemColumn)(column) ? null : column.table;
+                throw new dataTypes_1.DataError(column.type === 'relation'
+                    ? `${label} takes the id (a whole number) of a row in ${target}.`
+                    : `${label} must be a whole number.`);
+            }
+            return n;
+        }
+        case 'decimal': {
+            const n = asNumber(value);
+            if (n === undefined)
+                throw new dataTypes_1.DataError(`${label} must be a number.`);
+            return n;
+        }
+        case 'boolean':
+            if (value === true || value === 'true' || value === 1)
+                return 1;
+            if (value === false || value === 'false' || value === 0)
+                return 0;
+            throw new dataTypes_1.DataError(`${label} must be true or false.`);
+        case 'date':
+            if (typeof value !== 'string' ||
+                !/^\d{4}-\d{2}-\d{2}$/.test(value) ||
+                !isRealDate(value)) {
+                throw new dataTypes_1.DataError(`${label} must be a date, YYYY-MM-DD.`);
+            }
+            return value;
+        case 'datetime':
+            return normaliseDatetime(value, label, timeZone);
+        case 'enum': {
+            const values = (0, exports.isSystemColumn)(column) ? [] : (column.values ?? []);
+            const match = values.find(v => v.toLowerCase() === String(value).toLowerCase());
+            if (!match) {
+                throw new dataTypes_1.DataError(`${label} must be one of: ${values.join(', ')}.`);
+            }
+            return match;
+        }
+        case 'json':
+            return checkSize(label, JSON.stringify(value));
+        case 'email': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(text)) {
+                throw new dataTypes_1.DataError(`${label} must be an email address.`);
+            }
+            return checkSize(label, text);
+        }
+        case 'url':
+            if (typeof value !== 'string' || !/^https?:\/\/\S+$/i.test(value.trim())) {
+                throw new dataTypes_1.DataError(`${label} must be a URL starting with http(s)://.`);
+            }
+            return checkSize(label, value.trim());
+        case 'phone': {
+            if (typeof value !== 'string' && typeof value !== 'number') {
+                throw new dataTypes_1.DataError(`${label} must be a phone number.`);
+            }
+            const phone = String(value).replace(/[^\d+]/g, '');
+            if (!/^\+?\d{4,20}$/.test(phone)) {
+                throw new dataTypes_1.DataError(`${label} must be a phone number.`);
+            }
+            return phone;
+        }
+        default:
+            if (typeof value === 'object') {
+                throw new dataTypes_1.DataError(`${label} must be text.`);
+            }
+            return checkSize(label, String(value));
+    }
+};
+exports.toStored = toStored;
+const zoneOffsetMinutes = (date, timeZone) => {
+    if (!timeZone)
+        return 0;
+    const parts = {};
+    for (const part of new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit'
+    }).formatToParts(date)) {
+        parts[part.type] = part.value;
+    }
+    const asUtc = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute), Number(parts.second));
+    return Math.round((asUtc - date.getTime()) / 60_000);
+};
+exports.zoneOffsetMinutes = zoneOffsetMinutes;
+// A stored UTC datetime in the caller's zone, with the offset. Given UTC,
+// models told customers "8:00 p. m." for a 3 pm appointment.
+const zoned = (iso, timeZone) => {
+    const date = new Date(iso);
+    if (!timeZone || Number.isNaN(date.getTime()))
+        return iso;
+    const offset = (0, exports.zoneOffsetMinutes)(date, timeZone);
+    const local = new Date(date.getTime() + offset * 60_000)
+        .toISOString()
+        .slice(0, 19);
+    const sign = offset < 0 ? '-' : '+';
+    const abs = Math.abs(offset);
+    return `${local}${sign}${String(Math.floor(abs / 60)).padStart(2, '0')}:${String(abs % 60).padStart(2, '0')}`;
+};
+exports.zoned = zoned;
+const fromStored = (column, value, timeZone) => {
+    if (value === null || value === undefined)
+        return null;
+    if (column.type === 'datetime')
+        return (0, exports.zoned)(String(value), timeZone);
+    if (column.type === 'boolean')
+        return value === 1;
+    if (column.type === 'json') {
+        try {
+            return JSON.parse(String(value));
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+};
+exports.fromStored = fromStored;
+// "column" or "relation.column", adding the join a relation path needs.
+const resolvePath = (ctx, path) => {
+    if (typeof path !== 'string') {
+        throw new dataTypes_1.DataError('Column names are strings.');
+    }
+    const [head, tail, ...rest] = path.split('.');
+    if (rest.length > 0) {
+        throw new dataTypes_1.DataError(`"${path}": only one level of relation is supported (relation.column).`);
+    }
+    const column = (0, exports.columnFor)(ctx.table, head);
+    if (!column)
+        throw (0, exports.unknownColumn)(ctx.table, head);
+    if (tail === undefined) {
+        return { sql: `t.${(0, dataIdentifiers_1.quoteIdentifier)(head)}`, column, table: ctx.table, own: true };
+    }
+    if ((0, exports.isSystemColumn)(column) || column.type !== 'relation' || !column.table) {
+        throw new dataTypes_1.DataError(`"${head}" is not a relation, so "${path}" can't be used.`);
+    }
+    const target = (0, exports.tableFor)(ctx.schema, ctx.caller, column.table);
+    const targetColumn = (0, exports.columnFor)(target, tail);
+    if (!targetColumn)
+        throw (0, exports.unknownColumn)(target, tail);
+    const alias = `j_${head}`;
+    ctx.joins.set(alias, (0, exports.relationJoin)(ctx.caller, target, alias, `t.${(0, dataIdentifiers_1.quoteIdentifier)(head)}`));
+    return {
+        sql: `${alias}.${(0, dataIdentifiers_1.quoteIdentifier)(tail)}`,
+        column: targetColumn,
+        table: target,
+        own: false
+    };
+};
+exports.resolvePath = resolvePath;
+const filterValue = (resolved, value, timeZone) => {
+    const { column, table } = resolved;
+    const label = `${table.name}.${column.name}`;
+    if (column.type === 'datetime') {
+        return normaliseDatetime(value, label, timeZone);
+    }
+    if (column.type === 'boolean' || column.type === 'enum') {
+        if (column.type === 'enum') {
+            const values = (0, exports.isSystemColumn)(column) ? [] : (column.values ?? []);
+            const match = values.find(v => v.toLowerCase() === String(value).toLowerCase());
+            if (!match) {
+                throw new dataTypes_1.DataError(`${label} is one of: ${values.join(', ')}.`);
+            }
+            return match;
+        }
+        return (0, exports.toStored)(table, column, value);
+    }
+    if (dataDdl_1.NUMERIC_TYPES.has(column.type) || column.type === 'relation') {
+        const n = asNumber(value);
+        if (n === undefined) {
+            throw new dataTypes_1.DataError(`${label} compares with a number.`);
+        }
+        return n;
+    }
+    if (typeof value === 'object' && value !== null) {
+        throw new dataTypes_1.DataError(`${label}: expected a value or an operator object.`);
+    }
+    if (typeof value === 'boolean')
+        return String(value);
+    return value;
+};
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// The conditions of a `where`, as SQL joined with AND by the caller.
+// `indexed` collects the columns of the queried table an AND-ed condition
+// filters on, which is what lets a large table be aggregated.
+const compileWhere = (ctx, where, indexed) => {
+    if (where === undefined || where === null)
+        return [];
+    if (!isPlainObject(where)) {
+        throw new dataTypes_1.DataError('"where" is an object: { column: value, column: { operator: value } }.');
+    }
+    const clauses = [];
+    for (const [key, condition] of Object.entries(where)) {
+        if (key === 'or' || key === 'and') {
+            if (!Array.isArray(condition) || condition.length === 0) {
+                throw new dataTypes_1.DataError(`"${key}" takes a list of where objects.`);
+            }
+            const parts = condition.map(sub => {
+                const inner = (0, exports.compileWhere)(ctx, sub, key === 'and' ? indexed : undefined);
+                // An empty entry would match every row: { "or": [{}] } is "1".
+                if (inner.length === 0) {
+                    throw new dataTypes_1.DataError(`Each entry in "${key}" is a where object with at least one condition.`);
+                }
+                return `(${inner.join(' AND ')})`;
+            });
+            clauses.push(`(${parts.join(key === 'or' ? ' OR ' : ' AND ')})`);
+            continue;
+        }
+        const resolved = (0, exports.resolvePath)(ctx, key);
+        // { "customer": { "name": "Ana" } } reads as "customer.name": models
+        // write relation filters this way unprompted.
+        if (resolved.column.type === 'relation' &&
+            !key.includes('.') &&
+            isPlainObject(condition) &&
+            Object.keys(condition).some(k => !exports.FILTER_OPERATORS.includes(k))) {
+            clauses.push(...(0, exports.compileWhere)(ctx, Object.fromEntries(Object.entries(condition).map(([k, v]) => [`${key}.${k}`, v]))));
+            continue;
+        }
+        if (resolved.own && indexed) {
+            const column = resolved.column;
+            if (column.name === 'id' ||
+                (!(0, exports.isSystemColumn)(column) &&
+                    (column.unique ||
+                        column.filterable ||
+                        column.type === 'relation' ||
+                        column.type === 'file'))) {
+                indexed.add(column.name);
+            }
+        }
+        if (!isPlainObject(condition) || resolved.column.type === 'json') {
+            if (Array.isArray(condition)) {
+                throw new dataTypes_1.DataError(`${key}: to match several values use { "in": [...] }.`);
+            }
+            if (condition === null) {
+                clauses.push(`${resolved.sql} IS NULL`);
+            }
+            else {
+                clauses.push(`${resolved.sql} = ?`);
+                ctx.params.push(resolved.column.type === 'json'
+                    ? JSON.stringify(condition)
+                    : filterValue(resolved, condition, ctx.caller.timeZone));
+            }
+            continue;
+        }
+        for (const [operator, value] of Object.entries(condition)) {
+            if (!exports.FILTER_OPERATORS.includes(operator)) {
+                throw new dataTypes_1.DataError(`${key}: unknown operator "${operator}". Operators: ${exports.FILTER_OPERATORS.join(', ')}.`);
+            }
+            switch (operator) {
+                case 'eq':
+                case 'ne':
+                case 'gt':
+                case 'gte':
+                case 'lt':
+                case 'lte': {
+                    if (value === null && (operator === 'eq' || operator === 'ne')) {
+                        clauses.push(`${resolved.sql} IS ${operator === 'ne' ? 'NOT ' : ''}NULL`);
+                        break;
+                    }
+                    const sign = {
+                        eq: '=',
+                        ne: '!=',
+                        gt: '>',
+                        gte: '>=',
+                        lt: '<',
+                        lte: '<='
+                    }[operator];
+                    // { "stock": { "lt": { "column": "reorder_level" } } }
+                    if (isPlainObject(value) && typeof value.column === 'string') {
+                        const other = (0, exports.resolvePath)(ctx, value.column);
+                        clauses.push(`${resolved.sql} ${sign} ${other.sql}`);
+                        break;
+                    }
+                    clauses.push(`${resolved.sql} ${sign} ?`);
+                    ctx.params.push(filterValue(resolved, value, ctx.caller.timeZone));
+                    break;
+                }
+                case 'in':
+                case 'notIn': {
+                    if (!Array.isArray(value) ||
+                        value.length === 0 ||
+                        value.length > dataTypes_1.DATA_MAX_IN_VALUES) {
+                        throw new dataTypes_1.DataError(`${key}.${operator} takes a list of 1 to ${dataTypes_1.DATA_MAX_IN_VALUES} values.`);
+                    }
+                    clauses.push(`${resolved.sql} ${operator === 'notIn' ? 'NOT ' : ''}IN (${value
+                        .map(() => '?')
+                        .join(', ')})`);
+                    ctx.params.push(...value.map(v => filterValue(resolved, v, ctx.caller.timeZone)));
+                    break;
+                }
+                case 'contains':
+                case 'startsWith': {
+                    if (typeof value !== 'string') {
+                        throw new dataTypes_1.DataError(`${key}.${operator} takes text.`);
+                    }
+                    const escaped = value.replace(/[\\%_]/g, c => `\\${c}`);
+                    clauses.push(`${resolved.sql} LIKE ? ESCAPE '\\'`);
+                    ctx.params.push(operator === 'contains' ? `%${escaped}%` : `${escaped}%`);
+                    break;
+                }
+                case 'isNull':
+                    clauses.push(`${resolved.sql} IS ${value ? '' : 'NOT '}NULL`);
+                    break;
+            }
+        }
+    }
+    return clauses;
+};
+exports.compileWhere = compileWhere;
+const assertParamCount = (params) => {
+    if (params.length > dataTypes_1.DATA_MAX_PARAMS) {
+        throw new dataTypes_1.DataError(`This query uses ${params.length} values; the limit is ${dataTypes_1.DATA_MAX_PARAMS}. Use fewer "in" values or split it.`, 'too_large');
+    }
+};
+exports.assertParamCount = assertParamCount;
+// Search
+// FTS5 query for the words in `text`: each word as a quoted prefix, so
+// nothing the caller types is FTS syntax. All words, or any with `any`.
+const ftsMatch = (text, any) => {
+    const tokens = String(text ?? '')
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+/gu);
+    if (!tokens || tokens.length === 0) {
+        throw new dataTypes_1.DataError('"search" needs at least one word.');
+    }
+    return tokens
+        .slice(0, 10)
+        .map(t => `"${t}"*`)
+        .join(any ? ' OR ' : ' ');
+};
+exports.ftsMatch = ftsMatch;
+const encodeCursor = (cursor) => (0, base64_1.utf8ToBase64Url)(JSON.stringify(cursor));
+exports.encodeCursor = encodeCursor;
+const decodeCursor = (raw, signature) => {
+    try {
+        const cursor = JSON.parse((0, base64_1.base64UrlToUtf8)(String(raw)));
+        if (!cursor ||
+            cursor.k !== signature ||
+            !Array.isArray(cursor.v) ||
+            cursor.v.some(v => v !== null && typeof v !== 'string' && typeof v !== 'number')) {
+            throw new Error('mismatch');
+        }
+        return cursor;
+    }
+    catch {
+        throw new dataTypes_1.DataError('"cursor" is not one this query returned; send the same table and sort with the cursor from the previous page.');
+    }
+};
+exports.decodeCursor = decodeCursor;
+// Rows strictly after `values` in the order `keys`, as one condition. NULLs
+// sort first ascending and last descending, as in SQLite. The last key is
+// unique (the id), so no row is skipped or repeated across pages, even when
+// rows share a sort value.
+const keysetCondition = (keys, values, params) => {
+    const branches = [];
+    for (let i = 0; i < keys.length; i++) {
+        const parts = [];
+        for (let j = 0; j < i; j++) {
+            if (values[j] === null) {
+                parts.push(`${keys[j].sql} IS NULL`);
+            }
+            else {
+                parts.push(`${keys[j].sql} = ?`);
+                params.push(values[j]);
+            }
+        }
+        const { sql, descending } = keys[i];
+        const value = values[i];
+        if (!descending) {
+            if (value === null) {
+                parts.push(`${sql} IS NOT NULL`);
+            }
+            else {
+                parts.push(`${sql} > ?`);
+                params.push(value);
+            }
+        }
+        else {
+            if (value === null)
+                continue;
+            parts.push(`(${sql} < ? OR ${sql} IS NULL)`);
+            params.push(value);
+        }
+        branches.push(`(${parts.join(' AND ')})`);
+    }
+    return branches.length ? `(${branches.join(' OR ')})` : '0';
+};
+exports.keysetCondition = keysetCondition;
+// Inserts
+// How many rows of `columnsPerRow` values fit in one statement.
+const rowsPerInsert = (columnsPerRow) => Math.max(1, Math.floor(dataTypes_1.DATA_MAX_PARAMS / Math.max(1, columnsPerRow)));
+exports.rowsPerInsert = rowsPerInsert;
+// Splits rows into groups that each bind at most 100 parameters.
+const chunkRows = (rows, columnsPerRow) => {
+    if (columnsPerRow > dataTypes_1.DATA_MAX_PARAMS) {
+        throw new dataTypes_1.DataError(`A row with ${columnsPerRow} values can't be written in one statement.`, 'too_large');
+    }
+    const size = (0, exports.rowsPerInsert)(columnsPerRow);
+    const out = [];
+    for (let i = 0; i < rows.length; i += size)
+        out.push(rows.slice(i, i + size));
+    return out;
+};
+exports.chunkRows = chunkRows;
+// Arguments
+// Models sometimes quote keys twice ("\"stock\"") or send "where" as a JSON
+// string; both are read as meant. Keys inside a value a row stores (a json
+// column) are left alone: only column names and our own operators are ours
+// to tidy.
+const tidyKey = (key) => key.replace(/^[\s"'`]+|[\s"'`]+$/g, '');
+const tidy = (value) => {
+    if (Array.isArray(value))
+        return value.map(tidy);
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [tidyKey(k), tidy(v)]));
+    }
+    return value;
+};
+const VALUE_OPERATORS = ['increment', 'decrement', '$ref'];
+// A value in "values", "rows" or "set": { "\"decrement\"": 2 } is ours,
+// anything else is what the column stores, as sent.
+const tidyValue = (value) => {
+    if (!isPlainObject(value))
+        return value;
+    const entries = Object.entries(value);
+    if (entries.length !== 1)
+        return value;
+    const key = tidyKey(entries[0][0]);
+    return VALUE_OPERATORS.includes(key) ? { [key]: entries[0][1] } : value;
+};
+const tidyColumns = (values) => isPlainObject(values)
+    ? Object.fromEntries(Object.entries(values).map(([k, v]) => [tidyKey(k), tidyValue(v)]))
+    : values;
+const tidyOperation = (op) => {
+    if (!isPlainObject(op))
+        return op;
+    const out = {};
+    for (const [rawKey, value] of Object.entries(op)) {
+        const key = tidyKey(rawKey);
+        out[key] =
+            key === 'values' || key === 'set'
+                ? tidyColumns(value)
+                : key === 'rows' && Array.isArray(value)
+                    ? value.map(tidyColumns)
+                    : key === 'where'
+                        ? tidy(value)
+                        : value;
+    }
+    return out;
+};
+const tidyArgs = (args) => {
+    if (!isPlainObject(args ?? {})) {
+        throw new dataTypes_1.DataError('Arguments are an object.');
+    }
+    const out = {};
+    for (const [rawKey, value] of Object.entries((args ?? {}))) {
+        out[tidyKey(rawKey)] = value;
+    }
+    for (const key of [
+        'where',
+        'aggregate',
+        'groupBy',
+        'sort',
+        'include',
+        'operations'
+    ]) {
+        if (typeof out[key] === 'string') {
+            try {
+                out[key] = JSON.parse(out[key]);
+            }
+            catch {
+                // Left as is; the compiler explains the expected shape.
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(out)) {
+        if (key === 'operations') {
+            out[key] = Array.isArray(value) ? value.map(tidyOperation) : value;
+        }
+        else if (key !== 'search' && key !== 'cursor') {
+            out[key] = tidy(value);
+        }
+    }
+    return out;
+};
+exports.tidyArgs = tidyArgs;
+const singleId = (value) => {
+    const n = typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : value;
+    return typeof n === 'number' && Number.isInteger(n);
+};
+// Whether an update can touch one row at most: it names an `id`, or its
+// "where" pins id to one value ({ "id": 1 }, { "id": { "eq": 1 } },
+// { "id": { "in": [1] } }), or it names a row inserted earlier in the same
+// write ({ "$ref": 0 }, always a single-row insert). Other keys sit beside it
+// with AND, so they only narrow it further.
+const targetsOneRow = (op) => {
+    if (typeof op.id === 'number')
+        return true;
+    if (isPlainObject(op.id) && '$ref' in op.id)
+        return true;
+    if (!isPlainObject(op.where) || !('id' in op.where))
+        return false;
+    const id = op.where.id;
+    if (singleId(id))
+        return true;
+    if (!isPlainObject(id))
+        return false;
+    return (singleId(id.eq) ||
+        (Array.isArray(id.in) && id.in.length === 1 && singleId(id.in[0])));
+};
+const isRelativeChange = (value) => isPlainObject(value) &&
+    Object.keys(value).length === 1 &&
+    ('increment' in value || 'decrement' in value);
+// Whether a write is held for confirmation: it deletes, or sets a column to
+// a value. Inserts are not, or every order would ask. A relative change (the
+// stock an order uses) is not held when it reaches one row by id, or when the
+// column has a minimum that stops it; otherwise "lower every price by
+// 27,999" would run without asking. Without `schema`, only the id counts.
+const isSensitiveWrite = (rawArgs, schema) => {
+    const args = (0, exports.tidyArgs)(rawArgs);
+    const operations = args.operations;
+    if (!Array.isArray(operations))
+        return true;
+    return operations.some(op => {
+        if (!isPlainObject(op))
+            return true;
+        if (op.op === 'insert')
+            return false;
+        if (op.op !== 'update')
+            return true;
+        const oneRow = targetsOneRow(op);
+        const table = schema?.tables.find(t => t.name === op.table);
+        return Object.entries(isPlainObject(op.set) ? op.set : {}).some(([name, value]) => {
+            if (!isRelativeChange(value))
+                return true;
+            if (oneRow)
+                return false;
+            const column = table?.columns.find(c => c.name === name);
+            return column?.min === null || column?.min === undefined;
+        });
+    });
+};
+exports.isSensitiveWrite = isSensitiveWrite;