@query-farm/vgi-rpc 0.6.3 → 0.7.0

package/src/util/zstd.ts

@@ -4,40 +4,159 @@
 /**
  * Cross-runtime zstd compression/decompression.
  *
- * Uses Bun.zstd* when running on Bun, otherwise falls back to node:zlib
- * (available on Node.js 22.15+ and Deno 2.6.9+).
+ * Decompression order of preference: Bun.zstd → node:zlib zstd (Node 22.15+,
+ * Deno 2.6.9+) → fzstd pure-JS fallback. The fzstd fallback exists so
+ * Cloudflare workerd — which has no native zstd — can still decode
+ * `Content-Encoding: zstd` request bodies (the DuckDB VGI extension always
+ * sends them). fzstd is decompression-only, so compression on workerd still
+ * throws.
  */
 
-import * as zlib from "node:zlib";
+import { decompress as fzstdDecompress } from "fzstd";
 
+// Resolve node:zlib via indirect-string require so esbuild/wrangler can't
+// trace it statically. On workerd we want the fzstd path, not a node:zlib
+// import that wouldn't have zstd anyway.
+const _NODE_ZLIB_MOD = "node:zlib";
 const isBun = typeof globalThis.Bun !== "undefined";
+function _loadZlibOrNull(): any | null {
+  const req: any = (import.meta as any).require ?? (globalThis as any).require ?? null;
+  if (!req) return null;
+  try {
+    return req(_NODE_ZLIB_MOD);
+  } catch {
+    return null;
+  }
+}
+
+/** Return true when the current runtime can produce zstd-compressed output.
+ *
+ *  Bun has `Bun.zstdCompressSync`; Node ≥22.15 / Deno ≥2.6.9 expose it via
+ *  `node:zlib`. Other runtimes (workerd, older Node) have no encoder. The
+ *  fzstd fallback is decompress-only so it doesn't count.
+ */
+export function isZstdCompressAvailable(): boolean {
+  if (isBun) return true;
+  const zlib = _loadZlibOrNull();
+  return typeof zlib?.zstdCompressSync === "function";
+}
 
 /** Compress data with zstd at the given level (1-22). */
-export function zstdCompress(data: Uint8Array, level: number): Uint8Array<ArrayBuffer> {
+export async function zstdCompress(data: Uint8Array, level: number): Promise<Uint8Array<ArrayBuffer>> {
   if (isBun) {
     return new Uint8Array(Bun.zstdCompressSync(data, { level }));
   }
-  const fn = (zlib as any).zstdCompressSync;
+  const zlib = _loadZlibOrNull();
+  const fn = zlib?.zstdCompressSync;
   if (typeof fn !== "function") {
-    throw new Error("zstd is not available in this runtime. " + "Requires Bun, Node.js >= 22.15, or Deno >= 2.6.9.");
+    throw new Error(
+      "zstd compression is not available in this runtime. " +
+        "Requires Bun or Node.js >= 22.15 / Deno >= 2.6.9. " +
+        "(workerd has no native zstd encoder; fzstd is decompress-only.)",
+    );
   }
   return new Uint8Array(
     fn(data, {
       params: {
-        [(zlib.constants as any).ZSTD_c_compressionLevel]: level,
+        [zlib.constants.ZSTD_c_compressionLevel]: level,
       },
     }),
   );
 }
 
-/** Decompress zstd-compressed data. */
-export function zstdDecompress(data: Uint8Array): Uint8Array<ArrayBuffer> {
+/**
+ * Decompress zstd-compressed data, optionally bounding the output size.
+ *
+ * Zstd frames carry the decompressed size in the header and decompressors
+ * trust it eagerly: a ~3 KB compressed body claiming 100 MB output would
+ * allocate 100 MB. When `maxOutputSize` is supplied, this helper:
+ *
+ * 1. Reads `Frame_Content_Size` from the frame header. If declared and
+ *    above the cap, refuses *before* allocation with a clear error.
+ * 2. Decompresses, then asserts the actual output size is also under the
+ *    cap (covers frames whose size is not in the header — a streaming
+ *    cap would be tighter, but neither Bun.zstdDecompressSync nor
+ *    node:zlib's sync API exposes one, so we use the post-check).
+ *
+ * Mirrors the Python server-side fix in `_decompress_body` and the
+ * client-side fix in `external_fetch.fetch_url`.
+ */
+export async function zstdDecompress(data: Uint8Array, maxOutputSize?: number): Promise<Uint8Array<ArrayBuffer>> {
+  if (maxOutputSize != null) {
+    const declared = readZstdFrameContentSize(data);
+    if (declared !== null && declared > maxOutputSize) {
+      throw new Error(`zstd decompressed size (${declared}) would exceed cap (${maxOutputSize})`);
+    }
+  }
+
+  let out: Uint8Array<ArrayBuffer>;
   if (isBun) {
-    return new Uint8Array(Bun.zstdDecompressSync(data));
+    out = new Uint8Array(Bun.zstdDecompressSync(data));
+  } else {
+    const zlib = _loadZlibOrNull();
+    const fn = zlib?.zstdDecompressSync;
+    if (typeof fn === "function") {
+      out = new Uint8Array(fn(data));
+    } else {
+      // workerd path: no native zstd, fall back to the pure-JS decoder.
+      // fzstd is decompress-only and synchronous; cap-checking already ran
+      // above against the frame header, but pure-JS decode of large inputs
+      // is slow — keep the upstream maxOutputSize tight.
+      //
+      // CRITICAL: copy into a freshly-allocated ArrayBuffer so byteOffset is
+      // 0. fzstd internally returns subarray views with arbitrary byteOffset
+      // (often not 8-aligned), and downstream Arrow IPC readers create
+      // BigInt64Array views relative to the buffer's byteOffset — those
+      // throw `start offset of BigInt64Array should be a multiple of 8` if
+      // the underlying offset isn't 8-aligned.
+      const decoded = fzstdDecompress(data);
+      out = new Uint8Array(decoded.byteLength);
+      out.set(decoded);
+    }
   }
-  const fn = (zlib as any).zstdDecompressSync;
-  if (typeof fn !== "function") {
-    throw new Error("zstd is not available in this runtime. " + "Requires Bun, Node.js >= 22.15, or Deno >= 2.6.9.");
+
+  if (maxOutputSize != null && out.byteLength > maxOutputSize) {
+    throw new Error(`zstd decompressed size (${out.byteLength}) exceeds cap (${maxOutputSize})`);
+  }
+  return out;
+}
+
+/**
+ * Parse `Frame_Content_Size` from a zstd frame header.
+ *
+ * Returns the declared decompressed size, or `null` if the frame header
+ * does not include it (frames may omit it for streaming compression) or
+ * the input is too short / not a valid zstd frame magic.
+ *
+ * Frame format (RFC 8478): magic(4) | FHD(1) | window_desc(0|1) |
+ * dict_id(0|1|2|4) | frame_content_size(0|1|2|4|8). FCS_size depends on
+ * FCS_field_size (FHD bits 6-7) and Single_Segment_flag (FHD bit 5).
+ */
+function readZstdFrameContentSize(data: Uint8Array): number | null {
+  if (data.length < 6) return null;
+  // Magic: 0xFD2FB528 little-endian.
+  if (data[0] !== 0x28 || data[1] !== 0xb5 || data[2] !== 0x2f || data[3] !== 0xfd) {
+    return null;
+  }
+  const fhd = data[4];
+  const fcsFieldSize = (fhd >> 6) & 0x3;
+  const singleSegment = ((fhd >> 5) & 0x1) === 1;
+  const dictIdFlag = fhd & 0x3;
+  // Per spec: FCS_size = 0 → 0 unless Single_Segment_flag is set, then 1.
+  const fcsSize = fcsFieldSize === 0 ? (singleSegment ? 1 : 0) : fcsFieldSize === 1 ? 2 : fcsFieldSize === 2 ? 4 : 8;
+  if (fcsSize === 0) return null;
+
+  const windowDescSize = singleSegment ? 0 : 1;
+  const dictIdSize = dictIdFlag === 0 ? 0 : dictIdFlag === 1 ? 1 : dictIdFlag === 2 ? 2 : 4;
+  const fcsOffset = 5 + windowDescSize + dictIdSize;
+  if (data.length < fcsOffset + fcsSize) return null;
+
+  let fcs = 0n;
+  for (let i = 0; i < fcsSize; i++) {
+    fcs |= BigInt(data[fcsOffset + i]) << BigInt(i * 8);
   }
-  return new Uint8Array(fn(data));
+  // FCS_field_size == 1 (size 2) carries an offset of 256.
+  if (fcsSize === 2) fcs += 256n;
+  if (fcs > BigInt(Number.MAX_SAFE_INTEGER)) return Number.MAX_SAFE_INTEGER;
+  return Number(fcs);
 }

package/src/wire/opaque.ts

@@ -0,0 +1,37 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  isDate,
+  isDecimal,
+  isDictionary,
+  isDuration,
+  isFixedSizeBinary,
+  isLargeBinary,
+  isLargeUtf8,
+  isTime,
+  isTimestamp,
+  type VgiDataType,
+} from "../arrow/index.js";
+
+/**
+ * Arrow types whose `.get(0)` / `vectorFromArray` round-trips are unreliable
+ * in arrow-js. For these we extract and re-emit the underlying `Data` object
+ * directly (passthrough), like we already do for Map_.
+ *
+ * Covers Date/Time/Timestamp/Duration/Decimal/LargeUtf8/LargeBinary/
+ * FixedSizeBinary/Dictionary.
+ */
+export function isOpaquePassthroughType(type: VgiDataType): boolean {
+  return (
+    isDate(type) ||
+    isTime(type) ||
+    isTimestamp(type) ||
+    isDuration(type) ||
+    isDecimal(type) ||
+    isLargeUtf8(type) ||
+    isLargeBinary(type) ||
+    isFixedSizeBinary(type) ||
+    isDictionary(type)
+  );
+}

package/src/wire/reader.ts

@@ -2,10 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { type RecordBatch, RecordBatchReader, type Schema } from "@query-farm/apache-arrow";
+import type { VgiBatch, VgiSchema } from "../arrow/index.js";
 
 export interface StreamMessage {
-  schema: Schema;
-  batches: RecordBatch[];
+  schema: VgiSchema;
+  batches: VgiBatch[];
 }
 
 /**
@@ -68,7 +69,7 @@ export class IpcStreamReader {
    * Use readNextBatch() to read batches one at a time.
    * Returns null on EOF.
    */
-  async openNextStream(): Promise<Schema | null> {
+  async openNextStream(): Promise<VgiSchema | null> {
     if (this.initialized) {
       await this.reader.reset().open();
       if (this.reader.closed) {
@@ -88,7 +89,7 @@ export class IpcStreamReader {
    * reading from the underlying byte source. This prevents the Arrow-JS
    * reader from consuming bytes that belong to the next IPC stream.
    */
-  async readNextBatch(): Promise<RecordBatch | null> {
+  async readNextBatch(): Promise<VgiBatch | null> {
     if (this.streamEnded) return null;
     const result = await this.reader.next();
     if (result.done) {

package/src/wire/request.ts

@@ -1,15 +1,16 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-import { DataType, type RecordBatch, type Schema } from "@query-farm/apache-arrow";
+import { backend, isMap, type VgiBatch, type VgiSchema } from "../arrow/index.js";
 import { REQUEST_ID_KEY, REQUEST_VERSION, REQUEST_VERSION_KEY, RPC_METHOD_KEY } from "../constants.js";
 import { RpcError, VersionError } from "../errors.js";
+import { isOpaquePassthroughType } from "./opaque.js";
 
 export interface ParsedRequest {
   methodName: string;
   requestVersion: string;
   requestId: string | null;
-  schema: Schema;
+  schema: VgiSchema;
   params: Record<string, any>;
   rawMetadata: Map<string, string>;
 }
@@ -18,7 +19,7 @@ export interface ParsedRequest {
  * Parse a request from a RecordBatch with metadata.
  * Extracts method name, version, and params from the batch.
  */
-export function parseRequest(schema: Schema, batch: RecordBatch): ParsedRequest {
+export function parseRequest(schema: VgiSchema, batch: VgiBatch): ParsedRequest {
   const metadata: Map<string, string> = batch.metadata ?? new Map();
 
   const methodName = metadata.get(RPC_METHOD_KEY);
@@ -59,16 +60,54 @@ export function parseRequest(schema: Schema, batch: RecordBatch): ParsedRequest
     );
   }
 
+  // Map_ + Date/Time/Timestamp/Duration/Decimal/LargeUtf8/LargeBinary/
+  // FixedSizeBinary/Dictionary all need passthrough on arrow-js because
+  // its `.get(0)` round-trip is unreliable for those types. On flechette
+  // those same types extract cleanly via `col.get(0)`, and `col.data[0]`
+  // is a Batch (not a Data) so the arrow-js passthrough trick doesn't
+  // apply. The backend advertises whether passthrough is needed.
+  const useOpaquePassthrough = backend.opaquePassthrough;
   for (let i = 0; i < schema.fields.length; i++) {
     const field = schema.fields[i];
-    // Map_ columns have a broken .get() in arrow-js — pass through raw Data
-    if (DataType.isMap(field.type)) {
-      params[field.name] = batch.getChildAt(i)!.data[0];
+    if (useOpaquePassthrough && (isMap(field.type) || isOpaquePassthroughType(field.type))) {
+      const col = batch.getChildAt(i)!;
+      params[field.name] = (col as any).data?.[0] ?? col.get(0);
       continue;
     }
     let value = batch.getChildAt(i)?.get(0);
-    // Convert BigInt to Number when safe
-    if (typeof value === "bigint") {
+    // Normalize arrow-js DecimalBigNum wrappers to primitive BigInt.
+    //
+    // TODO: remove once the stdio transport reads through a facade-aware
+    // reader. The stdio reader is arrow-js-coupled (the facade exposes no
+    // streaming reader), so under the flechette facade we still receive
+    // arrow-js batches; an opaque Decimal column then yields a
+    // `DecimalBigNum` (a Uint32Array subclass whose `.toString()` is the
+    // numeric value). Downstream construction goes through the flechette
+    // facade and expects a primitive — without this the encoder treats the
+    // BigNum as a Number and loses precision.
+    //
+    // Detect structurally via `instanceof Uint32Array` rather than by
+    // constructor name (which minifies away): DecimalBigNum is the only
+    // opaque type whose `.get(0)` returns a Uint32Array, so this also
+    // excludes binary `Uint8Array` values from being mis-parsed as BigInt.
+    if (value instanceof Uint32Array && isOpaquePassthroughType(field.type)) {
+      // BigInt(decimalBigNum) triggers arrow-js's
+      // Symbol.toPrimitive('number') path which throws for values
+      // outside the safe-integer range. Go through `.toString()`
+      // instead — it handles arbitrary precision.
+      try {
+        value = BigInt((value as unknown as { toString(): string }).toString());
+      } catch {
+        // leave as-is on unexpected shape
+      }
+    }
+    // Convert BigInt to Number when safe — but NOT for types whose
+    // BigInt-encoded value is type-scaled (Decimal: unscaled integer;
+    // Date32: ms-since-epoch; Timestamp/Time/Duration: native-unit
+    // ticks). Re-encoding a Number where a BigInt is expected would
+    // make the builder apply a `*scale` multiplication (Decimal) or
+    // `* 10^unit` (Time/Timestamp), corrupting the value.
+    if (typeof value === "bigint" && !isOpaquePassthroughType(field.type)) {
       if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
         value = Number(value);
       }
@@ -85,3 +124,23 @@ export function parseRequest(schema: Schema, batch: RecordBatch): ParsedRequest
     rawMetadata: metadata,
   };
 }
+
+/**
+ * Fill in `defaults` for any params that arrived as null/undefined.
+ * The slim DESCRIBE_VERSION 4 wire format no longer carries defaults to the
+ * client, so default substitution must happen server-side: the client sends
+ * a null in any column it didn't supply, and dispatch swaps in the registered
+ * default before invoking the handler.
+ */
+export function applyDefaults(
+  params: Record<string, any>,
+  defaults: Record<string, any> | undefined,
+): Record<string, any> {
+  if (!defaults) return params;
+  for (const key of Object.keys(defaults)) {
+    if (params[key] == null) {
+      params[key] = defaults[key];
+    }
+  }
+  return params;
+}

package/src/wire/response.ts

@@ -2,32 +2,36 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import {
-  Data,
-  DataType,
-  type Field,
-  makeData,
-  RecordBatch,
-  type Schema,
-  Struct,
-  vectorFromArray,
-} from "@query-farm/apache-arrow";
-import { LOG_EXTRA_KEY, LOG_LEVEL_KEY, LOG_MESSAGE_KEY, REQUEST_ID_KEY, SERVER_ID_KEY } from "../constants.js";
+  emptyBatchWithMetadata,
+  isInt,
+  singleRowBatchWithMetadata,
+  type VgiBatch,
+  type VgiSchema,
+} from "../arrow/index.js";
+import {
+  ERROR_KIND_KEY,
+  LOG_EXTRA_KEY,
+  LOG_LEVEL_KEY,
+  LOG_MESSAGE_KEY,
+  REQUEST_ID_KEY,
+  SERVER_ID_KEY,
+} from "../constants.js";
 
 /**
  * Coerce values for Int64 schema fields from Number to BigInt.
  * Handles both single values and arrays. Returns a new record with coerced values.
  */
-export function coerceInt64(schema: Schema, values: Record<string, any>): Record<string, any> {
+export function coerceInt64(schema: VgiSchema, values: Record<string, any>): Record<string, any> {
   const result: Record<string, any> = { ...values };
-  for (const field of schema.fields) {
-    const val = result[field.name];
+  for (const f of schema.fields) {
+    const val = result[f.name];
     if (val === undefined) continue;
-    if (!DataType.isInt(field.type) || (field.type as any).bitWidth !== 64) continue;
+    if (!isInt(f.type) || (f.type as any).bitWidth !== 64) continue;
 
     if (Array.isArray(val)) {
-      result[field.name] = val.map((v: any) => (typeof v === "number" ? BigInt(v) : v));
+      result[f.name] = val.map((v: any) => (typeof v === "number" ? BigInt(v) : v));
     } else if (typeof val === "number") {
-      result[field.name] = BigInt(val);
+      result[f.name] = BigInt(val);
     }
   }
   return result;
@@ -38,11 +42,11 @@ export function coerceInt64(schema: Schema, values: Record<string, any>): Record
  * For unary methods, `values` maps field names to single values.
  */
 export function buildResultBatch(
-  schema: Schema,
+  schema: VgiSchema,
   values: Record<string, any>,
   serverId: string,
   requestId: string | null,
-): RecordBatch {
+): VgiBatch {
   const metadata = new Map<string, string>();
   metadata.set(SERVER_ID_KEY, serverId);
   if (requestId !== null) {
@@ -54,49 +58,48 @@ export function buildResultBatch(
   }
 
   // Validate required fields
-  for (const field of schema.fields) {
-    if (values[field.name] === undefined && !field.nullable) {
+  for (const f of schema.fields) {
+    if (values[f.name] === undefined && !f.nullable) {
       const got = Object.keys(values);
-      throw new TypeError(`Handler result missing required field '${field.name}'. Got keys: [${got.join(", ")}]`);
+      throw new TypeError(`Handler result missing required field '${f.name}'. Got keys: [${got.join(", ")}]`);
     }
   }
 
   const coerced = coerceInt64(schema, values);
-
-  const children = schema.fields.map((f: Field) => {
-    const val = coerced[f.name];
-    // Raw Data passthrough for Map_ types (whose .get() is broken in arrow-js)
-    if (val instanceof Data) {
-      return val;
-    }
-    const arr = vectorFromArray([val], f.type);
-    return arr.data[0];
-  });
-
-  const structType = new Struct(schema.fields);
-  const data = makeData({
-    type: structType,
-    length: 1,
-    children,
-    nullCount: 0,
-  });
-
-  return new RecordBatch(schema, data, metadata);
+  return singleRowBatchWithMetadata(schema, coerced, metadata);
 }
 
 /**
  * Build a 0-row error batch with EXCEPTION metadata matching Python's Message.from_exception().
  */
-export function buildErrorBatch(schema: Schema, error: Error, serverId: string, requestId: string | null): RecordBatch {
+export function buildErrorBatch(schema: VgiSchema, error: Error, serverId: string, requestId: string | null): VgiBatch {
   const metadata = new Map<string, string>();
   metadata.set(LOG_LEVEL_KEY, "EXCEPTION");
-  metadata.set(LOG_MESSAGE_KEY, `${error.constructor.name}: ${error.message}`);
+  // Prefer the standard `error.name` property (which user classes can set
+  // via `this.name = "Foo"` even after a bundler renames the class) over
+  // `constructor.name`, which is fragile under minification.
+  const exceptionType = typeof error.name === "string" && error.name !== "Error" ? error.name : error.constructor.name;
+  metadata.set(LOG_MESSAGE_KEY, `${exceptionType}: ${error.message}`);
+
+  // Hoist `errorKind` (typed-exception marker) into the EXCEPTION batch
+  // metadata as a top-level `vgi_rpc.error_kind` field so clients can
+  // branch on the kind without parsing the log_extra JSON blob. Mirrors
+  // Python's `Message.from_exception()` + `add_to_metadata()` hoisting.
+  const errorKind =
+    (error as { errorKind?: unknown }).errorKind ??
+    ((error.constructor as { errorKind?: unknown }).errorKind as unknown);
+  if (typeof errorKind === "string" && errorKind.length > 0) {
+    metadata.set(ERROR_KIND_KEY, errorKind);
+  }
 
   const extra: Record<string, any> = {
-    exception_type: error.constructor.name,
+    exception_type: exceptionType,
     exception_message: error.message,
     traceback: error.stack ?? "",
   };
+  if (typeof errorKind === "string" && errorKind.length > 0) {
+    extra.error_kind = errorKind;
+  }
   metadata.set(LOG_EXTRA_KEY, JSON.stringify(extra));
   metadata.set(SERVER_ID_KEY, serverId);
   if (requestId !== null) {
@@ -110,13 +113,13 @@ export function buildErrorBatch(schema: Schema, error: Error, serverId: string,
  * Build a 0-row log batch.
  */
 export function buildLogBatch(
-  schema: Schema,
+  schema: VgiSchema,
   level: string,
   message: string,
   extra?: Record<string, any>,
   serverId?: string,
   requestId?: string | null,
-): RecordBatch {
+): VgiBatch {
   const metadata = new Map<string, string>();
   metadata.set(LOG_LEVEL_KEY, level);
   metadata.set(LOG_MESSAGE_KEY, message);
@@ -133,47 +136,10 @@ export function buildLogBatch(
   return buildEmptyBatch(schema, metadata);
 }
 
-/**
- * Recursively create empty (0-row) Data for any Arrow type,
- * including complex types (Struct, List, FixedSizeList, Map).
- */
-function makeEmptyData(type: DataType): Data {
-  if (DataType.isStruct(type)) {
-    const children = type.children.map((f: Field) => makeEmptyData(f.type));
-    return makeData({ type, length: 0, children, nullCount: 0 });
-  }
-  if (DataType.isList(type)) {
-    const childData = makeEmptyData(type.children[0].type);
-    return makeData({ type, length: 0, children: [childData], nullCount: 0, valueOffsets: new Int32Array([0]) } as any);
-  }
-  if (DataType.isFixedSizeList(type)) {
-    const childData = makeEmptyData(type.children[0].type);
-    return makeData({ type, length: 0, child: childData, nullCount: 0 } as any);
-  }
-  if (DataType.isMap(type)) {
-    const entryType = type.children[0]?.type;
-    const entryData = entryType
-      ? makeEmptyData(entryType)
-      : makeData({ type: new Struct([]), length: 0, children: [], nullCount: 0 });
-    return makeData({ type, length: 0, children: [entryData], nullCount: 0, valueOffsets: new Int32Array([0]) } as any);
-  }
-  return makeData({ type, length: 0, nullCount: 0 });
-}
-
 /**
  * Build a 0-row batch from a schema with metadata.
  * Used for error/log batches.
  */
-export function buildEmptyBatch(schema: Schema, metadata?: Map<string, string>): RecordBatch {
-  const children = schema.fields.map((f: Field) => makeEmptyData(f.type));
-
-  const structType = new Struct(schema.fields);
-  const data = makeData({
-    type: structType,
-    length: 0,
-    children,
-    nullCount: 0,
-  });
-
-  return new RecordBatch(schema, data, metadata);
+export function buildEmptyBatch(schema: VgiSchema, metadata?: Map<string, string>): VgiBatch {
+  return emptyBatchWithMetadata(schema, metadata);
 }