duckdb 0.4.1-dev1265.0 → 0.4.1-dev1287.0

package/lib/duckdb.js

@@ -1,13 +1,79 @@
+/**
+ * @module duckdb
+ * @summary these jsdoc annotations are still a work in progress - feedback and suggestions are welcome!
+ */
+
 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
+ */
 var Database = duckdb.Database;
+/**
+ * @class
+ */
 var Connection = duckdb.Connection;
+/**
+ * @class
+ */
 var Statement = duckdb.Statement;
+/**
+ * @class
+ */
 var QueryResult = duckdb.QueryResult;
 
+/**
+ * @method
+ * @return data chunk
+ */
+QueryResult.prototype.nextChunk;
+
+/**
+ * @name asyncIterator
+ * @memberof module:duckdb~QueryResult
+ * @method
+ * @instance
+ * @yields data chunks
+ */
 QueryResult.prototype[Symbol.asyncIterator] = async function*() {
     let prefetch = this.nextChunk();
     while (true) {
@@ -25,22 +91,45 @@ QueryResult.prototype[Symbol.asyncIterator] = async function*() {
 }
 
 
-Connection.prototype.run = function(sql) {
+/**
+ * @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);
 }
 
-Connection.prototype.all = function(sql) {
-    var statement = new Statement(this,sql);
+/**
+ * @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);
 }
 
-Connection.prototype.each = function(sql) {
+/**
+ * @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);
 }
 
-Connection.prototype.stream = async function*(sql) {
+/**
+ * @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) {
@@ -48,10 +137,18 @@ Connection.prototype.stream = async function*(sql) {
     }
 }
 
-// this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly
-Connection.prototype.register = function(name, return_type, fun) {
+/**
+ * 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 = function (name, return_type, fun) {
     // TODO what if this throws an error somewhere? do we need a try/catch?
-    return this.register_bulk(name, return_type, function(desc) {
+    return this.register_bulk(name, return_type, function (desc) {
         try {
             // Build an argument resolver
             const buildResolver = (arg) => {
@@ -151,62 +248,236 @@ Connection.prototype.register = function(name, return_type, fun) {
                 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
+        } catch (error) { // work around recently fixed napi bug https://github.com/nodejs/node-addon-api/issues/912
             console.log(desc.ret);
             msg = error;
             if (typeof error == 'object' && 'message' in error) {
                 msg = error.message
             }
-            throw {name: 'DuckDB-UDF-Exception', message : msg};
+            throw { name: 'DuckDB-UDF-Exception', message: msg };
         }
     })
 }
 
-default_connection = function(o) {
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {Statement}
+ */
+Connection.prototype.prepare;
+/**
+ * @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_bulk;
+/**
+ * Unregister a User Defined Function
+ *
+ * @method
+ * @arg name
+ * @arg return_type
+ * @param callback
+ * @return {void}
+ */
+Connection.prototype.unregister;
+
+default_connection = function (o) {
     if (o.default_connection == undefined) {
         o.default_connection = new duckdb.Connection(o);
     }
-    return(o.default_connection);
+    return o.default_connection;
 }
 
-Database.prototype.prepare = function() {
+
+/**
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.close;
+
+/**
+ * @method
+ * @param callback
+ * TODO: what does this do?
+ * @return {void}
+ */
+Database.prototype.wait;
+
+/**
+ * TODO: what does this do?
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.serialize;
+
+/**
+ * TODO: what does this do?
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.parallelize;
+
+/**
+ * @method
+ * @arg path the database to connect to, either a file path, or `:memory:`
+ * @return {Connection}
+ */
+Database.prototype.connect;
+
+/**
+ * TODO: what does this do?
+ * @method
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.interrupt;
+
+/**
+ * @arg sql
+ * @return {Statement}
+ */
+Database.prototype.prepare = function () {
     return default_connection(this).prepare.apply(this.default_connection, arguments);
 }
 
-Database.prototype.run = function() {
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.run = function () {
     default_connection(this).run.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.each = function() {
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.each = function () {
     default_connection(this).each.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.all = function() {
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.all = function () {
     default_connection(this).all.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.exec = function() {
+/**
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Database.prototype.exec = function () {
     default_connection(this).exec.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.register = function() {
+/**
+ * Register a User Defined Function
+ *
+ * Convenience method for Connection#register
+ * @arg name
+ * @arg return_type
+ * @arg fun
+ * @return {this}
+ */
+Database.prototype.register = function () {
     default_connection(this).register.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.unregister = function() {
+/**
+ * Unregister a User Defined Function
+ *
+ * Convenience method for Connection#unregister
+ * @arg name
+ * @return {this}
+ */
+Database.prototype.unregister = function () {
     default_connection(this).unregister.apply(this.default_connection, arguments);
     return this;
 }
 
-Database.prototype.get = function() {
+/**
+ * Not implemented
+ */
+Database.prototype.get = function () {
     throw "get() is not implemented because it's evil";
 }
 
-Statement.prototype.get = function() {
+/**
+ * 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.each;
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @param callback
+ * @return {void}
+ */
+Statement.prototype.finalize
+/**
+ * @method
+ * @arg sql
+ * @param {...*} params
+ * @yield callback
+ */
+Statement.prototype.stream;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "duckdb",
   "main": "./lib/duckdb.js",
-  "version": "0.4.1-dev1265.0",
+  "version": "0.4.1-dev1287.0",
   "description": "DuckDB node.js API",
   "gypfile": true,
   "dependencies": {
@@ -26,6 +26,8 @@
   },
   "devDependencies": {
     "aws-sdk": "^2.790.0",
+    "chai": "^4.3.6",
+    "jsdoc3-parser": "^2.0.0",
     "mocha": "^8.3.0"
   },
   "repository": {

package/src/duckdb.hpp

@@ -11,8 +11,8 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 #pragma once
 #define DUCKDB_AMALGAMATION 1
 #define DUCKDB_AMALGAMATION_EXTENDED 1
-#define DUCKDB_SOURCE_ID "5d25704f9"
-#define DUCKDB_VERSION "v0.4.1-dev1265"
+#define DUCKDB_SOURCE_ID "7863fb7e1"
+#define DUCKDB_VERSION "v0.4.1-dev1287"
 //===----------------------------------------------------------------------===//
 //                         DuckDB
 //