@avidian/duckdb-bun 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,403 @@
+import duckdb from "../../../src/bindings/index.ts";
+import { DuckDBDataChunk } from './DuckDBDataChunk';
+import { DuckDBLogicalType } from './DuckDBLogicalType';
+import { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { JS } from './JS';
+import { JSDuckDBValueConverter } from './JSDuckDBValueConverter';
+import { Json } from './Json';
+import { JsonDuckDBValueConverter } from './JsonDuckDBValueConverter';
+import { convertColumnsFromChunks } from './convertColumnsFromChunks';
+import { convertColumnsObjectFromChunks } from './convertColumnsObjectFromChunks';
+import { convertRowObjectsFromChunks } from './convertRowObjectsFromChunks';
+import { convertRowsFromChunks } from './convertRowsFromChunks';
+import { ResultReturnType, StatementType } from './enums';
+import { getColumnsFromChunks } from './getColumnsFromChunks';
+import { getColumnsObjectFromChunks } from './getColumnsObjectFromChunks';
+import { getRowObjectsFromChunks } from './getRowObjectsFromChunks';
+import { getRowsFromChunks } from './getRowsFromChunks';
+import { DuckDBValue } from './values';
+
+interface ClosedResultMetadata {
+  returnType: ResultReturnType;
+  statementType: StatementType;
+  columnNames: string[];
+  columnTypes: DuckDBType[];
+  isStreaming: boolean;
+  rowsChanged: number;
+}
+
+export class DuckDBResult {
+  protected readonly result: duckdb.Result;
+  private readonly preparedStatementType: StatementType | undefined;
+  private closedMetadata: ClosedResultMetadata | undefined;
+
+  /**
+   * `preparedStatementType` is the type of the prepared statement the result
+   * came from, if any. It is reported as the result's statement type when
+   * DuckDB reports EXECUTE instead.
+   */
+  constructor(result: duckdb.Result, preparedStatementType?: StatementType) {
+    this.result = result;
+    this.preparedStatementType = preparedStatementType;
+  }
+
+  /**
+   * Destroys the result, freeing its memory. On DuckDB 2.0, a streaming result
+   * that has not been read to the end blocks its connection from starting
+   * another statement until it is closed.
+   *
+   * The return type, statement type, column names and types, and rows changed
+   * stay available; fetching throws. If a fetch is in flight, the result is
+   * destroyed, and its connection unblocked, only once that fetch finishes.
+   * Closing again does nothing.
+   */
+  public closeSync() {
+    if (!this.closedMetadata) {
+      const columnCount = this.columnCount;
+      const columnNames: string[] = [];
+      const columnTypes: DuckDBType[] = [];
+      for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+        columnNames.push(this.columnName(columnIndex));
+        columnTypes.push(this.columnType(columnIndex));
+      }
+      this.closedMetadata = {
+        returnType: this.returnType,
+        statementType: this.statementType,
+        columnNames,
+        columnTypes,
+        isStreaming: this.isStreaming,
+        rowsChanged: this.rowsChanged,
+      };
+    }
+    duckdb.destroy_result_sync(this.result);
+  }
+
+  public get returnType(): ResultReturnType {
+    if (this.closedMetadata) {
+      return this.closedMetadata.returnType;
+    }
+    return duckdb.result_return_type(this.result);
+  }
+
+  public get statementType(): StatementType {
+    if (this.closedMetadata) {
+      return this.closedMetadata.statementType;
+    }
+    const statementType = duckdb.result_statement_type(this.result);
+    // On DuckDB 2.0, results of prepared statements report EXECUTE; see
+    // https://github.com/duckdb/duckdb/issues/27415
+    if (
+      statementType === StatementType.EXECUTE &&
+      this.preparedStatementType !== undefined
+    ) {
+      return this.preparedStatementType;
+    }
+    return statementType;
+  }
+
+  public get columnCount(): number {
+    if (this.closedMetadata) {
+      return this.closedMetadata.columnNames.length;
+    }
+    return duckdb.column_count(this.result);
+  }
+
+  public columnName(columnIndex: number): string {
+    if (this.closedMetadata) {
+      return this.closedMetadata.columnNames[
+        this.checkClosedColumnIndex(columnIndex)
+      ];
+    }
+    return duckdb.column_name(this.result, columnIndex);
+  }
+
+  public columnNames(): string[] {
+    const columnNames: string[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnNames.push(this.columnName(columnIndex));
+    }
+    return columnNames;
+  }
+
+  public deduplicatedColumnNames(): string[] {
+    const outputColumnNames: string[] = [];
+    const columnCount = this.columnCount;
+    const columnNameCount: { [columnName: string]: number } = {};
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const inputColumnName = this.columnName(columnIndex);
+      const nameCount = (columnNameCount[inputColumnName] || 0) + 1;
+      columnNameCount[inputColumnName] = nameCount;
+      if (nameCount > 1) {
+        outputColumnNames.push(`${inputColumnName}:${nameCount - 1}`);
+      } else {
+        outputColumnNames.push(inputColumnName);
+      }
+    }
+    return outputColumnNames;
+  }
+
+  public columnTypeId(columnIndex: number): DuckDBTypeId {
+    if (this.closedMetadata) {
+      return this.columnType(columnIndex).typeId;
+    }
+    return duckdb.column_type(
+      this.result,
+      columnIndex
+    ) as number as DuckDBTypeId;
+  }
+
+  public columnLogicalType(columnIndex: number): DuckDBLogicalType {
+    if (this.closedMetadata) {
+      return this.columnType(columnIndex).toLogicalType();
+    }
+    return DuckDBLogicalType.create(
+      duckdb.column_logical_type(this.result, columnIndex)
+    );
+  }
+
+  public columnType(columnIndex: number): DuckDBType {
+    if (this.closedMetadata) {
+      return this.closedMetadata.columnTypes[
+        this.checkClosedColumnIndex(columnIndex)
+      ];
+    }
+    return this.columnLogicalType(columnIndex).asType();
+  }
+
+  public columnTypeJson(columnIndex: number): Json {
+    return this.columnType(columnIndex).toJson();
+  }
+
+  public columnTypes(): DuckDBType[] {
+    const columnTypes: DuckDBType[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnTypes.push(this.columnType(columnIndex));
+    }
+    return columnTypes;
+  }
+
+  public columnTypesJson(): Json {
+    const columnTypesJson: Json[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnTypesJson.push(this.columnTypeJson(columnIndex));
+    }
+    return columnTypesJson;
+  }
+
+  public columnNamesAndTypesJson(): Json {
+    return {
+      columnNames: this.columnNames(),
+      columnTypes: this.columnTypesJson(),
+    };
+  }
+
+  public columnNameAndTypeObjectsJson(): Json {
+    const columnNameAndTypeObjects: Json[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnNameAndTypeObjects.push({
+        columnName: this.columnName(columnIndex),
+        columnType: this.columnTypeJson(columnIndex),
+      });
+    }
+    return columnNameAndTypeObjects;
+  }
+
+  public get isStreaming(): boolean {
+    if (this.closedMetadata) {
+      return this.closedMetadata.isStreaming;
+    }
+    return duckdb.result_is_streaming(this.result);
+  }
+
+  public get rowsChanged(): number {
+    if (this.closedMetadata) {
+      return this.closedMetadata.rowsChanged;
+    }
+    return duckdb.rows_changed(this.result);
+  }
+
+  public async fetchChunk(): Promise<DuckDBDataChunk | null> {
+    const chunk = await duckdb.fetch_chunk(this.result);
+    return chunk ? new DuckDBDataChunk(chunk) : null;
+  }
+
+  public async fetchAllChunks(): Promise<DuckDBDataChunk[]> {
+    const chunks: DuckDBDataChunk[] = [];
+    while (true) {
+      const chunk = await this.fetchChunk();
+      if (!chunk || chunk.rowCount === 0) {
+        return chunks;
+      }
+      chunks.push(chunk);
+    }
+  }
+
+  public async getColumns(): Promise<DuckDBValue[][]> {
+    const chunks = await this.fetchAllChunks();
+    return getColumnsFromChunks(chunks, this.columnCount);
+  }
+
+  public async convertColumns<T>(
+    converter: DuckDBValueConverter<T>
+  ): Promise<(T | null)[][]> {
+    const chunks = await this.fetchAllChunks();
+    return convertColumnsFromChunks(chunks, this.columnCount, converter);
+  }
+
+  public async getColumnsJS(): Promise<JS[][]> {
+    return this.convertColumns(JSDuckDBValueConverter);
+  }
+
+  public async getColumnsJson(): Promise<Json[][]> {
+    return this.convertColumns(JsonDuckDBValueConverter);
+  }
+
+  public async getColumnsObject(): Promise<Record<string, DuckDBValue[]>> {
+    const chunks = await this.fetchAllChunks();
+    return getColumnsObjectFromChunks(chunks, this.deduplicatedColumnNames());
+  }
+
+  public async convertColumnsObject<T>(
+    converter: DuckDBValueConverter<T>
+  ): Promise<Record<string, (T | null)[]>> {
+    const chunks = await this.fetchAllChunks();
+    return convertColumnsObjectFromChunks(
+      chunks,
+      this.deduplicatedColumnNames(),
+      converter
+    );
+  }
+
+  public async getColumnsObjectJS(): Promise<Record<string, JS[]>> {
+    return this.convertColumnsObject(JSDuckDBValueConverter);
+  }
+
+  public async getColumnsObjectJson(): Promise<Record<string, Json[]>> {
+    return this.convertColumnsObject(JsonDuckDBValueConverter);
+  }
+
+  public async getRows(): Promise<DuckDBValue[][]> {
+    const chunks = await this.fetchAllChunks();
+    return getRowsFromChunks(chunks);
+  }
+
+  public async convertRows<T>(
+    converter: DuckDBValueConverter<T>
+  ): Promise<(T | null)[][]> {
+    const chunks = await this.fetchAllChunks();
+    return convertRowsFromChunks(chunks, converter);
+  }
+
+  public async getRowsJS(): Promise<JS[][]> {
+    return this.convertRows(JSDuckDBValueConverter);
+  }
+
+  public async getRowsJson(): Promise<Json[][]> {
+    return this.convertRows(JsonDuckDBValueConverter);
+  }
+
+  public async getRowObjects(): Promise<Record<string, DuckDBValue>[]> {
+    const chunks = await this.fetchAllChunks();
+    return getRowObjectsFromChunks(chunks, this.deduplicatedColumnNames());
+  }
+
+  public async convertRowObjects<T>(
+    converter: DuckDBValueConverter<T>
+  ): Promise<Record<string, T | null>[]> {
+    const chunks = await this.fetchAllChunks();
+    return convertRowObjectsFromChunks(
+      chunks,
+      this.deduplicatedColumnNames(),
+      converter
+    );
+  }
+
+  public async getRowObjectsJS(): Promise<Record<string, JS>[]> {
+    return this.convertRowObjects(JSDuckDBValueConverter);
+  }
+
+  public async getRowObjectsJson(): Promise<Record<string, Json>[]> {
+    return this.convertRowObjects(JsonDuckDBValueConverter);
+  }
+
+  public async *[Symbol.asyncIterator](): AsyncIterableIterator<DuckDBDataChunk> {
+    while (true) {
+      const chunk = await this.fetchChunk();
+      if (chunk && chunk.rowCount > 0) {
+        yield chunk;
+      } else {
+        break;
+      }
+    }
+  }
+
+  public async *yieldRows(): AsyncIterableIterator<DuckDBValue[][]> {
+    for await (const chunk of this) {
+      yield getRowsFromChunks([chunk]);
+    }
+  }
+
+  public async *yieldRowObjects(): AsyncIterableIterator<
+    Record<string, DuckDBValue>[]
+  > {
+    const deduplicatedColumnNames = this.deduplicatedColumnNames();
+    for await (const chunk of this) {
+      yield getRowObjectsFromChunks([chunk], deduplicatedColumnNames);
+    }
+  }
+
+  public async *yieldConvertedRows<T>(
+    converter: DuckDBValueConverter<T>
+  ): AsyncIterableIterator<(T | null)[][]> {
+    for await (const chunk of this) {
+      yield convertRowsFromChunks([chunk], converter);
+    }
+  }
+
+  public async *yieldConvertedRowObjects<T>(
+    converter: DuckDBValueConverter<T>
+  ): AsyncIterableIterator<Record<string, T | null>[]> {
+    const deduplicatedColumnNames = this.deduplicatedColumnNames();
+    for await (const chunk of this) {
+      yield convertRowObjectsFromChunks(
+        [chunk],
+        deduplicatedColumnNames,
+        converter
+      );
+    }
+  }
+
+  public yieldRowsJs(): AsyncIterableIterator<JS[][]> {
+    return this.yieldConvertedRows(JSDuckDBValueConverter);
+  }
+
+  public yieldRowsJson(): AsyncIterableIterator<Json[][]> {
+    return this.yieldConvertedRows(JsonDuckDBValueConverter);
+  }
+
+  public yieldRowObjectJs(): AsyncIterableIterator<Record<string, JS>[]> {
+    return this.yieldConvertedRowObjects(JSDuckDBValueConverter);
+  }
+
+  public yieldRowObjectJson(): AsyncIterableIterator<Record<string, Json>[]> {
+    return this.yieldConvertedRowObjects(JsonDuckDBValueConverter);
+  }
+
+  /** Converts the index as the bindings do (ToUint32), then checks range. */
+  private checkClosedColumnIndex(columnIndex: number): number {
+    const index = columnIndex >>> 0;
+    const columnCount = this.closedMetadata?.columnNames.length ?? 0;
+    if (index >= columnCount) {
+      throw new RangeError(
+        `column index ${index} is out of range (count: ${columnCount})`
+      );
+    }
+    return index;
+  }
+}

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

@@ -0,0 +1,283 @@
+import { convertColumnsFromChunks } from './convertColumnsFromChunks';
+import { convertColumnsObjectFromChunks } from './convertColumnsObjectFromChunks';
+import { convertRowObjectsFromChunks } from './convertRowObjectsFromChunks';
+import { convertRowsFromChunks } from './convertRowsFromChunks';
+import { DuckDBDataChunk } from './DuckDBDataChunk';
+import { DuckDBLogicalType } from './DuckDBLogicalType';
+import { DuckDBResult } from './DuckDBResult';
+import { DuckDBType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { ResultReturnType, StatementType } from './enums';
+import { getColumnsFromChunks } from './getColumnsFromChunks';
+import { getColumnsObjectFromChunks } from './getColumnsObjectFromChunks';
+import { getRowObjectsFromChunks } from './getRowObjectsFromChunks';
+import { getRowsFromChunks } from './getRowsFromChunks';
+import { JS } from './JS';
+import { JSDuckDBValueConverter } from './JSDuckDBValueConverter';
+import { Json } from './Json';
+import { JsonDuckDBValueConverter } from './JsonDuckDBValueConverter';
+import { DuckDBValue } from './values';
+
+interface ChunkSizeRun {
+  chunkCount: number;
+  chunkSize: number;
+  rowCount: number; // Equal to chunkCount * chunkSize; precalculated for efficiency.
+}
+
+export class DuckDBResultReader {
+  private readonly result: DuckDBResult;
+  private readonly chunks: DuckDBDataChunk[];
+  private readonly chunkSizeRuns: ChunkSizeRun[];
+  private currentRowCount_: number;
+  private done_: boolean;
+
+  constructor(result: DuckDBResult) {
+    this.result = result;
+    this.chunks = [];
+    this.chunkSizeRuns = [];
+    this.currentRowCount_ = 0;
+    this.done_ = false;
+  }
+
+  /**
+   * Closes the result being read; see `DuckDBResult.closeSync`. Rows already
+   * read and the column metadata stay available; reading more throws.
+   */
+  public closeSync() {
+    this.result.closeSync();
+  }
+
+  public get returnType(): ResultReturnType {
+    return this.result.returnType;
+  }
+
+  public get statementType(): StatementType {
+    return this.result.statementType;
+  }
+
+  public get columnCount(): number {
+    return this.result.columnCount;
+  }
+
+  public columnName(columnIndex: number): string {
+    return this.result.columnName(columnIndex);
+  }
+
+  public columnNames(): string[] {
+    return this.result.columnNames();
+  }
+
+  public deduplicatedColumnNames(): string[] {
+    return this.result.deduplicatedColumnNames();
+  }
+
+  public columnTypeId(columnIndex: number): DuckDBTypeId {
+    return this.result.columnTypeId(columnIndex);
+  }
+
+  public columnLogicalType(columnIndex: number): DuckDBLogicalType {
+    return this.result.columnLogicalType(columnIndex);
+  }
+
+  public columnType(columnIndex: number): DuckDBType {
+    return this.result.columnType(columnIndex);
+  }
+
+  public columnTypeJson(columnIndex: number): Json {
+    return this.result.columnTypeJson(columnIndex);
+  }
+
+  public columnTypes(): DuckDBType[] {
+    return this.result.columnTypes();
+  }
+
+  public columnTypesJson(): Json {
+    return this.result.columnTypesJson();
+  }
+
+  public columnNamesAndTypesJson(): Json {
+    return this.result.columnNamesAndTypesJson();
+  }
+
+  public columnNameAndTypeObjectsJson(): Json {
+    return this.result.columnNameAndTypeObjectsJson();
+  }
+  
+  public get rowsChanged(): number {
+    return this.result.rowsChanged;
+  }
+
+  /** Total number of rows read so far. Call `readAll` or `readUntil` to read rows. */
+  public get currentRowCount() {
+    return this.currentRowCount_;
+  }
+
+  /** Whether reading is done, that is, there are no more rows to read. */
+  public get done() {
+    return this.done_;
+  }
+
+  /**
+   * Returns the value for the given column and row. Both are zero-indexed.
+   *
+   * Will return an error if `rowIndex` is greater than `currentRowCount`.
+   */
+  public value(columnIndex: number, rowIndex: number): DuckDBValue {
+    if (this.currentRowCount_ === 0) {
+      throw Error(`No rows have been read`);
+    }
+    let chunkIndex = 0;
+    let currentRowIndex = rowIndex;
+    // Find which run of chunks our row is in.
+    // Since chunkSizeRuns shouldn't ever be longer than 2, this should be O(1).
+    for (const run of this.chunkSizeRuns) {
+      if (currentRowIndex < run.rowCount) {
+        // The row we're looking for is in this run.
+        // Calculate the chunk index and the row index in that chunk.
+        chunkIndex += Math.floor(currentRowIndex / run.chunkSize);
+        const rowIndexInChunk = currentRowIndex % run.chunkSize;
+        const chunk = this.chunks[chunkIndex];
+        return chunk.getColumnVector(columnIndex).getItem(rowIndexInChunk);
+      }
+      // The row we're looking for is not in this run.
+      // Update our counts for this run and move to the next one.
+      chunkIndex += run.chunkCount;
+      currentRowIndex -= run.rowCount;
+    }
+    // We didn't find our row. It must have been out of range.
+    throw Error(
+      `Row index ${rowIndex} requested, but only ${this.currentRowCount_} row have been read so far.`
+    );
+  }
+
+  /** Read all rows. */
+  public async readAll(): Promise<void> {
+    return this.fetchChunks();
+  }
+
+  /**
+   * Read rows until at least the given target row count has been met.
+   *
+   * Note that the resulting row count could be greater than the target, since rows are read in chunks, typically of 2048 rows each.
+   */
+  public async readUntil(targetRowCount: number): Promise<void> {
+    return this.fetchChunks(targetRowCount);
+  }
+
+  private async fetchChunks(targetRowCount?: number): Promise<void> {
+    while (
+      !(
+        this.done_ ||
+        (targetRowCount !== undefined &&
+          this.currentRowCount_ >= targetRowCount)
+      )
+    ) {
+      const chunk = await this.result.fetchChunk();
+      if (chunk && chunk.rowCount > 0) {
+        this.updateChunkSizeRuns(chunk);
+        this.chunks.push(chunk);
+        this.currentRowCount_ += chunk.rowCount;
+      } else {
+        this.done_ = true;
+      }
+    }
+  }
+
+  private updateChunkSizeRuns(chunk: DuckDBDataChunk) {
+    if (this.chunkSizeRuns.length > 0) {
+      const lastRun = this.chunkSizeRuns[this.chunkSizeRuns.length - 1];
+      if (lastRun.chunkSize === chunk.rowCount) {
+        // If the new batch is the same size as the last one, just update our last run.
+        lastRun.chunkCount += 1;
+        lastRun.rowCount += lastRun.chunkSize;
+        return;
+      }
+    }
+    // If this is our first batch, or it's a different size, create a new run.
+    this.chunkSizeRuns.push({
+      chunkCount: 1,
+      chunkSize: chunk.rowCount,
+      rowCount: chunk.rowCount,
+    });
+  }
+
+  public getColumns(): DuckDBValue[][] {
+    return getColumnsFromChunks(this.chunks, this.columnCount);
+  }
+
+  public convertColumns<T>(converter: DuckDBValueConverter<T>): (T | null)[][] {
+    return convertColumnsFromChunks(this.chunks, this.columnCount, converter);
+  }
+
+  public getColumnsJS(): JS[][] {
+    return this.convertColumns(JSDuckDBValueConverter);
+  }
+
+  public getColumnsJson(): Json[][] {
+    return this.convertColumns(JsonDuckDBValueConverter);
+  }
+
+  public getColumnsObject(): Record<string, DuckDBValue[]> {
+    return getColumnsObjectFromChunks(
+      this.chunks,
+      this.deduplicatedColumnNames()
+    );
+  }
+
+  public convertColumnsObject<T>(
+    converter: DuckDBValueConverter<T>
+  ): Record<string, (T | null)[]> {
+    return convertColumnsObjectFromChunks(
+      this.chunks,
+      this.deduplicatedColumnNames(),
+      converter
+    );
+  }
+
+  public getColumnsObjectJS(): Record<string, JS[]> {
+    return this.convertColumnsObject(JSDuckDBValueConverter);
+  }
+
+  public getColumnsObjectJson(): Record<string, Json[]> {
+    return this.convertColumnsObject(JsonDuckDBValueConverter);
+  }
+
+  public getRows(): DuckDBValue[][] {
+    return getRowsFromChunks(this.chunks);
+  }
+
+  public convertRows<T>(converter: DuckDBValueConverter<T>): (T | null)[][] {
+    return convertRowsFromChunks(this.chunks, converter);
+  }
+
+  public getRowsJS(): JS[][] {
+    return this.convertRows(JSDuckDBValueConverter);
+  }
+
+  public getRowsJson(): Json[][] {
+    return this.convertRows(JsonDuckDBValueConverter);
+  }
+
+  public getRowObjects(): Record<string, DuckDBValue>[] {
+    return getRowObjectsFromChunks(this.chunks, this.deduplicatedColumnNames());
+  }
+
+  public convertRowObjects<T>(
+    converter: DuckDBValueConverter<T>
+  ): Record<string, T | null>[] {
+    return convertRowObjectsFromChunks(
+      this.chunks,
+      this.deduplicatedColumnNames(),
+      converter
+    );
+  }
+
+  public getRowObjectsJS(): Record<string, JS>[] {
+    return this.convertRowObjects(JSDuckDBValueConverter);
+  }
+
+  public getRowObjectsJson(): Record<string, Json>[] {
+    return this.convertRowObjects(JsonDuckDBValueConverter);
+  }
+}