@duckdb/node-api 1.1.2-alpha.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018-2023 Stichting DuckDB Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# DuckDB Node API
+
+API for using DuckDB in Node.
+
+[Documentation](https://github.com/duckdb/duckdb-node-neo)

package/lib/DuckDBAppender.d.ts

@@ -0,0 +1,36 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBType } from './DuckDBType';
+import { Date_, Interval, Time, Timestamp } from './DuckDBValue';
+import { DuckDBDataChunk } from './DuckDBDataChunk';
+export declare class DuckDBAppender {
+    private readonly appender;
+    constructor(appender: duckdb.Appender);
+    dispose(): void;
+    close(): void;
+    flush(): void;
+    get columnCount(): number;
+    columnType(columnIndex: number): DuckDBType;
+    endRow(): void;
+    appendDefault(): void;
+    appendBoolean(value: boolean): void;
+    appendTinyInt(value: number): void;
+    appendSmallInt(value: number): void;
+    appendInteger(value: number): void;
+    appendBigInt(value: bigint): void;
+    appendHugeInt(value: bigint): void;
+    appendUTinyInt(value: number): void;
+    appendUSmallInt(value: number): void;
+    appendUInteger(value: number): void;
+    appendUBigInt(value: bigint): void;
+    appendUHugeInt(value: bigint): void;
+    appendFloat(value: number): void;
+    appendDouble(value: number): void;
+    appendDate(value: Date_): void;
+    appendTime(value: Time): void;
+    appendTimestamp(value: Timestamp): void;
+    appendInterval(value: Interval): void;
+    appendVarchar(value: string): void;
+    appendBlob(value: Uint8Array): void;
+    appendNull(): void;
+    appendDataChunk(dataChunk: DuckDBDataChunk): void;
+}

package/lib/DuckDBAppender.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBAppender = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBLogicalType_1 = require("./DuckDBLogicalType");
+class DuckDBAppender {
+    appender;
+    constructor(appender) {
+        this.appender = appender;
+    }
+    dispose() {
+        node_bindings_1.default.appender_destroy(this.appender);
+    }
+    close() {
+        node_bindings_1.default.appender_close(this.appender);
+    }
+    flush() {
+        node_bindings_1.default.appender_flush(this.appender);
+    }
+    get columnCount() {
+        return node_bindings_1.default.appender_column_count(this.appender);
+    }
+    columnType(columnIndex) {
+        return DuckDBLogicalType_1.DuckDBLogicalType.consumeAsType(node_bindings_1.default.appender_column_type(this.appender, columnIndex));
+    }
+    endRow() {
+        node_bindings_1.default.appender_end_row(this.appender);
+    }
+    appendDefault() {
+        node_bindings_1.default.append_default(this.appender);
+    }
+    appendBoolean(value) {
+        node_bindings_1.default.append_bool(this.appender, value);
+    }
+    appendTinyInt(value) {
+        node_bindings_1.default.append_int8(this.appender, value);
+    }
+    appendSmallInt(value) {
+        node_bindings_1.default.append_int16(this.appender, value);
+    }
+    appendInteger(value) {
+        node_bindings_1.default.append_int32(this.appender, value);
+    }
+    appendBigInt(value) {
+        node_bindings_1.default.append_int64(this.appender, value);
+    }
+    appendHugeInt(value) {
+        node_bindings_1.default.append_hugeint(this.appender, value);
+    }
+    appendUTinyInt(value) {
+        node_bindings_1.default.append_uint8(this.appender, value);
+    }
+    appendUSmallInt(value) {
+        node_bindings_1.default.append_uint16(this.appender, value);
+    }
+    appendUInteger(value) {
+        node_bindings_1.default.append_uint32(this.appender, value);
+    }
+    appendUBigInt(value) {
+        node_bindings_1.default.append_uint64(this.appender, value);
+    }
+    appendUHugeInt(value) {
+        node_bindings_1.default.append_uhugeint(this.appender, value);
+    }
+    // TODO: append DECIMAL?
+    appendFloat(value) {
+        node_bindings_1.default.append_float(this.appender, value);
+    }
+    appendDouble(value) {
+        node_bindings_1.default.append_double(this.appender, value);
+    }
+    appendDate(value) {
+        node_bindings_1.default.append_date(this.appender, value);
+    }
+    appendTime(value) {
+        node_bindings_1.default.append_time(this.appender, value);
+    }
+    appendTimestamp(value) {
+        node_bindings_1.default.append_timestamp(this.appender, value);
+    }
+    // TODO: append TIMESTAMPS_S/_MS/_NS?
+    // TODO: append TIME_TZ/TIMESTAMP_TZ?
+    appendInterval(value) {
+        node_bindings_1.default.append_interval(this.appender, value);
+    }
+    appendVarchar(value) {
+        node_bindings_1.default.append_varchar(this.appender, value);
+    }
+    appendBlob(value) {
+        node_bindings_1.default.append_blob(this.appender, value);
+    }
+    // TODO: append ENUM?
+    // TODO: append nested types? (ARRAY, LIST, STRUCT, MAP, UNION)
+    // TODO: append UUID?
+    // TODO: append BIT?
+    appendNull() {
+        node_bindings_1.default.append_null(this.appender);
+    }
+    appendDataChunk(dataChunk) {
+        node_bindings_1.default.append_data_chunk(this.appender, dataChunk.chunk);
+    }
+}
+exports.DuckDBAppender = DuckDBAppender;

package/lib/DuckDBConnection.d.ts

@@ -0,0 +1,18 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBAppender } from './DuckDBAppender';
+import { DuckDBExtractedStatements } from './DuckDBExtractedStatements';
+import { DuckDBInstance } from './DuckDBInstance';
+import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+import { DuckDBResult } from './DuckDBResult';
+export declare class DuckDBConnection {
+    private readonly connection;
+    constructor(connection: duckdb.Connection);
+    static create(instance: DuckDBInstance): Promise<DuckDBConnection>;
+    dispose(): Promise<void>;
+    interrupt(): void;
+    get progress(): duckdb.QueryProgress;
+    run(sql: string): Promise<DuckDBResult>;
+    prepare(sql: string): Promise<DuckDBPreparedStatement>;
+    extractStatements(sql: string): Promise<DuckDBExtractedStatements>;
+    createAppender(schema: string, table: string): Promise<DuckDBAppender>;
+}

package/lib/DuckDBConnection.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBConnection = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBAppender_1 = require("./DuckDBAppender");
+const DuckDBExtractedStatements_1 = require("./DuckDBExtractedStatements");
+const DuckDBPreparedStatement_1 = require("./DuckDBPreparedStatement");
+const DuckDBResult_1 = require("./DuckDBResult");
+class DuckDBConnection {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    static async create(instance) {
+        return instance.connect();
+    }
+    dispose() {
+        return node_bindings_1.default.disconnect(this.connection);
+    }
+    interrupt() {
+        node_bindings_1.default.interrupt(this.connection);
+    }
+    get progress() {
+        return node_bindings_1.default.query_progress(this.connection);
+    }
+    async run(sql) {
+        return new DuckDBResult_1.DuckDBResult(await node_bindings_1.default.query(this.connection, sql));
+    }
+    async prepare(sql) {
+        return new DuckDBPreparedStatement_1.DuckDBPreparedStatement(await node_bindings_1.default.prepare(this.connection, sql));
+    }
+    async extractStatements(sql) {
+        const { extracted_statements, statement_count } = await node_bindings_1.default.extract_statements(this.connection, sql);
+        if (statement_count === 0) {
+            try {
+                throw new Error(`Failed to extract statements: ${node_bindings_1.default.extract_statements_error(extracted_statements)}`);
+            }
+            finally {
+                node_bindings_1.default.destroy_extracted(extracted_statements);
+            }
+        }
+        return new DuckDBExtractedStatements_1.DuckDBExtractedStatements(this.connection, extracted_statements, statement_count);
+    }
+    async createAppender(schema, table) {
+        return new DuckDBAppender_1.DuckDBAppender(node_bindings_1.default.appender_create(this.connection, schema, table));
+    }
+}
+exports.DuckDBConnection = DuckDBConnection;

package/lib/DuckDBDataChunk.d.ts

@@ -0,0 +1,13 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBVector } from './DuckDBVector';
+export declare class DuckDBDataChunk {
+    readonly chunk: duckdb.DataChunk;
+    constructor(chunk: duckdb.DataChunk);
+    static create(logical_types: duckdb.LogicalType[]): DuckDBDataChunk;
+    dispose(): void;
+    reset(): void;
+    get columnCount(): number;
+    getColumn(columnIndex: number): DuckDBVector<any>;
+    get rowCount(): number;
+    set rowCount(count: number);
+}

package/lib/DuckDBDataChunk.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBDataChunk = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBVector_1 = require("./DuckDBVector");
+class DuckDBDataChunk {
+    chunk;
+    constructor(chunk) {
+        this.chunk = chunk;
+    }
+    static create(logical_types) {
+        return new DuckDBDataChunk(node_bindings_1.default.create_data_chunk(logical_types));
+    }
+    dispose() {
+        node_bindings_1.default.destroy_data_chunk(this.chunk);
+    }
+    reset() {
+        node_bindings_1.default.data_chunk_reset(this.chunk);
+    }
+    get columnCount() {
+        return node_bindings_1.default.data_chunk_get_column_count(this.chunk);
+    }
+    getColumn(columnIndex) {
+        // TODO: cache vectors?
+        return DuckDBVector_1.DuckDBVector.create(node_bindings_1.default.data_chunk_get_vector(this.chunk, columnIndex), this.rowCount);
+    }
+    get rowCount() {
+        return node_bindings_1.default.data_chunk_get_size(this.chunk);
+    }
+    set rowCount(count) {
+        node_bindings_1.default.data_chunk_set_size(this.chunk, count);
+    }
+}
+exports.DuckDBDataChunk = DuckDBDataChunk;

package/lib/DuckDBExtractedStatements.d.ts

@@ -0,0 +1,11 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBPreparedStatement } from './DuckDBPreparedStatement';
+export declare class DuckDBExtractedStatements {
+    private readonly connection;
+    private readonly extracted_statements;
+    private readonly statement_count;
+    constructor(connection: duckdb.Connection, extracted_statements: duckdb.ExtractedStatements, statement_count: number);
+    dispose(): void;
+    get count(): number;
+    prepare(index: number): Promise<DuckDBPreparedStatement>;
+}

package/lib/DuckDBExtractedStatements.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBExtractedStatements = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBPreparedStatement_1 = require("./DuckDBPreparedStatement");
+class DuckDBExtractedStatements {
+    connection;
+    extracted_statements;
+    statement_count;
+    constructor(connection, extracted_statements, statement_count) {
+        this.connection = connection;
+        this.extracted_statements = extracted_statements;
+        this.statement_count = statement_count;
+    }
+    dispose() {
+        node_bindings_1.default.destroy_extracted(this.extracted_statements);
+    }
+    get count() {
+        return this.statement_count;
+    }
+    async prepare(index) {
+        return new DuckDBPreparedStatement_1.DuckDBPreparedStatement(await node_bindings_1.default.prepare_extracted_statement(this.connection, this.extracted_statements, index));
+    }
+}
+exports.DuckDBExtractedStatements = DuckDBExtractedStatements;

package/lib/DuckDBInstance.d.ts

@@ -0,0 +1,9 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBConnection } from './DuckDBConnection';
+export declare class DuckDBInstance {
+    private readonly db;
+    constructor(db: duckdb.Database);
+    static create(path?: string, options?: Record<string, string>): Promise<DuckDBInstance>;
+    dispose(): Promise<void>;
+    connect(): Promise<DuckDBConnection>;
+}

package/lib/DuckDBInstance.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBInstance = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBConnection_1 = require("./DuckDBConnection");
+class DuckDBInstance {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static async create(path, options) {
+        if (options) {
+            const config = node_bindings_1.default.create_config();
+            try {
+                for (const optionName in options) {
+                    const optionValue = options[optionName];
+                    node_bindings_1.default.set_config(config, optionName, optionValue);
+                }
+                return new DuckDBInstance(await node_bindings_1.default.open(path, config));
+            }
+            finally {
+                node_bindings_1.default.destroy_config(config);
+            }
+        }
+        else {
+            return new DuckDBInstance(await node_bindings_1.default.open(path));
+        }
+    }
+    dispose() {
+        return node_bindings_1.default.close(this.db);
+    }
+    async connect() {
+        return new DuckDBConnection_1.DuckDBConnection(await node_bindings_1.default.connect(this.db));
+    }
+}
+exports.DuckDBInstance = DuckDBInstance;

package/lib/DuckDBLogicalType.d.ts

@@ -0,0 +1,70 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBDecimalType, DuckDBEnumType, DuckDBListType, DuckDBMapType, DuckDBStructType, DuckDBType, DuckDBUnionType } from './DuckDBType';
+import { DuckDBTypeId } from './DuckDBTypeId';
+export declare class DuckDBLogicalType {
+    readonly logical_type: duckdb.LogicalType;
+    protected constructor(logical_type: duckdb.LogicalType);
+    static consumeAsType(logical_type: duckdb.LogicalType): DuckDBType;
+    static create(logical_type: duckdb.LogicalType): DuckDBLogicalType;
+    static createDecimal(width: number, scale: number): DuckDBDecimalLogicalType;
+    static createEnum(member_names: readonly string[]): DuckDBEnumLogicalType;
+    static createList(valueType: DuckDBLogicalType): DuckDBListLogicalType;
+    static createStruct(entries: readonly DuckDBLogicalStructEntry[]): DuckDBStructLogicalType;
+    static createMap(keyType: DuckDBLogicalType, valueType: DuckDBLogicalType): DuckDBMapLogicalType;
+    static createArray(valueType: DuckDBLogicalType, length: number): DuckDBArrayLogicalType;
+    static createUnion(alternatives: readonly DuckDBLogicalUnionAlternative[]): DuckDBUnionLogicalType;
+    dispose(): void;
+    get typeId(): DuckDBTypeId;
+    get alias(): string | null;
+    set alias(newAlias: string);
+    asType(): DuckDBType;
+}
+export declare class DuckDBDecimalLogicalType extends DuckDBLogicalType {
+    get width(): number;
+    get scale(): number;
+    get internalTypeId(): DuckDBTypeId;
+    asType(): DuckDBDecimalType;
+}
+export declare class DuckDBEnumLogicalType extends DuckDBLogicalType {
+    get valueCount(): number;
+    value(index: number): string;
+    values(): readonly string[];
+    get internalTypeId(): DuckDBTypeId;
+    asType(): DuckDBEnumType;
+}
+export declare class DuckDBListLogicalType extends DuckDBLogicalType {
+    get valueType(): DuckDBLogicalType;
+    asType(): DuckDBListType;
+}
+export interface DuckDBLogicalStructEntry {
+    readonly name: string;
+    readonly valueType: DuckDBLogicalType;
+}
+export declare class DuckDBStructLogicalType extends DuckDBLogicalType {
+    get entryCount(): number;
+    entryName(index: number): string;
+    entryValueType(index: number): DuckDBLogicalType;
+    entries(): readonly DuckDBLogicalStructEntry[];
+    asType(): DuckDBStructType;
+}
+export declare class DuckDBMapLogicalType extends DuckDBLogicalType {
+    get keyType(): DuckDBLogicalType;
+    get valueType(): DuckDBLogicalType;
+    asType(): DuckDBMapType;
+}
+export declare class DuckDBArrayLogicalType extends DuckDBLogicalType {
+    get valueType(): DuckDBLogicalType;
+    get length(): number;
+    asType(): DuckDBListType;
+}
+export interface DuckDBLogicalUnionAlternative {
+    readonly tag: string;
+    readonly valueType: DuckDBLogicalType;
+}
+export declare class DuckDBUnionLogicalType extends DuckDBLogicalType {
+    get alternativeCount(): number;
+    alternativeTag(index: number): string;
+    alternativeValueType(index: number): DuckDBLogicalType;
+    alternatives(): readonly DuckDBLogicalUnionAlternative[];
+    asType(): DuckDBUnionType;
+}