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

package/dist/testing/index.d.ts

@@ -0,0 +1,274 @@
+import { z, type DatasourcePlugin, type KeyChange, type KeyContents, type KeyType, type PluginManifest, type Routine, type RoutineArgument, type Row, type ServerMessage } from "@tablecraft-app/plugin-api";
+export interface ContractFixture {
+    /** The plugin's parsed `table-craft-plugin.json`, whose connection form the suite checks. */
+    readonly manifest: PluginManifest;
+    /** Configuration that connects to a reachable, writable database seeded with `TYPE_PROBE_TABLE`. */
+    readonly config: unknown;
+    /** The same database with a wrong password; omitted by plugins that do not authenticate. */
+    readonly wrongPasswordConfig?: unknown;
+    readonly statements?: {
+        /** A statement that runs for `seconds`; required when the plugin declares `cancel`. */
+        readonly sleep?: (seconds: number) => string;
+        /**
+         * A write that succeeds on a writable session and leaves the fixture unchanged, such as an
+         * update setting a column to itself; the read-only case is skipped without one.
+         */
+        readonly write?: string;
+        /**
+         * A statement the server answers with a warning or notice, and the level and code of the
+         * first one; required when the plugin declares `serverMessages`.
+         */
+        readonly message?: {
+            readonly sql: string;
+            readonly level: ServerMessage["level"];
+            readonly code: string | null;
+        };
+        /**
+         * A statement with a syntax error and the 0-based offset the plugin's `PluginError.position`
+         * must resolve to; leave it out for a database that cannot locate one.
+         */
+        readonly syntaxError?: {
+            readonly sql: string;
+            readonly offset: number;
+        };
+    };
+    /** Required when the plugin declares `sql`. */
+    readonly typeProbe?: {
+        /** The rows of `SELECT * FROM type_probe ORDER BY id`, as wire values. */
+        readonly expected: readonly Row[];
+        /**
+         * Creates `TYPE_PROBE_COPY_TABLE` with `type_probe`'s columns and declared types; the literal
+         * round trip creates and drops it. `CREATE TABLE … AS` will not do where it drops declared types.
+         */
+        readonly copyTable: string;
+    };
+    /** Scripts only this dialect splits, and the statements `language.split` must find in each. */
+    readonly scripts?: readonly SplitCase[];
+    /** Required when the plugin declares `schemaTree`. */
+    readonly catalog?: {
+        /** The namespace the fixture tables live in, which is also the connection's current one. */
+        readonly path: readonly string[];
+        /** An identifier that needs quoting, and what `qualifiedName(path, name)` must return for it. */
+        readonly quoted: {
+            readonly name: string;
+            readonly qualified: string;
+        };
+        /** `LINE_ITEMS_TABLE` as the dialect writes it in a statement, which completion must insert. */
+        readonly lineItems: string;
+        /** The name `orders`' check constraint carries, which its definition must show. */
+        readonly ordersCheck: string;
+        /** `customers`' table comment; null where the dialect has no comments. */
+        readonly customersComment: string | null;
+    };
+    /** Required when the plugin declares `currentNamespace`, which also needs `catalog`. */
+    readonly namespaceSwitch?: {
+        /** A statement that makes another namespace current, such as `USE archive`. */
+        readonly statement: string;
+        /** The path `currentNamespace` reports after it. */
+        readonly path: readonly string[];
+        /** A switch to a namespace that does not exist, where the dialect rejects one. */
+        readonly missing?: string;
+    };
+    /** Required when the plugin declares `commands` (decision 112). */
+    readonly commands?: CommandsFixture;
+    /** Required when the plugin declares `keyValue` (decision 113). */
+    readonly keyspace?: KeyspaceFixture;
+    /**
+     * Required when the plugin declares `sessions`, which also needs `statements.sleep`, and
+     * `statements.write` where it declares `transactions`.
+     */
+    readonly sessions?: {
+        /** Connects as an account that sees every session and may stop any, such as a superuser. */
+        readonly monitorConfig: unknown;
+        /** What a listing shows as the sleeping statement's query; the statement itself by default. */
+        readonly sleepQuery?: string;
+        /** An account that sees only its own sessions, and what the listing's note must say about it. */
+        readonly limited?: {
+            readonly config: unknown;
+            readonly note: RegExp;
+        };
+    };
+    /** Required when the plugin declares `routineCall`, which also needs `catalog`. */
+    readonly routines?: {
+        /** Every routine the fixture seeds in `catalog.path`, as `describe` lists them. */
+        readonly expected: readonly Routine[];
+        /** A function given values, and the rows its call returns. */
+        readonly function: RoutineCase;
+        /** A call with one argument NULL, which must bind as SQL NULL. */
+        readonly nullArgument: RoutineCase;
+        /** A procedure whose OUT values come back as the last statement's rows. */
+        readonly procedureOut: RoutineCase;
+        /** A call that leaves a parameter to its default; omitted where the dialect has no defaults. */
+        readonly defaulted?: RoutineCase;
+    };
+    /** The statements whose text differs by dialect; each defaults to the text PostgreSQL, MySQL and SQLite accept. */
+    readonly sql?: ContractSql;
+    /**
+     * How the database stores an unquoted fixture name, such as Oracle's upper case; identity by
+     * default. `LINE_ITEMS_TABLE` is quoted in every dialect and never folded.
+     */
+    readonly foldName?: (name: string) => string;
+}
+/** Dialect-specific text the suite runs; every member is optional (decision 100). */
+export interface ContractSql {
+    /** A one-row query of `expressions`; Oracle adds `FROM DUAL`. */
+    readonly select?: (expressions: string) => string;
+    /** At least 100,000 rows; built from `select` by default. */
+    readonly largeResult?: string;
+    /** A join over `orders` and `customers` that plans with more than one step. */
+    readonly explainJoin?: string;
+    /** Replaces the scripts every other dialect splits the same way. */
+    readonly sharedScripts?: readonly SplitCase[];
+    /** Drops table `name` where it exists and does nothing where it does not. */
+    readonly dropTableIfExists?: (name: string) => string;
+    /** Creates a session-scoped table from `name`, and the name later statements reach it by. */
+    readonly temporaryTable?: (name: string, columns: string) => {
+        readonly create: string;
+        readonly name: string;
+    };
+    /** Opens a transaction explicitly in auto-commit mode. */
+    readonly begin?: string;
+}
+/** A command and the result tab it opens: column names and rows as wire values. */
+export interface CommandRows {
+    readonly command: string;
+    readonly columns: readonly string[];
+    readonly rows: readonly Row[];
+}
+/** What a `commands` plugin's console runs against the fixture database (decision 112). */
+export interface CommandsFixture {
+    /** Scripts the language splits, and the commands it must find in each. */
+    readonly scripts: readonly SplitCase[];
+    /** A command answered with one scalar, and the text Output shows for the reply. */
+    readonly scalar: {
+        readonly command: string;
+        readonly text: string;
+    };
+    /** A command answered with an array. */
+    readonly array: CommandRows;
+    /** A command answered with a map. */
+    readonly map: CommandRows;
+    /** A command answering bytes that are not UTF-8, and those bytes in hex. */
+    readonly binary: {
+        readonly command: string;
+        readonly hex: string;
+    };
+    /** A write a read-only session refuses, and the command name the refusal carries. */
+    readonly write: {
+        readonly command: string;
+        readonly name: string;
+    };
+    /** A command classified costly, and the text of the first quick fix its problem offers. */
+    readonly costly: {
+        readonly command: string;
+        readonly fixed: string;
+    };
+    /** A command classified destructive and confirmed by the datasource's name. */
+    readonly confirmByName: string;
+}
+/** The keys a `keyValue` plugin's fixture database carries (decision 113). */
+export interface KeyspaceFixture {
+    /** The database the fixture keys live in. */
+    readonly database: number;
+    /** A glob, and how many keys it matches: enough for many scan batches. */
+    readonly scan: {
+        readonly match: string;
+        readonly count: number;
+        readonly batch: number;
+    };
+    /** A glob and a type, and the names of the keys of that type it matches. */
+    readonly typed: {
+        readonly match: string;
+        readonly type: KeyType;
+        readonly keys: readonly string[];
+    };
+    /** A key with an expiry. */
+    readonly expiring: string;
+    /** A key whose name is not valid UTF-8, as lower-case hex, a glob that finds it, and its value. */
+    readonly binary: {
+        readonly hex: string;
+        readonly match: string;
+        readonly type: KeyType;
+        readonly value: string;
+    };
+    /** A hash key and its first two columns' rows, in any order. */
+    readonly hash: KeyRowsFixture;
+    /** A sorted-set key and its member and score cells, in rank order. */
+    readonly zset: KeyRowsFixture;
+    /** A stream key, its columns and its rows, in id order. */
+    readonly stream: KeyRowsFixture & {
+        readonly columns: readonly string[];
+    };
+    /** A scratch key the suite creates, changes and removes. */
+    readonly edit: KeyEditFixture;
+}
+/** How the suite changes one element of a scratch key and reads it back (decision 115). */
+export interface KeyEditFixture {
+    readonly key: string;
+    readonly type: KeyType;
+    /** A change setting the element to `value`, read as `original` (null: it did not exist). */
+    readonly change: (value: string, original: string | null) => KeyChange;
+    /** The element's value in what `read` returned; null when it is missing. */
+    readonly valueOf: (contents: KeyContents) => Promise<string | null>;
+}
+/** A key and the rows reading it gives. */
+export interface KeyRowsFixture {
+    readonly key: string;
+    readonly rows: readonly Row[];
+}
+/** One routine call: which routine (from `routines.expected`), its arguments, and the rows it returns. */
+export interface RoutineCase {
+    readonly name: string;
+    readonly kind: Routine["kind"];
+    readonly signature: string;
+    readonly args: readonly RoutineArgument[];
+    readonly rows: readonly Row[];
+}
+export interface SplitCase {
+    readonly text: string;
+    readonly statements: readonly string[];
+}
+/** The table every fixture database carries, one column per value rule the contract pins. */
+export declare const TYPE_PROBE_TABLE = "type_probe";
+/** Where the literal round trip inserts `type_probe`'s rows; created and dropped by the suite. */
+export declare const TYPE_PROBE_COPY_TABLE = "type_probe_copy";
+export declare const TYPE_PROBE_COLUMNS: readonly ["id", "small_int", "big_int", "exact_decimal", "unicode_text", "flag", "doc", "payload", "day", "moment"];
+/** A fixture table whose name needs quoting in every dialect, for completion's quoting. */
+export declare const LINE_ITEMS_TABLE = "Line Items";
+/** The relations every fixture database carries, sorted by name as `describe` returns them. */
+export declare const FIXTURE_RELATIONS: readonly [{
+    readonly name: "customer_totals";
+    readonly kind: "view";
+}, {
+    readonly name: "customers";
+    readonly kind: "table";
+}, {
+    readonly name: "orders";
+    readonly kind: "table";
+}, {
+    readonly name: "edit_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "no_key_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "type_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "Line Items";
+    readonly kind: "table";
+}];
+/** The data editor's table (decision 026): a serial key and a default for every other column. */
+export declare const EDIT_PROBE_TABLE = "edit_probe";
+/** The statements the suite runs for `fixture`, each default filled in. */
+export declare function contractSql(fixture: Pick<ContractFixture, "sql">): Required<ContractSql>;
+/**
+ * Where a manifest's connection form and the plugin's `connectionSchema` disagree (decision 019),
+ * one sentence per problem; empty when they agree.
+ */
+export declare function connectionFormProblems(manifest: PluginManifest, connectionSchema: z.ZodType): string[];
+/**
+ * The behaviour every plugin owes the host, gated on the capabilities it declares (decision 013).
+ * Call it from a Vitest file; it registers one `describe` block.
+ */
+export declare function runPluginContract(plugin: DatasourcePlugin, fixture: ContractFixture): void;