@homeofthings/sqlite3 6.3.0 → 6.3.1

package/lib/promise/backup.js

@@ -0,0 +1,121 @@
+/**
+ * Promise-based wrapper for the Backup class from node-sqlite3
+ * @module promise/backup
+ */
+
+'use strict';
+
+/**
+ * A thin wrapper for the 'Backup' class from 'node-sqlite3' using Promises
+ * instead of callbacks
+ *
+ * @see https://github.com/mapbox/node-sqlite3/wiki/API
+ */
+class SqliteBackup {
+    /**
+   * Creates an instance of SqliteBackup.
+   *
+   * @param {import('../sqlite3.js').Backup} backup - The underlying Backup instance
+   */
+    constructor(backup) {
+        /**
+      * @type {import('../sqlite3.js').Backup}
+      * @private
+      */
+        this._backup = backup;
+    }
+
+    /**
+   * Returns true if the backup is idle (not actively copying)
+   *
+   * @returns {boolean}
+   */
+    get idle() {
+        return this._backup.idle;
+    }
+
+    /**
+   * Returns true if the backup is completed
+   *
+   * @returns {boolean}
+   */
+    get completed() {
+        return this._backup.completed;
+    }
+
+    /**
+   * Returns true if the backup has failed
+   *
+   * @returns {boolean}
+   */
+    get failed() {
+        return this._backup.failed;
+    }
+
+    /**
+   * Returns the remaining number of pages left to copy
+   * Returns -1 if `step` not yet called
+   *
+   * @returns {number}
+   */
+    get remaining() {
+        return this._backup.remaining;
+    }
+
+    /**
+   * Returns the total number of pages
+   * Returns -1 if `step` not yet called
+   *
+   * @returns {number}
+   */
+    get pageCount() {
+        return this._backup.pageCount;
+    }
+
+    /**
+   * Returns the progress (percentage completion)
+   *
+   * @returns {number} Progress as percentage (0-100)
+   */
+    get progress() {
+        const pageCount = this.pageCount;
+        const remaining = this.remaining;
+        if (pageCount === -1 || remaining === -1) {
+            return 0;
+        }
+        return pageCount === 0 ? 100 : ((pageCount - remaining) / pageCount) * 100;
+    }
+
+    /**
+   * Copy the next page or all remaining pages of the backup
+   *
+   * @param {number} [pages=-1] - Number of pages to copy (-1 for all remaining)
+   * @returns {Promise<void>}
+   */
+    step(pages) {
+        return new Promise((resolve, reject) => {
+            if (!this._backup) {
+                reject(new Error('backup handle not open'));
+                return;
+            }
+            this._backup.step(pages === undefined ? -1 : pages, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Finish the backup (synchronous)
+   */
+    finish() {
+        if (this._backup) {
+            this._backup.finish();
+        }
+    }
+}
+
+module.exports = { SqliteBackup };

package/lib/promise/database.js

@@ -0,0 +1,505 @@
+/**
+ * Promise-based wrapper for the Database class from node-sqlite3
+ * @module promise/database
+ */
+
+'use strict';
+
+const { Database } = require('../sqlite3.js');
+const { SqliteStatement } = require('./statement');
+const { SqliteBackup } = require('./backup');
+
+/**
+ * Result object returned by run() operations
+ * @typedef {Object} SqlRunResult
+ * @property {number} lastID - The ID of the last inserted row
+ * @property {number} changes - The number of rows affected
+ */
+
+/**
+ * @typedef {import('../sqlite3-binding.js').Database} Database
+ */
+
+/**
+ * A thin wrapper for the 'Database' class from 'node-sqlite3' using Promises
+ * instead of callbacks
+ *
+ * @see https://github.com/mapbox/node-sqlite3/wiki/API
+ */
+class SqliteDatabase {
+    /**
+   * Creates a new SqliteDatabase instance (without opening a database).
+   * Use open() to open a database connection, or use the static factory method open().
+   *
+   * @example
+   * // Using constructor + open
+   * const db = new SqliteDatabase();
+   * await db.open(':memory:');
+   *
+   * // Using static factory method
+   * const db = await SqliteDatabase.open(':memory:');
+   */
+    constructor() {
+        /**
+         * @type {Database | undefined}
+      * @protected
+      */
+        this.db = undefined;
+    }
+
+    /**
+   * Static factory method to create and open a database connection.
+   *
+   * @param {string} filename - The path to the database file or ':memory:' for in-memory
+   * @param {number} [mode] - Optional mode flags (OPEN_READONLY, OPEN_READWRITE, OPEN_CREATE)
+   * @returns {Promise<SqliteDatabase>} A promise that resolves to the opened database
+   * @example
+   * const db = await SqliteDatabase.open(':memory:');
+   * const db = await SqliteDatabase.open('mydb.sqlite', sqlite3.OPEN_READONLY);
+   */
+    static async open(filename, mode) {
+        const db = new SqliteDatabase();
+        await db.open(filename, mode);
+        return db;
+    }
+
+    /**
+   * Open a database connection
+   *
+   * @param {string} filename - The path to the database file or ':memory:' for in-memory
+   * @param {number} [mode] - Optional mode flags (OPEN_READONLY, OPEN_READWRITE, OPEN_CREATE)
+   * @returns {Promise<void>}
+   */
+    open(filename, mode) {
+        return new Promise((resolve, reject) => {
+            // Default mode: OPEN_READWRITE | OPEN_CREATE
+            const defaultMode = 0x00000002 | 0x00000004; // OPEN_READWRITE | OPEN_CREATE
+            const db = new Database(filename, mode === undefined ? defaultMode : mode, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    this.db = db;
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Close the database connection
+   *
+   * @returns {Promise<void>}
+   */
+    close() {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                resolve();
+                return;
+            }
+            const db = this.db;
+            this.db = undefined;
+            db.close((err) => {
+                db.removeAllListeners();
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Test if a connection is open
+   *
+   * @returns {boolean}
+   */
+    isOpen() {
+        return !!this.db;
+    }
+
+    /**
+   * Runs a SQL statement with the specified parameters
+   *
+   * @param {string} sql - The SQL statement
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<SqlRunResult>} A promise that resolves to the result object
+   */
+    run(sql, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            // Use function() to get 'this' context with lastID and changes
+            this.db.run(sql, params, function (err) {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve({
+                        lastID: this.lastID,
+                        changes: this.changes
+                    });
+                }
+            });
+        });
+    }
+
+    /**
+   * Runs a SQL query with the specified parameters, fetching only the first row
+   *
+   * @template T
+   * @param {string} sql - The DQL statement
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<T | undefined>} A promise that resolves to the row or undefined
+   */
+    get(sql, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.get(sql, params, (err, row) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(row);
+                }
+            });
+        });
+    }
+
+    /**
+   * Runs a SQL query with the specified parameters, fetching all rows
+   *
+   * @template T
+   * @param {string} sql - The DQL statement
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<T[]>} A promise that resolves to an array of rows
+   */
+    all(sql, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.all(sql, params, (err, rows) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(rows);
+                }
+            });
+        });
+    }
+
+    /**
+   * Runs a SQL query with the specified parameters, fetching all rows
+   * using a callback for each row
+   *
+   * @param {string} sql - The DQL statement
+   * @param {any} [params] - The parameters referenced in the statement
+   * @param {(err: Error | null, row: any) => void} [callback] - The callback function for each row
+   * @returns {Promise<number>} A promise that resolves to the number of rows retrieved
+   */
+    each(sql, params, callback) {
+    // Handle case where params is actually the callback (no params provided)
+        if (typeof params === 'function') {
+            callback = params;
+            params = undefined;
+        }
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.each(sql, params, callback, (err, count) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(count);
+                }
+            });
+        });
+    }
+
+    /**
+   * Execute a SQL statement
+   *
+   * @param {string} sql - The SQL statement
+   * @returns {Promise<void>}
+   */
+    exec(sql) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.exec(sql, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Prepare a SQL statement
+   *
+   * @param {string} sql - The SQL statement
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<SqliteStatement>} A promise that resolves to the prepared statement
+   */
+    prepare(sql, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            const stmt = this.db.prepare(sql, params, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(new SqliteStatement(stmt));
+                }
+            });
+        });
+    }
+
+    /**
+   * Initiate online backup
+   *
+   * @param {string} filename - The database file to backup from or to
+   * @param {boolean} [filenameIsDest=true] - Whether filename is destination
+   * @param {string} [destName='main'] - The destination database name
+   * @param {string} [sourceName='main'] - The source database name
+   * @returns {Promise<SqliteBackup>} A promise that resolves to the backup object
+   */
+    backup(filename, filenameIsDest = true, destName = 'main', sourceName = 'main') {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            const backup = this.db.backup(filename, destName, sourceName, filenameIsDest, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(new SqliteBackup(backup));
+                }
+            });
+        });
+    }
+
+    /**
+   * Serialized sqlite3 calls
+   * If callback is provided, run callback in serialized mode
+   * Otherwise, switch connection to serialized mode
+   *
+   * @param {() => void} [callback] - Optional callback to run in serialized mode
+   */
+    serialize(callback) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.serialize(callback);
+    }
+
+    /**
+   * Parallelized sqlite3 calls
+   * If callback is provided, run callback in parallel mode
+   * Otherwise, switch connection to parallel mode
+   *
+   * @param {() => void} [callback] - Optional callback to run in parallel mode
+   */
+    parallelize(callback) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.parallelize(callback);
+    }
+
+    /**
+   * Run callback inside a database transaction
+   *
+   * @template T
+   * @param {() => Promise<T>} callback - The callback to run in transaction
+   * @returns {Promise<T>} A promise that resolves to the callback result
+   */
+    async transactionalize(callback) {
+        await this.beginTransaction();
+        try {
+            const result = await callback();
+            await this.commitTransaction();
+            return result;
+        } catch (err) {
+            await this.rollbackTransaction();
+            throw err;
+        }
+    }
+
+    /**
+   * Begin a transaction
+   *
+   * @returns {Promise<SqlRunResult>}
+   */
+    beginTransaction() {
+        return this.run('BEGIN IMMEDIATE TRANSACTION');
+    }
+
+    /**
+   * Commit a transaction
+   *
+   * @returns {Promise<SqlRunResult>}
+   */
+    commitTransaction() {
+        return this.run('COMMIT TRANSACTION');
+    }
+
+    /**
+   * Rollback a transaction
+   *
+   * @returns {Promise<SqlRunResult>}
+   */
+    rollbackTransaction() {
+        return this.run('ROLLBACK TRANSACTION');
+    }
+
+    /**
+   * End a transaction (commit or rollback)
+   *
+   * @param {boolean} commit - Whether to commit (true) or rollback (false)
+   * @returns {Promise<void>}
+   */
+    endTransaction(commit) {
+        const sql = commit ? 'COMMIT TRANSACTION' : 'ROLLBACK TRANSACTION';
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.run(sql, (err) => {
+                // Ignore "no transaction" errors
+                if (err && !err.message.includes('no transaction')) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Load an extension
+   *
+   * @param {string} filename - The path to the extension
+   * @returns {Promise<void>}
+   */
+    loadExtension(filename) {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.loadExtension(filename, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Wait for the database to be ready
+   *
+   * @returns {Promise<void>}
+   */
+    wait() {
+        return new Promise((resolve, reject) => {
+            if (!this.db) {
+                reject(new Error('database connection not open'));
+                return;
+            }
+            this.db.wait((err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Interrupt a running query
+   */
+    interrupt() {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.interrupt();
+    }
+
+    /**
+   * Configure database options
+   *
+   * @param {string} option - The option name
+   * @param {number} [value] - The option value
+   */
+    configure(option, value) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.configure(option, value);
+    }
+
+    /**
+   * Register an event listener
+   *
+   * @param {'trace' | 'profile' | 'error' | 'close' | 'open' | 'change'} event - The event name
+   * @param {Function} listener - The listener function
+   * @returns {this}
+   */
+    on(event, listener) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.on(event, listener);
+        return this;
+    }
+
+    /**
+   * Remove an event listener
+   *
+   * @param {string} event - The event name
+   * @param {Function} listener - The listener function
+   * @returns {this}
+   */
+    off(event, listener) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.off(event, listener);
+        return this;
+    }
+
+    /**
+   * Remove all event listeners for an event
+   *
+   * @param {string} [event] - The event name
+   * @returns {this}
+   */
+    removeAllListeners(event) {
+        if (!this.db) {
+            throw new Error('database connection not open');
+        }
+        this.db.removeAllListeners(event);
+        return this;
+    }
+}
+
+module.exports = { SqliteDatabase };

package/lib/promise/index.js

@@ -0,0 +1,16 @@
+/**
+ * Promise-based wrappers for node-sqlite3
+ * @module promise
+ */
+
+'use strict';
+
+const { SqliteDatabase } = require('./database');
+const { SqliteStatement } = require('./statement');
+const { SqliteBackup } = require('./backup');
+
+module.exports = {
+    SqliteDatabase,
+    SqliteStatement,
+    SqliteBackup
+};

package/lib/promise/statement.js

@@ -0,0 +1,181 @@
+/**
+ * Promise-based wrapper for the Statement class from node-sqlite3
+ * @module promise/statement
+ */
+
+'use strict';
+
+/**
+ * Result object returned by run() operations
+ * @typedef {Object} SqlRunResult
+ * @property {number} lastID - The ID of the last inserted row
+ * @property {number} changes - The number of rows affected
+ */
+
+/**
+ * A thin wrapper for the 'Statement' class from 'node-sqlite3' using Promises
+ * instead of callbacks
+ *
+ * @see https://github.com/mapbox/node-sqlite3/wiki/API
+ */
+class SqliteStatement {
+    /**
+   * Creates an instance of SqliteStatement.
+   *
+   * @param {import('../sqlite3.js').Statement} stmt - The underlying Statement instance
+   */
+    constructor(stmt) {
+        /**
+      * @type {import('../sqlite3.js').Statement}
+      * @private
+      */
+        this._stmt = stmt;
+    }
+
+    /**
+   * Bind the given parameters to the prepared statement
+   *
+   * @param {...any} params - The parameters to bind
+   * @returns {this} Returns this for chaining
+   */
+    bind(...params) {
+        this._stmt.bind(params);
+        return this;
+    }
+
+    /**
+   * Reset a open cursor of the prepared statement preserving the parameter binding
+   * Allows re-execute of the same query
+   *
+   * @returns {Promise<void>}
+   */
+    reset() {
+        return new Promise((resolve) => {
+            this._stmt.reset(() => {
+                resolve();
+            });
+        });
+    }
+
+    /**
+   * Finalizes a prepared statement (freeing any resource used by this statement)
+   *
+   * @returns {Promise<void>}
+   */
+    finalize() {
+        return new Promise((resolve, reject) => {
+            this._stmt.finalize((err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+
+    /**
+   * Runs a prepared statement with the specified parameters
+   *
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<SqlRunResult>} A promise that resolves to the result object
+   */
+    run(params) {
+        return new Promise((resolve, reject) => {
+            // Use function() to get 'this' context with lastID and changes
+            const callback = function(err) {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve({
+                        lastID: this.lastID,
+                        changes: this.changes
+                    });
+                }
+            };
+            // Only pass params if provided - otherwise use bound parameters
+            if (params === undefined) {
+                this._stmt.run(callback);
+            } else {
+                this._stmt.run(params, callback);
+            }
+        });
+    }
+
+    /**
+   * Runs a prepared statement with the specified parameters, fetching only the first row
+   *
+   * @template T
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<T | undefined>} A promise that resolves to the row or undefined
+   */
+    get(params) {
+        return new Promise((resolve, reject) => {
+            const callback = (err, row) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(row);
+                }
+            };
+            // Only pass params if provided - otherwise use bound parameters
+            if (params === undefined) {
+                this._stmt.get(callback);
+            } else {
+                this._stmt.get(params, callback);
+            }
+        });
+    }
+
+    /**
+   * Runs a prepared statement with the specified parameters, fetching all rows
+   *
+   * @template T
+   * @param {any} [params] - The parameters referenced in the statement
+   * @returns {Promise<T[]>} A promise that resolves to an array of rows
+   */
+    all(params) {
+        return new Promise((resolve, reject) => {
+            const callback = (err, rows) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(rows);
+                }
+            };
+            // Only pass params if provided - otherwise use bound parameters
+            if (params === undefined) {
+                this._stmt.all(callback);
+            } else {
+                this._stmt.all(params, callback);
+            }
+        });
+    }
+
+    /**
+   * Runs a prepared statement with the specified parameters, fetching all rows
+   * using a callback for each row
+   *
+   * @param {any} [params] - The parameters referenced in the statement
+   * @param {(err: Error | null, row: any) => void} [callback] - The callback function for each row
+   * @returns {Promise<number>} A promise that resolves to the number of rows retrieved
+   */
+    each(params, callback) {
+    // Handle case where params is actually the callback (no params provided)
+        if (typeof params === 'function') {
+            callback = params;
+            params = undefined;
+        }
+        return new Promise((resolve, reject) => {
+            this._stmt.each(params, callback, (err, count) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(count);
+                }
+            });
+        });
+    }
+}
+
+module.exports = { SqliteStatement };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeofthings/sqlite3",
   "description": "Asynchronous, non-blocking SQLite3 bindings",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "homepage": "https://github.com/gms1/node-sqlite3",
   "author": {
     "name": "Mapbox",
@@ -35,8 +35,8 @@
   "files": [
     "binding.gyp",
     "deps/",
-    "lib/*.js",
-    "lib/*.d.ts",
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
     "src/"
   ],
   "repository": {