@tablecraft-app/plugin-api 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { COMPLETION_KINDS, type CompletionCatalog, type CompletionItem, type Com
 export { INSPECTION_IDS, type InspectionId, type InspectionRequest, type Problem, PROBLEM_SEVERITIES, type ProblemSeverity, type QuickFix, type TextEdit, } from "./inspection.js";
 export { ConflictError, DefinitionNotFoundError, type ErrorPosition, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, type PluginErrorCode, type PluginErrorOptions, TlsSettingsError, } from "./errors.js";
 export { type ExplainedPlan, type Explainability, type ExplainOptions, type PlanNode, type PlanProperty, } from "./explain.js";
-export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type KeyChange, type KeyContents, type KeyDatabase, type KeyDetails, type KeyExpiry, type KeyInfo, type KeyName, type KeyReadRequest, type KeyScan, type KeyScanRequest, type Keyspace, type KeyType, } from "./keyspace.js";
+export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type KeyChange, type KeyContents, type KeyDatabase, type KeyDetails, type KeyExpiry, type KeyInfo, type KeyName, type KeyReadRequest, type KeyScan, type KeyScanRequest, type KeySource, type Keyspace, type KeyType, } from "./keyspace.js";
 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 { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, 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";

package/dist/keyspace.d.ts

@@ -15,6 +15,18 @@ export interface KeyBytes {
 }
 /** A key's name: bytes, since a key may be any binary string. */
 export type KeyName = KeyBytes;
+/**
+ * The one key a command's reply was read from (decision 119), so the host can open the key or
+ * edit the reply as the key. `whole` is true when the reply holds the entire key, such as
+ * `HGETALL` or `LRANGE k 0 -1`; its columns are then the ones `Keyspace.read` gives that type,
+ * without positions a key tab adds (a zset's `#`), and a string's is one `value` column.
+ */
+export interface KeySource {
+    readonly database: number;
+    readonly key: KeyName;
+    readonly type: KeyType;
+    readonly whole: boolean;
+}
 /** One logical database of the keyspace: Redis' `db0`–`db15`, or the one database of a cluster. */
 export interface KeyDatabase {
     readonly index: number;

package/dist/plugin.d.ts

@@ -3,7 +3,7 @@ import type { Introspector, Namespace, Relation, Routine } from "./catalog.js";
 import type { CompletionCatalog, CompletionRequest, CompletionResult, Declaration, ResolveRequest, SignatureHelp } from "./completion.js";
 import type { ExplainedPlan, Explainability, ExplainOptions } from "./explain.js";
 import type { InspectionRequest, Problem } from "./inspection.js";
-import type { Keyspace } from "./keyspace.js";
+import type { KeySource, Keyspace } from "./keyspace.js";
 import type { ObjectEditor } from "./objects.js";
 import type { SessionMonitor } from "./sessions.js";
 import type { TypeClass, WireValue } from "./values.js";
@@ -58,16 +58,27 @@ export interface ExecuteResult {
     readonly messages?: readonly ServerMessage[];
     /**
      * A command's one-value answer, such as a status, a number or a string (decision 112): the
-     * console shows it in Output and opens no result. Only a `commands` plugin sets it, and then
+     * console shows it in Output and opens no result unless it is `read`. Only a `commands` plugin sets it, and then
      * `columns` and `rows` are empty.
      */
     readonly reply?: CommandReply;
+    /**
+     * The one key the command read, when it read exactly one (decision 119); absent for writes,
+     * keyless and multi-key commands. Only a `keyValue` plugin sets it.
+     */
+    readonly source?: KeySource;
 }
 /** A scalar reply to a command (decision 112). */
 export interface CommandReply {
     readonly value: WireValue;
     /** The reply as the server's own client prints it: `"Ann"`, `(integer) 5`, `(nil)`, `OK`. */
     readonly text: string;
+    /**
+     * The reply is a value read, such as a bulk string from `GET` or `HGET` or the nil of a missing
+     * one (decision 119): the console opens it as a one-row `value` result besides Output. Absent
+     * for statuses, numbers and errors, which stay in Output.
+     */
+    readonly read?: boolean;
 }
 /** How serious a `ServerMessage` is, from the server's own word for it. */
 export declare const SERVER_MESSAGE_LEVELS: readonly ["error", "warning", "notice", "info"];

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-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";
+import { z, type DatasourcePlugin, type KeyChange, type KeyContents, type KeySource, 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;
@@ -201,6 +201,19 @@ export interface KeyspaceFixture {
     };
     /** A scratch key the suite creates, changes and removes. */
     readonly edit: KeyEditFixture;
+    /**
+     * Commands run in a console and the key each reply names as its source, null for none
+     * (decision 119): one that reads a whole key, one that reads part of one, and one that reads
+     * several. Without it the reply-source tests are skipped.
+     */
+    readonly sources?: readonly KeySourceFixture[];
+}
+/** A command and the source its reply names (decision 119). */
+export interface KeySourceFixture {
+    readonly command: string;
+    readonly source: KeySource | null;
+    /** The reply is a value read, which the console opens as a one-row result. */
+    readonly read?: boolean;
 }
 /** How the suite changes one element of a scratch key and reads it back (decision 115). */
 export interface KeyEditFixture {

package/dist/testing/index.js

@@ -1934,6 +1934,17 @@ export function runPluginContract(plugin, fixture) {
                 expect(cursor).toBeNull();
                 return { keys, batches };
             }
+            it.runIf(fixture.keyspace?.sources !== undefined)("givenSingleKeyRead_whenExecute_thenReplyNamesItsSourceKey", async () => {
+                await withSession(plugin, fixture, async (session) => {
+                    for (const expected of keyspaceFixture().sources ?? []) {
+                        const result = await session.execute(expected.command);
+                        await collect(result.rows);
+                        expect(result.source ?? null, expected.command).toEqual(expected.source);
+                        if (expected.read !== undefined)
+                            expect(result.reply?.read ?? false, expected.command).toBe(expected.read);
+                    }
+                });
+            });
             it("givenKeyspace_whenDatabases_thenFixtureDatabaseCountedAndOneCurrent", async () => {
                 await withSession(plugin, fixture, async (session) => {
                     const databases = await keyspaceOf(session).databases();

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.2.0";
+export const API_VERSION = "1.3.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.2.0",
+  "version": "1.3.0",
   "description": "The datasource plugin contract for TableCraft",
   "license": "MIT",
   "type": "module",