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

package/dist/sessions.d.ts

@@ -0,0 +1,59 @@
+/** What a server session is doing, from the dialect's own state (plan 045). */
+export declare const SERVER_SESSION_STATES: readonly ["active", "idle", "idleInTransaction", "blocked", "other"];
+export type ServerSessionState = (typeof SERVER_SESSION_STATES)[number];
+/**
+ * One session on the server, as `SessionMonitor.list` reads it (decision 088). Every field the
+ * dialect or the account's grants cannot supply is null.
+ */
+export interface ServerSession {
+    /** The server's id: PostgreSQL's pid, MySQL's connection id. Text, because TiDB's pass 2^53. */
+    readonly id: string;
+    /** The cluster member the session lives on, as the server names it; null on a single server. */
+    readonly instance: string | null;
+    readonly state: ServerSessionState;
+    /** The server's own words for the state, shown beside it. */
+    readonly rawState: string | null;
+    readonly user: string | null;
+    readonly database: string | null;
+    /** Client address, as the server reports it. */
+    readonly client: string | null;
+    readonly application: string | null;
+    /** How long the current or last query has run, by the server's clock when listed. */
+    readonly queryMs: number | null;
+    /** How long its open transaction has been open, by the server's clock; null when none is. */
+    readonly transactionMs: number | null;
+    readonly waitEvent: string | null;
+    /** Ids of the sessions this one waits on; null when the dialect or the grants cannot tell. */
+    readonly blockedBy: readonly string[] | null;
+    readonly query: string | null;
+    /** A server worker rather than a client connection. */
+    readonly system: boolean;
+    /** The exact statement `cancelSession` runs for it; null when cancelling it is unsupported or unsafe. */
+    readonly cancel: string | null;
+    /** The exact statement `terminateSession` runs for it; null when terminating it is unsupported or unsafe. */
+    readonly terminate: string | null;
+}
+export interface SessionListing {
+    readonly sessions: readonly ServerSession[];
+    /** What the listing leaves out and why, such as a missing grant, with the grant to ask for. */
+    readonly notes: readonly string[];
+}
+/** Which session `cancelSession` and `terminateSession` act on: a listed row's `id` and `instance`. */
+export interface SessionTarget {
+    readonly id: string;
+    readonly instance: string | null;
+}
+/**
+ * The server's sessions, read and stopped by the plugin's own SQL (decisions 008, 088). Calls
+ * queue on the session they hang off, like the introspector's.
+ */
+export interface SessionMonitor {
+    list(): Promise<SessionListing>;
+    /**
+     * Interrupts the target's running statement and leaves it connected. Rejects with
+     * `statementFailed` when the server refuses, the target is gone, or it cannot be reached safely.
+     */
+    cancelSession(target: SessionTarget): Promise<void>;
+    /** Ends the target's connection; rejects as `cancelSession` does. */
+    terminateSession(target: SessionTarget): Promise<void>;
+}

package/dist/sessions.js

@@ -0,0 +1,2 @@
+/** What a server session is doing, from the dialect's own state (plan 045). */
+export const SERVER_SESSION_STATES = ["active", "idle", "idleInTransaction", "blocked", "other"];

package/dist/sql/classify.d.ts

@@ -0,0 +1,19 @@
+import type { StatementClass } from "@tablecraft-app/plugin-api";
+import { type SqlDialectOptions } from "./tokens.js";
+/** Prefixes the explained statement's destructive reason, so the confirmation says why it matters. */
+export declare const EXPLAIN_ANALYZE_REASON_PREFIX = "EXPLAIN ANALYZE runs it: ";
+/**
+ * A token-level classifier plugins may build `SqlLanguage.classify` on (decision 023). The first
+ * keyword picks the kind; `UPDATE` or `DELETE` without a top-level `WHERE`, `DROP` and `TRUNCATE`
+ * are destructive (decision 011). `EXPLAIN` is a read unless it analyses, which runs the statement,
+ * so `EXPLAIN ANALYZE` takes the statement's kind and destructive reason (decision 031). It never
+ * parses, so it never rejects a statement.
+ */
+export declare function classifyTokens(sql: string, options?: SqlDialectOptions): StatementClass;
+export type TransactionEffect = "begin" | "end";
+/**
+ * Whether a statement opens or ends a transaction, for plugins that track `Transactions.open` in
+ * auto mode: `BEGIN` and `START TRANSACTION` open one; `COMMIT`, `ROLLBACK` (not `ROLLBACK TO`),
+ * `END`, `ABORT` and `PREPARE TRANSACTION` end it. Null for anything else.
+ */
+export declare function transactionEffect(sql: string, options?: SqlDialectOptions): TransactionEffect | null;

package/dist/sql/classify.js

@@ -0,0 +1,95 @@
+import { namespaceTarget } from "./namespace.js";
+import { significantTokens } from "./tokens.js";
+import { explainPrefix, mainVerb, words } from "./words.js";
+const KINDS = new Map([
+    ...["SELECT", "SHOW", "EXPLAIN", "DESCRIBE", "DESC", "VALUES", "TABLE"].map((word) => [word, "read"]),
+    ...["INSERT", "UPDATE", "DELETE", "MERGE", "REPLACE", "UPSERT", "COPY", "LOAD"].map((word) => [word, "write"]),
+    ...["CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME", "COMMENT"].map((word) => [word, "ddl"]),
+    ...["BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "RELEASE", "END", "ABORT"].map((word) => [word, "transaction"]),
+]);
+const START = "START";
+const TRANSACTION = "TRANSACTION";
+const WHERE = "WHERE";
+const LIMIT = "LIMIT";
+const WITH = "WITH";
+/** Prefixes the explained statement's destructive reason, so the confirmation says why it matters. */
+export const EXPLAIN_ANALYZE_REASON_PREFIX = "EXPLAIN ANALYZE runs it: ";
+function hasTopLevel(list, from, word) {
+    return list.some((entry, at) => at > from && entry.depth === 0 && entry.word === word);
+}
+function destructiveReason(list, verbAt) {
+    const verb = list[verbAt]?.word;
+    switch (verb) {
+        case "DELETE":
+            if (hasTopLevel(list, verbAt, WHERE))
+                return null;
+            return hasTopLevel(list, verbAt, LIMIT)
+                ? "DELETE without WHERE (LIMIT does not choose the rows)"
+                : "DELETE without WHERE";
+        case "UPDATE":
+            return hasTopLevel(list, verbAt, WHERE) ? null : "UPDATE without WHERE";
+        case "DROP": {
+            const object = list[verbAt + 1]?.word;
+            return object === undefined ? "DROP" : `DROP ${object}`;
+        }
+        case "TRUNCATE":
+            return "TRUNCATE";
+        default:
+            return null;
+    }
+}
+/**
+ * A token-level classifier plugins may build `SqlLanguage.classify` on (decision 023). The first
+ * keyword picks the kind; `UPDATE` or `DELETE` without a top-level `WHERE`, `DROP` and `TRUNCATE`
+ * are destructive (decision 011). `EXPLAIN` is a read unless it analyses, which runs the statement,
+ * so `EXPLAIN ANALYZE` takes the statement's kind and destructive reason (decision 031). It never
+ * parses, so it never rejects a statement.
+ */
+export function classifyTokens(sql, options = {}) {
+    const statementClass = classifyWords(words(sql, significantTokens(sql, options)));
+    return namespaceTarget(sql, options) === null ? statementClass : { ...statementClass, setsNamespace: true };
+}
+function classifyWords(list) {
+    const first = list[0]?.word;
+    if (first === undefined)
+        return { kind: "other", destructive: null };
+    if (first === START) {
+        return { kind: list[1]?.word === TRANSACTION ? "transaction" : "other", destructive: null };
+    }
+    const explain = explainPrefix(list);
+    if (explain !== null) {
+        if (!explain.analyze)
+            return { kind: "read", destructive: null };
+        const inner = classifyWords(list.slice(explain.statementAt));
+        return {
+            kind: inner.kind,
+            destructive: inner.destructive === null ? null : `${EXPLAIN_ANALYZE_REASON_PREFIX}${inner.destructive}`,
+        };
+    }
+    const verbAt = mainVerb(list);
+    const verb = list[verbAt]?.word ?? first;
+    const kind = first === WITH && verbAt === 0 ? "read" : (KINDS.get(verb) ?? "other");
+    return { kind, destructive: destructiveReason(list, verbAt) };
+}
+const ENDS = new Set(["COMMIT", "END", "ABORT"]);
+const ROLLBACK = "ROLLBACK";
+const TO = "TO";
+const PREPARE = "PREPARE";
+/**
+ * Whether a statement opens or ends a transaction, for plugins that track `Transactions.open` in
+ * auto mode: `BEGIN` and `START TRANSACTION` open one; `COMMIT`, `ROLLBACK` (not `ROLLBACK TO`),
+ * `END`, `ABORT` and `PREPARE TRANSACTION` end it. Null for anything else.
+ */
+export function transactionEffect(sql, options = {}) {
+    const list = words(sql, significantTokens(sql, options)).map((entry) => entry.word);
+    const [first, second] = list;
+    if (first === "BEGIN" || (first === START && second === TRANSACTION))
+        return "begin";
+    if (first !== undefined && ENDS.has(first))
+        return "end";
+    if (first === PREPARE && second === TRANSACTION)
+        return "end";
+    if (first === ROLLBACK)
+        return list.includes(TO) ? null : "end";
+    return null;
+}

package/dist/sql/complete.d.ts

@@ -0,0 +1,23 @@
+import type { SqlLanguage } from "@tablecraft-app/plugin-api";
+import { type FunctionSpec, type ServerIdentity } from "./functions.js";
+import { type IdentifierFolding } from "./resolution.js";
+import type { SqlDialectOptions } from "./tokens.js";
+export type { IdentifierFolding } from "./resolution.js";
+/** What the shared completer needs to know about a dialect (decision 028). */
+export interface CompleterOptions {
+    readonly dialect: SqlDialectOptions;
+    readonly identifierFolding: IdentifierFolding;
+    /** A name the dialect reads back unchanged without quotes; any other is quoted when inserted. */
+    readonly plainIdentifier: RegExp;
+    readonly quoteIdentifier: (name: string) => string;
+    /** Offered where a keyword fits; a name that spells one is quoted. Upper case. */
+    readonly keywords: readonly string[];
+    /** Built-in functions; a spec brings its signatures, summary and server range (decision 097). */
+    readonly functions: readonly (string | FunctionSpec)[];
+    /** Reads the catalog's server version into the flavour and version the specs' ranges name; null when it cannot. */
+    readonly server?: (version: string) => ServerIdentity | null;
+}
+/** Reserved words every built-in dialect shares; a plugin adds its own. */
+export declare const SQL_KEYWORDS: readonly string[];
+/** The shared completion and navigation every built-in plugin spreads into its `SqlLanguage` (decision 028). */
+export declare function sqlCompleter(options: CompleterOptions): Pick<SqlLanguage, "complete" | "resolve"> & Required<Pick<SqlLanguage, "selectSource" | "signatureAt">>;