@ohos-ports/duckdb 0.0.0-stage → 1.4.2-beta.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018-2025 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

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+> [!WARNING]
+> The original DuckDB <> Node.js bindings in this package are deprecated in favor of the new and shiny `@duckdb/node-api` package. Currently, the plan is to release this package `duckdb-node` for the last time for the DuckDB 1.4.x (~Fall 2025) series but *not* for the DuckDB 1.5.x series (~Early 2026) any more. Please [contact](https://duckdblabs.com/contact/) DuckDB Labs if you absolutely require updates after that.
+
+# DuckDB Node Bindings
+
+This package provides a Node.js API for [DuckDB](https://github.com/duckdb/duckdb), the "SQLite for Analytics". The API for this client is somewhat compliant to the SQLite Node.js client for easier transition (and transition you must eventually).
+
+Load the package and create a database object:
+
+```js
+var duckdb = require('duckdb');
+
+var db = new duckdb.Database(':memory:'); // or a file name for a persistent DB
+```
+
+Then you can run a query:
+
+```js
+db.all('SELECT 42 AS fortytwo', function(err, res) {
+  if (err) {
+    console.warn(err);
+  }
+  console.log(res[0].fortytwo)
+});
+```
+
+Other available methods are `each`, where the callback is invoked for each row, `run` to execute a single statement without results and `exec`, which can execute several SQL commands at once but also does not return results. All those commands can work with prepared statements, taking the values for the parameters as additional arguments. For example like so:
+
+```js
+db.all('SELECT ?::INTEGER AS fortytwo, ?::STRING as hello', 42, 'Hello, World', function(err, res) {
+  if (err) {
+    console.warn(err);
+  }
+  console.log(res[0].fortytwo)
+  console.log(res[0].hello)
+});
+```
+
+However, these are all shorthands for something much more elegant. A database can have multiple `Connection`s, those are created using `db.connect()`.
+
+```js
+var con = db.connect();
+```
+
+You can create multiple connections, each with their own transaction context.
+
+
+`Connection` objects also contain shorthands to directly call `run()`, `all()` and `each()` with parameters and callbacks, respectively, for example:
+
+```js
+con.all('SELECT 42 AS fortytwo', function(err, res) {
+  if (err) {
+    console.warn(err);
+  }
+  console.log(res[0].fortytwo)
+});
+```
+
+From connections, you can create prepared statements (and only that) using `con.prepare()`:
+
+```js
+var stmt = con.prepare('select ?::INTEGER as fortytwo');
+``` 
+
+To execute this statement, you can call for example `all()` on the `stmt` object:
+
+```js
+stmt.all(42, function(err, res) {
+  if (err) {
+    console.warn(err);
+  }
+  console.log(res[0].fortytwo)
+});
+```
+
+You can also execute the prepared statement multiple times. This is for example useful to fill a table with data:
+
+```js
+con.run('CREATE TABLE a (i INTEGER)');
+var stmt = con.prepare('INSERT INTO a VALUES (?)');
+for (var i = 0; i < 10; i++) {
+  stmt.run(i);
+}
+stmt.finalize();
+con.all('SELECT * FROM a', function(err, res) {
+  if (err) {
+    console.warn(err);
+  }
+  console.log(res)
+});
+```
+
+`prepare()` can also take a callback which gets the prepared statement as an argument:
+
+```js
+var stmt = con.prepare('select ?::INTEGER as fortytwo', function(err, stmt) {
+  stmt.all(42, function(err, res) {
+    if (err) {
+      console.warn(err);
+    }
+    console.log(res[0].fortytwo)
+  });
+});
+```
+
+## Supported Node versions
+We actively support only LTS and In-Support Node versions, as per July 2023, they are: Node 18, Node 20 and Node 21. For OSX and Linux targets, also Node 22 is available.
+Release schedule for Node.js can be checked here: https://github.com/nodejs/release#release-schedule.
+
+We currently bundle and test DuckDB also for Node 12, 14, 16, 17 and 19. We plan of going so going forward as long as the tooling supports it.
+As per July 2023, Node 15 has been removed from the supported versions.
+
+## Development
+
+### First install:
+
+To install all the dev dependencies of the project, run `npm install` (this uses package.json)
+You might want to add the `--ignore-scripts` option if you don't care about building the package for now and just want to install the dependencies.
+
+### Tests:
+Tests are located in `test` and can be run with `npm test`
+To run a single test, you can use `npm test -- --grep "name of test as given in describe"`
+
+### Additional notes:
+To build the NodeJS package from source, when on Windows, requires the following extra steps:
+- Set `OPENSSL_ROOT_DIR` to the root directory of an OpenSSL installation
+- Supply the `STATIC_OPENSSL=1` option when executing `make`, or set `-DOPENSSL_USE_STATIC_LIBS=1` manually when calling `cmake`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/duckdb.js

@@ -0,0 +1 @@
+module.exports = require('./lib/duckdb');

package/lib/binding/duckdb.node

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/lib/binding/duckdb.node
+size: 64145920 bytes
+sha256: 27e61cfd99fa79d7f63005beaccc6b26e32e6263d4c20b685b0c3897565a4adc

package/lib/duckdb-binding.js

@@ -0,0 +1,16 @@
+// @ohos-ports/duckdb: vendored native binding loader (openharmony/arm64)
+// The prebuilt, signed duckdb.node addon is shipped inside this package at
+// lib/binding/duckdb.node, so no @mapbox/node-pre-gyp download/build step is
+// needed at install time (upstream npm duckdb 404s its openharmony prebuilds).
+var path = require('path');
+var binding_path = path.join(__dirname, 'binding', 'duckdb.node');
+var fs = require('fs');
+if (!fs.existsSync(binding_path)) {
+    throw new Error(
+        '@ohos-ports/duckdb: native binding not found at ' + binding_path +
+        ' — this package ships a prebuilt openharmony/arm64 addon and does not support building from source at install time.'
+    );
+}
+var binding = require(binding_path);
+
+module.exports = exports = binding;

package/lib/duckdb.d.ts

@@ -0,0 +1,281 @@
+/**
+ * TypeScript declarations for Node.JS bindings for DuckDb.
+ * See https://duckdb.org/docs/api/nodejs/overview for details
+ * on Node.JS API
+ */
+
+export type ExceptionType =
+    | "Invalid"          // invalid type
+    | "Out of Range"     // value out of range error
+    | "Conversion"       // conversion/casting error
+    | "Unknown Type"     // unknown type
+    | "Decimal"          // decimal related
+    | "Mismatch Type"    // type mismatch
+    | "Divide by Zero"   // divide by 0
+    | "Object Size"      // object size exceeded
+    | "Invalid type"     // incompatible for operation
+    | "Serialization"    // serialization
+    | "TransactionContext" // transaction management
+    | "Not implemented"  // method not implemented
+    | "Expression"       // expression parsing
+    | "Catalog"          // catalog related
+    | "Parser"           // parser related
+    | "Binder"           // binder related
+    | "Planner"          // planner related
+    | "Scheduler"        // scheduler related
+    | "Executor"         // executor related
+    | "Constraint"       // constraint related
+    | "Index"            // index related
+    | "Stat"             // stat related
+    | "Connection"       // connection related
+    | "Syntax"           // syntax related
+    | "Settings"         // settings related
+    | "Optimizer"        // optimizer related
+    | "NullPointer"      // nullptr exception
+    | "IO"               // IO exception
+    | "INTERRUPT"        // interrupt
+    | "FATAL"            // Fatal exceptions are non-recoverable and render the entire DB in an unusable state
+    | "INTERNAL"         // Internal exceptions indicate something went wrong internally (i.e. bug in the code base)
+    | "Invalid Input"    // Input or arguments error
+    | "Out of Memory"    // out of memory
+    | "Permission"       // insufficient permissions
+    | "Parameter Not Resolved" // parameter types could not be resolved
+    | "Parameter Not Allowed"  // parameter types not allowed
+    | "Dependency"       // dependency
+    | "Unknown"
+    | "HTTP"
+    ;
+
+/**
+ * Standard error shape for DuckDB errors
+ */
+export interface _DuckDbError extends Error {
+  errno: -1; // value of ERROR
+  code: 'DUCKDB_NODEJS_ERROR';
+  errorType: ExceptionType;
+}
+
+export interface HttpError extends _DuckDbError {
+  errorType: 'HTTP';
+  statusCode: number;
+  response: string;
+  reason: string;
+  headers: Record<string, string>;
+}
+
+export type DuckDbError = HttpError | _DuckDbError;
+
+type Callback<T> = (err: DuckDbError | null, res: T) => void;
+
+export type RowData = {
+  [columnName: string]: any;
+};
+
+export type TableData = RowData[];
+export type ArrowIterable = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
+export type ArrowArray = Uint8Array[];
+
+export class Connection {
+  constructor(db: Database, callback?: Callback<any>);
+
+  close(callback?: Callback<void>): void;
+
+  all(sql: string, ...args: [...any, Callback<TableData>] | []): void;
+  arrowIPCAll(sql: string, ...args: [...any, Callback<ArrowArray>] | []): void;
+  each(sql: string, ...args: [...any, Callback<RowData>] | []): void;
+  exec(sql: string, ...args: [...any, Callback<void>] | []): void;
+
+  prepare(sql: string, ...args: [...any, Callback<Statement>] | []): Statement;
+  run(sql: string, ...args: [...any, Callback<void>] | []): Statement;
+
+  register_udf(
+    name: string,
+    return_type: string,
+    fun: (...args: any[]) => any
+  ): void;
+
+  register_bulk(
+    name: string,
+    return_type: string,
+    fun: (...args: any[]) => any
+  ): void;
+  unregister_udf(name: string, callback: Callback<any>): void;
+
+  stream(sql: any, ...args: any[]): QueryResult;
+  arrowIPCStream(sql: any, ...args: any[]): Promise<IpcResultStreamIterator>;
+
+  register_buffer(name: string, array: ArrowIterable, force: boolean, callback?: Callback<void>): void;
+  unregister_buffer(name: string, callback?: Callback<void>): void;
+}
+
+export class QueryResult implements AsyncIterable<RowData> {
+  [Symbol.asyncIterator](): AsyncIterator<RowData>;
+}
+
+export class IpcResultStreamIterator implements AsyncIterator<Uint8Array>, AsyncIterable<Uint8Array> {
+  [Symbol.asyncIterator](): this;
+
+  next(...args: [] | [undefined]): Promise<IteratorResult<Uint8Array, any>>;
+
+  toArray(): Promise<ArrowArray>;
+}
+
+export interface ReplacementScanResult {
+  function: string;
+  parameters: Array<unknown>;
+}
+
+export type ReplacementScanCallback = (
+  table: string
+) => ReplacementScanResult | null;
+
+export enum TokenType {
+  IDENTIFIER = 0,
+  NUMERIC_CONSTANT = 1,
+  STRING_CONSTANT = 2,
+  OPERATOR = 3,
+  KEYWORD = 4,
+  COMMENT = 5,
+}
+
+export interface ScriptTokens {
+  offsets: number[];
+  types: TokenType[];
+}
+
+export class Database {
+  constructor(path: string, accessMode?: number | Record<string,string>, callback?: Callback<any>);
+  constructor(path: string, callback?: Callback<any>);
+
+  close(callback?: Callback<void>): void;
+
+  connect(): Connection;
+
+  all(sql: string, ...args: [...any, Callback<TableData>] | []): this;
+  arrowIPCAll(sql: string, ...args: [...any, Callback<ArrowArray>] | []): void;
+  each(sql: string, ...args: [...any, Callback<RowData>] | []): this;
+  exec(sql: string, ...args: [...any, Callback<void>] | []): void;
+
+  prepare(sql: string, ...args: [...any, Callback<Statement>] | []): Statement;
+  run(sql: string, ...args: [...any, Callback<void>] | []): Statement;
+
+  register_udf(
+    name: string,
+    return_type: string,
+    fun: (...args: any[]) => any
+  ): void;
+  unregister_udf(name: string, callback: Callback<any>): void;
+
+  stream(sql: any, ...args: any[]): QueryResult;
+  arrowIPCStream(sql: any, ...args: any[]): Promise<IpcResultStreamIterator>;
+
+  serialize(done?: Callback<void>): void;
+  parallelize(done?: Callback<void>): void;
+  wait(done: Callback<void>): void;
+
+  get(columnName: string, cb: Callback<RowData>): void;
+  get(columnName: string, num: number, cb: Callback<RowData>): void;
+
+  interrupt(): void;
+
+  register_buffer(name: string, array: ArrowIterable, force: boolean, callback?: Callback<void>): void;
+
+  unregister_buffer(name: string, callback?: Callback<void>): void;
+
+  registerReplacementScan(
+    replacementScan: ReplacementScanCallback
+  ): Promise<void>;
+
+  tokenize(text: string): ScriptTokens;
+}
+
+export type GenericTypeInfo = {
+  id: string,
+  sql_type: string,
+  alias?: string,
+}
+
+export type StructTypeInfo = {
+  id: "STRUCT",
+  alias?: string,
+  sql_type: string,
+  children: TypeInfoChildren,
+}
+
+export type ListTypeInfo = {
+  id: "LIST",
+  alias?: string,
+  sql_type: string,
+  child: TypeInfo,
+}
+
+export type MapTypeInfo = {
+  id: "MAP",
+  alias?: string,
+  sql_type: string,
+  key: TypeInfo,
+  value: TypeInfo,
+}
+
+export type UnionTypeInfo = {
+  id: "UNION",
+  alias?: string,
+  sql_type: string,
+  children: TypeInfoChildren,
+}
+
+export type DecimalTypeInfo = {
+  id: "DECIMAL",
+  alias?: string,
+  sql_type: string,
+  width: number,
+  scale: number,
+}
+
+export type EnumTypeInfo = {
+  id: "ENUM",
+  alias?: string,
+  sql_type: string,
+  name: string,
+  values: string[],
+}
+
+export type TypeInfoChildren = { name: string, type: TypeInfo }[];
+
+export type TypeInfo = GenericTypeInfo | StructTypeInfo | ListTypeInfo | MapTypeInfo | UnionTypeInfo | DecimalTypeInfo | EnumTypeInfo;
+
+export type ColumnInfo = { name: string, type: TypeInfo };
+
+export class Statement {
+  sql: string;
+
+  constructor(connection: Connection, sql: string);
+
+  all(...args: [...any, Callback<TableData>] | any[]): this;
+
+  arrowIPCAll(...args: [...any, Callback<ArrowArray>] | any[]): void;
+
+  each(...args: [...any, Callback<RowData>] | any[]): this;
+
+  finalize(callback?: Callback<void>): void;
+
+  run(...args: [...any, Callback<void>] | any[]): Statement;
+
+  columns(): ColumnInfo[];
+}
+
+export const ERROR: number;
+
+export const OPEN_CREATE: number;
+
+export const OPEN_FULLMUTEX: number;
+
+export const OPEN_PRIVATECACHE: number;
+
+export const OPEN_READONLY: number;
+
+export const OPEN_READWRITE: number;
+
+export const OPEN_SHAREDCACHE: number;
+
+export const INTERRUPT: number;

package/lib/duckdb.js

@@ -0,0 +1,763 @@
+/**
+ * @module duckdb
+ * @summary DuckDB is an embeddable SQL OLAP Database Management System
+ */
+
+var duckdb = require('./duckdb-binding.js');
+module.exports = exports = duckdb;
+
+/**
+ * Check that errno attribute equals this to check for a duckdb error
+ * @constant {number}
+ */
+var ERROR = duckdb.ERROR;
+
+/**
+ * Open database in readonly mode
+ * @constant {number}
+ */
+var OPEN_READONLY = duckdb.OPEN_READONLY;
+/**
+ * Currently ignored
+ * @constant {number}
+ */
+var OPEN_READWRITE = duckdb.OPEN_READWRITE;
+/**
+ * Currently ignored
+ * @constant {number}
+ */
+var OPEN_CREATE = duckdb.OPEN_CREATE;
+/**
+ * Currently ignored
+ * @constant {number}
+ */
+var OPEN_FULLMUTEX = duckdb.OPEN_FULLMUTEX;
+/**
+ * Currently ignored
+ * @constant {number}
+ */
+var OPEN_SHAREDCACHE = duckdb.OPEN_SHAREDCACHE;
+/**
+ * Currently ignored
+ * @constant {number}
+ */
+var OPEN_PRIVATECACHE = duckdb.OPEN_PRIVATECACHE;
+
+// some wrappers for compatibilities sake
+/**
+ * Main database interface
+ * @arg path - path to database file or :memory: for in-memory database
+ * @arg access_mode - access mode
+ * @arg config - the configuration object
+ * @arg callback - callback function
+ */
+var Database = duckdb.Database;
+/**
+ * @class
+ */
+var Connection = duckdb.Connection;
+/**
+ * @class
+ */
+var Statement = duckdb.Statement;
+/**
+ * @class
+ */
+var QueryResult = duckdb.QueryResult;
+/**
+ * Types of tokens return by `tokenize`.
+ */
+var TokenType = duckdb.TokenType;
+
+/**
+ * @method
+ * @return data chunk
+ */
+QueryResult.prototype.nextChunk;
+
+/**
+ * Function to fetch the next result blob of an Arrow IPC Stream in a zero-copy way.
+ * (requires arrow extension to be loaded)
+ *
+ * @method
+ * @return data chunk
+ */
+QueryResult.prototype.nextIpcBuffer;
+
+/**
+ * @name asyncIterator
+ * @memberof module:duckdb~QueryResult
+ * @method
+ * @instance
+ * @yields data chunks
+ */
+QueryResult.prototype[Symbol.asyncIterator] = async function*() {
+    let prefetch = this.nextChunk();
+    while (true) {
+        const chunk = await prefetch;
+        // Null chunk indicates end of stream
+        if (!chunk) {
+            return;
+        }
+        // Prefetch the next chunk while we're iterating
+        prefetch = this.nextChunk();
+        for (const row of chunk) {
+            yield row;
+        }
+    }
+}
+
+
+/**
+ * Run a SQL statement and trigger a callback when done
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.run = function (sql) {
+    var statement = new Statement(this, sql);
+    return statement.run.apply(statement, arguments);
+}
+
+/**
+ * Run a SQL query and triggers the callback once for all result rows
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.all = function (sql) {
+    var statement = new Statement(this, sql);
+    return statement.all.apply(statement, arguments);
+}
+
+// Utility class for streaming Apache Arrow IPC
+class IpcResultStreamIterator {
+    constructor(stream_result_p) {
+        this._depleted = false;
+        this.stream_result = stream_result_p;
+    }
+
+    async next() {
+        if (this._depleted) {
+            return { done: true, value: null };
+        }
+
+        const ipc_raw = await this.stream_result.nextIpcBuffer();
+        const res = new Uint8Array(ipc_raw);
+
+        this._depleted = res.length == 0;
+        return {
+            done: this._depleted,
+            value: res,
+        };
+    }
+
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+
+    // Materialize the IPC stream into a list of Uint8Arrays
+    async toArray () {
+        const retval = []
+
+        for await (const ipc_buf of this) {
+            retval.push(ipc_buf);
+        }
+
+        // Push EOS message containing 4 bytes of 0
+        retval.push(new Uint8Array([0,0,0,0]));
+
+        return retval;
+    }
+}
+
+/**
+ * Run a SQL query and serialize the result into the Apache Arrow IPC format (requires arrow extension to be loaded)
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.arrowIPCAll = function (sql) {
+    const query = "SELECT * FROM to_arrow_ipc((" + sql + "));";
+    var statement = new Statement(this, query);
+    return statement.arrowIPCAll.apply(statement, arguments);
+}
+
+/**
+ * Run a SQL query, returns a IpcResultStreamIterator that allows streaming the result into the Apache Arrow IPC format
+ * (requires arrow extension to be loaded)
+ *
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return Promise<IpcResultStreamIterator>
+ */
+Connection.prototype.arrowIPCStream = async function (sql) {
+    const query = "SELECT * FROM to_arrow_ipc((" + sql + "));";
+    const statement = new Statement(this, query);
+    return new IpcResultStreamIterator(await statement.stream.apply(statement, arguments));
+}
+
+/**
+ * Runs a SQL query and triggers the callback for each result row
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.each = function (sql) {
+    var statement = new Statement(this, sql);
+    return statement.each.apply(statement, arguments);
+}
+
+/**
+ * @arg sql
+ * @param {...*} params
+ * @yields row chunks
+ */
+Connection.prototype.stream = async function* (sql) {
+    const statement = new Statement(this, sql);
+    const queryResult = await statement.stream.apply(statement, arguments);
+    for await (const result of queryResult) {
+        yield result;
+    }
+}
+
+/**
+ * Register a User Defined Function
+ *
+ * @arg name
+ * @arg return_type
+ * @arg fun
+ * @return {void}
+ * @note this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly
+ */
+Connection.prototype.register_udf = function (name, return_type, fun) {
+    // TODO what if this throws an error somewhere? do we need a try/catch?
+    return this.register_udf_bulk(name, return_type, function (desc) {
+        try {
+            // Build an argument resolver
+            const buildResolver = (arg) => {
+                let validity = arg.validity || null;
+                switch (arg.physicalType) {
+                    case 'STRUCT': {
+                        const tmp = {};
+                        const children = [];
+                        for (let j = 0; j < (arg.children.length || 0); ++j) {
+                            const attr = arg.children[j];
+                            const child = buildResolver(attr);
+                            children.push((row) => {
+                                tmp[attr.name] = child(row);
+                            });
+                        }
+                        if (validity != null) {
+                            return (row) => {
+                                if (!validity[row]) {
+                                    return null;
+                                }
+                                for (const resolver of children) {
+                                    resolver(row);
+                                }
+                                return tmp;
+                            };
+                        } else {
+                            return (row) => {
+                                for (const resolver of children) {
+                                    resolver(row);
+                                }
+                                return tmp;
+                            };
+                        }
+                    }
+                    default: {
+                        if (arg.data === undefined) {
+                            throw new Error(
+                                'malformed data view, expected data buffer for argument of type: ' + arg.physicalType,
+                            );
+                        }
+                        const data = arg.data;
+                        if (validity != null) {
+                            return (row) => (!validity[row] ? null : data[row]);
+                        } else {
+                            return (row) => data[row];
+                        }
+                    }
+                }
+            };
+
+            // Translate argument data
+            const argResolvers = [];
+            for (let i = 0; i < desc.args.length; ++i) {
+                argResolvers.push(buildResolver(desc.args[i]));
+            }
+            const args = [];
+            for (let i = 0; i < desc.args.length; ++i) {
+                args.push(null);
+            }
+
+            // Return type
+            desc.ret.validity = new Uint8Array(desc.rows);
+            switch (desc.ret.physicalType) {
+                case 'INT8':
+                    desc.ret.data = new Int8Array(desc.rows);
+                    break;
+                case 'INT16':
+                    desc.ret.data = new Int16Array(desc.rows);
+                    break;
+                case 'INT32':
+                    desc.ret.data = new Int32Array(desc.rows);
+                    break;
+                case 'DOUBLE':
+                    desc.ret.data = new Float64Array(desc.rows);
+                    break;
+                case 'DATE64':
+                case 'TIME64':
+                case 'TIMESTAMP':
+                case 'INT64':
+                    desc.ret.data = new BigInt64Array(desc.rows);
+                    break;
+                case 'UINT64':
+                    desc.ret.data = new BigUint64Array(desc.rows);
+                    break;
+                case 'BLOB':
+                case 'VARCHAR':
+                    desc.ret.data = new Array(desc.rows);
+                    break;
+            }
+
+            // Call the function
+            for (let i = 0; i < desc.rows; ++i) {
+                for (let j = 0; j < desc.args.length; ++j) {
+                    args[j] = argResolvers[j](i);
+                }
+                const res = fun(...args);
+                desc.ret.data[i] = res;
+                desc.ret.validity[i] = res === undefined || res === null ? 0 : 1;
+            }
+        } catch (error) { // work around recently fixed napi bug https://github.com/nodejs/node-addon-api/issues/912
+            msg = error;
+            if (typeof error == 'object' && 'message' in error) {
+                msg = error.message
+            }
+            throw { name: 'DuckDB-UDF-Exception', message: msg };
+        }
+    })
+}
+
+/**
+ * Prepare a SQL query for execution
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {Statement}
+ */
+Connection.prototype.prepare;
+/**
+ * Execute a SQL query
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.exec;
+/**
+ * Register a User Defined Function
+ *
+ * @method
+ * @arg name
+ * @arg return_type
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.register_udf_bulk;
+/**
+ * Unregister a User Defined Function
+ *
+ * @method
+ * @arg name
+ * @arg return_type
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.unregister_udf;
+
+var default_connection = function (o) {
+    if (o.default_connection == undefined) {
+        o.default_connection = new duckdb.Connection(o);
+    }
+    return o.default_connection;
+}
+
+/**
+ * Register a Buffer to be scanned using the Apache Arrow IPC scanner
+ * (requires arrow extension to be loaded)
+ *
+ * @method
+ * @arg name
+ * @arg array
+ * @arg force
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.register_buffer;
+
+/**
+ * Unregister the Buffer
+ *
+ * @method
+ * @arg name
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.unregister_buffer;
+
+/**
+ * Closes connection
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.close;
+
+/**
+ * Closes database instance
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.close = function() {
+    if (this.default_connection) {
+        this.default_connection.close(); // this queues up a job in the internals, which blocks the below close call
+        this.default_connection = null;
+    }
+    this.close_internal.apply(this, arguments);
+};
+
+/**
+ * Internal method. Do not use, call Connection#close instead
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.close_internal;
+
+/**
+ * Triggers callback when all scheduled database tasks have completed.
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.wait;
+
+/**
+ * Currently a no-op. Provided for SQLite compatibility
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.serialize;
+
+/**
+ * Currently a no-op. Provided for SQLite compatibility
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.parallelize;
+
+/**
+ * Create a new database connection
+ * @method
+ * @arg path the database to connect to, either a file path, or `:memory:`
+ * @return {Connection}
+ */
+Database.prototype.connect;
+
+/**
+ * Supposedly interrupt queries, but currently does not do anything.
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.interrupt;
+
+/**
+ * Prepare a SQL query for execution
+ * @arg sql
+ * @return {Statement}
+ */
+Database.prototype.prepare = function () {
+    return default_connection(this).prepare.apply(this.default_connection, arguments);
+}
+
+/**
+ * Convenience method for Connection#run using a built-in default connection
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.run = function () {
+    default_connection(this).run.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Convenience method for Connection#scanArrowIpc using a built-in default connection
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.scanArrowIpc = function () {
+    default_connection(this).scanArrowIpc.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.each = function () {
+    default_connection(this).each.apply(this.default_connection, arguments);
+    return this;
+}
+
+
+/**
+ * @arg sql
+ * @param {...*} params
+ * @yields row chunks
+ */
+Database.prototype.stream = function() {
+    return default_connection(this).stream.apply(this.default_connection, arguments);
+}
+
+
+/**
+ * Convenience method for Connection#apply using a built-in default connection
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.all = function () {
+    default_connection(this).all.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Convenience method for Connection#arrowIPCAll using a built-in default connection
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.arrowIPCAll = function () {
+    default_connection(this).arrowIPCAll.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Convenience method for Connection#arrowIPCStream using a built-in default connection
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.arrowIPCStream = function () {
+    return default_connection(this).arrowIPCStream.apply(this.default_connection, arguments);
+}
+
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.exec = function () {
+    default_connection(this).exec.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Register a User Defined Function
+ *
+ * Convenience method for Connection#register_udf
+ * @arg name
+ * @arg return_type
+ * @arg fun
+ * @return {this}
+ */
+Database.prototype.register_udf = function () {
+    default_connection(this).register_udf.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Register a buffer containing serialized data to be scanned from DuckDB.
+ *
+ * Convenience method for Connection#unregister_buffer
+ * @arg name
+ * @return {this}
+ */
+Database.prototype.register_buffer = function () {
+    default_connection(this).register_buffer.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Unregister a Buffer
+ *
+ * Convenience method for Connection#unregister_buffer
+ * @arg name
+ * @return {this}
+ */
+Database.prototype.unregister_buffer = function () {
+    default_connection(this).unregister_buffer.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Unregister a UDF
+ *
+ * Convenience method for Connection#unregister_udf
+ * @arg name
+ * @return {this}
+ */
+Database.prototype.unregister_udf = function () {
+    default_connection(this).unregister_udf.apply(this.default_connection, arguments);
+    return this;
+}
+
+/**
+ * Register a table replace scan function
+ * @method
+ * @arg fun Replacement scan function
+ * @return {this}
+ */
+
+Database.prototype.registerReplacementScan;
+
+/**
+ * Return positions and types of tokens in given text
+ * @method
+ * @arg text
+ * @return {ScriptTokens}
+ */
+Database.prototype.tokenize;
+
+/**
+ * Not implemented
+ */
+Database.prototype.get = function () {
+    throw "get() is not implemented because it's evil";
+}
+
+/**
+ * Not implemented
+ */
+Statement.prototype.get = function () {
+    throw "get() is not implemented because it's evil";
+}
+
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.run;
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.all;
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.arrowIPCAll;
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.each;
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.finalize
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @yield callback
+ */
+Statement.prototype.stream;
+
+/**
+ * @field
+ * @returns sql contained in statement
+ */
+Statement.prototype.sql;
+
+/**
+ * @method
+ * @return {ColumnInfo[]} - Array of column names and types
+ */
+Statement.prototype.columns;
+
+/**
+ * @typedef ColumnInfo
+ * @type {object}
+ * @property {string} name - Column name
+ * @property {TypeInfo} type - Column type
+ */
+
+/**
+ * @typedef TypeInfo
+ * @type {object}
+ * @property {string} id - Type ID
+ * @property {string} [alias] - SQL type alias
+ * @property {string} sql_type - SQL type name
+ */
+
+/**
+ * @typedef DuckDbError
+ * @type {object}
+ * @property {number} errno - -1 for DuckDB errors
+ * @property {string} message - Error message
+ * @property {string} code - 'DUCKDB_NODEJS_ERROR' for DuckDB errors
+ * @property {string} errorType - DuckDB error type code (eg, HTTP, IO, Catalog)
+ */
+
+/**
+ * @typedef HTTPError
+ * @type {object}
+ * @extends {DuckDbError}
+ * @property {number} statusCode - HTTP response status code
+ * @property {string} reason - HTTP response reason
+ * @property {string} response - HTTP response body
+ * @property {object} headers - HTTP headers
+ */

package/lib/index.js

@@ -0,0 +1 @@
+module.exports = require('./duckdb');

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@ohos-ports/duckdb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.2-beta.0",
+  "description": "DuckDB node.js API (HarmonyOS openharmony/arm64 port with vendored prebuilt native binding; companion package of @ohos-ports/duckdb-async)",
+  "main": "./lib/duckdb.js",
+  "types": "./lib/duckdb.d.ts",
+  "files": [
+    "lib",
+    "duckdb.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "os": [
+    "openharmony"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "scripts": {},
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/duckdb/1.4.2"
+  },
+  "keywords": [
+    "database",
+    "sql",
+    "duckdb",
+    "openharmony",
+    "harmonyos"
+  ],
+  "author": "Hannes Mühleisen",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ohos-ports/ohos-ports/issues"
+  },
+  "homepage": "https://github.com/ohos-ports/ohos-ports/tree/main/ports/duckdb/1.4.2",
+  "ohos-ports": {
+    "upstream": "duckdb@1.4.2",
+    "platform": "openharmony",
+    "arch": "arm64",
+    "native_artifact": "lib/binding/duckdb.node",
+    "content_delta": "statement.cpp each()-completion persistent-handle fix + exception hardening, compiled from source for openharmony/arm64 and signed; binding vendored in lib/binding (no node-pre-gyp download at install time)"
+  }
+}