@query-farm/vgi 0.6.0

package/src/arrow/codec/repr.ts

@@ -0,0 +1,181 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// Type-level value mapping — phase 3.
+//
+// Given the precise static descriptor for an Arrow type (see
+// ./type-descriptors.ts), `RichValue<T>` / `RawValue<T>` / `ValueFor<T, M>`
+// compute the exact JS value that type represents in the `rich` (default) and
+// `raw` (branded) representations. These mirror the runtime codec rules:
+//
+//   rich  = canonical EXCEPT date32/date64 -> JS Date.
+//   raw   = canonical, but with branded aliases that carry the wire unit.
+//
+// struct/list/map recurse. Corners that are genuinely ambiguous at the type
+// level (union; an Int/Decimal/Timestamp built through a non-literal factory
+// such as `int(bitWidth)` or `timestamp(unit)` with a runtime `number` unit)
+// degrade to the canonical/`unknown` value and are noted inline.
+
+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";
+
+// Re-export TypedField for callers building struct value shapes manually.
+export type { TypedField };
+
+/** Representation mode selector. */
+export type Repr = "rich" | "raw";
+
+// ---------------------------------------------------------------------------
+// Per-unit branded selectors (raw mode)
+// ---------------------------------------------------------------------------
+
+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;
+
+// 64-bit int brands. The descriptor's `__signed` phantom picks signed vs
+// unsigned; anything else (e.g. a non-literal `int(64)`) falls back to bigint.
+type RawInt64<Signed extends boolean | undefined> = Signed extends true
+  ? Int64
+  : Signed extends false
+    ? Uint64
+    : bigint;
+
+// ---------------------------------------------------------------------------
+// RichValue<T>
+// ---------------------------------------------------------------------------
+
+/** 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 :
+  // date32 / date64 -> JS Date (the ONLY rich != canonical case)
+  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;
+};
+
+// ---------------------------------------------------------------------------
+// RawValue<T>
+// ---------------------------------------------------------------------------
+
+/** 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;
+};
+
+// ---------------------------------------------------------------------------
+// ValueFor<T, M>
+// ---------------------------------------------------------------------------
+
+/** 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/src/arrow/codec/type-descriptors.ts

@@ -0,0 +1,137 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// Precise NOMINAL static type descriptors for Arrow types — phase 3.
+//
+// These interfaces are the compile-time face of the runtime `VgiDataType`
+// values built by the facade factories (see ../schema-types.ts). Each carries
+// a LITERAL `typeId` (and `unit` / `bitWidth` / child shape where relevant) so
+// the type-level mapping in ./repr.ts can recover the exact JS value a type
+// represents in `rich` vs `raw` mode.
+//
+// They are purely structural over `VgiDataType` (`{ readonly typeId }`): the
+// runtime value is unchanged — the facade factories just cast their return to
+// the matching descriptor (`new A_Int64() as unknown as Int64Type`), so both
+// the arrow-js and flechette backends report IDENTICAL static types from the
+// facade while keeping their native runtime values.
+
+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";
+
+// ---------------------------------------------------------------------------
+// Scalar descriptors
+// ---------------------------------------------------------------------------
+
+export interface NullDescriptor extends VgiDataType { readonly typeId: typeof TypeId.Null; }
+export interface BoolType extends VgiDataType { readonly typeId: typeof TypeId.Bool; }
+
+// The width/sign discriminants are REQUIRED phantom properties (they don't
+// exist at runtime — factories cast through `as unknown as` — but being
+// required lets the conditional types in ./repr.ts discriminate int widths
+// cleanly; optional phantoms collapse `IntType<64>` into the number arm).
+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; }
+
+// As with IntType, the unit/width discriminants below are REQUIRED phantom
+// properties so the conditional value mappings in ./repr.ts can tell apart
+// date32/date64, time32/time64, and the timestamp/duration units. They are
+// type-only (factories cast through `as unknown as`).
+
+/** 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; }
+
+// ---------------------------------------------------------------------------
+// Composite descriptors
+// ---------------------------------------------------------------------------
+
+/** 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/src/arrow/impl-arrowjs/build.ts

@@ -0,0 +1,88 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Build Arrow RecordBatches from row objects or column arrays (arrow-js).
+//
+// The public build path routes RICH author values through the codec registry
+// (rich -> canonical) and then through the per-backend canonical writer
+// (canonical -> arrow-js column data). All the arrow-js-specific assembly that
+// used to live here now lives in ./canonical.ts; this file is just the public
+// shape (batchFromRows / batchFromColumns / columnFromArray).
+
+import {
+  RecordBatch,
+  Schema,
+  Field,
+  Struct,
+  DataType,
+  makeData,
+  vectorFromArray,
+} from "@query-farm/apache-arrow";
+import type { VgiSchema, VgiDataType, VgiColumnData } from "../types.js";
+import { emptyBatch } from "./empty.js";
+import { codecFor } from "../codec/registry.js";
+import { writeCanonicalColumn } from "./canonical.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 function columnFromArray(values: any[], type: VgiDataType): VgiColumnData {
+  return vectorFromArray(values, type as DataType).data[0] as VgiColumnData;
+}
+
+/**
+ * Build a RecordBatch from row objects (values are RICH).
+ */
+export function batchFromRows(
+  rows: Record<string, any>[],
+  schema: Schema | VgiSchema,
+): RecordBatch {
+  const a = schema as Schema;
+  if (rows.length === 0) {
+    return emptyBatch(a);
+  }
+  const columns: Record<string, any[]> = {};
+  for (const field of a.fields) {
+    columns[field.name] = rows.map((r) => r[field.name] ?? null);
+  }
+  return batchFromColumns(columns, a);
+}
+
+/**
+ * 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 function batchFromColumns(
+  columns: Record<string, any[]>,
+  schema: Schema | VgiSchema,
+  repr: "rich" | "raw" = "rich",
+): RecordBatch {
+  const a = schema as Schema;
+  const numRows =
+    a.fields.length > 0
+      ? columns[a.fields[0].name]?.length ?? 0
+      : 0;
+
+  const children = a.fields.map((f: Field) => {
+    const values = columns[f.name];
+    if (!values) {
+      return makeData({ type: f.type, length: numRows, nullCount: numRows });
+    }
+    const codec = codecFor(f.type as VgiDataType);
+    const toCanon = repr === "raw" ? codec.rawToCanonical : codec.richToCanonical;
+    const canonical = values.map((v) => toCanon.call(codec, v));
+    return writeCanonicalColumn(f.type as VgiDataType, canonical);
+  });
+
+  const structType = new Struct(a.fields);
+  const data = makeData({
+    type: structType,
+    length: numRows,
+    children: children as any,
+    nullCount: 0,
+  });
+
+  return new RecordBatch(a, data);
+}