@tablecraft-app/plugin-api 1.6.0 → 1.7.0

package/dist/explain.d.ts

@@ -26,6 +26,12 @@ export interface PlanNode {
     /** Everything else the dialect reports about the step, in its order. */
     readonly properties: readonly PlanProperty[];
     readonly children: readonly PlanNode[];
+    /**
+     * What a reviewer should notice about the step, one sentence each, such as a full table scan or
+     * estimates made without statistics (decision 130). The host marks the step and lists each
+     * distinct sentence once. Absent or empty when there is nothing to say.
+     */
+    readonly warnings?: readonly string[];
 }
 /** What `Session.explain` answers. */
 export interface ExplainedPlan {

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type K
 export { OBJECT_KINDS, type CatalogObject, type CheckDesign, type ColumnDesign, type DdlContext, type DdlScript, type ForeignKeyDesign, type IndexDesign, type ObjectChange, type ObjectChangeKind, type ObjectEditor, type ObjectFeatures, type ObjectKind, type TableDesign, } from "./objects.js";
 export { BRAND_ID, brandSchema, CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, type Brand, type ConnectionField, type ConnectionFieldGroup, type ConnectionFieldKind, type ConnectionUrl, type ConnectionUrlForm, type ConnectionUrlPart, type NetworkSpec, type PluginManifest, type TlsFieldRole, type TlsSpec, } from "./manifest.js";
 export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, type ConnectionForm, type ConnectionUrlSpec, type ConnectionValue, type ParsedConnectionUrl, } from "./url.js";
-export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type ServerTimeout, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
+export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type ServerTimeout, type CancelReach, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
 export { SERVER_SESSION_STATES, type ServerSession, type ServerSessionState, type SessionListing, type SessionMonitor, type SessionTarget, } from "./sessions.js";
 export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, type TlsVerification, } from "./tls.js";
 export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, type WireValueOptions, type BigIntValue, type BytesValue, type DateValue, type JsonValue, type TypeClass, type WireValue, } from "./values.js";

package/dist/plugin.d.ts

@@ -148,6 +148,17 @@ export interface ServerTimeout {
      */
     readonly counts: "statement" | "serverWork";
 }
+/** How `cancel` stops a running statement on this server (decision 131). */
+export interface CancelReach {
+    /** What the plugin sends, for people: `KILL QUERY`, `pg_cancel_backend`, `CLIENT UNBLOCK`. */
+    readonly method: string;
+    /**
+     * `statement`: the server stops the work. `connection`: the plugin drops its connection and the
+     * server may keep running the statement. `blockingCommands`: only commands waiting on the server
+     * (Redis `BLPOP`) are stopped; the rest run to their end.
+     */
+    readonly reaches: "statement" | "connection" | "blockingCommands";
+}
 /** `ExecuteOptions.node`: the plugin routes the command by its keys (decision 114). */
 export declare const NODE_AUTO = "auto";
 /** `ExecuteOptions.node`: the command runs once on every primary (decision 114). */
@@ -312,6 +323,8 @@ export interface Session {
      * version has no such setting.
      */
     readonly serverTimeout?: ServerTimeout | null;
+    /** Optional, only with `cancel`: how this session's cancel reaches the server, read once at connect. */
+    readonly cancelReach?: CancelReach;
 }
 /** What a TLS handshake agreed, as Node's socket names it: `TLSv1.3`, `TLS_AES_256_GCM_SHA384`. */
 export interface TlsInfo {

package/dist/testing/index.js

@@ -179,6 +179,7 @@ const SLEEP_SECONDS = 30;
 const CANCEL_DELAY_MS = 500;
 /** Well under `SLEEP_SECONDS`, so a cancel that did nothing fails the test instead of passing late. */
 const CANCEL_DEADLINE_MS = 10_000;
+const CANCEL_REACHES = ["statement", "connection", "blockingCommands"];
 /** The limit the `serverTimeout` cases ask for; servers check theirs about every 100 ms. */
 const SERVER_LIMIT_MS = 1500;
 /** Far past `SERVER_LIMIT_MS`, so a limit that did nothing fails the test instead of passing late. */
@@ -2161,6 +2162,24 @@ export function runPluginContract(plugin, fixture) {
                     await expectAlive(session);
                 });
             });
+            it("givenCancelReach_whenSessionOpens_thenMethodNamedAndReachKnown", async () => {
+                await withSession(plugin, fixture, (session) => {
+                    const reach = session.cancelReach;
+                    if (reach === undefined)
+                        return Promise.resolve();
+                    expect(reach.method).toMatch(/\S/);
+                    expect(CANCEL_REACHES).toContain(reach.reaches);
+                    return Promise.resolve();
+                });
+            });
+        });
+        describe.runIf(!plugin.capabilities.includes("cancel"))("no cancel", () => {
+            it("givenNoCancel_whenSessionOpens_thenNoCancelReach", async () => {
+                await withSession(plugin, fixture, (session) => {
+                    expect(session.cancelReach).toBeUndefined();
+                    return Promise.resolve();
+                });
+            });
         });
         describe.runIf(plugin.capabilities.includes("serverTimeout"))("serverTimeout", () => {
             function slowRead(seconds) {

package/dist/version.js

@@ -2,7 +2,7 @@
  * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
  * major and an older or equal minor. Typed `string` so a bump does not change the API report.
  */
-export const API_VERSION = "1.6.0";
+export const API_VERSION = "1.7.0";
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 /** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
 export function parseVersion(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablecraft-app/plugin-api",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "The datasource plugin contract for TableCraft",
   "license": "MIT",
   "type": "module",