@query-farm/vgi 0.24.1 → 0.25.0

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,33 @@ 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[];
+/**
+ * Deserialize one AttachOptionSpec from the wire format above.
+ *
+ * Reads by column name, so a spec written by a peer that predates the
+ * `required` column deserializes with `required: false` rather than failing —
+ * the same tolerance the Python and C++ readers have.
+ */
+export declare function deserializeAttachOptionSpec(bytes: Uint8Array): AttachOptionSpec;
+/** Deserialize many specs — the shape `CatalogInfo.attach_option_specs` holds. */
+export declare function deserializeAttachOptionSpecs(specs: Iterable<Uint8Array>): AttachOptionSpec[];
+/**
+ * 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/client-entry.d.ts

@@ -7,5 +7,7 @@ export type { BindRequest, BindResponse, InitRequest, GlobalInitResponse, TableC
 export { type SchemaInfo, encodeSchemaInfo, decodeSchemaInfo, type TableInfo, encodeTableInfo, decodeTableInfo, type ViewInfo, encodeViewInfo, decodeViewInfo, type FunctionInfo, encodeFunctionInfo, decodeFunctionInfo, type MacroInfo, encodeMacroInfo, decodeMacroInfo, type CatalogAttachResult, type AttachOpaqueData, type TransactionOpaqueData, } from "./catalog/interface.js";
 export { VgiError, RowCountMismatchError, FunctionNotFoundError, CatalogReadOnlyError, CatalogNotFoundError, CatalogAlreadyExistsError, ArgumentValidationError, NoCatalogError, } from "./errors.js";
 export { iterRows, batchFromRows, batchFromColumns, emptyBatch, filterBatch, projectSchema, projectBatch, batchToScalarDict, safeNumber, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./util/arrow/index.js";
+export { TypeId, typeSignature } from "./arrow/predicates.js";
+export { type AttachOptionSpec, deserializeAttachOptionSpec, deserializeAttachOptionSpecs, } from "./catalog/attach-option.js";
 export { toUint8Array } from "./util/bytes.js";
 export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";

package/dist/client-entry.js

@@ -58,6 +58,42 @@ function isMap(t) {
 function isDictionary(t) {
   return t.typeId === TypeId.Dictionary;
 }
+function typeSignature(t) {
+  if (t == null)
+    return "null";
+  const a = t;
+  const kids = () => Array.isArray(a.children) ? a.children.map((c) => `${c?.name ?? ""}:${typeSignature(c?.type ?? c)}`).join(",") : "";
+  switch (t.typeId) {
+    case TypeId.Int:
+      return `int${a.bitWidth}${a.isSigned ?? a.signed ?? true ? "" : "u"}`;
+    case TypeId.Float:
+      return `float${a.precision}`;
+    case TypeId.Decimal:
+      return `decimal${a.bitWidth ?? 128}(${a.precision},${a.scale})`;
+    case TypeId.Date:
+    case TypeId.Time:
+    case TypeId.Duration:
+      return `${t.typeId}[${a.unit}]`;
+    case TypeId.Timestamp:
+      return `ts[${a.unit},${a.timezone ?? ""}]`;
+    case TypeId.Interval:
+      return `iv[${a.unit}]`;
+    case TypeId.FixedSizeBinary:
+      return `fsb(${a.byteWidth ?? a.stride})`;
+    case TypeId.FixedSizeList:
+      return `fsl(${a.listSize ?? a.stride},${kids()})`;
+    case TypeId.List:
+    case TypeId.Struct:
+    case TypeId.Map:
+      return `${t.typeId}<${kids()}>`;
+    case TypeId.Union:
+      return `union(${a.mode},${kids()})`;
+    case TypeId.Dictionary:
+      return `dict(${typeSignature(a.dictionary)},${typeSignature(a.indices)},${a.ordered ?? a.isOrdered ?? false})`;
+    default:
+      return Array.isArray(a.children) ? `${t.typeId}<${kids()}>` : String(t.typeId);
+  }
+}
 // src/arrow/impl-arrowjs/index.ts
 var exports_impl_arrowjs = {};
 __export(exports_impl_arrowjs, {
@@ -3880,7 +3916,43 @@ function schemaToArgumentSpecs(schema3) {
   }
   return specs;
 }
+// src/catalog/attach-option.ts
+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 deserializeAttachOptionSpec(bytes) {
+  const row = [...iterRows(deserializeBatch(bytes))][0];
+  if (row === undefined) {
+    throw new Error("Cannot deserialize AttachOptionSpec from an empty batch");
+  }
+  const typeSchema = deserializeSchema(toUint8Array(row.type));
+  const type = typeSchema.fields[0].type;
+  let value;
+  const defaultBytes = row.default_value;
+  if (defaultBytes != null) {
+    const asBytes = toUint8Array(defaultBytes);
+    if (asBytes.length > 0) {
+      const defaultRow = [...iterRows(deserializeBatch(asBytes))][0];
+      value = defaultRow?.value;
+    }
+  }
+  return {
+    name: String(row.name),
+    description: String(row.description ?? ""),
+    type,
+    ...value === undefined || value === null ? {} : { default: value },
+    required: row.required === true
+  };
+}
+function deserializeAttachOptionSpecs(specs) {
+  return Array.from(specs, deserializeAttachOptionSpec);
+}
 export {
+  typeSignature,
   toUint8Array,
   serializeSchema,
   serializeBatch,
@@ -3898,6 +3970,8 @@ export {
   emptyBatch,
   deserializeSchema,
   deserializeBatch,
+  deserializeAttachOptionSpecs,
+  deserializeAttachOptionSpec,
   decodeViewInfo,
   decodeTableInfo,
   decodeSchemaInfo,
@@ -3910,6 +3984,7 @@ export {
   VgiError,
   VgiClientError,
   VgiClient,
+  TypeId,
   TableInOutPhase,
   RowCountMismatchError,
   OrderPreservation,
@@ -3927,4 +4002,4 @@ export {
   ArgumentValidationError
 };
 
-//# debugId=34D58DEB536066C064756E2164756E21
+//# debugId=B61D9AABA0B3DE2E64756E2164756E21