@tablecraft-app/plugin-api 0.0.0-stage → 1.2.0

package/dist/sql/layoutWriter.d.ts

@@ -0,0 +1,21 @@
+import { type Tok } from "./layoutNodes.js";
+/**
+ * Text built line by line with the column it has reached. A line comment forces the next token
+ * onto a new line at `indent`, the column the current layout continues at.
+ */
+export declare class Writer {
+    #private;
+    out: string;
+    column: number;
+    indent: number;
+    constructor(column: number);
+    /** The text ends in a line comment, so nothing may follow it on its line. */
+    get endsInLineComment(): boolean;
+    newline(column?: number): void;
+    pad(width: number): void;
+    /** `text` (one token, or a comment that may span lines), a space before it when asked and the line has text. */
+    write(text: string, spaceBefore: boolean): void;
+    tok(tok: Tok, text: string, spaceBefore: boolean): void;
+    /** A comment on a line of its own. */
+    comment(comment: string, column: number): void;
+}

package/dist/sql/layoutWriter.js

@@ -0,0 +1,77 @@
+import { isLineComment } from "./layoutNodes.js";
+const LINE_BREAK = "\n";
+const SPACE = " ";
+/**
+ * Text built line by line with the column it has reached. A line comment forces the next token
+ * onto a new line at `indent`, the column the current layout continues at.
+ */
+export class Writer {
+    out = "";
+    column;
+    indent;
+    #content = false;
+    #pendingBreak = false;
+    constructor(column) {
+        this.column = column;
+        this.indent = column;
+    }
+    /** The text ends in a line comment, so nothing may follow it on its line. */
+    get endsInLineComment() {
+        return this.#pendingBreak;
+    }
+    newline(column = this.indent) {
+        this.#pendingBreak = false;
+        const lineStart = this.out.lastIndexOf(LINE_BREAK) + 1;
+        if (!this.#content) {
+            if (lineStart === 0)
+                return;
+            this.out = this.out.slice(0, lineStart) + SPACE.repeat(column);
+        }
+        else {
+            this.out += LINE_BREAK + SPACE.repeat(column);
+        }
+        this.column = column;
+        this.#content = false;
+    }
+    pad(width) {
+        if (width <= 0)
+            return;
+        this.out += SPACE.repeat(width);
+        this.column += width;
+    }
+    /** `text` (one token, or a comment that may span lines), a space before it when asked and the line has text. */
+    write(text, spaceBefore) {
+        if (this.#pendingBreak)
+            this.newline();
+        else if (spaceBefore && this.#content)
+            this.#append(SPACE);
+        this.#append(text);
+    }
+    tok(tok, text, spaceBefore) {
+        for (const comment of tok.leading) {
+            if (this.#content)
+                this.newline();
+            this.#append(comment);
+            this.newline();
+        }
+        this.write(text, spaceBefore);
+        for (const comment of tok.trailing) {
+            this.#append(SPACE + comment);
+            if (isLineComment(comment))
+                this.#pendingBreak = true;
+        }
+    }
+    /** A comment on a line of its own. */
+    comment(comment, column) {
+        this.newline(column);
+        this.#append(comment);
+        if (isLineComment(comment))
+            this.#pendingBreak = true;
+    }
+    #append(text) {
+        this.out += text;
+        const lineBreak = text.lastIndexOf(LINE_BREAK);
+        this.column = lineBreak < 0 ? this.column + text.length : text.length - lineBreak - 1;
+        this.#content = true;
+    }
+}

package/dist/sql/literals.d.ts

@@ -0,0 +1,28 @@
+import type { SavepointStatements, WireValue } from "@tablecraft-app/plugin-api";
+/** How a dialect spells what the shared literal writer cannot decide for it. */
+export interface SqlLiteralOptions {
+    /** `'` doubled is standard; MySQL also needs backslashes escaped unless `NO_BACKSLASH_ESCAPES` is set. */
+    readonly backslashEscapes: boolean;
+    /** A bytes literal from lower-case hex, such as `X'dead'` or `'\xdead'::bytea`. */
+    readonly bytes: (hex: string) => string;
+    /** Text holding a non-ASCII character is written `N'…'`, which SQL Server and Oracle need to keep it whole. */
+    readonly nationalText?: boolean;
+}
+export type IdentifierQuote = '"' | "`" | "[";
+/**
+ * Quotes an identifier with `quote`, doubling the closing quote inside it: `"a""b"`, `` `a``b` ``
+ * or SQL Server's `[a]]b]`.
+ */
+export declare function quoteIdentifierWith(quote: IdentifierQuote): (name: string) => string;
+/** The standard savepoint statements, which PostgreSQL, MySQL and SQLite all accept (plan 026). */
+export declare function sqlSavepoints(quoteIdentifier: (name: string) => string): (name: string) => SavepointStatements;
+/** The standard insert of a row made only of defaults, which PostgreSQL and SQLite accept. */
+export declare function defaultValuesInsert(qualifiedTable: string): string;
+/** `DEFAULT` inside `SET`, which PostgreSQL and MySQL accept. */
+export declare function defaultKeyword(): string;
+/**
+ * A literal any of the three built-in dialects reads back as the same value. Decimals, dates and
+ * JSON travel as text (decision 017), so they are written as strings and the column's type
+ * converts them; `columnType` is accepted for dialects that need a cast.
+ */
+export declare function sqlLiteral(value: WireValue, options: SqlLiteralOptions): string;

package/dist/sql/literals.js

@@ -0,0 +1,78 @@
+const CLOSING_QUOTE = { '"': '"', "`": "`", "[": "]" };
+/**
+ * Quotes an identifier with `quote`, doubling the closing quote inside it: `"a""b"`, `` `a``b` ``
+ * or SQL Server's `[a]]b]`.
+ */
+export function quoteIdentifierWith(quote) {
+    const close = CLOSING_QUOTE[quote];
+    return (name) => `${quote}${name.replaceAll(close, close + close)}${close}`;
+}
+/** The standard savepoint statements, which PostgreSQL, MySQL and SQLite all accept (plan 026). */
+export function sqlSavepoints(quoteIdentifier) {
+    return (name) => {
+        const quoted = quoteIdentifier(name);
+        return {
+            set: `SAVEPOINT ${quoted}`,
+            rollback: `ROLLBACK TO SAVEPOINT ${quoted}`,
+            release: `RELEASE SAVEPOINT ${quoted}`,
+        };
+    };
+}
+/** The standard insert of a row made only of defaults, which PostgreSQL and SQLite accept. */
+export function defaultValuesInsert(qualifiedTable) {
+    return `INSERT INTO ${qualifiedTable} DEFAULT VALUES`;
+}
+/** `DEFAULT` inside `SET`, which PostgreSQL and MySQL accept. */
+export function defaultKeyword() {
+    return "DEFAULT";
+}
+const BACKSLASH_ESCAPES = new Map([
+    ["\\", "\\\\"],
+    ["'", "\\'"],
+    ["\0", "\\0"],
+    ["\n", "\\n"],
+    ["\r", "\\r"],
+    ["\u001a", "\\Z"],
+]);
+const NATIONAL_PREFIX = "N";
+const NON_ASCII = /[\u0080-\uffff]/;
+function quoteString(text, options) {
+    const prefix = options.nationalText === true && NON_ASCII.test(text) ? NATIONAL_PREFIX : "";
+    if (options.backslashEscapes) {
+        return `${prefix}'${Array.from(text, (char) => BACKSLASH_ESCAPES.get(char) ?? char).join("")}'`;
+    }
+    return `${prefix}'${text.replaceAll("'", "''")}'`;
+}
+const BYTES_PER_HEX_DIGIT = 0.5;
+/**
+ * A literal any of the three built-in dialects reads back as the same value. Decimals, dates and
+ * JSON travel as text (decision 017), so they are written as strings and the column's type
+ * converts them; `columnType` is accepted for dialects that need a cast.
+ */
+export function sqlLiteral(value, options) {
+    if (value === null)
+        return "NULL";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "TRUE" : "FALSE";
+        case "number":
+            return Number.isFinite(value) ? String(value) : quoteString(String(value), options);
+        case "string":
+            return quoteString(value, options);
+        default:
+            break;
+    }
+    switch (value.kind) {
+        case "bigint":
+            return value.value;
+        case "json":
+            return quoteString(value.text, options);
+        case "date":
+            return quoteString(value.iso, options);
+        case "bytes": {
+            const literal = options.bytes(value.preview);
+            const shown = value.preview.length * BYTES_PER_HEX_DIGIT;
+            return shown < value.length ? `${literal} /* ${String(shown)} of ${String(value.length)} bytes */` : literal;
+        }
+    }
+}

package/dist/sql/namespace.d.ts

@@ -0,0 +1,41 @@
+import { type NamespaceSwitch } from "@tablecraft-app/plugin-api";
+import { type Identifier } from "./scope.js";
+import { type NamespaceStatementForm, type SqlDialectOptions } from "./tokens.js";
+/** Where a session-namespace statement points unqualified names. */
+export interface NamespaceTarget {
+    readonly kind: "database" | "schema";
+    /** In the order the statement lists them; empty for `DEFAULT` and `RESET`, which restore the server's setting. */
+    readonly candidates: readonly Identifier[];
+}
+/** The caret's place in a session-namespace statement's target list. */
+export interface NamespaceSlot {
+    readonly kind: NamespaceTarget["kind"];
+    /** What accepting an item replaces; inside a quote it starts after the quote. */
+    readonly from: number;
+    readonly to: number;
+    /** The quote the caret is inside, and whether the name already closes it. */
+    readonly quote: {
+        readonly char: string;
+        readonly closed: boolean;
+    } | null;
+    /** The names the statement lists before the caret's. */
+    readonly listed: readonly Identifier[];
+}
+/**
+ * Where the caret at `offset` names a namespace a session-namespace statement of the dialect moves
+ * to: `USE |` or the elements of `SET search_path TO a, |` and `SET SCHEMA |`. Null anywhere else,
+ * and after a name whose closing quote is typed.
+ */
+export declare function namespaceSlotAt(text: string, offset: number, dialect: SqlDialectOptions): NamespaceSlot | null;
+/**
+ * Whether `sql` is a statement that moves the session's current namespace in a dialect declaring
+ * `namespaceStatements`, and where it points. It never asks the server, so a named namespace may
+ * not exist; the session's `currentNamespace()` is the truth once the statement ran.
+ */
+export declare function namespaceTarget(sql: string, dialect: SqlDialectOptions): NamespaceTarget | null;
+/**
+ * The console's namespace switch for a dialect moving its namespace by `form` (decision 060):
+ * `USE db`, or a search path of exactly the one schema, so nothing unqualified resolves in a schema
+ * the console's label does not show. Only the search path is undone by a rollback.
+ */
+export declare function namespaceSwitcher(form: NamespaceStatementForm, quoteIdentifier: (name: string) => string): NamespaceSwitch;

package/dist/sql/namespace.js

@@ -0,0 +1,220 @@
+import { PluginError } from "@tablecraft-app/plugin-api";
+import { closingQuote, unquote } from "./scope.js";
+import { Lexer, significantTokens, wordOf, } from "./tokens.js";
+const USE = "USE";
+const SET = "SET";
+const RESET = "RESET";
+const SET_SCOPES = new Set(["SESSION", "LOCAL"]);
+const SEARCH_PATH = "SEARCH_PATH";
+const SCHEMA = "SCHEMA";
+const ALL = "ALL";
+const ASSIGNMENTS = new Set(["TO", "="]);
+const DEFAULT = "DEFAULT";
+const LIST_SEPARATOR = ",";
+const STRING_QUOTE = "'";
+const BLOCK_COMMENT_END = "*/";
+function identifier(text, token) {
+    if (token === undefined)
+        return null;
+    const raw = text.slice(token.from, token.to);
+    const { from, to } = token;
+    if (token.kind === "word")
+        return { name: raw, quoted: false, from, to };
+    if (token.kind === "quoted")
+        return { name: unquote(raw), quoted: true, from, to };
+    // search_path quotes each element (GUC_LIST_QUOTE), so a string element is an exact name.
+    if (token.kind === "string" && raw.startsWith(STRING_QUOTE))
+        return { name: unquote(raw), quoted: true, from, to };
+    return null;
+}
+function wordAt(text, tokens, at) {
+    const token = tokens[at];
+    if (token === undefined)
+        return undefined;
+    return token.kind === "word" || token.kind === "symbol" ? wordOf(text, token) : undefined;
+}
+function useTarget(text, tokens) {
+    if (tokens.length !== 2 || wordAt(text, tokens, 0) !== USE)
+        return null;
+    const name = identifier(text, tokens[1]);
+    return name === null || tokens[1]?.kind === "string" ? null : { kind: "database", candidates: [name] };
+}
+/** `a, "b", 'c'` from `at` to the end; null when it is not such a list. */
+function list(text, tokens, at) {
+    const names = [];
+    for (let index = at; index < tokens.length; index += 2) {
+        const name = identifier(text, tokens[index]);
+        if (name === null)
+            return null;
+        names.push(name);
+        const separator = tokens[index + 1];
+        if (separator !== undefined && wordAt(text, tokens, index + 1) !== LIST_SEPARATOR)
+            return null;
+        if (separator !== undefined && index + 2 >= tokens.length)
+            return null;
+    }
+    return names.length === 0 ? null : names;
+}
+function searchPathTarget(text, tokens) {
+    const first = wordAt(text, tokens, 0);
+    if (first === RESET) {
+        const what = wordAt(text, tokens, 1);
+        return tokens.length === 2 && (what === SEARCH_PATH || what === ALL) ? { kind: "schema", candidates: [] } : null;
+    }
+    if (first !== SET)
+        return null;
+    let at = SET_SCOPES.has(wordAt(text, tokens, 1) ?? "") ? 2 : 1;
+    const parameter = wordAt(text, tokens, at);
+    at += 1;
+    if (parameter === SEARCH_PATH) {
+        if (!ASSIGNMENTS.has(wordAt(text, tokens, at) ?? ""))
+            return null;
+        at += 1;
+    }
+    else if (parameter !== SCHEMA) {
+        return null;
+    }
+    if (tokens.length === at + 1 && tokens[at]?.kind === "word" && wordAt(text, tokens, at) === DEFAULT) {
+        return { kind: "schema", candidates: [] };
+    }
+    const names = list(text, tokens, at);
+    if (names === null || (parameter === SCHEMA && names.length !== 1))
+        return null;
+    return { kind: "schema", candidates: names };
+}
+const NAME_TOKENS = new Set(["word", "quoted", "string"]);
+/** The statement's tokens around `offset`, comments dropped; null when the caret is in a comment. */
+function tokensAround(text, offset, dialect) {
+    const lexer = new Lexer(text, dialect);
+    let tokens = [];
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        if (token.kind === "comment") {
+            if (token.from < offset && offset < token.to)
+                return null;
+            if (offset === token.to && !text.slice(token.from, token.to).endsWith(BLOCK_COMMENT_END))
+                return null;
+            continue;
+        }
+        if (token.kind === "delimiter") {
+            if (token.to <= offset)
+                tokens = [];
+            else if (token.from >= offset)
+                break;
+            continue;
+        }
+        tokens.push(token);
+    }
+    return tokens;
+}
+function closes(raw) {
+    return raw.length >= 2 && raw.endsWith(closingQuote(raw.charAt(0)));
+}
+/** The names of `name , name ,` from `at` to the end; null when the tokens are not such a list. */
+function listedBefore(text, tokens, at) {
+    if ((tokens.length - at) % 2 !== 0)
+        return null;
+    const names = [];
+    for (let index = at; index < tokens.length; index += 2) {
+        const name = identifier(text, tokens[index]);
+        if (name === null || wordAt(text, tokens, index + 1) !== LIST_SEPARATOR)
+            return null;
+        names.push(name);
+    }
+    return names;
+}
+function searchPathListStart(text, tokens) {
+    if (wordAt(text, tokens, 0) !== SET)
+        return null;
+    let at = SET_SCOPES.has(wordAt(text, tokens, 1) ?? "") ? 2 : 1;
+    const parameter = wordAt(text, tokens, at);
+    at += 1;
+    if (parameter === SCHEMA)
+        return { at, single: true };
+    if (parameter !== SEARCH_PATH || !ASSIGNMENTS.has(wordAt(text, tokens, at) ?? ""))
+        return null;
+    return { at: at + 1, single: false };
+}
+/**
+ * Where the caret at `offset` names a namespace a session-namespace statement of the dialect moves
+ * to: `USE |` or the elements of `SET search_path TO a, |` and `SET SCHEMA |`. Null anywhere else,
+ * and after a name whose closing quote is typed.
+ */
+export function namespaceSlotAt(text, offset, dialect) {
+    const forms = dialect.namespaceStatements ?? [];
+    if (forms.length === 0)
+        return null;
+    const tokens = tokensAround(text, offset, dialect);
+    if (tokens === null)
+        return null;
+    const touched = tokens.findIndex((token) => token.from < offset && offset <= token.to);
+    const prefix = touched >= 0 && NAME_TOKENS.has(tokens[touched]?.kind ?? "symbol") ? tokens[touched] : undefined;
+    const before = tokens.filter((token) => (prefix === undefined ? token.to <= offset : token.to <= prefix.from));
+    let from = prefix?.from ?? offset;
+    let quote = null;
+    if (prefix !== undefined && prefix.kind !== "word") {
+        const raw = text.slice(prefix.from, prefix.to);
+        const char = raw.charAt(0);
+        if (prefix.kind === "string" && char !== STRING_QUOTE)
+            return null;
+        const closed = closes(raw);
+        if (closed && offset === prefix.to)
+            return null;
+        quote = { char, closed };
+        from = prefix.from + char.length;
+    }
+    for (const form of forms) {
+        if (form === "use") {
+            if (prefix?.kind === "string" || before.length !== 1 || wordAt(text, before, 0) !== USE)
+                continue;
+            return { kind: "database", from, to: offset, quote, listed: [] };
+        }
+        const start = searchPathListStart(text, before);
+        if (start === null)
+            continue;
+        if (start.single && before.length !== start.at)
+            continue;
+        const listed = listedBefore(text, before, start.at);
+        if (listed !== null)
+            return { kind: "schema", from, to: offset, quote, listed };
+    }
+    return null;
+}
+/**
+ * Whether `sql` is a statement that moves the session's current namespace in a dialect declaring
+ * `namespaceStatements`, and where it points. It never asks the server, so a named namespace may
+ * not exist; the session's `currentNamespace()` is the truth once the statement ran.
+ */
+export function namespaceTarget(sql, dialect) {
+    const forms = dialect.namespaceStatements ?? [];
+    if (forms.length === 0)
+        return null;
+    const tokens = significantTokens(sql, dialect).filter((token) => token.kind !== "delimiter");
+    for (const form of forms) {
+        const target = form === "use" ? useTarget(sql, tokens) : searchPathTarget(sql, tokens);
+        if (target !== null)
+            return target;
+    }
+    return null;
+}
+const SWITCH_TARGETS = {
+    use: "topLevel",
+    searchPath: "schema",
+};
+/**
+ * The console's namespace switch for a dialect moving its namespace by `form` (decision 060):
+ * `USE db`, or a search path of exactly the one schema, so nothing unqualified resolves in a schema
+ * the console's label does not show. Only the search path is undone by a rollback.
+ */
+export function namespaceSwitcher(form, quoteIdentifier) {
+    return {
+        targets: SWITCH_TARGETS[form],
+        transactional: form === "searchPath",
+        statement(path) {
+            const name = path.at(-1);
+            if (name === undefined) {
+                throw new PluginError("statementFailed", "A namespace switch names no namespace; pick one from the list.");
+            }
+            return form === "use" ? `USE ${quoteIdentifier(name)}` : `SET search_path TO ${quoteIdentifier(name)}`;
+        },
+    };
+}

package/dist/sql/objects.d.ts

@@ -0,0 +1,42 @@
+import { PluginError, type CheckDesign, type ColumnDesign, type DdlScript, type ForeignKeyDesign, type IndexDesign, type Relation, type TableDesign } from "@tablecraft-app/plugin-api";
+/** The referential actions a design may name, as SQL spells them. */
+export declare const REFERENTIAL_ACTIONS: readonly ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
+/** A failure the user fixes in the dialog, so the host shows it as the dialog's error. */
+export declare function designError(message: string): PluginError;
+/**
+ * The design of a described table (decision 052). `columnDefault` turns the catalog's default into
+ * the expression a `DEFAULT` clause takes, for a dialect whose catalog stores it otherwise.
+ */
+export declare function tableDesignOf(relation: Relation, columnDefault?: (column: Relation["columns"][number]) => string | null): TableDesign;
+/** Throws a `designError` naming the first thing in `design` no dialect can create. */
+export declare function validateDesign(design: TableDesign): void;
+/** What an `alterTable` changes, each part matched by its `original` name. */
+export interface TableDifference {
+    readonly renamedTo: string | null;
+    readonly commentChanged: boolean;
+    readonly droppedColumns: readonly ColumnDesign[];
+    readonly addedColumns: readonly ColumnDesign[];
+    /** A column whose name or definition differs; `before` is as the table has it now. */
+    readonly changedColumns: readonly {
+        readonly before: ColumnDesign;
+        readonly after: ColumnDesign;
+    }[];
+    readonly primaryKeyChanged: boolean;
+    readonly droppedIndexes: readonly IndexDesign[];
+    readonly addedIndexes: readonly IndexDesign[];
+    readonly droppedForeignKeys: readonly ForeignKeyDesign[];
+    readonly addedForeignKeys: readonly ForeignKeyDesign[];
+    readonly droppedChecks: readonly CheckDesign[];
+    readonly addedChecks: readonly CheckDesign[];
+}
+/** Whether a column's definition, everything but its name, differs. */
+export declare function columnChanged(before: ColumnDesign, after: ColumnDesign): boolean;
+export declare function tableDifference(before: TableDesign, after: TableDesign): TableDifference;
+/** Whether a difference holds no change at all. */
+export declare function unchanged(difference: TableDifference): boolean;
+/** A script of `statements` with nothing around them. */
+export declare function ddlScript(statements: readonly string[], options: Partial<Omit<DdlScript, "statements">> & Pick<DdlScript, "transactional">): DdlScript;
+/** `NOTHING_TO_CHANGE` is the note an alter without a difference carries, so the dialog can say so. */
+export declare const NOTHING_TO_CHANGE = "The design matches the table; there is nothing to run.";
+/** The `REFERENCES` tail of a foreign key, actions only where they differ from the default. */
+export declare function referencesClause(key: ForeignKeyDesign, qualifiedTarget: string, name: (identifier: string) => string): string;