@haybarn/node-api 1.5.6-rc1 → 2.0.0-rc5

package/lib/vectors/DuckDBVariantVector.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBVariantVector = void 0;
+const varintDecode_1 = require("../conversion/varintDecode");
+const DuckDBType_1 = require("../DuckDBType");
+const DuckDBTypeId_1 = require("../DuckDBTypeId");
+const values_1 = require("../values");
+const DuckDBVector_1 = require("./DuckDBVector");
+const dataAccessors_1 = require("./dataAccessors");
+const DuckDBStructVector_1 = require("./DuckDBStructVector");
+// ---------------------------------------------------------------------------
+// VARIANT
+// ---------------------------------------------------------------------------
+//
+// VARIANT is a self-describing tagged value type whose physical layout is a
+// STRUCT of four children: `keys` (LIST(VARCHAR)), `children`
+// (LIST(STRUCT(keys_index, values_index))), `values`
+// (LIST(STRUCT(type_id, byte_offset))), and `data` (BLOB). Each row's root
+// node sits at index 0 of its `values` slice; primitive payloads live at
+// `byte_offsets[...]` inside the row's blob, and OBJECT/ARRAY nodes
+// reference their children through the row's `children` slice.
+//
+// Reading reuses the existing DuckDBStructVector / DuckDBListVector /
+// DuckDBBlobVector construction plus the byte-readers above for primitive
+// payloads. Writing is not yet supported.
+/**
+ * On-disk tag for a single VARIANT node. Mirrors DuckDB's
+ * `VariantLogicalType` enum.
+ */
+var VariantLogicalType;
+(function (VariantLogicalType) {
+    VariantLogicalType[VariantLogicalType["VARIANT_NULL"] = 0] = "VARIANT_NULL";
+    VariantLogicalType[VariantLogicalType["BOOL_TRUE"] = 1] = "BOOL_TRUE";
+    VariantLogicalType[VariantLogicalType["BOOL_FALSE"] = 2] = "BOOL_FALSE";
+    VariantLogicalType[VariantLogicalType["INT8"] = 3] = "INT8";
+    VariantLogicalType[VariantLogicalType["INT16"] = 4] = "INT16";
+    VariantLogicalType[VariantLogicalType["INT32"] = 5] = "INT32";
+    VariantLogicalType[VariantLogicalType["INT64"] = 6] = "INT64";
+    VariantLogicalType[VariantLogicalType["INT128"] = 7] = "INT128";
+    VariantLogicalType[VariantLogicalType["UINT8"] = 8] = "UINT8";
+    VariantLogicalType[VariantLogicalType["UINT16"] = 9] = "UINT16";
+    VariantLogicalType[VariantLogicalType["UINT32"] = 10] = "UINT32";
+    VariantLogicalType[VariantLogicalType["UINT64"] = 11] = "UINT64";
+    VariantLogicalType[VariantLogicalType["UINT128"] = 12] = "UINT128";
+    VariantLogicalType[VariantLogicalType["FLOAT"] = 13] = "FLOAT";
+    VariantLogicalType[VariantLogicalType["DOUBLE"] = 14] = "DOUBLE";
+    VariantLogicalType[VariantLogicalType["DECIMAL"] = 15] = "DECIMAL";
+    VariantLogicalType[VariantLogicalType["VARCHAR"] = 16] = "VARCHAR";
+    VariantLogicalType[VariantLogicalType["BLOB"] = 17] = "BLOB";
+    VariantLogicalType[VariantLogicalType["UUID"] = 18] = "UUID";
+    VariantLogicalType[VariantLogicalType["DATE"] = 19] = "DATE";
+    VariantLogicalType[VariantLogicalType["TIME_MICROS"] = 20] = "TIME_MICROS";
+    VariantLogicalType[VariantLogicalType["TIME_NANOS"] = 21] = "TIME_NANOS";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_SEC"] = 22] = "TIMESTAMP_SEC";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_MILIS"] = 23] = "TIMESTAMP_MILIS";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_MICROS"] = 24] = "TIMESTAMP_MICROS";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_NANOS"] = 25] = "TIMESTAMP_NANOS";
+    VariantLogicalType[VariantLogicalType["TIME_MICROS_TZ"] = 26] = "TIME_MICROS_TZ";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_MICROS_TZ"] = 27] = "TIMESTAMP_MICROS_TZ";
+    VariantLogicalType[VariantLogicalType["INTERVAL"] = 28] = "INTERVAL";
+    VariantLogicalType[VariantLogicalType["OBJECT"] = 29] = "OBJECT";
+    VariantLogicalType[VariantLogicalType["ARRAY"] = 30] = "ARRAY";
+    VariantLogicalType[VariantLogicalType["BIGNUM"] = 31] = "BIGNUM";
+    VariantLogicalType[VariantLogicalType["BITSTRING"] = 32] = "BITSTRING";
+    VariantLogicalType[VariantLogicalType["GEOMETRY"] = 33] = "GEOMETRY";
+    VariantLogicalType[VariantLogicalType["TIMESTAMP_NANOS_TZ"] = 34] = "TIMESTAMP_NANOS_TZ";
+})(VariantLogicalType || (VariantLogicalType = {}));
+/** Physical STRUCT layout of a VARIANT column. Mirrors `LogicalType::VARIANT()`. */
+const VARIANT_PHYSICAL_TYPE = (0, DuckDBType_1.STRUCT)({
+    keys: (0, DuckDBType_1.LIST)(DuckDBType_1.VARCHAR),
+    children: (0, DuckDBType_1.LIST)((0, DuckDBType_1.STRUCT)({ keys_index: DuckDBType_1.UINTEGER, values_index: DuckDBType_1.UINTEGER })),
+    values: (0, DuckDBType_1.LIST)((0, DuckDBType_1.STRUCT)({ type_id: DuckDBType_1.UTINYINT, byte_offset: DuckDBType_1.UINTEGER })),
+    data: DuckDBType_1.BLOB,
+});
+class DuckDBVariantVector extends DuckDBVector_1.DuckDBVector {
+    structVec;
+    keysList;
+    childrenList;
+    valuesList;
+    dataBlob;
+    keysEntry;
+    keysIdxVec;
+    valuesIdxVec;
+    typeIdVec;
+    byteOffsetVec;
+    constructor(structVec) {
+        super();
+        this.structVec = structVec;
+        this.keysList = structVec.entryVectorAt(0);
+        this.childrenList = structVec.entryVectorAt(1);
+        this.valuesList = structVec.entryVectorAt(2);
+        this.dataBlob = structVec.entryVectorAt(3);
+        this.keysEntry = this.keysList.childVector;
+        const childrenInner = this.childrenList.childVector;
+        const valuesInner = this.valuesList.childVector;
+        this.keysIdxVec = childrenInner.entryVectorAt(0);
+        this.valuesIdxVec = childrenInner.entryVectorAt(1);
+        this.typeIdVec = valuesInner.entryVectorAt(0);
+        this.byteOffsetVec = valuesInner.entryVectorAt(1);
+    }
+    static fromRawVector(vector, itemCount) {
+        const structVec = DuckDBStructVector_1.DuckDBStructVector.fromRawVector(VARIANT_PHYSICAL_TYPE, vector, itemCount);
+        return new DuckDBVariantVector(structVec);
+    }
+    get type() {
+        return DuckDBType_1.DuckDBVariantType.instance;
+    }
+    get itemCount() {
+        return this.structVec.itemCount;
+    }
+    getItem(itemIndex) {
+        // Top-level validity is the canonical SQL-NULL indicator. Child rows
+        // may still carry data when the row is SQL-NULL; the inverse — that a
+        // non-NULL row has non-NULL children — is the only direction
+        // guaranteed by the format.
+        if (!this.structVec.isItemValid(itemIndex)) {
+            return null;
+        }
+        const blob = this.dataBlob.getItemBytes(itemIndex);
+        if (blob === null) {
+            // Defensive: a valid row's data BLOB is expected to be present.
+            return null;
+        }
+        const row = {
+            blob,
+            view: new DataView(blob.buffer, blob.byteOffset, blob.byteLength),
+            valuesOffset: this.valuesList.getEntryOffset(itemIndex),
+            valuesLength: this.valuesList.getEntryLength(itemIndex),
+            childrenOffset: this.childrenList.getEntryOffset(itemIndex),
+            childrenLength: this.childrenList.getEntryLength(itemIndex),
+            keysOffset: this.keysList.getEntryOffset(itemIndex),
+            keysLength: this.keysList.getEntryLength(itemIndex),
+        };
+        const root = this.decodeNode(0, row);
+        return new values_1.DuckDBVariantValue(root.value, root.type);
+    }
+    setItem(_itemIndex, value) {
+        // Writing a VARIANT value isn't supported yet. setItem(null) is
+        // tolerated as a no-op so a parent struct/list/array can iterate
+        // every child and call setItem(null) on this column without failing
+        // — the read path remains usable inside arbitrary container types.
+        if (value !== null) {
+            throw new Error('Setting VARIANT values is not yet supported.');
+        }
+    }
+    flush() {
+        // No-op: VARIANT is read-only, but a parent vector's flush() will
+        // still call this on every child. Nothing to write back.
+    }
+    slice(offset, length) {
+        return new DuckDBVariantVector(this.structVec.slice(offset, length));
+    }
+    /**
+     * Decode one variant node identified by its row-local `valueIndex`
+     * (an index into the row's `values` list). Per-row state is bundled in
+     * `row`: the data blob plus the row-local list slice extents and the
+     * absolute backing-array offsets they begin at. All recursive calls
+     * share the same `row`; only `valueIndex` changes.
+     *
+     * Returns both the decoded value and the `DuckDBType` corresponding to
+     * the node's on-disk tag, so the top-level caller can attach the type
+     * to the resulting `DuckDBVariantValue` for round-trip fidelity.
+     *
+     * Throws if any index decoded from the blob falls outside its row-local
+     * list slice — guards against malformed or hostile VARIANT payloads.
+     */
+    decodeNode(valueIndex, row) {
+        if (valueIndex >= row.valuesLength) {
+            throw new Error(`Malformed VARIANT: value_index ${valueIndex} out of bounds (row values length ${row.valuesLength})`);
+        }
+        const nodeAbs = row.valuesOffset + valueIndex;
+        const tag = this.typeIdVec.getItem(nodeAbs);
+        const byteOffset = this.byteOffsetVec.getItem(nodeAbs);
+        const { blob, view } = row;
+        switch (tag) {
+            case VariantLogicalType.VARIANT_NULL:
+                return { value: null, type: DuckDBType_1.SQLNULL };
+            case VariantLogicalType.BOOL_TRUE:
+                return { value: true, type: DuckDBType_1.BOOLEAN };
+            case VariantLogicalType.BOOL_FALSE:
+                return { value: false, type: DuckDBType_1.BOOLEAN };
+            case VariantLogicalType.INT8:
+                return { value: view.getInt8(byteOffset), type: DuckDBType_1.TINYINT };
+            case VariantLogicalType.INT16:
+                return { value: (0, dataAccessors_1.getInt16)(view, byteOffset), type: DuckDBType_1.SMALLINT };
+            case VariantLogicalType.INT32:
+                return { value: (0, dataAccessors_1.getInt32)(view, byteOffset), type: DuckDBType_1.INTEGER };
+            case VariantLogicalType.INT64:
+                return { value: (0, dataAccessors_1.getInt64)(view, byteOffset), type: DuckDBType_1.BIGINT };
+            case VariantLogicalType.INT128:
+                return { value: (0, dataAccessors_1.getInt128)(view, byteOffset), type: DuckDBType_1.HUGEINT };
+            case VariantLogicalType.UINT8:
+                return { value: (0, dataAccessors_1.getUInt8)(view, byteOffset), type: DuckDBType_1.UTINYINT };
+            case VariantLogicalType.UINT16:
+                return { value: (0, dataAccessors_1.getUInt16)(view, byteOffset), type: DuckDBType_1.USMALLINT };
+            case VariantLogicalType.UINT32:
+                return { value: (0, dataAccessors_1.getUInt32)(view, byteOffset), type: DuckDBType_1.UINTEGER };
+            case VariantLogicalType.UINT64:
+                return { value: (0, dataAccessors_1.getUInt64)(view, byteOffset), type: DuckDBType_1.UBIGINT };
+            case VariantLogicalType.UINT128:
+                return { value: (0, dataAccessors_1.getUInt128)(view, byteOffset), type: DuckDBType_1.UHUGEINT };
+            case VariantLogicalType.FLOAT:
+                return {
+                    value: view.getFloat32(byteOffset, dataAccessors_1.littleEndian),
+                    type: DuckDBType_1.FLOAT,
+                };
+            case VariantLogicalType.DOUBLE:
+                return {
+                    value: view.getFloat64(byteOffset, dataAccessors_1.littleEndian),
+                    type: DuckDBType_1.DOUBLE,
+                };
+            case VariantLogicalType.UUID:
+                return {
+                    value: values_1.DuckDBUUIDValue.fromStoredHugeInt((0, dataAccessors_1.getInt128)(view, byteOffset)),
+                    type: DuckDBType_1.UUID,
+                };
+            case VariantLogicalType.DATE:
+                return {
+                    value: new values_1.DuckDBDateValue((0, dataAccessors_1.getInt32)(view, byteOffset)),
+                    type: DuckDBType_1.DATE,
+                };
+            case VariantLogicalType.TIME_MICROS:
+                return {
+                    value: new values_1.DuckDBTimeValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIME,
+                };
+            case VariantLogicalType.TIME_NANOS:
+                return {
+                    value: new values_1.DuckDBTimeNSValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIME_NS,
+                };
+            case VariantLogicalType.TIME_MICROS_TZ:
+                return {
+                    value: values_1.DuckDBTimeTZValue.fromBits((0, dataAccessors_1.getUInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMETZ,
+                };
+            case VariantLogicalType.TIMESTAMP_SEC:
+                return {
+                    value: new values_1.DuckDBTimestampSecondsValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMP_S,
+                };
+            case VariantLogicalType.TIMESTAMP_MILIS:
+                return {
+                    value: new values_1.DuckDBTimestampMillisecondsValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMP_MS,
+                };
+            case VariantLogicalType.TIMESTAMP_MICROS:
+                return {
+                    value: new values_1.DuckDBTimestampValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMP,
+                };
+            case VariantLogicalType.TIMESTAMP_NANOS:
+                return {
+                    value: new values_1.DuckDBTimestampNanosecondsValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMP_NS,
+                };
+            case VariantLogicalType.TIMESTAMP_MICROS_TZ:
+                return {
+                    value: new values_1.DuckDBTimestampTZValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMPTZ,
+                };
+            case VariantLogicalType.TIMESTAMP_NANOS_TZ:
+                return {
+                    value: new values_1.DuckDBTimestampTZNanosecondsValue((0, dataAccessors_1.getInt64)(view, byteOffset)),
+                    type: DuckDBType_1.TIMESTAMPTZ_NS,
+                };
+            case VariantLogicalType.INTERVAL:
+                return {
+                    value: new values_1.DuckDBIntervalValue((0, dataAccessors_1.getInt32)(view, byteOffset), (0, dataAccessors_1.getInt32)(view, byteOffset + 4), (0, dataAccessors_1.getInt64)(view, byteOffset + 8)),
+                    type: DuckDBType_1.INTERVAL,
+                };
+            case VariantLogicalType.VARCHAR: {
+                const bytes = readVarintBytes(view, byteOffset, blob);
+                return { value: dataAccessors_1.textDecoder.decode(bytes), type: DuckDBType_1.VARCHAR };
+            }
+            case VariantLogicalType.BLOB: {
+                // Copy out — the bytes alias the underlying vector storage, which
+                // we don't want to share through to user code.
+                const bytes = readVarintBytes(view, byteOffset, blob);
+                return {
+                    value: new values_1.DuckDBBlobValue(new Uint8Array(bytes)),
+                    type: DuckDBType_1.BLOB,
+                };
+            }
+            case VariantLogicalType.BITSTRING: {
+                const bytes = readVarintBytes(view, byteOffset, blob);
+                return {
+                    value: new values_1.DuckDBBitValue(new Uint8Array(bytes)),
+                    type: DuckDBType_1.BIT,
+                };
+            }
+            case VariantLogicalType.BIGNUM: {
+                const bytes = readVarintBytes(view, byteOffset, blob);
+                return { value: (0, dataAccessors_1.getBigNumFromBytes)(bytes), type: DuckDBType_1.BIGNUM };
+            }
+            case VariantLogicalType.GEOMETRY: {
+                const bytes = readVarintBytes(view, byteOffset, blob);
+                return {
+                    value: new values_1.DuckDBGeometryValue(new Uint8Array(bytes)),
+                    type: DuckDBType_1.GEOMETRY,
+                };
+            }
+            case VariantLogicalType.DECIMAL: {
+                const wParse = (0, varintDecode_1.varintDecode)(view, byteOffset);
+                const sParse = (0, varintDecode_1.varintDecode)(view, wParse.nextOffset);
+                const width = wParse.value;
+                const scale = sParse.value;
+                const valueOffset = sParse.nextOffset;
+                let intValue;
+                if (width <= 4) {
+                    intValue = BigInt((0, dataAccessors_1.getInt16)(view, valueOffset));
+                }
+                else if (width <= 9) {
+                    intValue = BigInt((0, dataAccessors_1.getInt32)(view, valueOffset));
+                }
+                else if (width <= 18) {
+                    intValue = (0, dataAccessors_1.getInt64)(view, valueOffset);
+                }
+                else if (width <= 38) {
+                    intValue = (0, dataAccessors_1.getInt128)(view, valueOffset);
+                }
+                else {
+                    throw new Error(`VARIANT DECIMAL width too large: ${width}`);
+                }
+                return {
+                    value: new values_1.DuckDBDecimalValue(intValue, width, scale),
+                    type: (0, DuckDBType_1.DECIMAL)(width, scale),
+                };
+            }
+            case VariantLogicalType.OBJECT: {
+                const { childCount, childrenIdx } = readNestedHeader(view, byteOffset);
+                this.checkChildrenSlice(childrenIdx, childCount, row);
+                const entries = {};
+                const fields = {};
+                for (let k = 0; k < childCount; k++) {
+                    const entryAbs = row.childrenOffset + childrenIdx + k;
+                    const keyIdx = this.keysIdxVec.getItem(entryAbs);
+                    if (keyIdx >= row.keysLength) {
+                        throw new Error(`Malformed VARIANT: keys_index ${keyIdx} out of bounds (row keys length ${row.keysLength})`);
+                    }
+                    const keyStr = this.keysEntry.getItem(row.keysOffset + keyIdx);
+                    const valIdx = this.valuesIdxVec.getItem(entryAbs);
+                    const child = this.decodeNode(valIdx, row);
+                    entries[keyStr] = child.value;
+                    fields[keyStr] = child.type;
+                }
+                return {
+                    value: new values_1.DuckDBStructValue(entries),
+                    type: (0, DuckDBType_1.STRUCT)(fields),
+                };
+            }
+            case VariantLogicalType.ARRAY: {
+                const { childCount, childrenIdx } = readNestedHeader(view, byteOffset);
+                this.checkChildrenSlice(childrenIdx, childCount, row);
+                // Decode all children first so we can decide whether their types
+                // are uniform. If they are (treating SQLNULL as compatible with
+                // any sibling, so e.g. [1, 2, null] reads as LIST(UBIGINT)), use
+                // `LIST(commonType)` with bare items — that's a Value the C API's
+                // create_list_value will accept, and it round-trips through
+                // bind/append cleanly. Otherwise fall back to `LIST(VARIANT)`
+                // with non-null items wrapped to preserve their type; null items
+                // remain bare to match how column-level LIST(VARIANT) decodes a
+                // null element.
+                const children = [];
+                for (let k = 0; k < childCount; k++) {
+                    const entryAbs = row.childrenOffset + childrenIdx + k;
+                    const valIdx = this.valuesIdxVec.getItem(entryAbs);
+                    children.push(this.decodeNode(valIdx, row));
+                }
+                const commonType = uniformVariantChildType(children);
+                if (commonType !== null) {
+                    return {
+                        value: new values_1.DuckDBListValue(children.map((c) => c.value)),
+                        type: (0, DuckDBType_1.LIST)(commonType),
+                    };
+                }
+                return {
+                    value: new values_1.DuckDBListValue(children.map((c) => c.value === null
+                        ? null
+                        : new values_1.DuckDBVariantValue(c.value, c.type))),
+                    type: (0, DuckDBType_1.LIST)(DuckDBType_1.VARIANT),
+                };
+            }
+            default:
+                throw new Error(`Unknown VARIANT type id: ${tag}`);
+        }
+    }
+    /** Bounds-check an OBJECT / ARRAY's `[childrenIdx, childrenIdx+childCount)` range. */
+    checkChildrenSlice(childrenIdx, childCount, row) {
+        if (childrenIdx + childCount > row.childrenLength) {
+            throw new Error(`Malformed VARIANT: children slice [${childrenIdx}, ${childrenIdx + childCount}) out of bounds (row children length ${row.childrenLength})`);
+        }
+    }
+}
+exports.DuckDBVariantVector = DuckDBVariantVector;
+/**
+ * Returns the shared DuckDBType if every non-null child has the same type,
+ * or `null` if non-null children differ. Used to pick between
+ * `LIST(commonType)` and `LIST(VARIANT)` for a decoded ARRAY.
+ *
+ * SQLNULL children are treated as compatible with any sibling — that way a
+ * very common JSON shape like `[1, 2, null]` decodes as `LIST(UBIGINT)`
+ * with a bare null element rather than `LIST(VARIANT)`. An array whose
+ * children are all SQLNULL (including the empty array) collapses to
+ * SQLNULL itself — DuckDB casts `LIST(SQLNULL)` to VARIANT for round-trip,
+ * but a `LIST(VARIANT)` of nulls or an empty `LIST(VARIANT)` doesn't
+ * survive `create_list_value`.
+ */
+function uniformVariantChildType(children) {
+    let common = null;
+    let commonKey = null;
+    for (const child of children) {
+        if (child.type.typeId === DuckDBTypeId_1.DuckDBTypeId.SQLNULL) {
+            continue;
+        }
+        const key = typeKey(child.type);
+        if (common === null) {
+            common = child.type;
+            commonKey = key;
+        }
+        else if (key !== commonKey) {
+            return null;
+        }
+    }
+    // All children (if any) are SQLNULL: collapse to SQLNULL.
+    return common ?? DuckDBType_1.SQLNULL;
+}
+/**
+ * Returns a canonical string for a DuckDBType, suitable for equality
+ * comparison between types produced by the same decode pass. Uses the
+ * structured `toJson()` representation rather than the SQL-syntactic
+ * `toString()` so nested types compare structurally.
+ */
+function typeKey(type) {
+    return JSON.stringify(type.toJson());
+}
+/**
+ * Reads a length-prefixed payload (`<varint length><length bytes>`) from a
+ * variant data blob. Returns a (possibly aliased) Uint8Array view over the
+ * payload bytes — callers that need to retain the data should copy.
+ * Throws if the prefix length would read past the row's blob.
+ */
+function readVarintBytes(view, offset, blob) {
+    const { value: length, nextOffset } = (0, varintDecode_1.varintDecode)(view, offset);
+    if (nextOffset + length > blob.byteLength) {
+        throw new Error(`Malformed VARIANT payload: length-prefixed read of ${length} bytes at offset ${nextOffset} exceeds row blob size ${blob.byteLength}`);
+    }
+    return new Uint8Array(blob.buffer, blob.byteOffset + nextOffset, length);
+}
+/**
+ * Reads an OBJECT / ARRAY header: `<varint child_count>` followed by
+ * `<varint children_idx>` iff `child_count > 0`.
+ */
+function readNestedHeader(view, offset) {
+    const cParse = (0, varintDecode_1.varintDecode)(view, offset);
+    if (cParse.value === 0) {
+        return { childCount: 0, childrenIdx: 0 };
+    }
+    const iParse = (0, varintDecode_1.varintDecode)(view, cParse.nextOffset);
+    return { childCount: cParse.value, childrenIdx: iParse.value };
+}

package/lib/vectors/DuckDBVector.d.ts

@@ -0,0 +1,14 @@
+import duckdb from '@haybarn/node-bindings';
+import { DuckDBType } from '../DuckDBType';
+import { DuckDBValue } from '../values';
+export declare abstract class DuckDBVector<TValue extends DuckDBValue = DuckDBValue> {
+    static standardSize(): number;
+    static create(vector: duckdb.Vector, itemCount: number, knownType?: DuckDBType): DuckDBVector;
+    abstract get type(): DuckDBType;
+    abstract get itemCount(): number;
+    abstract getItem(itemIndex: number): TValue | null;
+    abstract setItem(itemIndex: number, value: TValue | null): void;
+    abstract flush(): void;
+    abstract slice(offset: number, length: number): DuckDBVector<TValue>;
+    toArray(): (TValue | null)[];
+}

package/lib/vectors/DuckDBVector.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBVector = void 0;
+const node_bindings_1 = __importDefault(require("@haybarn/node-bindings"));
+const vectorRegistry_1 = require("./vectorRegistry");
+class DuckDBVector {
+    static standardSize() {
+        return node_bindings_1.default.vector_size();
+    }
+    static create(vector, itemCount, knownType) {
+        if (!vectorRegistry_1.vectorRegistry.create) {
+            throw new Error('DuckDBVector factory has not been registered');
+        }
+        return vectorRegistry_1.vectorRegistry.create(vector, itemCount, knownType);
+    }
+    toArray() {
+        const items = [];
+        for (let i = 0; i < this.itemCount; i++) {
+            items.push(this.getItem(i));
+        }
+        return items;
+    }
+}
+exports.DuckDBVector = DuckDBVector;

package/lib/vectors/createVector.d.ts

@@ -0,0 +1 @@
+export {};