@query-farm/vgi 0.6.0

package/dist/arrow/impl-flechette/normalize-type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Rebuild `type` as a flechette-native DataType. Idempotent for types that are
+ * already native (reconstructed from the same structural props). Unknown
+ * typeIds pass through unchanged as a safety net.
+ */
+export declare function toFlechetteType(type: any): any;
+/**
+ * Normalize every field's type in a schema-like object to flechette-native,
+ * preserving field name / nullable / metadata.
+ */
+export declare function normalizeSchemaFields(fields: readonly any[]): any[];

package/dist/arrow/impl-flechette/project.d.ts

@@ -0,0 +1,3 @@
+import type { VgiSchema, VgiBatch } from "../types.js";
+export declare function projectSchema(projectionIds: number[] | null, schema: VgiSchema): VgiSchema;
+export declare function projectBatch(projectionIds: number[] | null, batch: VgiBatch): VgiBatch;

package/dist/arrow/impl-flechette/schema.d.ts

@@ -0,0 +1,47 @@
+import { TimeUnit as F_TimeUnit, DateUnit as F_DateUnit, IntervalUnit as F_IntervalUnit, UnionMode as F_UnionMode } from "@query-farm/flechette";
+import type { VgiField, VgiSchema, VgiDataType } from "../types.js";
+export declare const TimeUnit: typeof F_TimeUnit;
+export declare const DateUnit: typeof F_DateUnit;
+export declare const IntervalUnit: typeof F_IntervalUnit;
+export declare const UnionMode: typeof F_UnionMode;
+export declare function schema(fields: readonly VgiField[], metadata?: Map<string, string>): VgiSchema;
+export declare function field(name: string, type: VgiDataType, nullable?: boolean, metadata?: Map<string, string>): VgiField;
+export declare const nullType: () => VgiDataType;
+export declare const bool: () => VgiDataType;
+export declare const int8: () => VgiDataType;
+export declare const int16: () => VgiDataType;
+export declare const int32: () => VgiDataType;
+export declare const int64: () => VgiDataType;
+export declare const uint8: () => VgiDataType;
+export declare const uint16: () => VgiDataType;
+export declare const uint32: () => VgiDataType;
+export declare const uint64: () => VgiDataType;
+export declare const int: (bitWidth?: 8 | 16 | 32 | 64, signed?: boolean) => VgiDataType;
+export declare const float16: () => VgiDataType;
+export declare const float32: () => VgiDataType;
+export declare const float64: () => VgiDataType;
+export declare const utf8: () => VgiDataType;
+export declare const binary: () => VgiDataType;
+export declare const fixedSizeBinary: (stride: number) => VgiDataType;
+export declare function decimal(precision: number, scale: number, bitWidth?: 32 | 64 | 128 | 256): VgiDataType;
+export declare const decimal128: (precision: number, scale: number) => VgiDataType;
+export declare const decimal256: (precision: number, scale: number) => VgiDataType;
+export declare const date: (unit?: number) => VgiDataType;
+export declare const dateDay: () => VgiDataType;
+export declare const dateMillisecond: () => VgiDataType;
+export declare function time(unit?: number, _bitWidth?: 32 | 64): VgiDataType;
+export declare const timeSecond: () => VgiDataType;
+export declare const timeMillisecond: () => VgiDataType;
+export declare const timeMicrosecond: () => VgiDataType;
+export declare const timeNanosecond: () => VgiDataType;
+export declare const timestamp: (unit?: number, timezone?: string | null) => VgiDataType;
+export declare const duration: (unit?: number) => VgiDataType;
+export declare const interval: (unit?: number) => VgiDataType;
+export declare function list(child: VgiField | VgiDataType): VgiDataType;
+export declare function fixedSizeList(child: VgiField | VgiDataType, listSize: number): VgiDataType;
+export declare function struct(children: readonly VgiField[]): VgiDataType;
+export declare function map(keyField: VgiField | VgiDataType, valueField: VgiField | VgiDataType, keysSorted?: boolean): VgiDataType;
+export declare function dictionary(valueType: VgiDataType, indexType?: VgiDataType, ordered?: boolean, id?: number): VgiDataType;
+export declare function union(mode: number, children: readonly (VgiField | VgiDataType)[], typeIds?: number[]): VgiDataType;
+export declare const sparseUnion: (children: readonly (VgiField | VgiDataType)[], typeIds?: number[]) => VgiDataType;
+export declare const denseUnion: (children: readonly (VgiField | VgiDataType)[], typeIds?: number[]) => VgiDataType;

package/dist/arrow/impl-flechette/statistics.d.ts

@@ -0,0 +1,13 @@
+import type { VgiBatch, VgiDataType } from "../types.js";
+export interface ColumnStatistics {
+    columnName: string;
+    arrowType: VgiDataType;
+    min: any;
+    max: any;
+    hasNull: boolean;
+    hasNotNull: boolean;
+    distinctCount: bigint | number | null;
+    containsUnicode: boolean | null;
+    maxStringLength: bigint | number | null;
+}
+export declare function buildStatisticsBatch(stats: ColumnStatistics[]): VgiBatch;

package/dist/arrow/index.d.ts

@@ -0,0 +1,11 @@
+export type { VgiTypeId, VgiDataType, VgiField, VgiSchema, VgiColumn, VgiColumnData, VgiBatch, VgiBackendInfo, TaggedUnion, } from "./types.js";
+export { TypeId, isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate, isTime, isTimestamp, isInterval, isList, isStruct, isUnion, isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch, } from "./predicates.js";
+export { backend, emptyBatch, batchFromRows, batchFromColumns, columnFromArray, iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, filterBatch, projectSchema, projectBatch, readCanonicalValue, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, buildStatisticsBatch, } from "#arrow-impl";
+export type { ColumnStatistics } from "#arrow-impl";
+export { schema, field, nullType, bool, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float16, float32, float64, utf8, binary, fixedSizeBinary, decimal, decimal128, decimal256, date, dateDay, dateMillisecond, time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond, timestamp, duration, interval, timestampSeconds, timestampMillis, timestampMicros, timestampNanos, durationSeconds, durationMillis, durationMicros, durationNanos, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, } from "./schema-types.js";
+export type { NullDescriptor, BoolType, IntType, Int8Type, Int16Type, Int32Type, Int64Type, Uint8Type, Uint16Type, Uint32Type, Uint64Type, FloatType, Utf8Type, LargeUtf8Type, BinaryType, LargeBinaryType, FixedSizeBinaryType, DecimalType, Date32Type, Date64Type, Time32Type, Time64Type, TimestampType, DurationType, IntervalType, ListType, FixedSizeListType, StructType, MapType, DictionaryType, UnionType, TypedField, TUnit, } from "./codec/type-descriptors.js";
+export type { RichValue, RawValue, ValueFor, Repr } from "./codec/repr.js";
+export { codecFor } from "./codec/registry.js";
+export type { Codec } from "./codec/registry.js";
+export type { Branded, Date32, Date64Ms, Time32S, Time32Ms, Time64Us, Time64Ns, TimestampSeconds, TimestampMillis, TimestampMicros, TimestampNanos, DurationSeconds, DurationMillis, DurationMicros, DurationNanos, UnscaledDecimal, Int64 as Int64Raw, Uint64 as Uint64Raw, } from "./codec/branded.js";
+export { asDate32, asDate64Ms, asTime32S, asTime32Ms, asTime64Us, asTime64Ns, asTimestampSeconds, asTimestampMillis, asTimestampMicros, asTimestampNanos, asDurationSeconds, asDurationMillis, asDurationMicros, asDurationNanos, asUnscaledDecimal, asInt64, asUint64, fromBranded, fromBrandedNumber, fromBrandedBigInt, } from "./codec/branded.js";

package/dist/arrow/predicates.d.ts

@@ -0,0 +1,47 @@
+import type { VgiDataType } from "./types.js";
+export declare const TypeId: {
+    readonly Null: 1;
+    readonly Int: 2;
+    readonly Float: 3;
+    readonly Binary: 4;
+    readonly Utf8: 5;
+    readonly Bool: 6;
+    readonly Decimal: 7;
+    readonly Date: 8;
+    readonly Time: 9;
+    readonly Timestamp: 10;
+    readonly Interval: 11;
+    readonly List: 12;
+    readonly Struct: 13;
+    readonly Union: 14;
+    readonly FixedSizeBinary: 15;
+    readonly FixedSizeList: 16;
+    readonly Map: 17;
+    readonly Duration: 18;
+    readonly LargeBinary: 19;
+    readonly LargeUtf8: 20;
+    readonly Dictionary: -1;
+};
+export declare function isNull(t: VgiDataType): boolean;
+export declare function isInt(t: VgiDataType): boolean;
+export declare function isFloat(t: VgiDataType): boolean;
+export declare function isBinary(t: VgiDataType): boolean;
+export declare function isUtf8(t: VgiDataType): boolean;
+export declare function isBool(t: VgiDataType): boolean;
+export declare function isDecimal(t: VgiDataType): boolean;
+export declare function isDate(t: VgiDataType): boolean;
+export declare function isTime(t: VgiDataType): boolean;
+export declare function isTimestamp(t: VgiDataType): boolean;
+export declare function isInterval(t: VgiDataType): boolean;
+export declare function isList(t: VgiDataType): boolean;
+export declare function isStruct(t: VgiDataType): boolean;
+export declare function isUnion(t: VgiDataType): boolean;
+export declare function isFixedSizeBinary(t: VgiDataType): boolean;
+export declare function isFixedSizeList(t: VgiDataType): boolean;
+export declare function isMap(t: VgiDataType): boolean;
+export declare function isDuration(t: VgiDataType): boolean;
+export declare function isDictionary(t: VgiDataType): boolean;
+/** Runtime check: does `x` quack like a VgiBatch? Used at API boundaries
+ *  where callers may pass either a batch or a plain column dict. Duck-typed
+ *  because arrow-js and flechette use unrelated classes. */
+export declare function isBatch(x: unknown): x is import("./types.js").VgiBatch;

package/dist/arrow/repr.test-d.d.ts

@@ -0,0 +1,52 @@
+import { list, asDate64Ms } from "./index.js";
+import type { RichValue, RawValue, ValueFor, Date32Type, Date64Type, Int64Type, Int32Type, Utf8Type, BoolType, TimestampType, DecimalType, FloatType, StructType, ListType, TypedField, Date32, TimestampMicros, UnscaledDecimal } from "./index.js";
+type Expect<T extends true> = T;
+type Equal<A, B> = (<G>() => G extends A ? 1 : 2) extends (<G>() => G extends B ? 1 : 2) ? true : false;
+type _r1 = Expect<Equal<RichValue<Date32Type>, Date>>;
+type _r2 = Expect<Equal<RawValue<Date32Type>, Date32>>;
+type _r3 = Expect<Equal<RichValue<Date64Type>, Date>>;
+type _r4 = Expect<Equal<RichValue<Int64Type>, bigint>>;
+type _r5 = Expect<Equal<RichValue<Int32Type>, number>>;
+type _r6 = Expect<Equal<RichValue<Utf8Type>, string>>;
+type _r7 = Expect<Equal<RichValue<BoolType>, boolean>>;
+type _r8 = Expect<Equal<ValueFor<TimestampType<"us">, "rich">, bigint>>;
+type _r9 = Expect<Equal<ValueFor<TimestampType<"us">, "raw">, TimestampMicros>>;
+type _r10 = Expect<Equal<RawValue<DecimalType>, UnscaledDecimal>>;
+type _r11 = Expect<Equal<RichValue<DecimalType>, bigint>>;
+type _r12 = Expect<Equal<RichValue<FloatType>, number>>;
+type _StructT = StructType<[TypedField<"a", Int32Type>, TypedField<"d", Date32Type>]>;
+type _r13 = Expect<Equal<RichValue<_StructT>, {
+    a: number | null;
+    d: Date | null;
+}>>;
+type _r14 = Expect<Equal<RawValue<_StructT>, {
+    a: number | null;
+    d: Date32 | null;
+}>>;
+type _ListT = ListType<Int64Type>;
+type _r15 = Expect<Equal<RichValue<_ListT>, Array<bigint | null>>>;
+export type _AllChecks = [
+    _r1,
+    _r2,
+    _r3,
+    _r4,
+    _r5,
+    _r6,
+    _r7,
+    _r8,
+    _r9,
+    _r10,
+    _r11,
+    _r12,
+    _r13,
+    _r14,
+    _r15
+];
+export declare const _unusedFactories: {
+    dateMillisecond: () => Date64Type;
+    bool: () => BoolType;
+    float64: () => FloatType;
+    list: typeof list;
+    asDate64Ms: typeof asDate64Ms;
+};
+export {};

package/dist/arrow/schema-types.d.ts

@@ -0,0 +1,71 @@
+import * as impl from "#arrow-impl";
+import type { VgiField, VgiDataType } from "./types.js";
+import type { NullDescriptor, BoolType, Int8Type, Int16Type, Int32Type, Int64Type, Uint8Type, Uint16Type, Uint32Type, Uint64Type, IntType, FloatType, Utf8Type, BinaryType, FixedSizeBinaryType, DecimalType, Date32Type, Date64Type, Time32Type, Time64Type, TimestampType, DurationType, IntervalType, ListType, FixedSizeListType, StructType, MapType, DictionaryType, UnionType, TypedField, TUnit } from "./codec/type-descriptors.js";
+export declare const TimeUnit: {
+    readonly SECOND: import("@query-farm/apache-arrow").TimeUnit.SECOND;
+    readonly MILLISECOND: import("@query-farm/apache-arrow").TimeUnit.MILLISECOND;
+    readonly MICROSECOND: import("@query-farm/apache-arrow").TimeUnit.MICROSECOND;
+    readonly NANOSECOND: import("@query-farm/apache-arrow").TimeUnit.NANOSECOND;
+}, DateUnit: {
+    readonly DAY: import("@query-farm/apache-arrow").DateUnit.DAY;
+    readonly MILLISECOND: import("@query-farm/apache-arrow").DateUnit.MILLISECOND;
+}, IntervalUnit: {
+    readonly YEAR_MONTH: import("@query-farm/apache-arrow").IntervalUnit.YEAR_MONTH;
+    readonly DAY_TIME: import("@query-farm/apache-arrow").IntervalUnit.DAY_TIME;
+    readonly MONTH_DAY_NANO: import("@query-farm/apache-arrow").IntervalUnit.MONTH_DAY_NANO;
+}, UnionMode: {
+    readonly Sparse: import("@query-farm/apache-arrow").UnionMode.Sparse;
+    readonly Dense: import("@query-farm/apache-arrow").UnionMode.Dense;
+}, schema: typeof impl.schema;
+/** field(): preserve the precise name + type so struct() can carry a typed
+ *  child tuple. Runtime is the backend `field`. */
+export declare function field<Name extends string, T extends VgiDataType>(name: Name, type: T, nullable?: boolean, metadata?: Map<string, string>): TypedField<Name, T>;
+export declare const nullType: () => NullDescriptor;
+export declare const bool: () => BoolType;
+export declare const int8: () => Int8Type;
+export declare const int16: () => Int16Type;
+export declare const int32: () => Int32Type;
+export declare const int64: () => Int64Type;
+export declare const uint8: () => Uint8Type;
+export declare const uint16: () => Uint16Type;
+export declare const uint32: () => Uint32Type;
+export declare const uint64: () => Uint64Type;
+export declare function int(bitWidth?: 8 | 16 | 32 | 64, signed?: boolean): IntType<8 | 16 | 32 | 64, boolean>;
+export declare const float16: () => FloatType;
+export declare const float32: () => FloatType;
+export declare const float64: () => FloatType;
+export declare const utf8: () => Utf8Type;
+export declare const binary: () => BinaryType;
+export declare const fixedSizeBinary: (byteWidth: number) => FixedSizeBinaryType;
+export declare const decimal: (precision: number, scale: number, bitWidth?: 32 | 64 | 128 | 256) => DecimalType;
+export declare const decimal128: (precision: number, scale: number) => DecimalType;
+export declare const decimal256: (precision: number, scale: number) => DecimalType;
+export declare const date: (unit?: number) => Date64Type;
+export declare const dateDay: () => Date32Type;
+export declare const dateMillisecond: () => Date64Type;
+export declare const timeSecond: () => Time32Type<"s">;
+export declare const timeMillisecond: () => Time32Type<"ms">;
+export declare const timeMicrosecond: () => Time64Type<"us">;
+export declare const timeNanosecond: () => Time64Type<"ns">;
+export declare function time(unit?: number, bitWidth?: 32 | 64): Time32Type<"s" | "ms"> | Time64Type<"us" | "ns">;
+/** timestamp(unit): when called with a literal unit constant the result type
+ *  carries that unit; with a runtime number it widens to TimestampType<TUnit>. */
+export declare function timestamp<U extends TUnit = TUnit>(unit?: number, timezone?: string | null): TimestampType<U>;
+export declare function duration<U extends TUnit = TUnit>(unit?: number): DurationType<U>;
+export declare const timestampSeconds: (timezone?: string | null) => TimestampType<"s">;
+export declare const timestampMillis: (timezone?: string | null) => TimestampType<"ms">;
+export declare const timestampMicros: (timezone?: string | null) => TimestampType<"us">;
+export declare const timestampNanos: (timezone?: string | null) => TimestampType<"ns">;
+export declare const durationSeconds: () => DurationType<"s">;
+export declare const durationMillis: () => DurationType<"ms">;
+export declare const durationMicros: () => DurationType<"us">;
+export declare const durationNanos: () => DurationType<"ns">;
+export declare const interval: (unit?: number) => IntervalType;
+export declare function list<T extends VgiDataType>(child: TypedField<string, T> | T): ListType<T>;
+export declare function fixedSizeList<T extends VgiDataType>(child: TypedField<string, T> | T, listSize: number): FixedSizeListType<T>;
+export declare function struct<const C extends readonly TypedField<string, VgiDataType>[]>(children: C): StructType<C>;
+export declare function map<K extends VgiDataType, V extends VgiDataType>(keyField: TypedField<string, K> | K, valueField: TypedField<string, V> | V, keysSorted?: boolean): MapType<K, V>;
+export declare function dictionary<V extends VgiDataType>(valueType: V, indexType?: VgiDataType, ordered?: boolean, id?: number): DictionaryType<V>;
+export declare function union(mode: number, children: readonly (VgiField | VgiDataType)[], typeIds?: number[]): UnionType;
+export declare const sparseUnion: (children: readonly (VgiField | VgiDataType)[], typeIds?: number[]) => UnionType;
+export declare const denseUnion: (children: readonly (VgiField | VgiDataType)[], typeIds?: number[]) => UnionType;

package/dist/arrow/types.d.ts

@@ -0,0 +1,57 @@
+/** Numeric Arrow type discriminator. Values match the Arrow Type enum
+ *  (Null=1, Int=2, Float=3, Binary=4, Utf8=5, Bool=6, Decimal=7,
+ *  Date=8, Time=9, Timestamp=10, Interval=11, List=12, Struct=13,
+ *  Union=14, FixedSizeBinary=15, FixedSizeList=16, Map=17, Duration=18,
+ *  LargeBinary=19, LargeUtf8=20, Dictionary=-1). Both backends agree. */
+export type VgiTypeId = number;
+export interface VgiDataType {
+    readonly typeId: VgiTypeId;
+}
+export interface VgiField {
+    readonly name: string;
+    readonly type: VgiDataType;
+    readonly nullable: boolean;
+    /** Always defined (possibly empty) so callers don't need null-checks.
+     *  Both arrow-js Field.metadata and flechette's field.metadata are a
+     *  Map; the field-factory in each backend ensures presence. */
+    readonly metadata: Map<string, string>;
+}
+export interface VgiSchema {
+    readonly fields: readonly VgiField[];
+    readonly metadata: Map<string, string>;
+}
+/** Column view. Generic dropped: arrow-js parameterizes on DataType, flechette
+ *  on value type, so the facade exposes an erased shape. Callers cast at the
+ *  use site (the column's static schema makes the value type known there). */
+export interface VgiColumn {
+    readonly type: VgiDataType;
+    readonly length: number;
+    get(index: number): unknown;
+    [Symbol.iterator](): Iterator<unknown>;
+}
+export interface VgiBatch {
+    readonly schema: VgiSchema;
+    readonly numRows: number;
+    getChild(name: string): VgiColumn | null;
+    getChildAt(index: number): VgiColumn | null;
+}
+export interface VgiBackendInfo {
+    readonly name: "arrow-js" | "flechette";
+}
+/** Low-level handle for a single column's underlying Arrow Data. The shape
+ *  differs per backend (arrow-js: a `Data` instance; flechette: the inner
+ *  `Column.data[0]`-style object), so this is treated opaquely; it's only
+ *  meant to be passed back into facade builders that know how to consume it. */
+export type VgiColumnData = unknown;
+/** A decoded union-typed value: which member is active (`tag`) and its `value`.
+ *
+ *  DuckDB `UNION` / Arrow union values are *tagged* — the discriminator (which
+ *  member is present) lives in the union's per-row type code, not in the member
+ *  value. A plain scalar read returns only the member value and drops that tag,
+ *  so union values are decoded into this wrapper instead: `tag` is the active
+ *  member's field name (or `null` for a null union) and `value` is its decoded
+ *  canonical value. Mirrors vgi-python's `vgi.arguments.TaggedUnion`. */
+export interface TaggedUnion {
+    readonly tag: string | null;
+    readonly value: unknown;
+}

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

@@ -0,0 +1,33 @@
+import { type VgiDataType } from "../arrow/index.js";
+/**
+ * Declarative spec for a single attach-time option.
+ *
+ * The catalog's `catalogsInfo()` emits these (serialized) in
+ * `CatalogInfo.attach_option_specs` so the DuckDB extension can validate
+ * user-supplied ATTACH options and cast them to the declared type before
+ * forwarding to the worker's `catalog_attach` handler.
+ */
+export interface AttachOptionSpec {
+    /** Option name — matches the key users pass in the ATTACH statement. */
+    name: string;
+    /** Human-readable description (shown in discovery UIs). */
+    description: string;
+    /** Arrow data type the extension should cast user input to. */
+    type: VgiDataType;
+    /**
+     * Default value used when the user omits this option. Passed through to
+     * the worker's catalog_attach handler as-is if no override is given.
+     * Use `null` for "no default" (an unset option will then be absent from
+     * the options dict delivered to attach()).
+     */
+    default?: unknown;
+}
+/**
+ * Serialize an AttachOptionSpec to the wire format the extension expects
+ * (one IPC-serialized RecordBatch with a single row).
+ */
+export declare function serializeAttachOptionSpec(spec: AttachOptionSpec): Uint8Array;
+/**
+ * Convenience: serialize many specs at once for CatalogInfo.attach_option_specs.
+ */
+export declare function serializeAttachOptionSpecs(specs: Iterable<AttachOptionSpec>): Uint8Array[];

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

@@ -0,0 +1,30 @@
+import { type VgiDataType } from "../arrow/index.js";
+/**
+ * Values supported in a CatalogAttach options map. The client infers an
+ * Arrow type per value:
+ *
+ *   string     → Utf8
+ *   bigint     → Int64
+ *   number     → Float64 (JS numbers are doubles — safe for small ints too)
+ *   boolean    → Bool
+ *   Uint8Array → Binary
+ *   null       → Null (column with no concrete type; value is null)
+ *
+ * If you need types this can't express (Decimal, Timestamp, Int32 vs Int64,
+ * nested structs), drop down to `optionsBytes` on CatalogAttachOptions and
+ * build the RecordBatch yourself.
+ */
+export type AttachOptionValue = string | number | bigint | boolean | null | Uint8Array;
+/**
+ * Infer an Arrow DataType for a single JS value. Exported for tests; not
+ * part of the stable public API.
+ */
+export declare function inferAttachOptionArrowType(value: AttachOptionValue): VgiDataType;
+/**
+ * Serialize a plain key→value options map to an Arrow IPC RecordBatch.
+ *
+ * Returns `null` when the map is empty or has no entries — the wire layer
+ * then sends a null options field rather than a zero-column batch (which
+ * pyarrow's IPC reader rejects).
+ */
+export declare function serializeAttachOptions(options: Record<string, AttachOptionValue> | undefined | null): Uint8Array | null;

package/dist/catalog/composite.d.ts

@@ -0,0 +1,33 @@
+import type { AttachOpaqueData, CatalogAttachResult, CatalogInfo, CopyFromFormatInfo, FunctionInfo, IndexInfo, MacroInfo, SchemaInfo, TableInfo, TransactionOpaqueData, ViewInfo } from "./interface.js";
+import { CatalogInterface } from "./interface.js";
+export declare class CompositeCatalogInterface extends CatalogInterface {
+    private readonly _backends;
+    constructor(_backends: CatalogInterface[]);
+    private _route;
+    catalogs(): string[];
+    catalogsInfo(): Promise<CatalogInfo[]>;
+    attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): Promise<CatalogAttachResult>;
+    detach(attachOpaqueData: AttachOpaqueData): Promise<void>;
+    version(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<number>;
+    schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo[]>;
+    schemaGet(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<SchemaInfo | null>;
+    schemaContentsTables(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo[]>;
+    schemaContentsViews(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
+    schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
+    schemaContentsMacros(attachOpaqueData: AttachOpaqueData, name: string, type: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo[]>;
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]>;
+    indexGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo | null>;
+    tableGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
+    tableScanFunctionGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
+    tableScanBranchesGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, atUnit?: string, atValue?: string, transactionOpaqueData?: TransactionOpaqueData): Promise<any>;
+    tableColumnStatisticsGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<{
+        bytes: Uint8Array;
+        cacheMaxAgeSeconds: number | null;
+    } | null>;
+    viewGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null>;
+    macroGet(attachOpaqueData: AttachOpaqueData, schemaName: string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null>;
+    copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<CopyFromFormatInfo[]>;
+    transactionBegin(attachOpaqueData: AttachOpaqueData): Promise<Uint8Array | null>;
+    transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;
+    transactionRollback(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;
+}

package/dist/catalog/descriptors.d.ts

@@ -0,0 +1,154 @@
+import type { VgiSchema, VgiDataType } from "../arrow/index.js";
+import type { VgiFunction } from "../functions/types.js";
+import type { Arguments } from "../arguments/arguments.js";
+import type { ColumnStatistics } from "../util/statistics.js";
+export interface SettingDescriptor {
+    name: string;
+    description: string;
+    type: VgiDataType;
+    /** Must be a JS primitive compatible with `type` (string, number, bigint, boolean). */
+    defaultValue?: string | number | bigint | boolean;
+}
+export interface ForeignKeyDef {
+    columns: string[];
+    referencedTable: string;
+    referencedColumns: string[];
+    referencedSchema?: string;
+}
+export type DefaultValue = string | number | boolean | null;
+export interface TableDescriptor {
+    name: string;
+    columns?: VgiSchema;
+    function?: VgiFunction;
+    arguments?: Arguments;
+    notNull?: string[];
+    unique?: string[][];
+    check?: string[];
+    primaryKey?: string[][];
+    foreignKey?: ForeignKeyDef[];
+    defaults?: Record<string, DefaultValue>;
+    /** Per-column comment strings, applied as field metadata `comment`. */
+    columnComments?: Record<string, string>;
+    /**
+     * Generated (virtual) columns: map of column name → SQL expression computed
+     * from other physical columns. Applied as Arrow field metadata
+     * `generated_expression`, which the DuckDB VGI extension reads at table
+     * registration. The backing scan function should not return these columns —
+     * DuckDB evaluates the expressions client-side.
+     */
+    generatedColumns?: Record<string, string>;
+    /**
+     * Per-column statistics for the optimizer. Keys are column names; values
+     * are ColumnStatistics records with typed min/max and Arrow type info.
+     * DuckDB uses these for plan-time filter elimination and join reordering
+     * via the `catalog_table_column_statistics_get` RPC.
+     */
+    statistics?: Record<string, ColumnStatistics>;
+    /**
+     * Cache TTL for this table's column statistics. DuckDB caches the result
+     * of `catalog_table_column_statistics_get` for up to this many seconds.
+     * `undefined`/null means cache indefinitely; `0` means never cache
+     * (always re-fetch).
+     */
+    statisticsCacheMaxAgeSeconds?: number | null;
+    /**
+     * Dotted-path column references that MUST appear in a WHERE expression for
+     * any scan of this table. Top-level names (`"country"`) or struct subfields
+     * (`"bbox.xmin"`, `"nested.outer.inner"`). Empty/undefined (default) means
+     * no enforcement — the zero-cost fast path for every existing table.
+     *
+     * Satisfaction is prefix-based: a present filter on a shorter path satisfies
+     * any required path it is a prefix of. So a whole-struct filter on `bbox`
+     * satisfies all of `bbox.xmin` / `.xmax` / `.ymin` / `.ymax`. The VGI DuckDB
+     * extension's optimizer pass consults this list at bind time and throws a
+     * `BinderException` listing any unsatisfied paths.
+     */
+    requiredFieldFilterPaths?: string[];
+    supportsTimeTravel?: boolean;
+    /**
+     * Inline cardinality estimate/max surfaced through TableInfo. When set,
+     * the C++ extension uses these directly and skips the per-bind
+     * table_function_cardinality RPC. Only meaningful for function-backed
+     * tables; static-column tables don't have a function to call.
+     */
+    inlinedCardinality?: {
+        estimate: bigint;
+        max: bigint;
+    };
+    comment?: string;
+    tags?: Record<string, string>;
+}
+export interface ViewDescriptor {
+    name: string;
+    definition: string;
+    comment?: string;
+    /**
+     * Per-column comments keyed by the view's output column name. Unlike tables
+     * (whose column comments ride along as Arrow field metadata), a view ships
+     * only its SQL `definition`, so column comments need their own channel. The
+     * C++ extension aligns these by name against the bound output columns and
+     * feeds them into `CreateViewInfo.column_comments_map`; names that don't
+     * match a bound column are ignored.
+     */
+    columnComments?: Record<string, string>;
+    tags?: Record<string, string>;
+}
+export interface MacroDescriptor {
+    name: string;
+    macroType: "scalar" | "table";
+    parameters: string[];
+    parameterDefaultValues?: Uint8Array | null;
+    /**
+     * Optional mapping of parameter name to a human/agent-facing description.
+     * Keys must appear in `parameters`. Descriptions flow over the wire via the
+     * macro `arguments_schema`'s `vgi_doc` field metadata (the same channel
+     * functions use for per-argument docs), so the DuckDB extension's
+     * `vgi_function_arguments()` can surface them. Empty/omitted = no docs.
+     */
+    parameterDocs?: Record<string, string>;
+    definition: string;
+    comment?: string;
+    tags?: Record<string, string>;
+}
+export interface IndexDescriptor {
+    name: string;
+    tableName: string;
+    expressions: string[];
+    /** UNIQUE / PRIMARY / NONE; defaults to NONE. */
+    constraintType?: "NONE" | "UNIQUE" | "PRIMARY";
+    indexType?: string;
+    options?: Record<string, string>;
+    comment?: string;
+    tags?: Record<string, string>;
+}
+export interface SchemaDescriptor {
+    name: string;
+    tables?: TableDescriptor[];
+    views?: ViewDescriptor[];
+    macros?: MacroDescriptor[];
+    functions?: VgiFunction[];
+    indexes?: IndexDescriptor[];
+    comment?: string;
+    tags?: Record<string, string>;
+}
+export interface SecretTypeDescriptor {
+    name: string;
+    description: string;
+    schema: VgiSchema;
+}
+export interface CatalogDescriptor {
+    name: string;
+    defaultSchema?: string;
+    schemas: SchemaDescriptor[];
+    settings?: SettingDescriptor[];
+    secretTypes?: SecretTypeDescriptor[];
+    comment?: string;
+    tags?: Record<string, string>;
+    /**
+     * Homepage for this catalog — repo, docs, or dataset landing page. Surfaced
+     * through the `catalog_catalogs` discovery record as `CatalogInfo.source_url`,
+     * which DuckDB exposes via `duckdb_databases()`. Optional; omitted/`undefined`
+     * advertises a null `source_url`.
+     */
+    sourceUrl?: string;
+}