@adecore/database 0.0.1 → 0.16.0-beta.0

package/dist/protocol/index.d.ts

@@ -0,0 +1,5 @@
+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/dist/protocol/index.js

@@ -0,0 +1,3 @@
+/* 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 { PROTOCOL_VERSION } from './messages.js';
+export { valueOfCell } from './values.js';

package/dist/protocol/messages.d.ts

@@ -0,0 +1,250 @@
+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';
+export declare const PROTOCOL_VERSION = 2;
+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[])[];
+    readonly hasMore: boolean;
+    readonly elapsedMs: number;
+}
+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;
+};
+export type FileFormat = 'csv' | 'tsv' | 'json' | 'sql';
+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;
+}
+export interface DatabaseMethods {
+    open: {
+        params: {
+            readonly connection: ConnectionConfig;
+        };
+        result: {
+            readonly session: string;
+            readonly server: ServerInfo;
+        };
+    };
+    close: {
+        params: {
+            readonly session: string;
+        };
+        result: null;
+    };
+    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;
+            readonly limit: number;
+            readonly cellLimit?: number;
+        };
+        result: RowsResult;
+    };
+    count: {
+        params: TableTarget & {
+            readonly where?: string;
+        };
+        result: {
+            readonly count: number;
+        };
+    };
+    cell: {
+        params: TableTarget & {
+            readonly key: RowKey;
+            readonly column: string;
+        };
+        result: {
+            readonly value: Value;
+        };
+    };
+    apply: {
+        params: TableTarget & {
+            readonly changes: readonly RowChange[];
+        };
+        result: {
+            readonly affected: number;
+        };
+    };
+    execute: {
+        params: {
+            readonly session: string;
+            readonly sql: string;
+            readonly schema?: string;
+            readonly limit?: number;
+            readonly cellLimit?: number;
+        };
+        result: {
+            readonly results: readonly StatementResult[];
+            readonly inTransaction: boolean;
+        };
+    };
+    page: {
+        params: {
+            readonly session: string;
+            readonly sql: string;
+            readonly schema?: string;
+            readonly offset: number;
+            readonly limit: number;
+            readonly cellLimit?: number;
+        };
+        result: RowsResult;
+    };
+    transaction: {
+        params: {
+            readonly session: string;
+            readonly action: 'begin' | 'commit' | 'rollback';
+        };
+        result: {
+            readonly active: boolean;
+        };
+    };
+    export: {
+        params: {
+            readonly session: string;
+            readonly source: ExportSource;
+            readonly format: FileFormat;
+            readonly path: string;
+            readonly header?: boolean;
+            readonly tableName?: string;
+        };
+        result: {
+            readonly rows: number;
+            readonly bytes: number;
+            readonly elapsedMs: number;
+        };
+    };
+    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[])[];
+        };
+    };
+    import: {
+        params: TableTarget & {
+            readonly path: string;
+            readonly format: 'csv' | 'tsv';
+            readonly header: boolean;
+            readonly columns: readonly (string | null)[];
+        };
+        result: {
+            readonly rows: number;
+            readonly elapsedMs: number;
+        };
+    };
+    discover: {
+        params: {
+            readonly kind: 'docker';
+            readonly context?: string;
+        };
+        result: {
+            readonly containers: readonly DockerContainer[];
+        };
+    };
+    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'];
+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;
+};
+export interface HelperReady {
+    readonly event: 'ready';
+    readonly protocol: number;
+    readonly version: string;
+}
+export {};

package/dist/protocol/messages.js

@@ -0,0 +1,2 @@
+/* Raised whenever a message changes shape, so a host refuses a helper from another release. */
+export const PROTOCOL_VERSION = 2;

package/dist/protocol/schema.d.ts

@@ -0,0 +1,53 @@
+import type { ValueKind } from './values.ts';
+export interface SchemaInfo {
+    readonly name: string;
+    readonly system: boolean;
+}
+export type TableKind = 'table' | 'view';
+export interface TableInfo {
+    readonly name: string;
+    readonly kind: TableKind;
+    readonly rowEstimate: number | null;
+    readonly comment: string | null;
+}
+export interface ColumnInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly kind: ValueKind;
+    readonly nullable: boolean;
+    readonly defaultValue: string | null;
+    readonly autoIncrement: boolean;
+    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 {
+    readonly name: string | null;
+    readonly columns: readonly string[];
+    readonly referencedSchema: string;
+    readonly referencedTable: string;
+    readonly referencedColumns: readonly string[];
+    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[];
+    readonly rowKey: readonly string[] | null;
+    readonly indexes: readonly IndexInfo[];
+    readonly foreignKeys: readonly ForeignKeyInfo[];
+    readonly ddl: string | null;
+}
+export interface ResultColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly kind: ValueKind;
+}

package/dist/protocol/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/protocol/values.d.ts

@@ -0,0 +1,21 @@
+export interface BinaryValue {
+    readonly kind: 'binary';
+    readonly hex: string;
+}
+export type Value = null | boolean | number | string | BinaryValue;
+export type EditValue = Value | {
+    readonly kind: 'default';
+};
+export interface BinaryCell {
+    readonly kind: 'binary';
+    readonly hex: string;
+    readonly length: number;
+}
+export interface LongTextCell {
+    readonly kind: 'longText';
+    readonly preview: string;
+    readonly length: number;
+}
+export type Cell = null | boolean | number | string | BinaryCell | LongTextCell;
+export type ValueKind = 'integer' | 'decimal' | 'float' | 'boolean' | 'text' | 'binary' | 'date' | 'time' | 'datetime' | 'json' | 'other';
+export declare const valueOfCell: (cell: Cell) => Value | undefined;

package/dist/protocol/values.js

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+/* 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) => {
+    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/dist/sql-split.d.ts

@@ -0,0 +1,15 @@
+import type { Engine } from './protocol/index.ts';
+export interface SqlToken {
+    readonly kind: 'word' | 'quoted' | 'comment' | 'punct' | 'semicolon';
+    readonly start: number;
+    readonly end: number;
+}
+export interface SqlStatement {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+export declare const tokenize: (text: string, engine: Engine) => SqlToken[];
+export declare const splitStatements: (text: string, engine: Engine) => SqlStatement[];
+export declare const statementAt: (text: string, offset: number, engine: Engine) => SqlStatement | null;
+export declare const firstKeyword: (text: string, engine: Engine) => string;

package/dist/sql-split.js

@@ -0,0 +1,201 @@
+const WHITESPACE = /\s/;
+const isWordCode = (code) => (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122) || code === 95 || code === 36 || code >= 128;
+const lineEnd = (text, at) => {
+    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, at, engine) => {
+    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, at, engine) => {
+    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, engine) => {
+    const tokens = [];
+    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 {
+    leading = [];
+    inBody = false;
+    caseDepth = 0;
+    closed = false;
+    word(word) {
+        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() {
+        return !this.isTrigger() || !this.inBody || this.closed;
+    }
+    isTrigger() {
+        const [first, second, third] = this.leading;
+        return first === 'CREATE' && (second === 'TRIGGER' || ((second === 'TEMP' || second === 'TEMPORARY') && third === 'TRIGGER'));
+    }
+}
+const trimmed = (text, from, to) => {
+    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, engine) => {
+    const statements = [];
+    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, offset, engine) => {
+    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, engine) => {
+    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 '';
+};

package/dist/sql.d.ts

@@ -0,0 +1,29 @@
+import type { Cell, Engine, Value, ValueKind } from './protocol/index.ts';
+export type SortDirection = 'asc' | 'desc';
+export interface ColumnSort {
+    readonly column: string;
+    readonly direction: SortDirection;
+}
+export interface SqlTarget {
+    readonly engine: Engine;
+    readonly table: string;
+    readonly schema?: string;
+}
+export type LiteralValue = Cell | Value | {
+    readonly kind: 'default';
+};
+export declare const quoteIdentifier: (engine: Engine, name: string) => string;
+export declare const qualifiedName: (target: SqlTarget) => string;
+export declare const sqlLiteral: (engine: Engine, value: LiteralValue, kind?: ValueKind) => string;
+export declare const equalsCondition: (engine: Engine, column: string, value: LiteralValue, kind?: ValueKind) => string;
+export declare const notEqualsCondition: (engine: Engine, column: string, value: LiteralValue, kind?: ValueKind) => string;
+export interface ColumnMatch {
+    readonly column: string;
+    readonly value: LiteralValue;
+    readonly kind?: ValueKind;
+}
+export declare const matchCondition: (engine: Engine, matches: readonly ColumnMatch[]) => string;
+export declare const orderByClause: (engine: Engine, sorts: readonly ColumnSort[]) => string;
+export declare const parseOrderBy: (engine: Engine, text: string, columns: readonly string[]) => ColumnSort[] | null;
+export declare const parseOrderByLoose: (engine: Engine, text: string) => ColumnSort[] | null;
+export declare const findColumn: (engine: Engine, word: string, columns: readonly string[]) => string | undefined;