@ganju/utils 0.0.16 → 0.0.17

package/dist/dataImport.d.ts

@@ -74,4 +74,6 @@ export declare const importRows: (table: Pick<DataTable, "name" | "columns">, ma
     lines?: number[];
 }) => ImportedRow[];
 export declare const csvLine: (cells: ImportCell[]) => string;
+export { detectSeparator, parseCsv } from './dataCsv';
+export type { ParsedCsv } from './dataCsv';
 //# sourceMappingURL=dataImport.d.ts.map

package/dist/dataImport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataImport.d.ts","sourceRoot":"","sources":["../src/dataImport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataImport.d.ts","sourceRoot":"","sources":["../src/dataImport.ts"],"names":[],"mappings":"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"}

package/dist/dataImport.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.csvLine = exports.importRows = exports.importCell = exports.relationKey = exports.matchHeaders = exports.guessColumns = exports.guessColumnType = exports.columnNameFromHeader = exports.normaliseHeader = exports.parseNumber = exports.detectDecimalMark = exports.DATA_IMPORT_BATCH = exports.DATA_IMPORT_SAMPLE_ROWS = exports.toTableInput = exports.isValidIdentifier = exports.identifierIssue = void 0;
+exports.parseCsv = exports.detectSeparator = exports.csvLine = exports.importRows = exports.importCell = exports.relationKey = exports.matchHeaders = exports.guessColumns = exports.guessColumnType = exports.columnNameFromHeader = exports.normaliseHeader = exports.parseNumber = exports.detectDecimalMark = exports.DATA_IMPORT_BATCH = exports.DATA_IMPORT_SAMPLE_ROWS = exports.toTableInput = exports.isValidIdentifier = exports.identifierIssue = void 0;
 // Reading a spreadsheet into a table: the column types guessed for a new
 // table, the headers matched to an existing one's columns, and each cell
 // checked the way the database will check it. The dashboard's import and
@@ -448,3 +448,6 @@ const csvLine = (cells) => cells
 })
     .join(',');
 exports.csvLine = csvLine;
+var dataCsv_1 = require("./dataCsv");
+Object.defineProperty(exports, "detectSeparator", { enumerable: true, get: function () { return dataCsv_1.detectSeparator; } });
+Object.defineProperty(exports, "parseCsv", { enumerable: true, get: function () { return dataCsv_1.parseCsv; } });

package/dist/dataQueries.d.ts

@@ -0,0 +1,73 @@
+import type { DataCaller, DataSchema } from './dataTypes';
+import type { SqlRow, SqlRunner } from './dataEngine';
+export declare const DATA_QUERY_PARAM_TYPES: readonly ["text", "integer", "decimal", "boolean", "date", "datetime"];
+export type DataQueryParamType = (typeof DATA_QUERY_PARAM_TYPES)[number];
+export interface DataQueryParam {
+    name: string;
+    type: DataQueryParamType;
+    description?: string | null;
+    required?: boolean;
+}
+export interface DataQueryInput {
+    name: string;
+    description?: string | null;
+    sql: string;
+    params?: DataQueryParam[];
+    assistant?: boolean;
+}
+export interface DataQuery {
+    name: string;
+    description: string | null;
+    sql: string;
+    params: DataQueryParam[];
+    assistant: boolean;
+    tables: string[];
+    plan: string[];
+    updatedAt: string;
+    updatedBy: string | null;
+}
+export declare const DATA_MAX_QUERIES = 100;
+export declare const DATA_MAX_QUERY_SQL = 10000;
+export declare const DATA_MAX_QUERY_PARAMS = 20;
+export declare const DATA_DEFAULT_QUERY_ROWS = 100;
+export interface CompiledQuerySql {
+    sql: string;
+    params: string[];
+}
+/**
+ * Checks a named query's text and compiles its parameters to positions. Pure:
+ * what only SQLite can tell (that it reads, and what) is checked when it is
+ * saved, by checkQueryPlan.
+ */
+export declare const compileQuerySql: (sql: unknown) => CompiledQuerySql;
+export interface QueryPlanCheck {
+    tables: string[];
+    plan: string[];
+}
+/**
+ * Compiles the statement with EXPLAIN (nothing runs) and checks its program:
+ * it may not open anything for writing or start a write transaction, and every
+ * table it reads must be one of `schema`'s. Returns those tables and the plan.
+ */
+export declare const checkQueryPlan: (runner: SqlRunner, schema: DataSchema, compiled: CompiledQuerySql) => QueryPlanCheck;
+export declare const listQueries: (runner: SqlRunner) => DataQuery[];
+/**
+ * Saves a named query, replacing one by the same name. Refused unless it
+ * passes both checks; the tables it reads and its plan are kept with it.
+ */
+export declare const saveQuery: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, input: unknown) => DataQuery;
+export declare const dropQuery: (runner: SqlRunner, name: unknown) => {
+    dropped: string;
+};
+export declare const queriesFor: (runner: SqlRunner, schema: DataSchema, caller: DataCaller) => DataQuery[];
+/**
+ * Runs a named query with `params`, up to `limit` rows (100 by default, 500 at
+ * most) and 1 MB. A query that would scan a table over 200,000 rows is refused
+ * before it runs: the database serves one request at a time.
+ */
+export declare const runQuery: (runner: SqlRunner, schema: DataSchema, caller: DataCaller, args: unknown) => {
+    truncated?: string | undefined;
+    query: string;
+    rows: SqlRow[];
+};
+//# sourceMappingURL=dataQueries.d.ts.map

package/dist/dataQueries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataQueries.d.ts","sourceRoot":"","sources":["../src/dataQueries.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EAEX,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,eAAO,MAAM,sBAAsB,wEAOzB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAE1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IAEnB,MAAM,EAAE,MAAM,EAAE,CAAC;IAGjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAsH3C,MAAM,WAAW,gBAAgB;IAE/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,gBA2E9C,CAAC;AAgDF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,EACjB,QAAQ,UAAU,EAClB,UAAU,gBAAgB,KACzB,cA0DF,CAAC;AAwCF,eAAO,MAAM,WAAW,GAAI,QAAQ,SAAS,KAAG,SAAS,EACc,CAAC;AA6DxE;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,EACjB,QAAQ,UAAU,EAClB,QAAQ,UAAU,EAClB,OAAO,OAAO,KACb,SA8CF,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,EACjB,MAAM,OAAO,KACZ;IAAE,OAAO,EAAE,MAAM,CAAA;CAInB,CAAC;AAuBF,eAAO,MAAM,UAAU,GACrB,QAAQ,SAAS,EACjB,QAAQ,UAAU,EAClB,QAAQ,UAAU,KACjB,SAAS,EACwD,CAAC;AAuBrE;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ,SAAS,EACjB,QAAQ,UAAU,EAClB,QAAQ,UAAU,EAClB,MAAM,OAAO;;;;CAgGd,CAAC"}

package/dist/dataQueries.js

@@ -0,0 +1,513 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQuery = exports.queriesFor = exports.dropQuery = exports.saveQuery = exports.listQueries = exports.checkQueryPlan = exports.compileQuerySql = exports.DATA_DEFAULT_QUERY_ROWS = exports.DATA_MAX_QUERY_PARAMS = exports.DATA_MAX_QUERY_SQL = exports.DATA_MAX_QUERIES = exports.DATA_QUERY_PARAM_TYPES = void 0;
+// Named queries: a SELECT the owner writes once, with named parameters, for
+// reports the structured query can't express. Functions run them by name, and
+// so may the assistant when the owner allows it; nobody sends SQL at run time.
+//
+// A Durable Object refuses `PRAGMA query_only`, so nothing in SQLite stops a
+// statement from writing. The check when a query is saved is the whole guard,
+// in two layers:
+// - our tokenizer: one statement, starting with SELECT or WITH, naming none
+//   of SQLite's or our own tables, with named parameters only. A Durable
+//   Object's exec runs every statement in a string ("SELECT 1; DELETE FROM
+//   orders" deletes), so the single statement is checked here, on tokens.
+// - SQLite's own parser: the statement is compiled with EXPLAIN, never run,
+//   and refused if its program opens anything for writing or reads a table
+//   that isn't one of the owner's.
+const dataIdentifiers_1 = require("./dataIdentifiers");
+const dataCompiler_1 = require("./dataCompiler");
+const dataTypes_1 = require("./dataTypes");
+exports.DATA_QUERY_PARAM_TYPES = [
+    'text',
+    'integer',
+    'decimal',
+    'boolean',
+    'date',
+    'datetime'
+];
+exports.DATA_MAX_QUERIES = 100;
+exports.DATA_MAX_QUERY_SQL = 10_000;
+exports.DATA_MAX_QUERY_PARAMS = 20;
+exports.DATA_DEFAULT_QUERY_ROWS = 100;
+const WORD_START = /[\p{L}_]/u;
+const WORD_PART = /[\p{L}\p{N}_$]/u;
+const unterminated = (what) => new dataTypes_1.DataError(`The SQL has an unterminated ${what}.`);
+// SQLite's lexical rules, as far as telling statements, names, literals and
+// parameters apart needs: comments and whitespace are dropped, everything
+// else becomes a token that keeps its place in the text.
+const tokenize = (sql) => {
+    const tokens = [];
+    let i = 0;
+    const push = (kind, start, end) => tokens.push({ kind, text: sql.slice(start, end), start, end });
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (/\s/.test(ch)) {
+            i++;
+        }
+        else if (ch === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i);
+            i = end === -1 ? sql.length : end + 1;
+        }
+        else if (ch === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            if (end === -1)
+                throw unterminated('comment');
+            i = end + 2;
+        }
+        else if (ch === "'" || ch === '"' || ch === '`' || ch === '[') {
+            const close = ch === '[' ? ']' : ch;
+            let j = i + 1;
+            for (;;) {
+                if (j >= sql.length) {
+                    throw unterminated(ch === "'" ? 'string' : 'quoted name');
+                }
+                if (sql[j] === close) {
+                    // A doubled quote is the quote itself, except in [brackets].
+                    if (close !== ']' && sql[j + 1] === close) {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            push(ch === "'" ? 'string' : 'quoted', i, j + 1);
+            i = j + 1;
+        }
+        else if (ch === ':' || ch === '@' || ch === '$') {
+            let j = i + 1;
+            while (j < sql.length && WORD_PART.test(sql[j]))
+                j++;
+            if (j === i + 1) {
+                push('other', i, j);
+            }
+            else {
+                push('param', i, j);
+            }
+            i = j;
+        }
+        else if (ch === '?') {
+            let j = i + 1;
+            while (j < sql.length && /\d/.test(sql[j]))
+                j++;
+            push('positional', i, j);
+            i = j;
+        }
+        else if (ch === ';') {
+            push('semicolon', i, i + 1);
+            i++;
+        }
+        else if (/\d/.test(ch) || (ch === '.' && /\d/.test(sql[i + 1] ?? ''))) {
+            let j = i + 1;
+            while (j < sql.length && /[\w.]/.test(sql[j]))
+                j++;
+            push('number', i, j);
+            i = j;
+        }
+        else if (WORD_START.test(ch)) {
+            let j = i + 1;
+            while (j < sql.length && WORD_PART.test(sql[j]))
+                j++;
+            push('word', i, j);
+            i = j;
+        }
+        else {
+            push('other', i, i + 1);
+            i++;
+        }
+    }
+    return tokens;
+};
+// A quoted name's text without its quotes, the way SQLite reads it.
+const nameOf = (token) => {
+    if (token.kind !== 'quoted')
+        return token.text.toLowerCase();
+    const inner = token.text.slice(1, -1);
+    const quote = token.text[0];
+    return (quote === '[' ? inner : inner.split(quote + quote).join(quote)).toLowerCase();
+};
+const FORBIDDEN_WORDS = new Set(['pragma', 'attach', 'detach', 'vacuum']);
+const reservedName = (name) => name.startsWith('_ganju_') ||
+    name.startsWith('sqlite_') ||
+    name.startsWith('pragma_') ||
+    name.includes('__');
+/**
+ * Checks a named query's text and compiles its parameters to positions. Pure:
+ * what only SQLite can tell (that it reads, and what) is checked when it is
+ * saved, by checkQueryPlan.
+ */
+const compileQuerySql = (sql) => {
+    if (typeof sql !== 'string' || !sql.trim()) {
+        throw new dataTypes_1.DataError('"sql" is the SELECT to run.');
+    }
+    if (sql.length > exports.DATA_MAX_QUERY_SQL) {
+        throw new dataTypes_1.DataError(`A named query is up to ${exports.DATA_MAX_QUERY_SQL.toLocaleString('en-US')} characters.`);
+    }
+    const tokens = tokenize(sql);
+    // Trailing semicolons are harmless; any other ends the statement early, and
+    // what follows would run as a second one.
+    while (tokens.length && tokens[tokens.length - 1].kind === 'semicolon') {
+        tokens.pop();
+    }
+    if (tokens.some(t => t.kind === 'semicolon')) {
+        throw new dataTypes_1.DataError('A named query is one statement: remove the ";" inside it.');
+    }
+    const head = tokens[0];
+    if (!head ||
+        head.kind !== 'word' ||
+        !['select', 'with'].includes(head.text.toLowerCase())) {
+        throw new dataTypes_1.DataError('A named query starts with SELECT or WITH; it only reads.');
+    }
+    const params = [];
+    let out = '';
+    let last = 0;
+    for (const token of tokens) {
+        if (token.kind === 'positional') {
+            throw new dataTypes_1.DataError('Use named parameters (:from, :to) instead of "?", so each one can be described.');
+        }
+        if (token.kind === 'word' &&
+            FORBIDDEN_WORDS.has(token.text.toLowerCase())) {
+            throw new dataTypes_1.DataError(`${token.text.toUpperCase()} isn't allowed in a named query.`);
+        }
+        if ((token.kind === 'word' || token.kind === 'quoted') &&
+            reservedName(nameOf(token))) {
+            throw new dataTypes_1.DataError(`"${nameOf(token)}" isn't one of this database's tables or columns; named queries read the tables you defined.`);
+        }
+        if (token.kind === 'param') {
+            const name = token.text.slice(1);
+            if (!dataIdentifiers_1.DATA_IDENTIFIER_PATTERN.test(name)) {
+                throw new dataTypes_1.DataError(`Parameter ${token.text}: use lowercase letters, digits and _, starting with a letter.`);
+            }
+            let index = params.indexOf(name);
+            if (index === -1)
+                index = params.push(name) - 1;
+            out += `${sql.slice(last, token.start)}?${index + 1}`;
+            last = token.end;
+        }
+    }
+    out += sql.slice(last, tokens.length ? tokens[tokens.length - 1].end : 0);
+    if (params.length > exports.DATA_MAX_QUERY_PARAMS) {
+        throw new dataTypes_1.DataError(`A named query takes up to ${exports.DATA_MAX_QUERY_PARAMS} parameters.`);
+    }
+    return { sql: out, params };
+};
+exports.compileQuerySql = compileQuerySql;
+// What SQLite's program does
+// Opcodes that only appear in a program that changes the database file. A
+// SELECT's own scratch tables (ORDER BY, DISTINCT, IN lists) use ephemeral
+// cursors and never these.
+const WRITE_OPCODES = new Set([
+    'OpenWrite',
+    'Clear',
+    'Destroy',
+    'CreateBtree',
+    'ParseSchema',
+    'DropTable',
+    'DropIndex',
+    'DropTrigger',
+    'VUpdate',
+    'VCreate',
+    'VDestroy',
+    'SqlExec',
+    'Vacuum',
+    'IncrVacuum',
+    'SetCookie',
+    'JournalMode'
+]);
+// Virtual tables are opened with VOpen, not OpenRead, and the program names
+// no module. What it does give is the virtual table's address, and the
+// built-in ones (json_each, dbstat) keep one per connection: so json_each's
+// and json_tree's are read off a query of their own, and any other is
+// refused. dbstat, for one, lists every table with its size.
+const ALLOWED_VIRTUAL_TABLES = [
+    "SELECT 1 FROM json_each('[]')",
+    "SELECT 1 FROM json_tree('[]')"
+];
+const virtualTablesOf = (program) => program.filter(step => String(step.opcode) === 'VOpen').map(step => step.p4);
+// SQLite's own error, without the code and offset it appends.
+const sqliteMessage = (error) => (error instanceof Error ? error.message : String(error))
+    .replace(/\s*at offset \d+/, '')
+    .replace(/:\s*SQLITE_\w+$/, '')
+    .trim();
+const placeholders = (count) => Array(count).fill(null);
+/**
+ * Compiles the statement with EXPLAIN (nothing runs) and checks its program:
+ * it may not open anything for writing or start a write transaction, and every
+ * table it reads must be one of `schema`'s. Returns those tables and the plan.
+ */
+const checkQueryPlan = (runner, schema, compiled) => {
+    let program;
+    try {
+        program = runner.all(`EXPLAIN ${compiled.sql}`, placeholders(compiled.params.length));
+    }
+    catch (error) {
+        throw new dataTypes_1.DataError(`The SQL doesn't compile: ${sqliteMessage(error)}.`);
+    }
+    const roots = new Map();
+    for (const row of runner.all("SELECT rootpage, tbl_name FROM sqlite_schema WHERE type IN ('table', 'index')")) {
+        roots.set(Number(row.rootpage), String(row.tbl_name));
+    }
+    const owned = new Set(schema.tables.map(t => t.name));
+    const opened = virtualTablesOf(program);
+    if (opened.length > 0) {
+        const allowed = new Set(ALLOWED_VIRTUAL_TABLES.flatMap(sql => virtualTablesOf(runner.all(`EXPLAIN ${sql}`))));
+        if (opened.some(vtab => typeof vtab !== 'string' || !allowed.has(vtab))) {
+            throw new dataTypes_1.DataError("A named query reads only this database's tables, with json_each and json_tree for JSON; not other virtual tables such as dbstat.");
+        }
+    }
+    const tables = new Set();
+    for (const step of program) {
+        const opcode = String(step.opcode);
+        if (WRITE_OPCODES.has(opcode) ||
+            (opcode === 'Transaction' && Number(step.p2) !== 0)) {
+            throw new dataTypes_1.DataError('A named query only reads: this one would change the database.');
+        }
+        if (opcode === 'OpenRead') {
+            const table = roots.get(Number(step.p2));
+            if (!table || !owned.has(table)) {
+                throw new dataTypes_1.DataError(`A named query reads only this database's tables${table ? `, not "${table}"` : ''}.`);
+            }
+            tables.add(table);
+        }
+    }
+    const plan = runner
+        .all(`EXPLAIN QUERY PLAN ${compiled.sql}`, placeholders(compiled.params.length))
+        .map(row => String(row.detail));
+    return { tables: [...tables].sort(), plan };
+};
+exports.checkQueryPlan = checkQueryPlan;
+const parseList = (raw) => {
+    try {
+        const value = JSON.parse(String(raw));
+        return Array.isArray(value) ? value : [];
+    }
+    catch {
+        return [];
+    }
+};
+const fromRow = (row) => {
+    const stored = row;
+    return {
+        name: stored.name,
+        description: stored.description,
+        sql: stored.sql,
+        params: parseList(stored.params),
+        assistant: Boolean(stored.assistant),
+        tables: parseList(stored.tables),
+        plan: parseList(stored.plan),
+        updatedAt: stored.updated_at,
+        updatedBy: stored.updated_by
+    };
+};
+const listQueries = (runner) => runner.all('SELECT * FROM _ganju_queries ORDER BY name').map(fromRow);
+exports.listQueries = listQueries;
+const findQuery = (runner, name) => {
+    const row = typeof name === 'string'
+        ? runner.all('SELECT * FROM _ganju_queries WHERE name = ?', [name])[0]
+        : undefined;
+    if (!row) {
+        const names = (0, exports.listQueries)(runner).map(query => query.name);
+        throw new dataTypes_1.DataError(`There is no named query "${String(name)}". Named queries: ${names.join(', ') || '(none)'}.`, 'not_found');
+    }
+    return fromRow(row);
+};
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const normaliseParams = (raw, used) => {
+    const list = raw === undefined || raw === null ? [] : raw;
+    if (!Array.isArray(list)) {
+        throw new dataTypes_1.DataError('"params" is a list of { name, type, description }.');
+    }
+    const params = list.map((entry, i) => {
+        if (!isPlainObject(entry) || typeof entry.name !== 'string') {
+            throw new dataTypes_1.DataError(`params[${i}] needs a name.`);
+        }
+        if (!exports.DATA_QUERY_PARAM_TYPES.includes(entry.type)) {
+            throw new dataTypes_1.DataError(`Parameter ${entry.name}: "type" is one of ${exports.DATA_QUERY_PARAM_TYPES.join(', ')}.`);
+        }
+        const description = typeof entry.description === 'string' && entry.description.trim()
+            ? entry.description.trim().slice(0, dataTypes_1.DATA_MAX_DESCRIPTION)
+            : null;
+        return {
+            name: entry.name,
+            type: entry.type,
+            ...(description ? { description } : {}),
+            ...(entry.required === false ? { required: false } : {})
+        };
+    });
+    const declared = params.map(p => p.name);
+    const undeclared = used.filter(name => !declared.includes(name));
+    if (undeclared.length) {
+        throw new dataTypes_1.DataError(`Declare the type of ${undeclared.map(n => `:${n}`).join(', ')} in "params".`);
+    }
+    const unused = declared.filter(name => !used.includes(name));
+    if (unused.length) {
+        throw new dataTypes_1.DataError(`The SQL doesn't use ${unused.map(n => `:${n}`).join(', ')}.`);
+    }
+    return used.map(name => params.find(p => p.name === name));
+};
+/**
+ * Saves a named query, replacing one by the same name. Refused unless it
+ * passes both checks; the tables it reads and its plan are kept with it.
+ */
+const saveQuery = (runner, schema, caller, input) => {
+    if (!isPlainObject(input))
+        throw new dataTypes_1.DataError('A named query is an object.');
+    const name = input.name;
+    if (typeof name !== 'string' || !dataIdentifiers_1.DATA_IDENTIFIER_PATTERN.test(name)) {
+        throw new dataTypes_1.DataError('A named query needs a name: lowercase letters, digits and _, starting with a letter.');
+    }
+    const compiled = (0, exports.compileQuerySql)(input.sql);
+    const params = normaliseParams(input.params, compiled.params);
+    const { tables, plan } = (0, exports.checkQueryPlan)(runner, schema, compiled);
+    const description = typeof input.description === 'string' && input.description.trim()
+        ? input.description.trim().slice(0, dataTypes_1.DATA_MAX_DESCRIPTION)
+        : null;
+    const exists = runner.all('SELECT 1 FROM _ganju_queries WHERE name = ?', [name]).length >
+        0;
+    if (!exists) {
+        const count = Number(runner.all('SELECT count(*) AS n FROM _ganju_queries')[0]?.n ?? 0);
+        if (count >= exports.DATA_MAX_QUERIES) {
+            throw new dataTypes_1.DataError(`A database holds up to ${exports.DATA_MAX_QUERIES} named queries.`);
+        }
+    }
+    runner.all(`INSERT INTO _ganju_queries (name, description, sql, params, assistant, tables, plan, updated_at, updated_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), ?)
+     ON CONFLICT(name) DO UPDATE SET description = excluded.description, sql = excluded.sql,
+       params = excluded.params, assistant = excluded.assistant, tables = excluded.tables,
+       plan = excluded.plan, updated_at = excluded.updated_at, updated_by = excluded.updated_by`, [
+        name,
+        description,
+        input.sql.trim(),
+        JSON.stringify(params),
+        input.assistant === true ? 1 : 0,
+        JSON.stringify(tables),
+        JSON.stringify(plan),
+        caller.actor
+    ]);
+    return findQuery(runner, name);
+};
+exports.saveQuery = saveQuery;
+const dropQuery = (runner, name) => {
+    const query = findQuery(runner, name);
+    runner.all('DELETE FROM _ganju_queries WHERE name = ?', [query.name]);
+    return { dropped: query.name };
+};
+exports.dropQuery = dropQuery;
+// The queries a caller may run: all of them, or for a channel bot those the
+// owner let the assistant run that read only tables it may read, none of
+// them scoped to a customer. A named query's SQL can't be scoped, so it could
+// read every customer's rows.
+const mayRun = (schema, caller, query) => {
+    if (caller.tables &&
+        !query.tables.every(name => caller.tables?.includes(name))) {
+        return false;
+    }
+    if (!caller.restricted)
+        return true;
+    if (!query.assistant)
+        return false;
+    return query.tables.every(name => {
+        const table = schema.tables.find(t => t.name === name);
+        return Boolean(table && dataTypes_1.DATA_ACCESS_RANK[table.access] >= 1 && !(0, dataCompiler_1.isScoped)(caller, table));
+    });
+};
+const queriesFor = (runner, schema, caller) => (0, exports.listQueries)(runner).filter(query => mayRun(schema, caller, query));
+exports.queriesFor = queriesFor;
+// A parameter's value as the column of its type would store it.
+const bindParam = (param, value, timeZone) => {
+    const column = {
+        name: param.name,
+        type: param.type,
+        required: param.required !== false
+    };
+    try {
+        return (0, dataCompiler_1.toStored)({ name: 'params' }, column, value, timeZone);
+    }
+    catch (error) {
+        if (error instanceof dataTypes_1.DataError) {
+            throw new dataTypes_1.DataError(error.message.replace(/^params\./, 'Parameter '));
+        }
+        throw error;
+    }
+};
+/**
+ * Runs a named query with `params`, up to `limit` rows (100 by default, 500 at
+ * most) and 1 MB. A query that would scan a table over 200,000 rows is refused
+ * before it runs: the database serves one request at a time.
+ */
+const runQuery = (runner, schema, caller, args) => {
+    if (!isPlainObject(args))
+        throw new dataTypes_1.DataError('Arguments are an object.');
+    const query = findQuery(runner, args.name ?? args.query);
+    if (!mayRun(schema, caller, query)) {
+        throw new dataTypes_1.DataError(`There is no named query "${query.name}" the assistant may run.`, 'not_found');
+    }
+    const given = args.params === undefined || args.params === null ? {} : args.params;
+    if (!isPlainObject(given)) {
+        throw new dataTypes_1.DataError('"params" is an object, e.g. { "from": "2026-10-01" }.');
+    }
+    const unknown = Object.keys(given).filter(key => !query.params.some(p => p.name === key));
+    if (unknown.length) {
+        throw new dataTypes_1.DataError(`${query.name} takes ${query.params.map(p => p.name).join(', ') || 'no parameters'}; not ${unknown.join(', ')}.`);
+    }
+    const limit = args.limit === undefined || args.limit === null
+        ? exports.DATA_DEFAULT_QUERY_ROWS
+        : args.limit;
+    if (typeof limit !== 'number' ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > dataTypes_1.DATA_MAX_PAGE) {
+        throw new dataTypes_1.DataError(`"limit" is 1 to ${dataTypes_1.DATA_MAX_PAGE}.`);
+    }
+    const values = query.params.map(param => bindParam(param, given[param.name], caller.timeZone));
+    const compiled = (0, exports.compileQuerySql)(query.sql);
+    // A full scan shows in the plan as "SCAN x", with or without "USING
+    // (COVERING) INDEX": either way it reads every row, and on a large table
+    // that is the request everyone else waits behind.
+    const scans = query.plan.some(line => {
+        const detail = line.trim();
+        return (detail.startsWith('SCAN ') &&
+            !detail.startsWith('SCAN CONSTANT ROW') &&
+            !detail.includes('VIRTUAL TABLE'));
+    });
+    if (scans) {
+        for (const name of query.tables) {
+            const n = Number(runner.all(`SELECT max(id) AS n FROM ${(0, dataIdentifiers_1.quoteIdentifier)(name)}`)[0]?.n ?? 0);
+            if (n > dataTypes_1.DATA_LARGE_TABLE_ROWS) {
+                throw new dataTypes_1.DataError(`${query.name} reads all of ${name}, which has about ${n.toLocaleString('en-US')} rows; filter on an indexed column (id, or a column marked filterable, unique or a relation).`, 'too_large');
+            }
+        }
+    }
+    const rows = [];
+    let bytes = 0;
+    let truncated = false;
+    try {
+        for (const row of runner.iterate(compiled.sql, values)) {
+            if (rows.length === limit) {
+                truncated = true;
+                break;
+            }
+            const size = JSON.stringify(row).length;
+            if (rows.length > 0 && bytes + size > dataTypes_1.DATA_MAX_RESULT_BYTES) {
+                truncated = true;
+                break;
+            }
+            bytes += size;
+            rows.push({ ...row });
+        }
+    }
+    catch (error) {
+        throw new dataTypes_1.DataError(`${query.name} failed: ${sqliteMessage(error)}.`);
+    }
+    return {
+        query: query.name,
+        rows,
+        ...(truncated
+            ? {
+                truncated: `stopped at ${rows.length} rows; narrow the parameters or ask the owner for a query that returns fewer`
+            }
+            : {})
+    };
+};
+exports.runQuery = runQuery;

package/dist/dataRpc.d.ts

@@ -1,4 +1,5 @@
 import type { DataCaller, DataDeleteImpact, DataResult, DataSchema, DataTable, DataTableCopy } from './dataTypes';
+import type { DataQuery } from './dataQueries';
 export type ExportFormat = 'jsonl' | 'csv';
 export interface ExportFile {
     table: string | null;
@@ -36,6 +37,7 @@ export interface DatabaseInfo {
     initializedAt: string | null;
     deletedAt: string | null;
     firstWriteAt: string | null;
+    timeZone: string | null;
     schemaVersion: number;
     size: number;
     tables: {
@@ -62,6 +64,9 @@ export interface ProjectDatabaseRpc {
     size(): R<{
         bytes: number;
     }>;
+    setTimeZone(caller: DataCaller, args: {
+        timeZone: string | null;
+    }): R<DatabaseInfo>;
     markDeleted(caller: DataCaller): R<{
         deletedAt: string | null;
         bookmark: string;
@@ -117,6 +122,20 @@ export interface ProjectDatabaseRpc {
         limit?: number;
         cursor?: number;
     }): R<unknown>;
+    listQueries(caller: DataCaller): R<DataQuery[]>;
+    saveQuery(caller: DataCaller, input: unknown): R<DataQuery>;
+    dropQuery(caller: DataCaller, name: string): R<{
+        dropped: string;
+    }>;
+    runQuery(caller: DataCaller, args: {
+        name: string;
+        params?: Record<string, unknown>;
+        limit?: number;
+    }): R<{
+        query: string;
+        rows: Record<string, unknown>[];
+        truncated?: string;
+    }>;
     exportStart(caller: DataCaller, args?: {
         format?: ExportFormat;
     }): R<{