@tablecraft-app/plugin-api 1.1.0 → 1.2.0

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { z, type DatasourcePlugin, type PluginManifest, type Routine, type RoutineArgument, type Row, type ServerMessage } from "@tablecraft-app/plugin-api";
+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;
@@ -32,7 +32,8 @@ export interface ContractFixture {
             readonly offset: number;
         };
     };
-    readonly typeProbe: {
+    /** 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[];
         /**
@@ -68,10 +69,19 @@ export interface ContractFixture {
         /** A switch to a namespace that does not exist, where the dialect rejects one. */
         readonly missing?: string;
     };
-    /** Required when the plugin declares `sessions`, which also needs `statements.sleep` and `write`. */
+    /** 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;
@@ -119,6 +129,93 @@ export interface ContractSql {
     /** 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;

package/dist/testing/index.js

@@ -122,6 +122,10 @@ export function contractSql(fixture) {
 const ROWS_READ_BEFORE_RETURN = 3;
 /** Longer than `BYTES_PREVIEW_LENGTH` and within every fixture's `payload` column (MySQL's is `VARBINARY(64)`). */
 const LONG_BYTES_LENGTH = 48;
+/** Stops a scan pass that never ends, so a broken cursor fails rather than hangs. */
+const MAX_SCAN_BATCHES = 10_000;
+const READ_WINDOW = 100;
+const SLOW_LOG_LIMIT = 5;
 const LONG_BYTES_HEX = "c3";
 const HEX_DIGITS_PER_BYTE = 2;
 /** Created and dropped by the import-type case. */
@@ -182,6 +186,16 @@ async function collect(rows) {
         collected.push(row);
     return collected;
 }
+function typeProbeOf(fixture) {
+    if (fixture.typeProbe === undefined)
+        throw new Error("A plugin that declares sql needs fixture.typeProbe.");
+    return fixture.typeProbe;
+}
+function commandsOf(fixture) {
+    if (fixture.commands === undefined)
+        throw new Error("A plugin that declares commands needs fixture.commands.");
+    return fixture.commands;
+}
 function catalogPathOf(fixture) {
     if (fixture.catalog === undefined)
         throw new Error("A plugin that declares schemaTree needs fixture.catalog.");
@@ -316,6 +330,15 @@ export function runPluginContract(plugin, fixture) {
     const fold = (name) => (name === LINE_ITEMS_TABLE ? name : (fixture.foldName?.(name) ?? name));
     const selectOne = dialectSql.select("1 AS one");
     const dropIfExists = dialectSql.dropTableIfExists;
+    /** Shows `session` still answers: a one-row SELECT, or the fixture's scalar command. */
+    async function expectAlive(session) {
+        if (plugin.capabilities.includes("commands")) {
+            const { command, text } = commandsOf(fixture).scalar;
+            expect((await session.execute(command)).reply?.text).toBe(text);
+            return;
+        }
+        expect(await collect((await session.execute(selectOne)).rows)).toEqual([[1]]);
+    }
     describe(`plugin contract: ${plugin.id}`, () => {
         it("givenPlugin_whenInspected_thenDeclaresOnlyKnownCapabilities", () => {
             for (const capability of plugin.capabilities)
@@ -346,6 +369,28 @@ export function runPluginContract(plugin, fixture) {
         it("givenPlugin_whenInspected_thenHasLanguageExactlyWhenSqlDeclared", () => {
             expect(plugin.language !== undefined).toBe(plugin.capabilities.includes("sql"));
         });
+        it("givenPlugin_whenInspected_thenHasCommandLanguageExactlyWhenCommandsDeclared", () => {
+            const commands = plugin.capabilities.includes("commands");
+            if (commands)
+                expect(plugin.capabilities).not.toContain("sql");
+            expect(plugin.commandLanguage !== undefined).toBe(commands);
+        });
+        it("givenSession_whenInspected_thenHasKeyspaceExactlyWhenKeyValueDeclared", async () => {
+            const keyValue = plugin.capabilities.includes("keyValue");
+            if (keyValue)
+                expect(plugin.capabilities).toContain("commands");
+            await withSession(plugin, fixture, (session) => {
+                expect(session.keyspace !== undefined).toBe(keyValue);
+                return Promise.resolve();
+            });
+        });
+        it("givenSession_whenInspected_thenHasNodesAndServerInfoExactlyWhenDeclared", async () => {
+            await withSession(plugin, fixture, (session) => {
+                expect(session.nodes !== undefined).toBe(plugin.capabilities.includes("nodes"));
+                expect(session.serverInfo !== undefined).toBe(plugin.capabilities.includes("serverInfo"));
+                return Promise.resolve();
+            });
+        });
         it("givenSession_whenInspected_thenHasTransactionsExactlyWhenDeclared", async () => {
             await withSession(plugin, fixture, (session) => {
                 expect(session.transactions !== undefined).toBe(plugin.capabilities.includes("transactions"));
@@ -412,8 +457,10 @@ export function runPluginContract(plugin, fixture) {
         });
         it("givenSession_whenInspected_thenHasSessionMonitorExactlyWhenSessionsDeclared", async () => {
             const declared = plugin.capabilities.includes("sessions");
-            if (declared)
-                expect(plugin.capabilities).toContain("sql");
+            if (declared) {
+                expect(plugin.capabilities.includes("sql") || plugin.capabilities.includes("commands")).toBe(true);
+                expect(plugin.capabilities.includes("schemaTree") || plugin.capabilities.includes("keyValue")).toBe(true);
+            }
             await withSession(plugin, fixture, (session) => {
                 expect(session.sessions !== undefined).toBe(declared);
                 expect(typeof session.serverSessionId === "string").toBe(declared);
@@ -492,7 +539,7 @@ export function runPluginContract(plugin, fixture) {
                 await withSession(plugin, fixture, async (session) => {
                     const result = await session.execute(`SELECT * FROM ${TYPE_PROBE_TABLE} ORDER BY id`);
                     expect(result.columns.map((column) => column.name)).toEqual(TYPE_PROBE_COLUMNS.map(fold));
-                    expect(await collect(result.rows)).toEqual(fixture.typeProbe.expected);
+                    expect(await collect(result.rows)).toEqual(typeProbeOf(fixture).expected);
                 });
             });
             describe("bound parameters", () => {
@@ -575,7 +622,7 @@ export function runPluginContract(plugin, fixture) {
                 it("givenTimestamp_whenSelected_thenTextIsUnshiftedByClientTimeZone", async () => {
                     const momentColumn = TYPE_PROBE_COLUMNS.indexOf("moment");
                     const dayColumn = TYPE_PROBE_COLUMNS.indexOf("day");
-                    const expected = fixture.typeProbe.expected.find((row) => row[0] === PROBE_ROW_ID);
+                    const expected = typeProbeOf(fixture).expected.find((row) => row[0] === PROBE_ROW_ID);
                     await withSession(plugin, fixture, async (session) => {
                         const result = await session.execute(`SELECT day, moment FROM ${TYPE_PROBE_TABLE} WHERE id = ${PROBE_ROW_ID}`);
                         expect(await collect(result.rows)).toEqual([[expected?.[dayColumn], expected?.[momentColumn]]]);
@@ -644,13 +691,13 @@ export function runPluginContract(plugin, fixture) {
                     const rows = await collect(source.rows);
                     const names = source.columns.map((column) => dialect.quoteIdentifier(column.name)).join(", ");
                     await run(session, dropIfExists(TYPE_PROBE_COPY_TABLE));
-                    await run(session, fixture.typeProbe.copyTable);
+                    await run(session, typeProbeOf(fixture).copyTable);
                     try {
                         for (const row of rows) {
                             const values = row.map((value, index) => dialect.literal(value, source.columns[index]?.type ?? null));
                             await run(session, `INSERT INTO ${dialect.quoteIdentifier(fold(TYPE_PROBE_COPY_TABLE))} (${names}) VALUES (${values.join(", ")})`);
                         }
-                        expect(await run(session, `SELECT * FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(fixture.typeProbe.expected);
+                        expect(await run(session, `SELECT * FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(typeProbeOf(fixture).expected);
                     }
                     finally {
                         await run(session, dropIfExists(TYPE_PROBE_COPY_TABLE));
@@ -666,7 +713,7 @@ export function runPluginContract(plugin, fixture) {
                     const payloadType = probe.columns[1]?.type ?? null;
                     await collect(probe.rows);
                     await run(session, dropIfExists(TYPE_PROBE_COPY_TABLE));
-                    await run(session, fixture.typeProbe.copyTable);
+                    await run(session, typeProbeOf(fixture).copyTable);
                     try {
                         const payload = dialect.literal({ kind: "bytes", preview: whole, length: LONG_BYTES_LENGTH }, payloadType);
                         await run(session, `INSERT INTO ${dialect.quoteIdentifier(fold(TYPE_PROBE_COPY_TABLE))} (id, payload) VALUES (${PROBE_ROW_ID}, ${payload})`);
@@ -759,7 +806,7 @@ export function runPluginContract(plugin, fixture) {
             /** The copy table as the engine targets it: named and typed by the introspector. */
             async function copyTarget(session) {
                 await run(session, dropIfExists(TYPE_PROBE_COPY_TABLE));
-                await run(session, fixture.typeProbe.copyTable);
+                await run(session, typeProbeOf(fixture).copyTable);
                 const introspector = session.introspector;
                 if (introspector === undefined) {
                     const probe = await session.execute(`SELECT * FROM ${TYPE_PROBE_COPY_TABLE}`);
@@ -788,9 +835,9 @@ export function runPluginContract(plugin, fixture) {
             }
             it("givenBulkInsert_whenTypeProbeTextInserted_thenReadBackEqual", async () => {
                 await withCopy(async (session, target) => {
-                    const rows = fixture.typeProbe.expected.map((row) => row.map(exportedText));
+                    const rows = typeProbeOf(fixture).expected.map((row) => row.map(exportedText));
                     await insertRowsOf(session)(target, rows);
-                    expect(await run(session, `SELECT * FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(fixture.typeProbe.expected);
+                    expect(await run(session, `SELECT * FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(typeProbeOf(fixture).expected);
                 });
             });
             it("givenBulkInsert_whenBatchRefused_thenNothingOfItAndTransactionUsable", async () => {
@@ -1770,6 +1817,265 @@ export function runPluginContract(plugin, fixture) {
                 });
             });
         });
+        describe.runIf(plugin.capabilities.includes("commands"))("commands", () => {
+            function language() {
+                if (plugin.commandLanguage === undefined)
+                    throw new Error("A plugin that declares commands has no commandLanguage.");
+                return plugin.commandLanguage;
+            }
+            async function rowsOf(command, session) {
+                const result = await session.execute(command);
+                return { columns: result.columns.map((column) => column.name), rows: await collect(result.rows) };
+            }
+            it("givenCommands_whenSplit_thenOneSpanPerLineSkippingComments", () => {
+                for (const script of commandsOf(fixture).scripts) {
+                    const spans = language().split(script.text);
+                    expect(spans.map((span) => span.sql)).toEqual(script.statements);
+                    for (const span of spans)
+                        expect(script.text.slice(span.from, span.to)).toBe(span.sql);
+                }
+            });
+            it("givenScalarCommand_whenExecute_thenReplyAndNoColumns", async () => {
+                const { command, text } = commandsOf(fixture).scalar;
+                await withSession(plugin, fixture, async (session) => {
+                    const result = await session.execute(command);
+                    expect(result.reply?.text).toBe(text);
+                    expect(result.columns).toEqual([]);
+                    expect(await collect(result.rows)).toEqual([]);
+                });
+            });
+            it("givenArrayCommand_whenExecute_thenIndexValueRows", async () => {
+                const { command, columns, rows } = commandsOf(fixture).array;
+                await withSession(plugin, fixture, async (session) => {
+                    expect(await rowsOf(command, session)).toEqual({ columns, rows });
+                });
+            });
+            it("givenMapReply_whenExecute_thenKeyValueRows", async () => {
+                const { command, columns, rows } = commandsOf(fixture).map;
+                await withSession(plugin, fixture, async (session) => {
+                    expect(await rowsOf(command, session)).toEqual({ columns, rows });
+                });
+            });
+            it("givenBinaryValue_whenExecute_thenBytesValue", async () => {
+                const { command, hex } = commandsOf(fixture).binary;
+                await withSession(plugin, fixture, async (session) => {
+                    const result = await session.execute(command, [], { fullBytes: true });
+                    expect(result.reply?.value).toEqual({
+                        kind: "bytes",
+                        preview: hex,
+                        length: hex.length / HEX_DIGITS_PER_BYTE,
+                    });
+                });
+            });
+            it("givenReadOnly_whenWriteCommand_thenStatementFailedNamingIt", async () => {
+                const { command, name } = commandsOf(fixture).write;
+                await withSession(plugin, fixture, async (session) => {
+                    const failure = await session.execute(command).then(() => undefined, (error) => error);
+                    expect(isPluginError(failure) ? failure.code : failure).toBe("statementFailed");
+                    expect(failure instanceof Error ? failure.message : "").toContain(name);
+                }, READ_ONLY);
+            });
+            it("givenFlushdb_whenClassify_thenDestructiveConfirmByName", () => {
+                const classified = language().classify(commandsOf(fixture).confirmByName);
+                expect(classified.destructive).not.toBeNull();
+                expect(classified.confirmByName).toBe(true);
+            });
+            it("givenKeysPattern_whenClassify_thenCostlyWithScanFix", async () => {
+                const { command, fixed } = commandsOf(fixture).costly;
+                expect(language().classify(command).costly).toMatch(/\S/);
+                const problems = (await language().inspect?.({ text: command })) ?? [];
+                const fix = problems[0]?.fixes[0];
+                expect(fix).toBeDefined();
+                let text = command;
+                for (const edit of [...(fix?.edits ?? [])].sort((a, b) => b.from - a.from)) {
+                    text = text.slice(0, edit.from) + edit.insert + text.slice(edit.to);
+                }
+                expect(text).toBe(fixed);
+            });
+            it("givenCommand_whenComplete_thenNeverRejects", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    for (const text of ["", "h", "HGET ", '"unterminated', "# only a comment"]) {
+                        const result = await language().complete({ text, offset: text.length }, session);
+                        expect(result.from).toBeLessThanOrEqual(text.length);
+                    }
+                    const offline = await language().complete({ text: "h", offset: 1 }, null);
+                    expect(offline.to).toBe(1);
+                });
+            });
+        });
+        describe.runIf(plugin.capabilities.includes("keyValue"))("keyValue", () => {
+            function keyspaceFixture() {
+                if (fixture.keyspace === undefined)
+                    throw new Error("keyValue needs fixture.keyspace");
+                return fixture.keyspace;
+            }
+            function keyspaceOf(session) {
+                if (session.keyspace === undefined)
+                    throw new Error("keyValue needs session.keyspace");
+                return session.keyspace;
+            }
+            /** Every key of one pass, and how many batches it took. */
+            async function scanAll(keyspace, request) {
+                const keys = [];
+                let cursor = null;
+                let batches = 0;
+                do {
+                    const scan = await keyspace.scan({
+                        database: keyspaceFixture().database,
+                        cursor,
+                        match: request.match,
+                        type: request.type ?? null,
+                        ...(request.count === undefined ? {} : { count: request.count }),
+                    });
+                    keys.push(...scan.keys);
+                    cursor = scan.cursor;
+                    batches += 1;
+                } while (cursor !== null && batches < MAX_SCAN_BATCHES);
+                expect(cursor).toBeNull();
+                return { keys, batches };
+            }
+            it("givenKeyspace_whenDatabases_thenFixtureDatabaseCountedAndOneCurrent", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const databases = await keyspaceOf(session).databases();
+                    const own = databases.find((database) => database.index === keyspaceFixture().database);
+                    expect(own?.keys).toBeGreaterThanOrEqual(keyspaceFixture().scan.count);
+                    expect(databases.filter((database) => database.current)).toHaveLength(1);
+                    expect(keyspaceOf(session).delimiter).not.toBe("");
+                });
+            });
+            it("givenKeyspace_whenScanToEnd_thenEveryFixtureKeyOnceAndCursorNull", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { match, count, batch } = keyspaceFixture().scan;
+                    const { keys, batches } = await scanAll(keyspaceOf(session), { match, count: batch });
+                    const names = keys.map((key) => key.text);
+                    expect(new Set(names).size).toBe(count);
+                    expect(names).toHaveLength(count);
+                    expect(batches).toBeGreaterThan(1);
+                });
+            });
+            it("givenMatchAndType_whenScan_thenOnlyMatchingKeys", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { match, type, keys } = keyspaceFixture().typed;
+                    const found = await scanAll(keyspaceOf(session), { match, type });
+                    expect(found.keys.map((key) => key.text).sort()).toEqual([...keys].sort());
+                });
+            });
+            it("givenKeys_whenDescribe_thenTypeExpiryAndMissingInOrder", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { typed, expiring, database } = keyspaceFixture();
+                    const [first = ""] = typed.keys;
+                    const names = [first, expiring, "table-craft:contract:missing"];
+                    const infos = await keyspaceOf(session).describe(database, names.map((text) => ({ text, hex: null })));
+                    expect(infos.map((info) => info.key.text)).toEqual(names);
+                    expect(infos[0]).toMatchObject({ type: typed.type, ttlMs: null });
+                    expect(infos[1]?.ttlMs).toBeGreaterThan(0);
+                    expect(infos[2]).toMatchObject({ type: null, typeName: null, ttlMs: null });
+                });
+            });
+            it("givenBinaryKeyName_whenScanAndRead_thenHexRoundTrips", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { binary, database } = keyspaceFixture();
+                    const found = await scanAll(keyspaceOf(session), { match: binary.match });
+                    const key = found.keys.find((candidate) => candidate.hex === binary.hex);
+                    expect(key?.text).toMatch(/\\x[0-9a-f]{2}/);
+                    if (key === undefined)
+                        return;
+                    const [info] = await keyspaceOf(session).describe(database, [key]);
+                    expect(info?.type).toBe(binary.type);
+                    const contents = await keyspaceOf(session).read(database, key, { window: READ_WINDOW });
+                    expect(contents.details.key).toEqual(key);
+                    expect(contents.value).toBe(binary.value);
+                });
+            });
+            /** The key's rows, each cut to its first `width` cells. */
+            async function readRows(session, key, width) {
+                const contents = await keyspaceOf(session).read(keyspaceFixture().database, { text: key, hex: null }, { window: READ_WINDOW });
+                if (contents.result === null)
+                    throw new Error(`${key} read no rows`);
+                const rows = await collect(contents.result.rows);
+                return {
+                    contents,
+                    columns: contents.result.columns.map((column) => column.name),
+                    rows: rows.map((row) => row.slice(0, width)),
+                };
+            }
+            it("givenHash_whenRead_thenFieldValueRows", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { hash } = keyspaceFixture();
+                    const read = await readRows(session, hash.key, 2);
+                    expect(read.columns.slice(0, 2)).toEqual(["field", "value"]);
+                    const sorted = (rows) => [...rows].sort((a, b) => JSON.stringify(a[0]).localeCompare(JSON.stringify(b[0])));
+                    expect(sorted(read.rows)).toEqual(sorted(hash.rows));
+                    expect(read.contents.details).toMatchObject({ type: "hash", length: hash.rows.length });
+                });
+            });
+            it("givenZset_whenRead_thenMemberScoreRowsInRankOrder", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { zset } = keyspaceFixture();
+                    const read = await readRows(session, zset.key, 3);
+                    expect(read.columns).toEqual(["#", "member", "score"]);
+                    expect(read.rows.map((row) => row.slice(1))).toEqual(zset.rows);
+                    expect(read.rows.map((row) => row[0])).toEqual(zset.rows.map((_, index) => index));
+                });
+            });
+            it("givenStream_whenRead_thenIdAndFieldColumns", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const { stream } = keyspaceFixture();
+                    const read = await readRows(session, stream.key, stream.columns.length);
+                    expect(read.columns).toEqual(stream.columns);
+                    expect(read.rows).toEqual(stream.rows);
+                });
+            });
+            it("givenMissingKey_whenRead_thenNoTypeAndNoContents", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const contents = await keyspaceOf(session).read(keyspaceFixture().database, { text: "table-craft:contract:missing", hex: null }, { window: READ_WINDOW });
+                    expect(contents).toMatchObject({ details: { type: null }, result: null, value: null });
+                });
+            });
+            /** Runs `use` with the scratch key removed before and after. */
+            async function withScratchKey(use) {
+                const { database, edit } = keyspaceFixture();
+                const key = { text: edit.key, hex: null };
+                await withSession(plugin, fixture, async (session) => {
+                    const keyspace = keyspaceOf(session);
+                    await keyspace.remove(database, [key]);
+                    try {
+                        await use(keyspace, {
+                            set: (value, original, guard) => keyspace.apply(database, key, [edit.change(value, original)], { type: edit.type, guard }),
+                            value: async () => edit.valueOf(await keyspace.read(database, key, { window: READ_WINDOW })),
+                        });
+                    }
+                    finally {
+                        await keyspace.remove(database, [key]);
+                    }
+                });
+            }
+            it("givenChange_whenApply_thenValueWritten", async () => {
+                await withScratchKey(async (keyspace, scratch) => {
+                    const { edit } = keyspaceFixture();
+                    const applied = await scratch.set("one", null, true);
+                    expect(await scratch.value()).toBe("one");
+                    const options = { type: edit.type, guard: true };
+                    expect(applied.commands).toEqual(keyspace.preview({ text: edit.key, hex: null }, [edit.change("one", null)], options));
+                });
+            });
+            it("givenChangedSinceRead_whenApplyGuarded_thenConflictAndNothingWritten", async () => {
+                await withScratchKey(async (_keyspace, scratch) => {
+                    await scratch.set("one", null, true);
+                    await scratch.set("two", "one", false);
+                    expect(await rejectionCode(scratch.set("three", "one", true))).toBe("conflict");
+                    expect(await scratch.value()).toBe("two");
+                });
+            });
+            it("givenChangedSinceRead_whenApplyUnguarded_thenWritten", async () => {
+                await withScratchKey(async (_keyspace, scratch) => {
+                    await scratch.set("one", null, true);
+                    await scratch.set("two", "one", false);
+                    await scratch.set("three", "one", false);
+                    expect(await scratch.value()).toBe("three");
+                });
+            });
+        });
         describe.runIf(plugin.capabilities.includes("cancel"))("cancel", () => {
             function sleepSql() {
                 const sleep = fixture.statements?.sleep;
@@ -1795,7 +2101,7 @@ export function runPluginContract(plugin, fixture) {
             it("givenIdleSession_whenCancelled_thenResolvesAndSessionWorks", async () => {
                 await withSession(plugin, fixture, async (session) => {
                     await session.cancel?.();
-                    expect(await collect((await session.execute(selectOne)).rows)).toEqual([[1]]);
+                    await expectAlive(session);
                 });
             });
             it("givenSleepingStatement_whenCancelled_thenExecuteRejectsWithCancelled", async () => {
@@ -1806,7 +2112,7 @@ export function runPluginContract(plugin, fixture) {
             it("givenCancelledStatement_whenNextStatementRun_thenSessionStillWorks", async () => {
                 await withSession(plugin, fixture, async (session) => {
                     await runAndCancel(session);
-                    expect(await collect((await session.execute(selectOne)).rows)).toEqual([[1]]);
+                    await expectAlive(session);
                 });
             });
         });
@@ -1815,9 +2121,7 @@ export function runPluginContract(plugin, fixture) {
                 await withSession(plugin, fixture, async (session) => {
                     await session.ping?.();
                     await session.ping?.();
-                    if (plugin.capabilities.includes("sql")) {
-                        expect(await collect((await session.execute(selectOne)).rows)).toEqual([[1]]);
-                    }
+                    await expectAlive(session);
                 }, { readOnly: false, keepAliveInitialDelayMs: KEEPALIVE_DELAY_MS });
             });
             it("givenClosedSession_whenPinged_thenRejectsWithConnectionLost", async () => {
@@ -1826,6 +2130,30 @@ export function runPluginContract(plugin, fixture) {
                 expect(await rejectionCode(session.ping?.() ?? Promise.resolve())).toBe("connectionLost");
             });
         });
+        describe.runIf(plugin.capabilities.includes("serverInfo"))("serverInfo", () => {
+            it("givenEveryNode_whenServerInfo_thenTitledSectionsWithEntries", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const nodes = (await session.nodes?.()) ?? [];
+                    for (const node of [null, ...nodes.map((listed) => listed.id)]) {
+                        const info = await session.serverInfo?.(node);
+                        expect(info?.sections.length).toBeGreaterThan(0);
+                        for (const section of info?.sections ?? [])
+                            expect(section.title).not.toBe("");
+                        expect(info?.sections.some((section) => section.entries.length > 0)).toBe(true);
+                        if (node !== null)
+                            expect(info?.node).toBe(node);
+                    }
+                });
+            });
+            it("givenSlowLog_whenRead_thenAtMostLimitNewestFirst", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    const entries = (await session.slowLog?.(null, SLOW_LOG_LIMIT)) ?? [];
+                    expect(entries.length).toBeLessThanOrEqual(SLOW_LOG_LIMIT);
+                    const times = entries.map((entry) => entry.at);
+                    expect(times).toEqual([...times].sort().reverse());
+                });
+            });
+        });
         describe.runIf(plugin.capabilities.includes("sessions"))("sessions", () => {
             function sessionsFixture() {
                 if (fixture.sessions === undefined)
@@ -1896,7 +2224,7 @@ export function runPluginContract(plugin, fixture) {
                 await withMonitor(async (monitor) => {
                     await withSleeper(async (sleeper) => {
                         const row = await present(monitor, idOf(sleeper), (listed) => listed.state === "active");
-                        expect(row.query).toContain(sleepSql());
+                        expect(row.query).toContain(sessionsFixture().sleepQuery ?? sleepSql());
                         expect(row.queryMs).not.toBeNull();
                     });
                 });
@@ -1911,7 +2239,7 @@ export function runPluginContract(plugin, fixture) {
                         // MySQL's SLEEP answers 1 when killed rather than failing; either way it stops early.
                         expect(["cancelled", "resolved"]).toContain(await running);
                         expect(Date.now() - started).toBeLessThan(CANCEL_DEADLINE_MS);
-                        expect(await collect((await sleeper.execute(selectOne)).rows)).toEqual([[1]]);
+                        await expectAlive(sleeper);
                     });
                 });
             });
@@ -1937,7 +2265,7 @@ export function runPluginContract(plugin, fixture) {
                     expect(await rejectionCode(monitor.terminateSession({ id, instance: null }))).toBe("statementFailed");
                 });
             });
-            it("givenLockWait_whenList_thenBlockedByFilled", async () => {
+            it.runIf(plugin.capabilities.includes("transactions"))("givenLockWait_whenList_thenBlockedByFilled", async () => {
                 const write = fixture.statements?.write;
                 if (write === undefined)
                     throw new Error("A plugin that declares sessions needs fixture.statements.write.");

package/dist/url.d.ts

@@ -24,6 +24,7 @@ export interface ConnectionUrlSpec {
         readonly key: string;
         readonly values?: Readonly<Record<string, string>> | undefined;
     }[] | undefined;
+    readonly sets?: Readonly<Record<string, Readonly<Record<string, ConnectionValue>>>> | undefined;
 }
 interface UrlField {
     readonly key: string;
@@ -45,7 +46,8 @@ export interface ConnectionForm {
  */
 export declare function parseConnectionUrl(form: ConnectionForm, text: string): ParsedConnectionUrl;
 /**
- * The connection URL of `config`, in the plugin's first scheme. Never carries a secret field, so
+ * The connection URL of `config`, in the first scheme whose `sets` the config holds, else the first
+ * that sets nothing. Never carries a secret field, so
  * the result is safe to copy, show and log; params equal to their field's default are left out.
  */
 export declare function formatConnectionUrl(form: ConnectionForm, config: Readonly<Record<string, unknown>>): string;