@query-farm/vgi 0.42.0 → 0.44.0

package/dist/codec/asd.d.ts

@@ -15,7 +15,9 @@
 import { type VgiSchema } from "../arrow/index.js";
 /**
  * Encode a typed object as a single-row Arrow IPC stream using `schema`.
- * Matches Python's `ArrowSerializableDataclass.serialize_to_bytes()`.
+ * Matches Python's `ArrowSerializableDataclass.serialize_to_bytes()`, including
+ * its container rules: a non-nullable list/map left out or null is written as
+ * empty, and list items / map values are never null (see `conformRecord`).
  */
 export declare function encodeASD(schema: VgiSchema, obj: Record<string, any>): Uint8Array;
 /** Compare two strings by Unicode code point (= UTF-8 byte order). */

package/dist/codec/conform.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Wire conformance for protocol records.
+ *
+ * vgi-python is the reference for the wire shape, and two of its rules are not
+ * expressed by a record's Arrow schema nullability flags alone:
+ *
+ *  1. A **non-nullable list or map column is never null.** Python's dataclass
+ *     defaults a `list[...]` / `dict[...]` field to an empty container, so an
+ *     "absent" list goes out as `[]`. A JS caller that leaves the field out (or
+ *     passes `null`) would otherwise put a null in a column the schema calls
+ *     non-null — `CatalogInfo.releases`, `CatalogInfo.attach_option_specs`,
+ *     ... — which a strict client rejects as a protocol error.
+ *
+ *  2. **List items and map values are never null** unless the Python annotation
+ *     says so (`list[str | None]`). pyarrow marks every list item field nullable,
+ *     so the generated schemas carry `item: nullable=true` everywhere and cannot
+ *     tell the two apart. In the whole protocol exactly one field has optional
+ *     items — `argument_names` on `BindRequest` / `AggregateBindRequest` (a
+ *     positional argument has no name). Every other null item is a bug on the
+ *     sending side (e.g. `BindResponse.lookup_names` built from an unset secret
+ *     name, where Python sends `""`).
+ *
+ * `conformRecord` applies both rules to a record about to be encoded: a null or
+ * absent non-nullable list/map becomes empty, and a null list item / map value
+ * becomes its type's zero value (`""`, `0`, `false`, empty bytes, empty list),
+ * which is also what the C++ client reads such an item as. It never mutates its
+ * input (catalog items may be frozen and shared) and returns the input itself
+ * when nothing needed changing. Nullable columns, and scalars, pass through
+ * untouched: a null in a non-nullable scalar column has no safe default and is
+ * left for the caller to fix (see `wireViolations`).
+ */
+import { type VgiSchema, type VgiDataType } from "../arrow/index.js";
+/**
+ * Top-level / struct-child field names whose list items may legitimately be
+ * null (the Python annotation is `list[X | None]`). Derived from vgi-python by
+ * walking every protocol dataclass's type hints; keep in sync if the protocol
+ * adds another optional-item list.
+ */
+export declare const OPTIONAL_ITEM_FIELDS: ReadonlySet<string>;
+/** The value a non-null slot of `type` takes when the sender left it null. */
+export declare function zeroValue(type: VgiDataType): unknown;
+/**
+ * `obj` conformed to `schema`'s wire rules (see the module comment). Returns
+ * `obj` itself when nothing changed.
+ */
+export declare function conformRecord<T extends Record<string, any>>(schema: VgiSchema, obj: T): T;
+/**
+ * Column-dict form of `conformRecord` for `batchFromColumns` callers: each
+ * value is a one-element array holding the row's value.
+ */
+export declare function conformColumns(schema: VgiSchema, columns: Record<string, unknown[]>): Record<string, unknown[]>;

package/dist/errors.d.ts

@@ -1,6 +1,10 @@
+import type { ErrorCode } from "@query-farm/vgi-rpc";
 export declare class VgiError extends Error {
-    constructor(message: string);
+    /** Canonical code hoisted as `vgi_rpc.error_code`; unset means `UNKNOWN`. */
+    readonly errorCode?: ErrorCode;
+    constructor(message: string, code?: ErrorCode);
 }
+/** A worker bug (the function returned the wrong number of rows): UNKNOWN. */
 export declare class RowCountMismatchError extends VgiError {
     constructor(expected: number, actual: number);
 }