@query-farm/vgi 0.6.0

package/dist/arguments/arguments.d.ts

@@ -0,0 +1,13 @@
+import type { VgiSchema } from "../arrow/index.js";
+export declare class Arguments {
+    readonly positional: (any | null)[];
+    readonly named: Map<string, any | null>;
+    /** Schema of the arguments batch (preserves original Arrow types). */
+    readonly argumentsSchema: VgiSchema | null;
+    constructor(positional?: (any | null)[], named?: Map<string, any | null>, argumentsSchema?: VgiSchema | null);
+    /**
+     * Get an argument by position (number) or name (string).
+     */
+    get(position: number | string, defaultValue?: any): any;
+    get length(): number;
+}

package/dist/arrow/codec/branded.d.ts

@@ -0,0 +1,83 @@
+import { TimeUnit } from "../schema-types.js";
+declare const __brand: unique symbol;
+/** A nominal brand over a base primitive. `Branded<number, 'date32'>` is a
+ *  `number` at runtime but a distinct type at compile time. */
+export type Branded<Base, Tag extends string> = Base & {
+    readonly [__brand]: Tag;
+};
+/** date32 raw: days since the Unix epoch. */
+export type Date32 = Branded<number, "date32">;
+/** date64 raw: milliseconds since the Unix epoch. */
+export type Date64Ms = Branded<bigint, "date64ms">;
+/** time32[s] raw: seconds since midnight. */
+export type Time32S = Branded<number, "time32s">;
+/** time32[ms] raw: milliseconds since midnight. */
+export type Time32Ms = Branded<number, "time32ms">;
+/** time64[us] raw: microseconds since midnight. */
+export type Time64Us = Branded<bigint, "time64us">;
+/** time64[ns] raw: nanoseconds since midnight. */
+export type Time64Ns = Branded<bigint, "time64ns">;
+/** timestamp[s] raw. */
+export type TimestampSeconds = Branded<bigint, "ts_s">;
+/** timestamp[ms] raw. */
+export type TimestampMillis = Branded<bigint, "ts_ms">;
+/** timestamp[us] raw. */
+export type TimestampMicros = Branded<bigint, "ts_us">;
+/** timestamp[ns] raw. */
+export type TimestampNanos = Branded<bigint, "ts_ns">;
+/** duration[s] raw. */
+export type DurationSeconds = Branded<bigint, "dur_s">;
+/** duration[ms] raw. */
+export type DurationMillis = Branded<bigint, "dur_ms">;
+/** duration[us] raw. */
+export type DurationMicros = Branded<bigint, "dur_us">;
+/** duration[ns] raw. */
+export type DurationNanos = Branded<bigint, "dur_ns">;
+/** A decimal's UNSCALED integer (the on-wire representation). */
+export type UnscaledDecimal = Branded<bigint, "decimal_unscaled">;
+/** int64 raw. (Rich int64 is already a plain bigint; the brand makes the
+ *  declared width explicit in raw mode.) */
+export type Int64 = Branded<bigint, "int64">;
+/** uint64 raw. */
+export type Uint64 = Branded<bigint, "uint64">;
+/** date32 days: validated as a 32-bit integer day-number, then branded. */
+export declare function asDate32(days: number): Date32;
+/** date64 ms: validated as a 64-bit integer, then branded. */
+export declare function asDate64Ms(ms: bigint): Date64Ms;
+/** time32[s]. */
+export declare const asTime32S: (n: number) => Time32S;
+/** time32[ms]. */
+export declare const asTime32Ms: (n: number) => Time32Ms;
+/** time64[us]. */
+export declare const asTime64Us: (b: bigint) => Time64Us;
+/** time64[ns]. */
+export declare const asTime64Ns: (b: bigint) => Time64Ns;
+/** timestamp[s]. */
+export declare const asTimestampSeconds: (b: bigint) => TimestampSeconds;
+/** timestamp[ms]. */
+export declare const asTimestampMillis: (b: bigint) => TimestampMillis;
+/** timestamp[us]. */
+export declare const asTimestampMicros: (b: bigint) => TimestampMicros;
+/** timestamp[ns]. */
+export declare const asTimestampNanos: (b: bigint) => TimestampNanos;
+/** duration[s]. */
+export declare const asDurationSeconds: (b: bigint) => DurationSeconds;
+/** duration[ms]. */
+export declare const asDurationMillis: (b: bigint) => DurationMillis;
+/** duration[us]. */
+export declare const asDurationMicros: (b: bigint) => DurationMicros;
+/** duration[ns]. */
+export declare const asDurationNanos: (b: bigint) => DurationNanos;
+/** A decimal's unscaled integer (validated as a bigint, then branded). */
+export declare function asUnscaledDecimal(unscaled: bigint): UnscaledDecimal;
+/** int64 (validated for signed 64-bit range). */
+export declare const asInt64: (b: bigint) => Int64;
+/** uint64 (validated for unsigned 64-bit range). */
+export declare const asUint64: (b: bigint) => Uint64;
+/** Strip a numeric brand, returning the plain `number`. */
+export declare function fromBrandedNumber(v: Branded<number, string>): number;
+/** Strip a bigint brand, returning the plain `bigint`. */
+export declare function fromBrandedBigInt(v: Branded<bigint, string>): bigint;
+/** Generic unbrand for either base type. */
+export declare function fromBranded<Base, Tag extends string>(v: Branded<Base, Tag>): Base;
+export { TimeUnit };

package/dist/arrow/codec/registry.d.ts

@@ -0,0 +1,29 @@
+import type { VgiDataType } from "../types.js";
+/** Codec for a single Arrow type. Converts between the author-facing rich
+ *  representation and the internal canonical pivot. Both directions validate
+ *  and throw on invalid/lossy input. null/undefined pass through as null.
+ *
+ *  (Raw<->canonical conversions are reserved for a later phase. When added they
+ *  belong here as `rawToCanonical` / `canonicalToRaw`.) */
+export interface Codec {
+    /** Human-readable type label, used in error messages. */
+    readonly label: string;
+    /** rich author value -> canonical pivot. */
+    richToCanonical(value: unknown): unknown;
+    /** canonical pivot -> rich author value. */
+    canonicalToRich(value: unknown): unknown;
+    /** branded raw author value -> canonical pivot. Largely identity on the
+     *  underlying number/bigint (raw === canonical for every type), but validates
+     *  and unbrands. Date32/Date64 raw values are plain day-number / ms-bigint,
+     *  so this differs from richToCanonical only in NOT accepting a JS Date. */
+    rawToCanonical(value: unknown): unknown;
+    /** canonical pivot -> branded raw author value. Validates and brands
+     *  (identity at runtime). */
+    canonicalToRaw(value: unknown): unknown;
+}
+/**
+ * Resolve the {@link Codec} for an Arrow type. Dispatches by `typeId` and
+ * reads unit / bitWidth / scale off the type. Composite types recurse into
+ * their child codecs.
+ */
+export declare function codecFor(type: VgiDataType): Codec;

package/dist/arrow/codec/repr.d.ts

@@ -0,0 +1,23 @@
+import type { VgiDataType } from "../types.js";
+import type { TypedField, BoolType, IntType, FloatType, Utf8Type, LargeUtf8Type, BinaryType, LargeBinaryType, FixedSizeBinaryType, DecimalType, Date32Type, Date64Type, Time32Type, Time64Type, TimestampType, DurationType, ListType, FixedSizeListType, StructType, MapType, DictionaryType, NullDescriptor, TUnit } from "./type-descriptors.js";
+import type { Date32, Date64Ms, Time32S, Time32Ms, Time64Us, Time64Ns, TimestampSeconds, TimestampMillis, TimestampMicros, TimestampNanos, DurationSeconds, DurationMillis, DurationMicros, DurationNanos, UnscaledDecimal, Int64, Uint64 } from "./branded.js";
+export type { TypedField };
+/** Representation mode selector. */
+export type Repr = "rich" | "raw";
+type RawTimestamp<U extends TUnit> = U extends "s" ? TimestampSeconds : U extends "ms" ? TimestampMillis : U extends "us" ? TimestampMicros : U extends "ns" ? TimestampNanos : bigint;
+type RawDuration<U extends TUnit> = U extends "s" ? DurationSeconds : U extends "ms" ? DurationMillis : U extends "us" ? DurationMicros : U extends "ns" ? DurationNanos : bigint;
+type RawTime32<U extends "s" | "ms"> = U extends "s" ? Time32S : Time32Ms;
+type RawTime64<U extends "us" | "ns"> = U extends "us" ? Time64Us : Time64Ns;
+type RawInt64<Signed extends boolean | undefined> = Signed extends true ? Int64 : Signed extends false ? Uint64 : bigint;
+/** The default author-facing JS value for the Arrow type `T`. */
+export type RichValue<T extends VgiDataType> = T extends NullDescriptor ? null : T extends BoolType ? boolean : T extends IntType<64, infer _S> ? bigint : T extends IntType<8 | 16 | 32, infer _S> ? number : T extends FloatType ? number : T extends Utf8Type ? string : T extends LargeUtf8Type ? string : T extends BinaryType ? Uint8Array : T extends LargeBinaryType ? Uint8Array : T extends FixedSizeBinaryType ? Uint8Array : T extends DecimalType ? bigint : T extends Date32Type ? Date : T extends Date64Type ? Date : T extends Time32Type<"s" | "ms"> ? number : T extends Time64Type<"us" | "ns"> ? bigint : T extends TimestampType<TUnit> ? bigint : T extends DurationType<TUnit> ? bigint : T extends StructType<infer C> ? RichStruct<C> : T extends ListType<infer E> ? Array<RichValue<E> | null> : T extends FixedSizeListType<infer E> ? Array<RichValue<E> | null> : T extends MapType<infer K, infer V> ? Array<[RichValue<K>, RichValue<V> | null]> : T extends DictionaryType<infer V> ? RichValue<V> : unknown;
+type RichStruct<C extends readonly TypedField<string, VgiDataType>[]> = {
+    [F in C[number] as F["name"]]: RichValue<F["type"]> | null;
+};
+/** The branded `raw` JS value for the Arrow type `T`. */
+export type RawValue<T extends VgiDataType> = T extends NullDescriptor ? null : T extends BoolType ? boolean : T extends IntType<64, infer S> ? RawInt64<S> : T extends IntType<8 | 16 | 32, infer _S> ? number : T extends FloatType ? number : T extends Utf8Type ? string : T extends LargeUtf8Type ? string : T extends BinaryType ? Uint8Array : T extends LargeBinaryType ? Uint8Array : T extends FixedSizeBinaryType ? Uint8Array : T extends DecimalType ? UnscaledDecimal : T extends Date32Type ? Date32 : T extends Date64Type ? Date64Ms : T extends Time32Type<infer U> ? RawTime32<U> : T extends Time64Type<infer U> ? RawTime64<U> : T extends TimestampType<infer U> ? RawTimestamp<U> : T extends DurationType<infer U> ? RawDuration<U> : T extends StructType<infer C> ? RawStruct<C> : T extends ListType<infer E> ? Array<RawValue<E> | null> : T extends FixedSizeListType<infer E> ? Array<RawValue<E> | null> : T extends MapType<infer K, infer V> ? Array<[RawValue<K>, RawValue<V> | null]> : T extends DictionaryType<infer V> ? RawValue<V> : unknown;
+type RawStruct<C extends readonly TypedField<string, VgiDataType>[]> = {
+    [F in C[number] as F["name"]]: RawValue<F["type"]> | null;
+};
+/** The JS value for the Arrow type `T` under representation mode `M`. */
+export type ValueFor<T extends VgiDataType, M extends Repr> = M extends "raw" ? RawValue<T> : RichValue<T>;

package/dist/arrow/codec/type-descriptors.d.ts

@@ -0,0 +1,109 @@
+import type { VgiDataType, VgiField } from "../types.js";
+import { TypeId } from "../predicates.js";
+/** Time/timestamp/duration unit tag (matches the facade `TimeUnit` integers,
+ *  but expressed as a string literal so it can flow through the type level). */
+export type TUnit = "s" | "ms" | "us" | "ns";
+export interface NullDescriptor extends VgiDataType {
+    readonly typeId: typeof TypeId.Null;
+}
+export interface BoolType extends VgiDataType {
+    readonly typeId: typeof TypeId.Bool;
+}
+export interface IntType<BW extends 8 | 16 | 32 | 64, Signed extends boolean> extends VgiDataType {
+    readonly typeId: typeof TypeId.Int;
+    readonly __bitWidth: BW;
+    readonly __signed: Signed;
+}
+export type Int8Type = IntType<8, true>;
+export type Int16Type = IntType<16, true>;
+export type Int32Type = IntType<32, true>;
+export type Int64Type = IntType<64, true>;
+export type Uint8Type = IntType<8, false>;
+export type Uint16Type = IntType<16, false>;
+export type Uint32Type = IntType<32, false>;
+export type Uint64Type = IntType<64, false>;
+export interface FloatType extends VgiDataType {
+    readonly typeId: typeof TypeId.Float;
+}
+export interface Utf8Type extends VgiDataType {
+    readonly typeId: typeof TypeId.Utf8;
+}
+export interface LargeUtf8Type extends VgiDataType {
+    readonly typeId: typeof TypeId.LargeUtf8;
+}
+export interface BinaryType extends VgiDataType {
+    readonly typeId: typeof TypeId.Binary;
+}
+export interface LargeBinaryType extends VgiDataType {
+    readonly typeId: typeof TypeId.LargeBinary;
+}
+export interface FixedSizeBinaryType extends VgiDataType {
+    readonly typeId: typeof TypeId.FixedSizeBinary;
+}
+export interface DecimalType extends VgiDataType {
+    readonly typeId: typeof TypeId.Decimal;
+}
+/** date32 (unit DAY) — days. */
+export interface Date32Type extends VgiDataType {
+    readonly typeId: typeof TypeId.Date;
+    readonly __dateUnit: "day";
+}
+/** date64 (unit MILLISECOND) — ms. */
+export interface Date64Type extends VgiDataType {
+    readonly typeId: typeof TypeId.Date;
+    readonly __dateUnit: "ms";
+}
+/** time32 (bitWidth 32; unit s or ms). */
+export interface Time32Type<U extends "s" | "ms"> extends VgiDataType {
+    readonly typeId: typeof TypeId.Time;
+    readonly __timeBits: 32;
+    readonly __unit: U;
+}
+/** time64 (bitWidth 64; unit us or ns). */
+export interface Time64Type<U extends "us" | "ns"> extends VgiDataType {
+    readonly typeId: typeof TypeId.Time;
+    readonly __timeBits: 64;
+    readonly __unit: U;
+}
+export interface TimestampType<U extends TUnit> extends VgiDataType {
+    readonly typeId: typeof TypeId.Timestamp;
+    readonly __tsUnit: U;
+}
+export interface DurationType<U extends TUnit> extends VgiDataType {
+    readonly typeId: typeof TypeId.Duration;
+    readonly __durUnit: U;
+}
+export interface IntervalType extends VgiDataType {
+    readonly typeId: typeof TypeId.Interval;
+}
+/** A typed field carrying its child's precise descriptor in the static type. */
+export interface TypedField<Name extends string, T extends VgiDataType> extends VgiField {
+    readonly name: Name;
+    readonly type: T;
+}
+export interface ListType<T extends VgiDataType> extends VgiDataType {
+    readonly typeId: typeof TypeId.List;
+    readonly __child?: T;
+}
+export interface FixedSizeListType<T extends VgiDataType> extends VgiDataType {
+    readonly typeId: typeof TypeId.FixedSizeList;
+    readonly __child?: T;
+}
+/** Struct descriptor carrying its children as a tuple of TypedFields so the
+ *  value mapping can build a precise `{ name: value }` shape. */
+export interface StructType<Children extends readonly TypedField<string, VgiDataType>[]> extends VgiDataType {
+    readonly typeId: typeof TypeId.Struct;
+    readonly __children?: Children;
+}
+export interface MapType<K extends VgiDataType, V extends VgiDataType> extends VgiDataType {
+    readonly typeId: typeof TypeId.Map;
+    readonly __key?: K;
+    readonly __value?: V;
+}
+export interface DictionaryType<V extends VgiDataType> extends VgiDataType {
+    readonly typeId: typeof TypeId.Dictionary;
+    readonly __dictValue?: V;
+}
+export interface UnionType extends VgiDataType {
+    readonly typeId: typeof TypeId.Union;
+}

package/dist/arrow/impl-arrowjs/build.d.ts

@@ -0,0 +1,19 @@
+import { RecordBatch, Schema } from "@query-farm/apache-arrow";
+import type { VgiSchema, VgiDataType, VgiColumnData } from "../types.js";
+/**
+ * Build an opaque column-data handle from a JS array. arrow-js wraps
+ * `vectorFromArray` and exposes its first `Data` node. Unlike the public
+ * build path, this is a low-level pass-through used by callers that already
+ * hold backend-native values, so it does NOT run the codec.
+ */
+export declare function columnFromArray(values: any[], type: VgiDataType): VgiColumnData;
+/**
+ * Build a RecordBatch from row objects (values are RICH).
+ */
+export declare function batchFromRows(rows: Record<string, any>[], schema: Schema | VgiSchema): RecordBatch;
+/**
+ * Build a RecordBatch from column arrays (values are RICH). Each column is
+ * converted rich -> canonical via the codec, then canonical -> arrow-js column
+ * data via the canonical writer.
+ */
+export declare function batchFromColumns(columns: Record<string, any[]>, schema: Schema | VgiSchema, repr?: "rich" | "raw"): RecordBatch;

package/dist/arrow/impl-arrowjs/canonical.d.ts

@@ -0,0 +1,15 @@
+import type { VgiDataType, VgiColumnData } from "../types.js";
+/**
+ * Build an arrow-js column `Data` node from an array of CANONICAL values for
+ * `type`. Folds together what used to be scattered across build.ts
+ * (`buildColumnData`, `dateTimeBitWidth`, decimal/bigint/date special-casing).
+ */
+export declare function writeCanonicalColumn(type: VgiDataType, canonical: unknown[]): VgiColumnData;
+/**
+ * Read a single CANONICAL value at `index` from an arrow-js column (Vector).
+ * Reads the underlying typed-array storage for scalars (so it is lossless and
+ * never depends on Vector.get()'s lossy/divergent coercions — e.g. arrow-js
+ * Vector.get() returns a JS number for timestamp[us], losing precision), and
+ * recurses for composites.
+ */
+export declare function readCanonicalValue(type: VgiDataType, column: unknown, index: number): unknown;

package/dist/arrow/impl-arrowjs/empty.d.ts

@@ -0,0 +1,7 @@
+import { RecordBatch, Schema } from "@query-farm/apache-arrow";
+import type { VgiSchema } from "../types.js";
+/**
+ * Create an empty (0-row) batch with the given schema. Accepts arrow-js
+ * `Schema` or facade `VgiSchema` (cast at the boundary).
+ */
+export declare function emptyBatch(schema: Schema | VgiSchema): RecordBatch;

package/dist/arrow/impl-arrowjs/filter.d.ts

@@ -0,0 +1,11 @@
+import { RecordBatch } from "@query-farm/apache-arrow";
+import type { VgiBatch } from "../types.js";
+/**
+ * Filter a RecordBatch using a Uint8Array mask (0=exclude, nonzero=include).
+ * Returns a new batch containing only the rows where mask[i] is nonzero.
+ *
+ * Rows are read in canonical form then mapped back to RICH so the rebuild goes
+ * through the same codec/canonical path as every other column build — lossless
+ * and identical across backends (never the lossy/raw `Vector.get`).
+ */
+export declare function filterBatch(batch: RecordBatch | VgiBatch, mask: Uint8Array): RecordBatch;

package/dist/arrow/impl-arrowjs/index.d.ts

@@ -0,0 +1,11 @@
+import type { VgiBackendInfo } from "../types.js";
+export declare const backend: VgiBackendInfo;
+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, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, } from "./schema.js";
+export { emptyBatch } from "./empty.js";
+export { batchFromRows, batchFromColumns, columnFromArray } from "./build.js";
+export { iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, } from "./iterate.js";
+export { filterBatch } from "./filter.js";
+export { projectSchema, projectBatch } from "./project.js";
+export { readCanonicalValue } from "./canonical.js";
+export { serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./ipc.js";
+export { buildStatisticsBatch, type ColumnStatistics } from "./statistics.js";

package/dist/arrow/impl-arrowjs/ipc.d.ts

@@ -0,0 +1,24 @@
+import { RecordBatch, Schema } from "@query-farm/apache-arrow";
+import type { VgiSchema, VgiBatch } from "../types.js";
+/**
+ * Serialize a Schema to Arrow IPC bytes. Accepts arrow-js `Schema` or
+ * facade `VgiSchema` (the latter is satisfied structurally by arrow-js
+ * Schema instances at runtime).
+ */
+export declare function serializeSchema(schema: Schema | VgiSchema): Uint8Array;
+/**
+ * Deserialize an Arrow Schema from IPC bytes.
+ * Note: In Bun, reader.schema is always undefined, so we must read from the batch.
+ *
+ * Returns arrow-js's `Schema` (which structurally satisfies VgiSchema).
+ */
+export declare function deserializeSchema(bytes: Uint8Array): Schema;
+/**
+ * Serialize a RecordBatch to Arrow IPC bytes. Accepts arrow-js `RecordBatch`
+ * or facade `VgiBatch`.
+ */
+export declare function serializeBatch(batch: RecordBatch | VgiBatch): Uint8Array;
+/**
+ * Deserialize a RecordBatch from Arrow IPC bytes.
+ */
+export declare function deserializeBatch(bytes: Uint8Array): RecordBatch;

package/dist/arrow/impl-arrowjs/iterate.d.ts

@@ -0,0 +1,39 @@
+import { RecordBatch } from "@query-farm/apache-arrow";
+import type { VgiBatch } from "../types.js";
+/**
+ * Iterate rows of a RecordBatch as plain objects, in the RICH representation
+ * (Date for date32/date64; canonical otherwise). Reads via the per-backend
+ * canonical reader (lossless, backend-agnostic) then maps canonical -> rich
+ * through the codec — symmetric with the build path. Accepts arrow-js
+ * `RecordBatch` or facade `VgiBatch`.
+ */
+export declare function iterRows(batch: RecordBatch | VgiBatch, repr?: "rich" | "raw"): Generator<Record<string, any>>;
+/**
+ * Extract single-row batch to a scalar dict, in the RICH representation. Routes
+ * through the canonical reader + codec (same as iterRows) so a temporal/decimal
+ * setting is represented identically to column data and across backends, and so
+ * Dictionary-encoded columns (DuckDB sends these for enum-shaped fields like
+ * SchemaObjectType) are decoded — readCanonicalValue handles dictionary decode.
+ */
+export declare function batchToScalarDict(batch: RecordBatch | VgiBatch | null): Record<string, any>;
+/**
+ * If `value` looks like a Dictionary-encoded Arrow scalar (Vector.get on a
+ * dict column on the apache-arrow fork returns the underlying Data, not the
+ * decoded string), pull out the decoded value at row `index`. Returns
+ * `value` unchanged when it isn't dict-shaped.
+ *
+ * Used at handler call sites where the incoming `params` came from the RPC
+ * layer's row extractor (which doesn't auto-decode dictionaries) and the
+ * handler needs the plain string.
+ */
+export declare function decodeDictValue(value: any, index?: number): any;
+/**
+ * Extract single-row batch to a secret dict (column per secret, each value is a struct).
+ * Handles both named secrets (column name = secret type) and scoped secrets
+ * (column name = "secret_N" with secret_type in field metadata).
+ */
+export declare function batchToSecretDict(batch: RecordBatch | VgiBatch | null): Record<string, Record<string, any>>;
+/**
+ * Safe number coercion for BigInt values.
+ */
+export declare function safeNumber(value: any): number;

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

@@ -0,0 +1,10 @@
+import { RecordBatch, Schema } from "@query-farm/apache-arrow";
+import type { VgiSchema, VgiBatch } from "../types.js";
+/**
+ * Project a schema by column indices, preserving only selected fields.
+ */
+export declare function projectSchema(projectionIds: number[] | null, schema: Schema | VgiSchema): Schema;
+/**
+ * Project a RecordBatch by column indices.
+ */
+export declare function projectBatch(projectionIds: number[] | null, batch: RecordBatch | VgiBatch): RecordBatch;

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

@@ -0,0 +1,62 @@
+import { DateUnit as A_DateUnit, TimeUnit as A_TimeUnit, IntervalUnit as A_IntervalUnit, UnionMode as A_UnionMode } from "@query-farm/apache-arrow";
+import type { VgiField, VgiSchema, VgiDataType } from "../types.js";
+export declare const TimeUnit: {
+    readonly SECOND: A_TimeUnit.SECOND;
+    readonly MILLISECOND: A_TimeUnit.MILLISECOND;
+    readonly MICROSECOND: A_TimeUnit.MICROSECOND;
+    readonly NANOSECOND: A_TimeUnit.NANOSECOND;
+};
+export declare const DateUnit: {
+    readonly DAY: A_DateUnit.DAY;
+    readonly MILLISECOND: A_DateUnit.MILLISECOND;
+};
+export declare const IntervalUnit: {
+    readonly YEAR_MONTH: A_IntervalUnit.YEAR_MONTH;
+    readonly DAY_TIME: A_IntervalUnit.DAY_TIME;
+    readonly MONTH_DAY_NANO: A_IntervalUnit.MONTH_DAY_NANO;
+};
+export declare const UnionMode: {
+    readonly Sparse: A_UnionMode.Sparse;
+    readonly Dense: A_UnionMode.Dense;
+};
+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 function 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: (byteWidth: 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-arrowjs/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/impl-flechette/build.d.ts

@@ -0,0 +1,14 @@
+import type { VgiSchema, VgiBatch, VgiDataType, VgiColumnData } from "../types.js";
+/**
+ * Build an opaque column-data handle from a JS array. Low-level pass-through
+ * for callers that already hold backend-native values; does NOT run the codec.
+ */
+export declare function columnFromArray(values: any[], type: VgiDataType): VgiColumnData;
+/** Build a batch from row objects (values are RICH). */
+export declare function batchFromRows(rows: Record<string, any>[], schema: VgiSchema): VgiBatch;
+/**
+ * Build a batch from column arrays (values are RICH). Each column is converted
+ * rich -> canonical via the codec, then the canonical batch writer assembles
+ * the flechette Table (preserving per-field nullable + metadata).
+ */
+export declare function batchFromColumns(columns: Record<string, any[]>, schema: VgiSchema, repr?: "rich" | "raw"): VgiBatch;

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

@@ -0,0 +1,18 @@
+import type { VgiSchema, VgiBatch, VgiDataType, VgiColumnData } from "../types.js";
+/** Build a flechette `Column` from an array of CANONICAL values for `type`. */
+export declare function writeCanonicalColumn(type: VgiDataType, canonical: unknown[]): VgiColumnData;
+/**
+ * Build a whole batch (Table) from canonical column arrays. Kept here so the
+ * per-field `nullable` flag and metadata are preserved on the output schema
+ * (tableFromColumns would drop them, which the C++ extension rejects).
+ */
+export declare function writeCanonicalBatch(columns: Record<string, unknown[]>, schema: VgiSchema, numRows: number): VgiBatch;
+/**
+ * Convert canonical values into the shape flechette's columnFromArray needs.
+ * Date columns: canonical day-number / ms-bigint -> JS Date. Map columns:
+ * canonical Array<[k,v]> -> Map. Struct/List recurse. Everything else passes
+ * through.
+ */
+export declare function prepareForFlechette(type: VgiDataType, values: unknown[]): unknown[];
+/** Read a single CANONICAL value at `index` from a flechette Column. */
+export declare function readCanonicalValue(type: VgiDataType, column: unknown, index: number): unknown;

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

@@ -0,0 +1,9 @@
+import type { VgiSchema, VgiBatch } from "../types.js";
+/**
+ * Create an empty (0-row) batch with the given schema.
+ *
+ * For each field we build a 0-length column of the matching type. flechette
+ * handles complex types (List, Map, Struct, Decimal) without the manual
+ * makeData scaffolding the arrow-js backend needs.
+ */
+export declare function emptyBatch(schema: VgiSchema): VgiBatch;

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

@@ -0,0 +1,10 @@
+import type { VgiBatch } from "../types.js";
+/**
+ * Filter a batch using a Uint8Array mask (0=exclude, nonzero=include).
+ *
+ * Rows are read in canonical form then mapped back to RICH so the rebuild goes
+ * through the same codec/canonical path as every other column build — lossless,
+ * Date-correct (flechette `.at()` returns epoch-ms for dates), and identical to
+ * the arrow-js backend.
+ */
+export declare function filterBatch(batch: VgiBatch, mask: Uint8Array): VgiBatch;

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

@@ -0,0 +1,11 @@
+import type { VgiBackendInfo } from "../types.js";
+export declare const backend: VgiBackendInfo;
+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, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, } from "./schema.js";
+export { emptyBatch } from "./empty.js";
+export { batchFromRows, batchFromColumns, columnFromArray } from "./build.js";
+export { iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, } from "./iterate.js";
+export { filterBatch } from "./filter.js";
+export { projectSchema, projectBatch } from "./project.js";
+export { readCanonicalValue } from "./canonical.js";
+export { serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./ipc.js";
+export { buildStatisticsBatch, type ColumnStatistics } from "./statistics.js";

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

@@ -0,0 +1,33 @@
+import type { VgiSchema, VgiBatch } from "../types.js";
+/**
+ * Serialize a Schema to Arrow IPC bytes.
+ *
+ * flechette has no schema-only serialization helper, so we encode an empty
+ * 0-row table that carries just the schema header. Decoders see the Schema
+ * + an immediate EOS marker — same wire shape arrow-js's
+ * `RecordBatchStreamWriter.close()` produces for an empty stream.
+ */
+export declare function serializeSchema(schema: VgiSchema): Uint8Array;
+/**
+ * Deserialize an Arrow Schema from IPC bytes. Returns the schema of the
+ * decoded table (which may be 0-row if the source was a schema-only stream).
+ */
+export declare function deserializeSchema(bytes: Uint8Array): VgiSchema;
+/**
+ * Serialize a RecordBatch to Arrow IPC bytes (stream format).
+ *
+ * The batch passed in is structurally a flechette Table (1 record batch's
+ * worth of data). flechette's `tableToIPC` round-trips it as a complete
+ * stream — schema + one batch + EOS — which is what subprocess transport
+ * consumers expect per call.
+ */
+export declare function serializeBatch(batch: VgiBatch): Uint8Array;
+/**
+ * Deserialize a RecordBatch from Arrow IPC bytes.
+ *
+ * We treat the decoded Table as the "batch" — flechette Tables expose
+ * numRows / schema / getChild that satisfy VgiBatch's shape. For
+ * multi-batch streams this collapses to a single logical batch, matching
+ * the subprocess transport's one-batch-per-call convention.
+ */
+export declare function deserializeBatch(bytes: Uint8Array): VgiBatch;

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

@@ -0,0 +1,29 @@
+import type { VgiBatch } from "../types.js";
+/**
+ * Iterate rows of a batch (flechette Table) as plain objects, in the RICH
+ * representation (Date for date32/date64; canonical otherwise). Reads via the
+ * per-backend canonical reader then maps canonical -> rich through the codec —
+ * symmetric with the build path and identical to the arrow-js backend.
+ */
+export declare function iterRows(batch: VgiBatch, repr?: "rich" | "raw"): Generator<Record<string, any>>;
+/**
+ * Extract a single-row batch as a flat dict { col: value }, in the RICH
+ * representation. Routes through the canonical reader + codec (same as iterRows)
+ * so a temporal/decimal setting is represented identically to column data and
+ * identically to the arrow-js backend.
+ */
+export declare function batchToScalarDict(batch: VgiBatch | null): Record<string, any>;
+/**
+ * No-op for flechette: dictionary columns auto-decode at extraction time.
+ * Provided for parity with impl-arrowjs (where the apache-arrow fork doesn't
+ * auto-decode in some paths).
+ */
+export declare function decodeDictValue(value: any, _index?: number): any;
+/**
+ * Single-row batch → secret dict. Mirrors impl-arrowjs's same-named function.
+ */
+export declare function batchToSecretDict(batch: VgiBatch | null): Record<string, Record<string, any>>;
+/**
+ * BigInt → number coercion (lossy for values past 2^53).
+ */
+export declare function safeNumber(value: any): number;

package/dist/arrow/impl-flechette/message-meta.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Walk an Arrow IPC stream and return the first RecordBatch message's
+ * (numRows, metadata) — the bits flechette drops on the floor.
+ *
+ * Returns null if the stream contains no RecordBatch.
+ */
+export declare function readFirstRecordBatchMeta(stream: Uint8Array): {
+    numRows: number;
+    metadata: Map<string, string>;
+} | null;