@avidian/duckdb-bun 0.0.0-stage → 1.0.1

package/vendor/node-api/src/DuckDBDataChunk.ts

@@ -0,0 +1,412 @@
+import duckdb from "../../../src/bindings/index.ts";
+import { DuckDBType } from './DuckDBType';
+import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { ToDuckDBValueConverter } from './ToDuckDBValueConverter';
+import { DuckDBVector } from './DuckDBVector';
+import { DuckDBValue } from './values';
+
+export class DuckDBDataChunk {
+  public readonly chunk: duckdb.DataChunk;
+  private readonly vectors: DuckDBVector[] = [];
+  constructor(chunk: duckdb.DataChunk) {
+    this.chunk = chunk;
+  }
+  public static create(
+    types: readonly DuckDBType[],
+    rowCount?: number
+  ): DuckDBDataChunk {
+    let chunk: DuckDBDataChunk;
+    try {
+      chunk = new DuckDBDataChunk(
+        duckdb.create_data_chunk(
+          types.map((t) => t.toLogicalType().logical_type)
+        )
+      );
+    } catch (cause) {
+      // The binding knows the chunk was refused but not which type did it, so
+      // name them here. Zero columns is a legitimate chunk, so there is
+      // nothing to check on the way out; only the refusal is an error.
+      throw new Error(
+        `Cannot create a data chunk with these column types: ${types.join(', ')}`,
+        { cause }
+      );
+    }
+    if (rowCount != undefined) {
+      chunk.rowCount = rowCount;
+    }
+    return chunk;
+  }
+  public reset() {
+    duckdb.data_chunk_reset(this.chunk);
+  }
+  public get columnCount(): number {
+    return duckdb.data_chunk_get_column_count(this.chunk);
+  }
+  public get rowCount(): number {
+    return duckdb.data_chunk_get_size(this.chunk);
+  }
+  public set rowCount(count: number) {
+    const maxRowCount = duckdb.vector_size();
+    if (count > maxRowCount) {
+      throw new Error(`A data chunk cannot have more than ${maxRowCount} rows`);
+    }
+    duckdb.data_chunk_set_size(this.chunk, count);
+    // Cached vectors were built for the previous row count, so they are the
+    // wrong size now. This matters most for a table function's output chunk,
+    // which arrives empty and is sized by the function on every call.
+    this.vectors.length = 0;
+  }
+  /**
+   * Refuses a column count that does not match the chunk's.
+   *
+   * A short array would leave the remaining vectors never written and never
+   * flushed while the chunk reports a non-zero row count, and reading or
+   * appending it then crashes the process instead of raising.
+   */
+  private assertColumnCount(count: number) {
+    const columnCount = this.columnCount;
+    if (count !== columnCount) {
+      throw new Error(
+        `Provided number of columns (${count}) does not match chunk column count (${columnCount})`
+      );
+    }
+  }
+  public getColumnVector(columnIndex: number): DuckDBVector {
+    if (this.vectors[columnIndex]) {
+      return this.vectors[columnIndex];
+    }
+    const vector = DuckDBVector.create(
+      duckdb.data_chunk_get_vector(this.chunk, columnIndex),
+      this.rowCount
+    );
+    this.vectors[columnIndex] = vector;
+    return vector;
+  }
+  public visitColumnValues(
+    columnIndex: number,
+    visitValue: (
+      value: DuckDBValue,
+      rowIndex: number,
+      columnIndex: number,
+      type: DuckDBType
+    ) => void
+  ) {
+    const vector = this.getColumnVector(columnIndex);
+    const type = vector.type;
+    for (let rowIndex = 0; rowIndex < vector.itemCount; rowIndex++) {
+      visitValue(vector.getItem(rowIndex), rowIndex, columnIndex, type);
+    }
+  }
+  public appendColumnValues(columnIndex: number, values: DuckDBValue[]) {
+    this.visitColumnValues(columnIndex, (value) => values.push(value));
+  }
+  public getColumnValues(columnIndex: number): DuckDBValue[] {
+    const values: DuckDBValue[] = [];
+    this.appendColumnValues(columnIndex, values);
+    return values;
+  }
+  public convertColumnValues<T>(
+    columnIndex: number,
+    converter: DuckDBValueConverter<T>
+  ): (T | null)[] {
+    const convertedValues: (T | null)[] = [];
+    this.visitColumnValues(columnIndex, (value, _r, _c, type) =>
+      convertedValues.push(converter(value, type, converter))
+    );
+    return convertedValues;
+  }
+  public setColumnValues(columnIndex: number, values: readonly DuckDBValue[]) {
+    const vector = this.getColumnVector(columnIndex);
+    if (vector.itemCount !== values.length) {
+      throw new Error(`number of values must equal chunk row count`);
+    }
+    for (let i = 0; i < values.length; i++) {
+      vector.setItem(i, values[i]);
+    }
+    vector.flush();
+  }
+  /**
+   * `setColumnValues` with each value converted on the way in: the write
+   * counterpart of `convertColumnValues`.
+   *
+   * The column's type comes from its vector, so the converter is the only
+   * thing the caller supplies.
+   */
+  public setColumnValuesConverted<T>(
+    columnIndex: number,
+    values: readonly (T | null)[],
+    converter: ToDuckDBValueConverter<T>
+  ) {
+    const vector = this.getColumnVector(columnIndex);
+    if (vector.itemCount !== values.length) {
+      throw new Error(`number of values must equal chunk row count`);
+    }
+    const { type } = vector;
+    try {
+      for (let i = 0; i < values.length; i++) {
+        vector.setItem(i, converter(values[i] as T, type, converter));
+      }
+    } catch (cause) {
+      throw new Error(`Failed to set column ${columnIndex} (${type})`, {
+        cause,
+      });
+    }
+    vector.flush();
+  }
+  public visitColumns(
+    visitColumn: (
+      column: DuckDBValue[],
+      columnIndex: number,
+      type: DuckDBType
+    ) => void
+  ) {
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      visitColumn(
+        this.getColumnValues(columnIndex),
+        columnIndex,
+        this.getColumnVector(columnIndex).type
+      );
+    }
+  }
+  public appendToColumns(columns: (DuckDBValue[] | undefined)[]) {
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      let column = columns[columnIndex];
+      if (!column) {
+        column = [];
+        columns[columnIndex] = column;
+      }
+      this.appendColumnValues(columnIndex, column);
+    }
+  }
+  public getColumns(): DuckDBValue[][] {
+    const columns: DuckDBValue[][] = [];
+    this.visitColumns((column) => columns.push(column));
+    return columns;
+  }
+  public convertColumns<T>(converter: DuckDBValueConverter<T>): (T | null)[][] {
+    const convertedColumns: (T | null)[][] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      convertedColumns.push(this.convertColumnValues(columnIndex, converter));
+    }
+    return convertedColumns;
+  }
+  public setColumns(columns: readonly (readonly DuckDBValue[])[]) {
+    this.assertColumnCount(columns.length);
+    if (columns.length > 0) {
+      this.rowCount = columns[0].length;
+    }
+    for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {
+      this.setColumnValues(columnIndex, columns[columnIndex]);
+    }
+  }
+  /**
+   * `setColumns` with each value converted on the way in: the write
+   * counterpart of `convertColumns`.
+   */
+  public setColumnsConverted<T>(
+    columns: readonly (readonly (T | null)[])[],
+    converter: ToDuckDBValueConverter<T>
+  ) {
+    this.assertColumnCount(columns.length);
+    if (columns.length > 0) {
+      this.rowCount = columns[0].length;
+    }
+    for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {
+      this.setColumnValuesConverted(
+        columnIndex,
+        columns[columnIndex],
+        converter
+      );
+    }
+  }
+  public appendToColumnsObject(
+    columnNames: readonly string[],
+    columnsObject: Record<string, DuckDBValue[] | undefined>
+  ) {
+    const columnCount = this.columnCount;
+    if (columnNames.length !== columnCount) {
+      throw new Error(
+        `Provided number of column names (${columnNames.length}) does not match column count (${this.columnCount})`
+      );
+    }
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const columnName = columnNames[columnIndex];
+      let columnValues = columnsObject[columnName];
+      if (!columnValues) {
+        columnValues = [];
+        columnsObject[columnName] = columnValues;
+      }
+      this.appendColumnValues(columnIndex, columnValues);
+    }
+  }
+  public getColumnsObject(
+    columnNames: readonly string[]
+  ): Record<string, DuckDBValue[]> {
+    const columnsObject: Record<string, DuckDBValue[]> = {};
+    this.appendToColumnsObject(columnNames, columnsObject);
+    return columnsObject;
+  }
+  public visitColumnMajor(
+    visitValue: (
+      value: DuckDBValue,
+      rowIndex: number,
+      columnIndex: number,
+      type: DuckDBType
+    ) => void
+  ) {
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      this.visitColumnValues(columnIndex, visitValue);
+    }
+  }
+  public visitRowValues(
+    rowIndex: number,
+    visitValue: (
+      value: DuckDBValue,
+      rowIndex: number,
+      columnIndex: number,
+      type: DuckDBType
+    ) => void
+  ) {
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const vector = this.getColumnVector(columnIndex);
+      visitValue(vector.getItem(rowIndex), rowIndex, columnIndex, vector.type);
+    }
+  }
+  public appendRowValues(rowIndex: number, values: DuckDBValue[]) {
+    this.visitRowValues(rowIndex, (value) => values.push(value));
+  }
+  public getRowValues(rowIndex: number): DuckDBValue[] {
+    const values: DuckDBValue[] = [];
+    this.appendRowValues(rowIndex, values);
+    return values;
+  }
+  public convertRowValues<T>(
+    rowIndex: number,
+    converter: DuckDBValueConverter<T>
+  ): (T | null)[] {
+    const convertedValues: (T | null)[] = [];
+    this.visitRowValues(rowIndex, (value, _, columnIndex) =>
+      convertedValues.push(
+        converter(value, this.getColumnVector(columnIndex).type, converter)
+      )
+    );
+    return convertedValues;
+  }
+  public visitRows(visitRow: (row: DuckDBValue[], rowIndex: number) => void) {
+    const rowCount = this.rowCount;
+    for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+      visitRow(this.getRowValues(rowIndex), rowIndex);
+    }
+  }
+  public appendToRows(rows: DuckDBValue[][]) {
+    this.visitRows((row) => rows.push(row));
+  }
+  public getRows(): DuckDBValue[][] {
+    const rows: DuckDBValue[][] = [];
+    this.appendToRows(rows);
+    return rows;
+  }
+  public convertRows<T>(converter: DuckDBValueConverter<T>): (T | null)[][] {
+    const convertedRows: (T | null)[][] = [];
+    const rowCount = this.rowCount;
+    for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+      convertedRows.push(this.convertRowValues(rowIndex, converter));
+    }
+    return convertedRows;
+  }
+  public setRows(rows: readonly (readonly DuckDBValue[])[]) {
+    this.rowCount = rows.length;
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const vector = this.getColumnVector(columnIndex);
+      for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+        vector.setItem(rowIndex, rows[rowIndex][columnIndex]);
+      }
+      vector.flush();
+    }
+  }
+  /**
+   * `setRows` with each value converted on the way in: the write counterpart
+   * of `convertRows`.
+   *
+   * Each column's type comes from its vector, so the converter is the only
+   * thing the caller supplies.
+   */
+  public setRowsConverted<T>(
+    rows: readonly (readonly (T | null)[])[],
+    converter: ToDuckDBValueConverter<T>
+  ) {
+    this.rowCount = rows.length;
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const vector = this.getColumnVector(columnIndex);
+      const { type } = vector;
+      // Wrapped per column rather than per value: a conversion failure names
+      // the column it came from without a try/catch in the inner loop.
+      try {
+        for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+          vector.setItem(
+            rowIndex,
+            converter(rows[rowIndex][columnIndex] as T, type, converter)
+          );
+        }
+      } catch (cause) {
+        throw new Error(`Failed to set column ${columnIndex} (${type})`, {
+          cause,
+        });
+      }
+      vector.flush();
+    }
+  }
+  public appendToRowObjects(
+    columnNames: readonly string[],
+    rowObjects: Record<string, DuckDBValue>[]
+  ) {
+    const columnCount = this.columnCount;
+    if (columnNames.length !== columnCount) {
+      throw new Error(
+        `Provided number of column names (${columnNames.length}) does not match column count (${this.columnCount})`
+      );
+    }
+    const rowCount = this.rowCount;
+    for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+      let rowObject: Record<string, DuckDBValue> = {};
+      this.visitRowValues(rowIndex, (value, _, columnIndex) => {
+        rowObject[columnNames[columnIndex]] = value;
+      });
+      rowObjects.push(rowObject);
+    }
+  }
+  public getRowObjects(columnNames: readonly string[]) {
+    const rowObjects: Record<string, DuckDBValue>[] = [];
+    this.appendToRowObjects(columnNames, rowObjects);
+    return rowObjects;
+  }
+  public visitRowMajor(
+    visitValue: (
+      value: DuckDBValue,
+      rowIndex: number,
+      columnIndex: number,
+      type: DuckDBType
+    ) => void
+  ) {
+    const rowCount = this.rowCount;
+    const columnCount = this.columnCount;
+    for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+      for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+        const vector = this.getColumnVector(columnIndex);
+        visitValue(
+          vector.getItem(rowIndex),
+          rowIndex,
+          columnIndex,
+          vector.type
+        );
+      }
+    }
+  }
+}

package/vendor/node-api/src/DuckDBDataChunkWriter.ts

@@ -0,0 +1,144 @@
+import duckdb from "../../../src/bindings/index.ts";
+import type { DuckDBAppender } from './DuckDBAppender';
+import { DuckDBDataChunk } from './DuckDBDataChunk';
+import { DuckDBType } from './DuckDBType';
+import { ToDuckDBValueConverter } from './ToDuckDBValueConverter';
+import { DuckDBValue } from './values';
+
+/** Receives each data chunk a `DuckDBDataChunkWriter` fills. */
+export type DuckDBDataChunkSink = (chunk: DuckDBDataChunk) => void;
+
+/**
+ * `converter` is optional only when the rows are already `DuckDBValue`s, which
+ * is what `T` defaults to. Supply one to write some other representation —
+ * `JSToDuckDBValueConverter` for plain JS — and `T` follows from it.
+ */
+export type DuckDBDataChunkWriterOptions<T> = {
+  /**
+   * How many rows each emitted data chunk holds — its `rowCount`. Defaults to
+   * the DuckDB vector size, which is also the most a data chunk can hold.
+   */
+  readonly rowsPerDataChunk?: number;
+} & ([DuckDBValue] extends [T]
+  ? { readonly converter?: ToDuckDBValueConverter<T> }
+  : { readonly converter: ToDuckDBValueConverter<T> });
+
+/**
+ * Accumulates rows and emits them as filled data chunks, one per
+ * `rowsPerDataChunk` rows, passing each to `sink`.
+ *
+ * Rows are `DuckDBValue`s by default. Supply a converter to write some other
+ * representation; the row type follows from it.
+ *
+ *     const writer = DuckDBDataChunkWriter.forAppender(appender, {
+ *       converter: JSToDuckDBValueConverter,
+ *     });
+ *     for (const row of rows) {
+ *       writer.appendRow(row);
+ *     }
+ *     writer.flush();
+ *
+ * `flush` emits whatever is buffered, so call it when done: the last chunk is
+ * usually a partial one. Rows already grouped into chunk-sized batches need no
+ * writer — fill a `DuckDBDataChunk` and pass it to the destination directly.
+ */
+export class DuckDBDataChunkWriter<T = DuckDBValue> {
+  private readonly types: readonly DuckDBType[];
+  private readonly sink: DuckDBDataChunkSink;
+  private readonly rowsPerDataChunk: number;
+  private readonly converter?: ToDuckDBValueConverter<T>;
+  private rows: (T | null)[][] = [];
+
+  public constructor(
+    types: readonly DuckDBType[],
+    sink: DuckDBDataChunkSink,
+    options: DuckDBDataChunkWriterOptions<T> = {} as DuckDBDataChunkWriterOptions<T>
+  ) {
+    this.types = types;
+    this.sink = sink;
+    const maxRowCount = duckdb.vector_size();
+    this.rowsPerDataChunk = options.rowsPerDataChunk ?? maxRowCount;
+    // Checked here rather than left to the first flush, which is where the
+    // chunk itself would refuse it — a whole buffer's worth of rows later.
+    if (this.rowsPerDataChunk < 1 || this.rowsPerDataChunk > maxRowCount) {
+      throw new Error(
+        `rowsPerDataChunk must be between 1 and ${maxRowCount}, got ${this.rowsPerDataChunk}`
+      );
+    }
+    this.converter = options.converter;
+  }
+
+  /**
+   * A writer that appends each filled data chunk to `appender`, using the
+   * appender's own column types.
+   *
+   * Equivalent to constructing one with those types and a sink that calls
+   * `appendDataChunk`, but with nothing to keep in step by hand.
+   */
+  public static forAppender<T = DuckDBValue>(
+    appender: DuckDBAppender,
+    options: DuckDBDataChunkWriterOptions<T> = {} as DuckDBDataChunkWriterOptions<T>
+  ): DuckDBDataChunkWriter<T> {
+    const types: DuckDBType[] = [];
+    const columnCount = appender.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      types.push(appender.columnType(columnIndex));
+    }
+    return new DuckDBDataChunkWriter<T>(
+      types,
+      (chunk) => appender.appendDataChunk(chunk),
+      options
+    );
+  }
+
+  public get bufferedRowCount(): number {
+    return this.rows.length;
+  }
+
+  /**
+   * Buffers one row, emitting a data chunk once `rowsPerDataChunk` are held.
+   *
+   * The row is copied, so the same array can be reused across calls.
+   */
+  public appendRow(values: readonly (T | null)[]): void {
+    if (values.length !== this.types.length) {
+      throw new Error(
+        `Provided number of values (${values.length}) does not match number of types (${this.types.length})`
+      );
+    }
+    this.rows.push(values.slice());
+    if (this.rows.length >= this.rowsPerDataChunk) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Emits the buffered rows as one data chunk. A no-op when none are
+   * buffered, so it is safe to call more than once.
+   *
+   * The buffer is emptied either way: if converting the rows fails, or the
+   * sink rejects the chunk, those rows are discarded along with the error.
+   * Appending afterwards starts a fresh chunk.
+   */
+  public flush(): void {
+    if (this.rows.length === 0) {
+      return;
+    }
+    // Taken before anything that can throw. Left in place, a batch that failed
+    // to convert or that the sink rejected would still be buffered, and later
+    // appends would grow it past `rowsPerDataChunk` and eventually past what a
+    // data chunk can hold at all — by which point the writer can no longer
+    // flush and the original error is long gone.
+    const rows = this.rows;
+    this.rows = [];
+    const chunk = DuckDBDataChunk.create(this.types);
+    if (this.converter) {
+      chunk.setRowsConverted(rows, this.converter);
+    } else {
+      // Without a converter the options type has already constrained `T` to
+      // `DuckDBValue`, which is the only thing that makes this cast sound.
+      chunk.setRows(rows as readonly (readonly DuckDBValue[])[]);
+    }
+    this.sink(chunk);
+  }
+}

package/vendor/node-api/src/DuckDBExtractedStatements.ts

@@ -0,0 +1,37 @@
+import duckdb from "../../../src/bindings/index.ts";
+import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+import { DuckDBPreparedStatementCollection } from './DuckDBPreparedStatementCollection';
+
+export class DuckDBExtractedStatements {
+  private readonly connection: duckdb.Connection;
+  private readonly extracted_statements: duckdb.ExtractedStatements;
+  private readonly statement_count: number;
+  private readonly preparedStatements?: DuckDBPreparedStatementCollection;
+  constructor(
+    connection: duckdb.Connection,
+    extracted_statements: duckdb.ExtractedStatements,
+    statement_count: number,
+    preparedStatements?: DuckDBPreparedStatementCollection
+  ) {
+    this.connection = connection;
+    this.extracted_statements = extracted_statements;
+    this.statement_count = statement_count;
+    this.preparedStatements = preparedStatements;
+  }
+  public get count(): number {
+    return this.statement_count;
+  }
+  public async prepare(index: number): Promise<DuckDBPreparedStatement> {
+    const prepared = new DuckDBPreparedStatement(
+      await duckdb.prepare_extracted_statement(
+        this.connection,
+        this.extracted_statements,
+        index
+      )
+    );
+    if (this.preparedStatements) {
+      this.preparedStatements.add(prepared);
+    }
+    return prepared;
+  }
+}

package/vendor/node-api/src/DuckDBInstance.ts

@@ -0,0 +1,35 @@
+import duckdb from "../../../src/bindings/index.ts";
+import { createConfig } from './createConfig';
+import { DuckDBConnection } from './DuckDBConnection';
+import { DuckDBInstanceCache } from './DuckDBInstanceCache';
+
+export class DuckDBInstance {
+  private readonly db: duckdb.Database;
+
+  constructor(db: duckdb.Database) {
+    this.db = db;
+  }
+
+  public static async create(
+    path?: string,
+    options?: Record<string, string>
+  ): Promise<DuckDBInstance> {
+    const config = createConfig(options);
+    return new DuckDBInstance(await duckdb.open(path, config));
+  }
+
+  public static async fromCache(
+    path?: string,
+    options?: Record<string, string>
+  ): Promise<DuckDBInstance> {
+    return DuckDBInstanceCache.singleton.getOrCreateInstance(path, options);
+  }
+
+  public async connect(): Promise<DuckDBConnection> {
+    return new DuckDBConnection(await duckdb.connect(this.db));
+  }
+
+  public closeSync() {
+    duckdb.close_sync(this.db);
+  }
+}

package/vendor/node-api/src/DuckDBInstanceCache.ts

@@ -0,0 +1,29 @@
+import duckdb from "../../../src/bindings/index.ts";
+import { DuckDBInstance } from './DuckDBInstance';
+import { createConfig } from './createConfig';
+
+export class DuckDBInstanceCache {
+  private readonly cache: duckdb.InstanceCache;
+
+  constructor() {
+    this.cache = duckdb.create_instance_cache();
+  }
+
+  public async getOrCreateInstance(
+    path?: string,
+    options?: Record<string, string>
+  ): Promise<DuckDBInstance> {
+    const config = createConfig(options);
+    const db = await duckdb.get_or_create_from_cache(this.cache, path, config);
+    return new DuckDBInstance(db);
+  }
+
+  private static singletonInstance: DuckDBInstanceCache;
+
+  public static get singleton(): DuckDBInstanceCache {
+    if (!DuckDBInstanceCache.singletonInstance) {
+      DuckDBInstanceCache.singletonInstance = new DuckDBInstanceCache();
+    }
+    return DuckDBInstanceCache.singletonInstance;
+  }
+}