@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/protocol/connection.ts

@@ -0,0 +1,86 @@
+/* A database file on the machine the helper runs on. */
+export interface SqliteConnectionConfig {
+    readonly engine: 'sqlite';
+    /* An absolute path. The helper never creates the file unless `create` is set. */
+    readonly path: string;
+    readonly create?: boolean;
+    readonly readOnly?: boolean;
+}
+
+/* How the connection to a MySQL or MariaDB server is encrypted. `prefer` falls back to plain text when the server offers no TLS; `verify` also checks the certificate against the host name. */
+export type MysqlTlsMode = 'disable' | 'prefer' | 'require' | 'verify';
+
+/*
+ * A server reached through a host the helper can SSH into. The helper runs the system's `ssh -W` for
+ * every connection, so `~/.ssh/config`, the agent and `ProxyJump` apply, and it never asks for a
+ * password: a key or the agent has to answer.
+ */
+export interface SshTunnel {
+    readonly kind: 'ssh';
+    /* A host name, or a `Host` of `~/.ssh/config`. */
+    readonly host: string;
+    readonly port?: number;
+    readonly user?: string;
+    readonly identityFile?: string;
+}
+
+/*
+ * A server in a Docker container. The helper connects to the port the container publishes, or, when it
+ * publishes none, through `docker exec`, which needs `bash` in the container.
+ */
+export interface DockerTunnel {
+    readonly kind: 'docker';
+    /* The name or id of the container. */
+    readonly container: string;
+    /* The port inside the container; the engine's default when left out. */
+    readonly port?: number;
+    /* A Docker context other than the current one. */
+    readonly context?: string;
+}
+
+export type Tunnel = SshTunnel | DockerTunnel;
+
+/* A MySQL or MariaDB server, over TCP or a Unix socket, directly or through a tunnel. */
+export interface MysqlConnectionConfig {
+    readonly engine: 'mysql';
+    /* As the far end of the tunnel sees it when there is one; a Docker tunnel ignores it. */
+    readonly host: string;
+    /* 3306 when left out. */
+    readonly port?: number;
+    /* A Unix socket to connect through instead of `host` and `port`. */
+    readonly socket?: string;
+    readonly user: string;
+    readonly password?: string;
+    /* The schema a session starts in; a session without one sees every schema and has none selected. */
+    readonly database?: string;
+    readonly tls?: MysqlTlsMode;
+    readonly readOnly?: boolean;
+    readonly tunnel?: Tunnel;
+}
+
+export type ConnectionConfig = SqliteConnectionConfig | MysqlConnectionConfig;
+
+export type Engine = ConnectionConfig['engine'];
+
+/* What answered: one engine can be served by more than one product, which differ in SQL. */
+export interface ServerInfo {
+    readonly flavor: 'sqlite' | 'mysql' | 'mariadb';
+    /* The version as the server reports it, such as `11.4.2-MariaDB`. */
+    readonly version: string;
+}
+
+/* A running container that looks like it serves a database, as `discover` lists it. */
+export interface DockerContainer {
+    readonly id: string;
+    readonly name: string;
+    readonly image: string;
+    /* What the image or its ports suggest; `null` when neither says. */
+    readonly engine: Engine | null;
+    /* The ports inside the container with the host port each is published on, or `null` when it is not. */
+    readonly ports: readonly { readonly container: number; readonly host: number | null }[];
+    /* From the Compose labels, so a list can group the containers of one project. */
+    readonly project: string | null;
+    readonly service: string | null;
+    /* What the container's environment sets for the image's own variables (`MYSQL_DATABASE`, `MARIADB_USER`, ...), to fill a form with. */
+    readonly suggested: { readonly user?: string; readonly password?: string; readonly database?: string };
+}

package/src/protocol/errors.ts

@@ -0,0 +1,38 @@
+/*
+ * Why a request failed. The helper sends the first group; the host adds `helper-exited` and
+ * `helper-unavailable`, and `forbidden` when the app's check turns a connection, a file or a discovery down.
+ */
+export type DatabaseErrorCode =
+    /* The request does not have the shape of the protocol. */
+    | 'invalid-request'
+    /* The session was closed, or belonged to a helper that has since exited. */
+    | 'unknown-session'
+    | 'connect-failed'
+    | 'auth-failed'
+    /* The SSH or Docker tunnel did not come up; `message` holds what `ssh` or `docker` said. */
+    | 'tunnel-failed'
+    /* The server turned the SQL down; `sqlState` and `message` say why. */
+    | 'query-failed'
+    /* A write on a connection opened read only. */
+    | 'read-only'
+    /* An update or a delete on a table without a primary key or a unique key over columns that cannot be null. */
+    | 'no-row-key'
+    /* An update or a delete matched no row or more than one, so the transaction was rolled back. */
+    | 'conflict'
+    | 'cancelled'
+    | 'unsupported'
+    /* A file to export to or import from could not be read or written. */
+    | 'file-failed'
+    | 'forbidden'
+    | 'helper-exited'
+    | 'helper-unavailable'
+    | 'internal';
+
+export interface DatabaseError {
+    readonly code: DatabaseErrorCode;
+    readonly message: string;
+    /* The five characters of SQLSTATE, when the server sent them. */
+    readonly sqlState?: string;
+    /* For `conflict`: which change of the request it was, counted from zero. */
+    readonly change?: number;
+}

package/src/protocol/index.ts

@@ -0,0 +1,33 @@
+/* The messages between a page, the host in the app's backend and the helper. Types and pure helpers only, so a page, a preload and a backend can all read it. */
+
+export type {
+    ConnectionConfig,
+    DockerContainer,
+    DockerTunnel,
+    Engine,
+    MysqlConnectionConfig,
+    MysqlTlsMode,
+    ServerInfo,
+    SqliteConnectionConfig,
+    SshTunnel,
+    Tunnel
+} from './connection.ts';
+export type { DatabaseError, DatabaseErrorCode } from './errors.ts';
+export {
+    PROTOCOL_VERSION,
+    type DatabaseMethod,
+    type DatabaseMethods,
+    type DatabaseParams,
+    type DatabaseRequest,
+    type DatabaseResponse,
+    type DatabaseResult,
+    type ExportSource,
+    type FileFormat,
+    type HelperReady,
+    type RowChange,
+    type RowKey,
+    type RowsResult,
+    type StatementResult
+} from './messages.ts';
+export type { ColumnInfo, ForeignKeyInfo, IndexInfo, ResultColumn, SchemaInfo, TableInfo, TableKind, TableStructure } from './schema.ts';
+export { valueOfCell, type BinaryCell, type BinaryValue, type Cell, type EditValue, type LongTextCell, type Value, type ValueKind } from './values.ts';

package/src/protocol/messages.ts

@@ -0,0 +1,168 @@
+import type { ConnectionConfig, DockerContainer, ServerInfo } from './connection.ts';
+import type { DatabaseError } from './errors.ts';
+import type { ResultColumn, SchemaInfo, TableInfo, TableStructure } from './schema.ts';
+import type { Cell, EditValue, Value } from './values.ts';
+
+/* Raised whenever a message changes shape, so a host refuses a helper from another release. */
+export const PROTOCOL_VERSION = 2;
+
+/* The columns of the row key and their values. */
+export type RowKey = Readonly<Record<string, Value>>;
+
+export type RowChange =
+    | { readonly kind: 'insert'; readonly values: Readonly<Record<string, EditValue>> }
+    | { readonly kind: 'update'; readonly key: RowKey; readonly values: Readonly<Record<string, EditValue>> }
+    | { readonly kind: 'delete'; readonly key: RowKey };
+
+export interface RowsResult {
+    readonly columns: readonly ResultColumn[];
+    readonly rows: readonly (readonly Cell[])[];
+    /* Whether a row exists past this page, which the helper learns by reading one row more than the limit. */
+    readonly hasMore: boolean;
+    readonly elapsedMs: number;
+}
+
+/* What one statement of an `execute` did. A failed statement ends the list, and the ones after it never ran. */
+export type StatementResult =
+    | ({ readonly kind: 'rows'; readonly sql: string } & RowsResult)
+    | { readonly kind: 'done'; readonly sql: string; readonly affected: number; readonly lastInsertId: number | string | null; readonly elapsedMs: number }
+    | { readonly kind: 'error'; readonly sql: string; readonly error: DatabaseError; readonly elapsedMs: number };
+
+/* A file format for `export` and `import`. JSON and SQL only export: an import reads delimited text. */
+export type FileFormat = 'csv' | 'tsv' | 'json' | 'sql';
+
+/* What an export writes: a table, filtered and ordered as a table view shows it, or the rows of one statement. */
+export type ExportSource =
+    | { readonly kind: 'table'; readonly schema: string; readonly table: string; readonly where?: string; readonly orderBy?: string }
+    | { readonly kind: 'query'; readonly sql: string; readonly schema?: string };
+
+interface TableTarget {
+    readonly session: string;
+    readonly schema: string;
+    readonly table: string;
+}
+
+/*
+ * Every method with its params and its result. `where` and `orderBy` are SQL as a person types it
+ * after those keywords; they reach the server as written, inside one statement. A connection opened
+ * read only stays read only, so neither can write.
+ */
+export interface DatabaseMethods {
+    open: { params: { readonly connection: ConnectionConfig }; result: { readonly session: string; readonly server: ServerInfo } };
+    close: { params: { readonly session: string }; result: null };
+    /* Opens a connection and closes it again, for a form that checks what a person filled in. */
+    test: { params: { readonly connection: ConnectionConfig }; result: { readonly server: ServerInfo } };
+    schemas: { params: { readonly session: string }; result: { readonly schemas: readonly SchemaInfo[] } };
+    tables: { params: { readonly session: string; readonly schema: string }; result: { readonly tables: readonly TableInfo[] } };
+    structure: { params: TableTarget; result: TableStructure };
+    rows: {
+        params: TableTarget & {
+            readonly where?: string;
+            readonly orderBy?: string;
+            readonly offset: number;
+            /* At most 10000. */
+            readonly limit: number;
+            /* Characters of text, or bytes of a binary value, before a cell becomes a preview. 1024 when left out. */
+            readonly cellLimit?: number;
+        };
+        result: RowsResult;
+    };
+    count: { params: TableTarget & { readonly where?: string }; result: { readonly count: number } };
+    /* The whole value of one cell, for a cell a read cut off. */
+    cell: { params: TableTarget & { readonly key: RowKey; readonly column: string }; result: { readonly value: Value } };
+    /* Every change in one transaction: all of them apply, or none does. */
+    apply: { params: TableTarget & { readonly changes: readonly RowChange[] }; result: { readonly affected: number } };
+    execute: {
+        params: {
+            readonly session: string;
+            /* One statement or several, separated by semicolons. */
+            readonly sql: string;
+            /* The schema to switch to first, which stays selected for the session. */
+            readonly schema?: string;
+            /* Rows per result, at most 10000. 500 when left out. */
+            readonly limit?: number;
+            /* As for `rows`; 65536 when left out. */
+            readonly cellLimit?: number;
+        };
+        /* `inTransaction` says whether a transaction is open after the last statement, also one the SQL itself began or ended. */
+        result: { readonly results: readonly StatementResult[]; readonly inTransaction: boolean };
+    };
+    /*
+     * One page of the rows of a single statement that reads, so a console can page through a result
+     * larger than its first page. The helper wraps the statement (`SELECT * FROM (<sql>) LIMIT .. OFFSET ..`),
+     * so a statement it cannot wrap, such as `SHOW` or `PRAGMA`, fails with `unsupported`.
+     */
+    page: {
+        params: {
+            readonly session: string;
+            readonly sql: string;
+            readonly schema?: string;
+            readonly offset: number;
+            readonly limit: number;
+            readonly cellLimit?: number;
+        };
+        result: RowsResult;
+    };
+    /*
+     * Starts, commits or rolls back a transaction the person drives. While one is open, `execute` and
+     * `apply` run inside it (an `apply` as a savepoint), and closing the session rolls it back.
+     */
+    transaction: { params: { readonly session: string; readonly action: 'begin' | 'commit' | 'rollback' }; result: { readonly active: boolean } };
+    /* Writes every row of the source to a file, streamed, so a table larger than memory still exports. */
+    export: {
+        params: {
+            readonly session: string;
+            readonly source: ExportSource;
+            readonly format: FileFormat;
+            /* An absolute path the app allowed. An existing file is replaced. */
+            readonly path: string;
+            /* For CSV and TSV: a first line with the column names. True when left out. */
+            readonly header?: boolean;
+            /* For SQL: the table name the INSERT statements use; the source table, or `result`, when left out. */
+            readonly tableName?: string;
+        };
+        result: { readonly rows: number; readonly bytes: number; readonly elapsedMs: number };
+    };
+    /* The first lines of a delimited file, so a form can map its columns before an import. */
+    sample: {
+        params: { readonly path: string; readonly format: 'csv' | 'tsv'; readonly header: boolean; readonly limit?: number };
+        result: { readonly columns: readonly string[]; readonly rows: readonly (readonly string[])[] };
+    };
+    /* Inserts every line of a delimited file in one transaction. A field that is empty, or `\N`, inserts NULL. */
+    import: {
+        params: TableTarget & {
+            readonly path: string;
+            readonly format: 'csv' | 'tsv';
+            readonly header: boolean;
+            /* The column each field of a line goes into, by position; `null` skips that field. */
+            readonly columns: readonly (string | null)[];
+        };
+        result: { readonly rows: number; readonly elapsedMs: number };
+    };
+    /* The running containers that look like database servers. */
+    discover: { params: { readonly kind: 'docker'; readonly context?: string }; result: { readonly containers: readonly DockerContainer[] } };
+    /* Stops the request with this id. Answers whether it was still running; the request itself fails with `cancelled`. */
+    cancel: { params: { readonly request: string }; result: { readonly cancelled: boolean } };
+}
+
+export type DatabaseMethod = keyof DatabaseMethods;
+
+export type DatabaseParams<M extends DatabaseMethod> = DatabaseMethods[M]['params'];
+
+export type DatabaseResult<M extends DatabaseMethod> = DatabaseMethods[M]['result'];
+
+/* A request names its own `id`, which its response repeats and a `cancel` points at. */
+export type DatabaseRequest<M extends DatabaseMethod = DatabaseMethod> = {
+    [K in M]: { readonly id: string; readonly method: K; readonly params: DatabaseParams<K> };
+}[M];
+
+export type DatabaseResponse<M extends DatabaseMethod = DatabaseMethod> =
+    | { readonly id: string; readonly ok: true; readonly result: DatabaseResult<M> }
+    | { readonly id: string; readonly ok: false; readonly error: DatabaseError };
+
+/* The first line a helper writes, before it reads a request. */
+export interface HelperReady {
+    readonly event: 'ready';
+    readonly protocol: number;
+    readonly version: string;
+}

package/src/protocol/schema.ts

@@ -0,0 +1,76 @@
+import type { ValueKind } from './values.ts';
+
+/* A schema in MySQL terms, which is a database there; SQLite has `main` and one per attached file. */
+export interface SchemaInfo {
+    readonly name: string;
+    /* A schema the server keeps for itself, such as `information_schema`; a list hides these by default. */
+    readonly system: boolean;
+}
+
+export type TableKind = 'table' | 'view';
+
+export interface TableInfo {
+    readonly name: string;
+    readonly kind: TableKind;
+    /* What the server's statistics say, which can be far off; `null` when it keeps none. */
+    readonly rowEstimate: number | null;
+    readonly comment: string | null;
+}
+
+export interface ColumnInfo {
+    readonly name: string;
+    /* The type as it was declared, such as `varchar(255)`; an SQLite column may have none, which is an empty string. */
+    readonly type: string;
+    readonly kind: ValueKind;
+    readonly nullable: boolean;
+    /* The default as an SQL expression, such as `'draft'` or `CURRENT_TIMESTAMP`. */
+    readonly defaultValue: string | null;
+    readonly autoIncrement: boolean;
+    /* A column the server computes, which an insert or an update leaves alone. */
+    readonly generated: boolean;
+    readonly comment: string | null;
+}
+
+export interface IndexInfo {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    readonly primary: boolean;
+}
+
+export interface ForeignKeyInfo {
+    /* SQLite leaves a foreign key without a name unless the DDL gives it one. */
+    readonly name: string | null;
+    readonly columns: readonly string[];
+    readonly referencedSchema: string;
+    readonly referencedTable: string;
+    readonly referencedColumns: readonly string[];
+    /* The action as SQL, such as `CASCADE`; `null` is the engine's default. */
+    readonly onUpdate: string | null;
+    readonly onDelete: string | null;
+}
+
+export interface TableStructure {
+    readonly schema: string;
+    readonly name: string;
+    readonly kind: TableKind;
+    readonly columns: readonly ColumnInfo[];
+    readonly primaryKey: readonly string[];
+    /*
+     * The columns that pick out one row for an update or a delete: the primary key, or else the first
+     * unique index over columns that cannot be null. `null` when there is neither, and the table is read only.
+     */
+    readonly rowKey: readonly string[] | null;
+    readonly indexes: readonly IndexInfo[];
+    readonly foreignKeys: readonly ForeignKeyInfo[];
+    /* The `CREATE` statement as the server writes it. */
+    readonly ddl: string | null;
+}
+
+/* A column of a result, which may come from a table or from an expression. */
+export interface ResultColumn {
+    readonly name: string;
+    /* The engine's name for the type of the value, such as `VARCHAR`; empty when it reports none. */
+    readonly type: string;
+    readonly kind: ValueKind;
+}

package/src/protocol/values.ts

@@ -0,0 +1,52 @@
+/*
+ * Every value crosses as JSON, so an app can carry it over any channel it already has. An integer
+ * beyond `Number.MAX_SAFE_INTEGER`, a decimal, a date and a time arrive as the text the server
+ * writes for them, so nothing is rounded on the way.
+ */
+
+/* Bytes as lowercase hex. */
+export interface BinaryValue {
+    readonly kind: 'binary';
+    readonly hex: string;
+}
+
+/* A whole value, as a key or an edit carries it. */
+export type Value = null | boolean | number | string | BinaryValue;
+
+/* What a cell in an edit is set to: a value, or the column's default. */
+export type EditValue = Value | { readonly kind: 'default' };
+
+/* Bytes in a result. `hex` holds the first bytes only when `length` is larger than `hex.length / 2`. */
+export interface BinaryCell {
+    readonly kind: 'binary';
+    readonly hex: string;
+    /* The size of the whole value, in bytes. */
+    readonly length: number;
+}
+
+/* Text cut off at the cell limit of the read. A cell that fits arrives as a plain string. */
+export interface LongTextCell {
+    readonly kind: 'longText';
+    readonly preview: string;
+    /* The length of the whole value, in characters. */
+    readonly length: number;
+}
+
+/* A value in a result: whole when it fits the cell limit of the read, a preview when it does not. */
+export type Cell = null | boolean | number | string | BinaryCell | LongTextCell;
+
+/* What a value is, independent of the engine's name for its type, so a grid can align and edit it. */
+export type ValueKind = 'integer' | 'decimal' | 'float' | 'boolean' | 'text' | 'binary' | 'date' | 'time' | 'datetime' | 'json' | 'other';
+
+/* The value a row key or an update can use for a cell, or `undefined` when the cell is only a preview. */
+export const valueOfCell = (cell: Cell): Value | undefined => {
+    if (cell === null || typeof cell !== 'object') {
+        return cell;
+    }
+
+    if (cell.kind === 'binary') {
+        return cell.hex.length === cell.length * 2 ? { kind: 'binary', hex: cell.hex } : undefined;
+    }
+
+    return undefined;
+};

package/src/sql-split.ts

@@ -0,0 +1,220 @@
+import type { Engine } from './protocol/index.ts';
+
+/* One piece of SQL text. Whitespace is no token; every other character is part of one. */
+export interface SqlToken {
+    readonly kind: 'word' | 'quoted' | 'comment' | 'punct' | 'semicolon';
+    /* Offsets into the text, `end` exclusive. */
+    readonly start: number;
+    readonly end: number;
+}
+
+/* A statement of a script, trimmed. `start` and `end` are offsets into the script, `end` exclusive and before the semicolon. */
+export interface SqlStatement {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+
+const WHITESPACE = /\s/;
+
+const isWordCode = (code: number): boolean =>
+    (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122) || code === 95 || code === 36 || code >= 128;
+
+const lineEnd = (text: string, at: number): number => {
+    const newline = text.indexOf('\n', at);
+    return newline === -1 ? text.length : newline + 1;
+};
+
+/* MySQL wants whitespace after the dashes; SQLite does not. */
+const startsLineComment = (text: string, at: number, engine: Engine): boolean => {
+    if (text[at] === '-' && text[at + 1] === '-') {
+        if (engine === 'sqlite') {
+            return true;
+        }
+        const next = text[at + 2];
+        return next === undefined || WHITESPACE.test(next) || next.charCodeAt(0) < 32;
+    }
+    return text[at] === '#' && engine === 'mysql';
+};
+
+/* The index after the closing quote, or the end of the text for one that never closes. */
+const quotedEnd = (text: string, at: number, engine: Engine): number => {
+    const quote = text[at]!;
+    const backslashEscapes = engine === 'mysql' && quote !== '`';
+    let i = at + 1;
+    while (i < text.length) {
+        if (backslashEscapes && text[i] === '\\') {
+            i += 2;
+        } else if (text[i] === quote) {
+            if (text[i + 1] === quote) {
+                i += 2;
+            } else {
+                return i + 1;
+            }
+        } else {
+            i += 1;
+        }
+    }
+    return text.length;
+};
+
+/* Reads SQL the way the helper's splitter does: quotes, comments and escapes decide what a semicolon is. */
+export const tokenize = (text: string, engine: Engine): SqlToken[] => {
+    const tokens: SqlToken[] = [];
+    let i = 0;
+    while (i < text.length) {
+        const char = text[i]!;
+        const code = text.charCodeAt(i);
+        if (WHITESPACE.test(char)) {
+            i += 1;
+        } else if (char === "'" || char === '"' || char === '`') {
+            const end = quotedEnd(text, i, engine);
+            tokens.push({ kind: 'quoted', start: i, end });
+            i = end;
+        } else if (char === '[' && engine === 'sqlite') {
+            const close = text.indexOf(']', i);
+            const end = close === -1 ? text.length : close + 1;
+            tokens.push({ kind: 'quoted', start: i, end });
+            i = end;
+        } else if (startsLineComment(text, i, engine)) {
+            const end = lineEnd(text, i);
+            tokens.push({ kind: 'comment', start: i, end });
+            i = end;
+        } else if (char === '/' && text[i + 1] === '*') {
+            const close = text.indexOf('*/', i + 2);
+            const end = close === -1 ? text.length : close + 2;
+            tokens.push({ kind: 'comment', start: i, end });
+            i = end;
+        } else if (char === ';') {
+            tokens.push({ kind: 'semicolon', start: i, end: i + 1 });
+            i += 1;
+        } else if (isWordCode(code)) {
+            let end = i + 1;
+            while (end < text.length && isWordCode(text.charCodeAt(end))) {
+                end += 1;
+            }
+            tokens.push({ kind: 'word', start: i, end });
+            i = end;
+        } else {
+            tokens.push({ kind: 'punct', start: i, end: i + 1 });
+            i += 1;
+        }
+    }
+    return tokens;
+};
+
+/* Follows `CREATE TRIGGER ... BEGIN ... END` so the semicolons inside its body do not end the statement. */
+class TriggerState {
+    private readonly leading: string[] = [];
+    private inBody = false;
+    private caseDepth = 0;
+    private closed = false;
+
+    word(word: string): void {
+        const upper = word.toUpperCase();
+        if (this.leading.length < 3) {
+            this.leading.push(upper);
+        }
+        if (!this.isTrigger()) {
+            return;
+        }
+        if (upper === 'BEGIN' && !this.inBody) {
+            this.inBody = true;
+        } else if (upper === 'CASE' && this.inBody) {
+            this.caseDepth += 1;
+        } else if (upper === 'END' && this.inBody) {
+            if (this.caseDepth > 0) {
+                this.caseDepth -= 1;
+            } else {
+                this.closed = true;
+            }
+        }
+    }
+
+    splitsHere(): boolean {
+        return !this.isTrigger() || !this.inBody || this.closed;
+    }
+
+    private isTrigger(): boolean {
+        const [first, second, third] = this.leading;
+        return first === 'CREATE' && (second === 'TRIGGER' || ((second === 'TEMP' || second === 'TEMPORARY') && third === 'TRIGGER'));
+    }
+}
+
+const trimmed = (text: string, from: number, to: number): SqlStatement => {
+    let start = from;
+    let end = to;
+    while (start < end && WHITESPACE.test(text[start]!)) {
+        start += 1;
+    }
+    while (end > start && WHITESPACE.test(text[end - 1]!)) {
+        end -= 1;
+    }
+    return { text: text.slice(start, end), start, end };
+};
+
+/*
+ * Splits a script at the semicolons outside strings, quoted names and comments, with the rules of the
+ * helper's splitter (`helper/src/splitter.rs`). A statement of nothing but comments is dropped, and
+ * MySQL's client-side `DELIMITER` command is not understood.
+ */
+export const splitStatements = (text: string, engine: Engine): SqlStatement[] => {
+    const statements: SqlStatement[] = [];
+    let start = 0;
+    let hasContent = false;
+    let trigger = new TriggerState();
+
+    for (const token of tokenize(text, engine)) {
+        if (token.kind === 'semicolon') {
+            if (trigger.splitsHere()) {
+                if (hasContent) {
+                    statements.push(trimmed(text, start, token.start));
+                }
+                start = token.end;
+                hasContent = false;
+                trigger = new TriggerState();
+            }
+        } else if (token.kind !== 'comment') {
+            hasContent = true;
+            if (token.kind === 'word' && engine === 'sqlite') {
+                trigger.word(text.slice(token.start, token.end));
+            }
+        }
+    }
+
+    if (hasContent) {
+        statements.push(trimmed(text, start, text.length));
+    }
+    return statements;
+};
+
+/*
+ * The statement the caret belongs to. A caret in the gap after a statement belongs to it while it
+ * stays on that line (so right after the semicolon is still that statement), and to the next one
+ * from the next line on. `null` when the text holds no statement.
+ */
+export const statementAt = (text: string, offset: number, engine: Engine): SqlStatement | null => {
+    const statements = splitStatements(text, engine);
+    for (const [index, statement] of statements.entries()) {
+        if (offset >= statement.start && offset <= statement.end) {
+            return statement;
+        }
+        const next = statements[index + 1];
+        if (offset > statement.end && (next === undefined || offset < next.start)) {
+            const gap = text.slice(statement.end, offset);
+            return gap.includes('\n') && next !== undefined ? next : statement;
+        }
+    }
+    return statements[0] ?? null;
+};
+
+/* The first word of a statement in upper case, after comments and opening parentheses. */
+export const firstKeyword = (text: string, engine: Engine): string => {
+    for (const token of tokenize(text, engine)) {
+        if (token.kind === 'comment' || (token.kind === 'punct' && text[token.start] === '(')) {
+            continue;
+        }
+        return token.kind === 'word' ? (/^[A-Za-z]*/.exec(text.slice(token.start, token.end))?.[0] ?? '').toUpperCase() : '';
+    }
+    return '';
+};