@query-farm/vgi 0.24.1 → 0.24.2

package/dist/catalog/attach-option.d.ts

@@ -21,6 +21,16 @@ export interface AttachOptionSpec {
      * the options dict delivered to attach()).
      */
     default?: unknown;
+    /**
+     * The caller must supply this option at ATTACH time. A catalog that cannot
+     * be attached without it advertises that fact at discovery, so a client can
+     * say so before attempting the attach rather than surfacing a failure that
+     * reads like an empty catalog.
+     *
+     * Mutually exclusive with `default` — an option that falls back to a value
+     * is by definition satisfiable without the caller.
+     */
+    required?: boolean;
 }
 /**
  * Serialize an AttachOptionSpec to the wire format the extension expects
@@ -31,3 +41,23 @@ export declare function serializeAttachOptionSpec(spec: AttachOptionSpec): Uint8
  * Convenience: serialize many specs at once for CatalogInfo.attach_option_specs.
  */
 export declare function serializeAttachOptionSpecs(specs: Iterable<AttachOptionSpec>): Uint8Array[];
+/**
+ * Raised when `attach` omits options declared `required`.
+ *
+ * Carries the option names in `missing` so a caller can act on them without
+ * parsing the message. Mirrors `MissingAttachOptionsError` on the Python side,
+ * message included — the extension's integration suite matches on its text.
+ */
+export declare class MissingAttachOptionsError extends Error {
+    readonly missing: string[];
+    constructor(catalogName: string, missing: string[]);
+}
+/**
+ * Throw if any `required` spec has no corresponding entry in `options`.
+ *
+ * Option names are matched case-insensitively, mirroring DuckDB's handling of
+ * ATTACH option keys.
+ *
+ * @throws {MissingAttachOptionsError} If a required option was not supplied.
+ */
+export declare function validateRequiredAttachOptions(catalogName: string, specs: Iterable<AttachOptionSpec>, options: Record<string, unknown>): void;

package/dist/catalog/read-only.d.ts

@@ -1,6 +1,7 @@
 import { CatalogInterface, type AttachOpaqueData, type TransactionOpaqueData, type CatalogAttachResult, type SchemaInfo, type CatalogInfo, type TableInfo, type ViewInfo, type FunctionInfo, type MacroInfo, type IndexInfo, type CopyFromFormatInfo } from "./interface.js";
 import type { CatalogDescriptor } from "./descriptors.js";
 import type { FunctionRegistry } from "../functions/registry.js";
+import { type AttachOptionSpec } from "./attach-option.js";
 export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     private _descriptor;
     private _registry;
@@ -8,6 +9,16 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     private _version;
     constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry);
     catalogs(): string[];
+    /**
+     * Attach-time options this catalog declares, for the named catalog.
+     *
+     * Empty by default — the declarative descriptor path carries no attach
+     * options. A subclass that advertises specs in `catalogsInfo()` should
+     * return the same specs here so `attach()` enforces the `required` ones it
+     * advertised. Takes the catalog name because one interface may serve
+     * several catalogs with different option sets.
+     */
+    attachOptionSpecs(_name: string): AttachOptionSpec[];
     catalogsInfo(): CatalogInfo[];
     attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): CatalogAttachResult | Promise<CatalogAttachResult>;
     detach(attachOpaqueData: AttachOpaqueData): void;

package/dist/index.js

@@ -7022,6 +7022,56 @@ function resolveMetadata(func) {
   };
 }
 
+// src/catalog/attach-option.ts
+init_arrow();
+var SPEC_SCHEMA = schema2([
+  field2("name", utf82(), false),
+  field2("description", utf82(), false),
+  field2("type", binary2(), false),
+  field2("default_value", binary2(), true),
+  field2("required", bool2(), true)
+]);
+function serializeAttachOptionSpec(spec) {
+  if (spec.required && spec.default !== undefined && spec.default !== null) {
+    throw new Error(`Attach option '${spec.name}' is required but also declares a default ` + `(${JSON.stringify(spec.default)}); an option with a default is always ` + "satisfiable without the caller. Drop one.");
+  }
+  const typeSchema = schema2([field2("value", spec.type, true)]);
+  const typeBytes = serializeSchema(typeSchema);
+  let defaultBytes = null;
+  if (spec.default !== undefined && spec.default !== null) {
+    const defaultBatch = batchFromColumns({ value: [spec.default] }, typeSchema);
+    defaultBytes = serializeBatch(defaultBatch);
+  }
+  const batch = batchFromColumns({
+    name: [spec.name],
+    description: [spec.description],
+    type: [typeBytes],
+    default_value: [defaultBytes],
+    required: [spec.required ?? false]
+  }, SPEC_SCHEMA);
+  return serializeBatch(batch);
+}
+function serializeAttachOptionSpecs(specs) {
+  return Array.from(specs, serializeAttachOptionSpec);
+}
+
+class MissingAttachOptionsError extends Error {
+  missing;
+  constructor(catalogName, missing) {
+    const joined = missing.map((name) => `'${name}'`).join(", ");
+    super(`Catalog '${catalogName}' cannot be attached without the required ` + `option${missing.length > 1 ? "s" : ""} ${joined}.`);
+    this.name = "MissingAttachOptionsError";
+    this.missing = missing;
+  }
+}
+function validateRequiredAttachOptions(catalogName, specs, options) {
+  const supplied = new Set(Object.keys(options).map((key) => key.toLowerCase()));
+  const missing = Array.from(specs).filter((spec) => spec.required && !supplied.has(spec.name.toLowerCase())).map((spec) => spec.name);
+  if (missing.length > 0) {
+    throw new MissingAttachOptionsError(catalogName, missing);
+  }
+}
+
 // src/catalog/read-only.ts
 class ReadOnlyCatalogInterface extends CatalogInterface {
   _descriptor;
@@ -7047,6 +7097,9 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
   catalogs() {
     return [this._descriptor.name];
   }
+  attachOptionSpecs(_name) {
+    return [];
+  }
   catalogsInfo() {
     return [{
       name: this._descriptor.name,
@@ -7061,6 +7114,7 @@ class ReadOnlyCatalogInterface extends CatalogInterface {
     if (!this.catalogs().includes(name)) {
       throw new Error(`No worker handles catalog '${name}'`);
     }
+    validateRequiredAttachOptions(name, this.attachOptionSpecs(name), options ?? {});
     const attachOpaqueData = new Uint8Array(16);
     crypto.getRandomValues(attachOpaqueData);
     this._attachments.set(name, attachOpaqueData);
@@ -10861,33 +10915,6 @@ function createLandingDescribe(iface, worker, opts = {}) {
     columns: (catalog, schema3, table) => buildColumnsJson(iface, catalog, schema3, table)
   };
 }
-// src/catalog/attach-option.ts
-init_arrow();
-var SPEC_SCHEMA = schema2([
-  field2("name", utf82(), false),
-  field2("description", utf82(), false),
-  field2("type", binary2(), false),
-  field2("default_value", binary2(), true)
-]);
-function serializeAttachOptionSpec(spec) {
-  const typeSchema = schema2([field2("value", spec.type, true)]);
-  const typeBytes = serializeSchema(typeSchema);
-  let defaultBytes = null;
-  if (spec.default !== undefined && spec.default !== null) {
-    const defaultBatch = batchFromColumns({ value: [spec.default] }, typeSchema);
-    defaultBytes = serializeBatch(defaultBatch);
-  }
-  const batch = batchFromColumns({
-    name: [spec.name],
-    description: [spec.description],
-    type: [typeBytes],
-    default_value: [defaultBytes]
-  }, SPEC_SCHEMA);
-  return serializeBatch(batch);
-}
-function serializeAttachOptionSpecs(specs) {
-  return Array.from(specs, serializeAttachOptionSpec);
-}
 // src/secrets/helpers.ts
 function scalarStr(v) {
   if (v === null || v === undefined)
@@ -12170,4 +12197,4 @@ export {
   ArgumentValidationError
 };
 
-//# debugId=F2B3478BD764EF8C64756E2164756E21
+//# debugId=266210B03996D0CD64756E2164756E21