@homeofthings/sqlite3 6.2.0 → 6.3.1

package/README.md

@@ -36,9 +36,9 @@ yarn add @homeofthings/sqlite3
 
 ### Prebuilt binaries
 
-`sqlite3` v5+ was rewritten to use [Node-API](https://nodejs.org/api/n-api.html) so prebuilt binaries do not need to be built for specific Node versions. `sqlite3` currently builds for both Node-API v3 and v6. Check the [Node-API version matrix](https://nodejs.org/api/n-api.html#node-api-version-matrix) to ensure your Node version supports one of these. The prebuilt binaries should be supported on Node v20.17.0+.
+`@homeofthings/sqlite3` uses [Node-API](https://nodejs.org/api/n-api.html) so prebuilt binaries do not need to be built for specific Node versions. Prebuilt binaries are available for Node-API v3 and v6. Check the [Node-API version matrix](https://nodejs.org/api/n-api.html#node-api-version-matrix) to ensure your Node version supports one of these. Requires Node.js v20.17.0 or later.
 
-The module uses [`prebuild-install`](https://github.com/prebuild/prebuild-install) to download the prebuilt binary for your platform, if it exists. These binaries are hosted on GitHub Releases for `sqlite3` versions above 5.0.2, and they are hosted on S3 otherwise. The following targets are currently provided:
+The module uses [`prebuild-install`](https://github.com/prebuild/prebuild-install) to download the prebuilt binary for your platform, if it exists. These binaries are hosted on GitHub Releases. The following targets are currently provided:
 
 * `darwin-arm64`
 * `darwin-x64`
@@ -64,7 +64,46 @@ SQLite's [SQLCipher extension](https://github.com/sqlcipher/sqlcipher) is also
 
 # API
 
-See the [API documentation](https://github.com/gms1/node-sqlite3/wiki/API) in the wiki.
+See the [API documentation](docs/API.md) for detailed documentation of both the callback-based and Promise-based APIs.
+
+## Quick Example
+
+### Callback-based API (Traditional)
+
+```js
+const sqlite3 = require('@homeofthings/sqlite3').verbose();
+const db = new sqlite3.Database(':memory:');
+
+db.serialize(() => {
+    db.run("CREATE TABLE lorem (info TEXT)");
+    db.run("INSERT INTO lorem VALUES (?)", ['test']);
+    db.each("SELECT * FROM lorem", (err, row) => {
+        console.log(row);
+    });
+});
+
+db.close();
+```
+
+### Promise-based API (Modern)
+
+```js
+const { SqliteDatabase } = require('@homeofthings/sqlite3');
+
+async function main() {
+    const db = await SqliteDatabase.open(':memory:');
+    
+    await db.run("CREATE TABLE lorem (info TEXT)");
+    await db.run("INSERT INTO lorem VALUES (?)", ['test']);
+    
+    const rows = await db.all("SELECT * FROM lorem");
+    console.log(rows);
+    
+    await db.close();
+}
+
+main().catch(console.error);
+```
 
 # Usage
 

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/lib/sqlite3.d.ts

@@ -26,23 +26,23 @@ export const BUSY: number;
 export const LOCKED: number;
 export const NOMEM: number;
 export const READONLY: number;
-export const INTERRUPT: number
+export const INTERRUPT: number;
 export const IOERR: number;
-export const CORRUPT: number
+export const CORRUPT: number;
 export const NOTFOUND: number;
 export const FULL: number;
 export const CANTOPEN: number;
 export const PROTOCOL: number;
 export const EMPTY: number;
 export const SCHEMA: number;
-export const TOOBIG: number
-export const CONSTRAINT: number
+export const TOOBIG: number;
+export const CONSTRAINT: number;
 export const MISMATCH: number;
 export const MISUSE: number;
 export const NOLFS: number;
-export const AUTH: number
+export const AUTH: number;
 export const FORMAT: number;
-export const RANGE: number
+export const RANGE: number;
 export const NOTADB: number;
 
 export const LIMIT_LENGTH: number;
@@ -64,8 +64,8 @@ export const cached: {
 };
 
 export interface RunResult extends Statement {
-    lastID: number;
-    changes: number;
+  lastID: number;
+  changes: number;
 }
 
 export class Statement extends events.EventEmitter {
@@ -143,6 +143,17 @@ export class Database extends events.EventEmitter {
 
 export function verbose(): sqlite3;
 
+export interface Backup {
+    idle: boolean;
+    completed: boolean;
+    failed: boolean;
+    remaining: number;
+    pageCount: number;
+    step(pages: number, callback: (err: Error | null) => void): void;
+    finish(): void;
+}
+
+
 export interface sqlite3 {
     OPEN_READONLY: number;
     OPEN_READWRITE: number;
@@ -165,23 +176,23 @@ export interface sqlite3 {
     LOCKED: number;
     NOMEM: number;
     READONLY: number;
-    INTERRUPT: number
+    INTERRUPT: number;
     IOERR: number;
-    CORRUPT: number
+    CORRUPT: number;
     NOTFOUND: number;
     FULL: number;
     CANTOPEN: number;
     PROTOCOL: number;
     EMPTY: number;
     SCHEMA: number;
-    TOOBIG: number
-    CONSTRAINT: number
+    TOOBIG: number;
+    CONSTRAINT: number;
     MISMATCH: number;
     MISUSE: number;
     NOLFS: number;
-    AUTH: number
+    AUTH: number;
     FORMAT: number;
-    RANGE: number
+    RANGE: number;
     NOTADB: number;
 
     LIMIT_LENGTH: number;
@@ -201,5 +212,143 @@ export interface sqlite3 {
     RunResult: RunResult;
     Statement: typeof Statement;
     Database: typeof Database;
+    Backup: Backup;
+    SqlRunResult: SqlRunResult;
+    SqliteDatabase: typeof SqliteDatabase;
+    SqliteStatement: typeof SqliteStatement;
+    SqliteBackup: typeof SqliteBackup;
     verbose(): this;
 }
+
+// Promise-based wrapper classes
+
+/**
+ * Result object returned by run() operations
+ */
+export interface SqlRunResult {
+    lastID: number;
+    changes: number;
+}
+
+/**
+ * Promise-based wrapper for the Database class
+ */
+export class SqliteDatabase {
+    protected db?: Database;
+
+    constructor();
+
+    static open(filename: string, mode?: number): Promise<SqliteDatabase>;
+
+    open(filename: string, mode?: number): Promise<void>;
+    close(): Promise<void>;
+
+    run(sql: string, params?: any): Promise<SqlRunResult>;
+    get<T = any>(sql: string, params?: any): Promise<T | undefined>;
+    all<T = any>(sql: string, params?: any): Promise<T[]>;
+    each<T = any>(
+        sql: string,
+        params?: any,
+        callback?: (err: Error | null, row: T) => void,
+    ): Promise<number>;
+
+    exec(sql: string): Promise<void>;
+    prepare(sql: string, params?: any): Promise<SqliteStatement>;
+
+    backup(
+        filename: string,
+        filenameIsDest?: boolean,
+        destName?: string,
+        sourceName?: string,
+    ): Promise<SqliteBackup>;
+
+    serialize(callback?: () => void): void;
+    parallelize(callback?: () => void): void;
+
+    transactionalize<T>(callback: () => Promise<T>): Promise<T>;
+    beginTransaction(): Promise<void>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
+    endTransaction(commit: boolean): Promise<void>;
+
+    loadExtension(filename: string): Promise<void>;
+
+    wait(): Promise<void>;
+    interrupt(): void;
+
+    configure(option: string, ...args: any[]): void;
+
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    removeAllListeners(event?: string): this;
+}
+
+/**
+ * Promise-based wrapper for the Statement class
+ */
+export class SqliteStatement {
+    constructor(stmt: Statement);
+
+    bind(...params: any[]): this;
+    reset(): Promise<void>;
+
+    run(params?: any): Promise<SqlRunResult>;
+    get<T = any>(params?: any): Promise<T | undefined>;
+    all<T = any>(params?: any): Promise<T[]>;
+    each<T = any>(
+        params?: any,
+        callback?: (err: Error | null, row: T) => void,
+    ): Promise<number>;
+
+    finalize(): Promise<void>;
+}
+
+/**
+ * Promise-based wrapper for the Backup class
+ */
+export class SqliteBackup {
+    constructor(backup: Backup);
+
+    /**
+     * Returns true if the backup is idle (not actively copying)
+     */
+    readonly idle: boolean;
+
+    /**
+     * Returns true if the backup is completed
+     */
+    readonly completed: boolean;
+
+    /**
+     * Returns true if the backup has failed
+     */
+    readonly failed: boolean;
+
+    /**
+     * Returns the remaining number of pages left to copy
+     * Returns -1 if `step` not yet called
+     */
+    readonly remaining: number;
+
+    /**
+     * Returns the total number of pages
+     * Returns -1 if `step` not yet called
+     */
+    readonly pageCount: number;
+
+    /**
+     * Returns the progress (percentage completion)
+     */
+    readonly progress: number;
+
+    /**
+     * Copy the next page or all remaining pages of the backup
+     * @param pages - Number of pages to copy (-1 for all remaining)
+     */
+    step(pages?: number): Promise<void>;
+
+    /**
+     * Finish the backup (synchronous)
+     */
+    finish(): void;
+}

package/lib/sqlite3.js

@@ -205,3 +205,9 @@ sqlite3.verbose = function() {
 
     return sqlite3;
 };
+
+// Export Promise-based wrapper classes
+const { SqliteDatabase, SqliteStatement, SqliteBackup } = require('./promise');
+sqlite3.SqliteDatabase = SqliteDatabase;
+sqlite3.SqliteStatement = SqliteStatement;
+sqlite3.SqliteBackup = SqliteBackup;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeofthings/sqlite3",
   "description": "Asynchronous, non-blocking SQLite3 bindings",
-  "version": "6.2.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": {
@@ -45,15 +45,18 @@
   },
   "dependencies": {
     "bindings": "^1.5.0",
-    "node-addon-api": "^8.0.0",
+    "node-addon-api": "^8.7.0",
     "prebuild-install": "^7.1.3",
-    "tar": "^7.5.10"
+    "tar": "^7.5.13"
   },
   "devDependencies": {
-    "eslint": "8.56.0",
-    "mocha": "10.2.0",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.2.0",
+    "globals": "^17.4.0",
+    "mocha": "11.7.5",
+    "nyc": "^18.0.0",
     "prebuild": "13.0.1",
-    "tinybench": "^2.9.0"
+    "tinybench": "^6.0.0"
   },
   "peerDependencies": {
     "node-gyp": "12.x"
@@ -75,8 +78,8 @@
     "rebuild": "node-gyp rebuild",
     "upload": "prebuild --verbose --prerelease",
     "frozen-install": "yarn install --frozen-lockfile",
-    "lint": "eslint .eslintrc.js lib/ test/ tools/",
-    "test": "node test/support/createdb.js && mocha -R spec --timeout 480000"
+    "lint": "eslint lib/ test/ tools/",
+    "test": "node test/support/createdb.js && nyc mocha -R spec --timeout 480000"
   },
   "license": "BSD-3-Clause",
   "publishConfig": {

package/src/database.cc

@@ -14,7 +14,7 @@ Napi::FunctionReference Database::constructor;
 Napi::Object Database::Init(Napi::Env env, Napi::Object exports) {
     Napi::HandleScope scope(env);
     // declare napi_default_method here as it is only available in Node v14.12.0+
-    auto napi_default_method = static_cast<napi_property_attributes>(napi_writable | napi_configurable); 
+    auto napi_default_method = static_cast<napi_property_attributes>(napi_writable | napi_configurable);
 
     auto t = DefineClass(env, "Database", {
         InstanceMethod("close", &Database::Close, napi_default_method),
@@ -81,8 +81,21 @@ void Database::Process() {
         queue.pop();
         std::unique_ptr<Call> call(c);
         locked = call->exclusive;
+
+        // Track pending before callback to detect synchronous operations
+        unsigned int before_pending = pending;
         call->callback(call->baton);
 
+        // If operation was synchronous (pending unchanged) and we're in exclusive mode,
+        // reset locked and continue processing the queue.
+        // Synchronous operations don't increment pending, so if pending is unchanged
+        // and locked is true, the operation completed synchronously.
+        if (locked && pending == before_pending) {
+            locked = false;
+            // Continue processing - don't break
+            continue;
+        }
+
         if (locked) break;
     }
 }
@@ -340,7 +353,7 @@ Napi::Value Database::Configure(const Napi::CallbackInfo& info) {
     REQUIRE_ARGUMENTS(2);
 
     Napi::Function handle;
-    if (info[0].StrictEquals( Napi::String::New(env, "trace"))) {    
+    if (info[0].StrictEquals( Napi::String::New(env, "trace"))) {
        auto* baton = new Baton(db, handle);
         db->Schedule(RegisterTraceCallback, baton);
     }

package/src/macros.h

@@ -4,9 +4,14 @@
 const char* sqlite_code_string(int code);
 const char* sqlite_authorizer_string(int type);
 #include <vector>
+#include <atomic>
 
 // TODO: better way to work around StringConcat?
 #include <napi.h>
+
+// Forward declaration of shutdown flag from node_sqlite3.cc
+extern std::atomic<bool> g_env_shutting_down;
+
 inline Napi::String StringConcat(Napi::Value str1, Napi::Value str2) {
   return Napi::String::New(str1.Env(), str1.As<Napi::String>().Utf8Value() +
                     str2.As<Napi::String>().Utf8Value() );
@@ -128,8 +133,21 @@ inline bool OtherIsInt(Napi::Number source) {
     if ((argc != 0) && (passed_argv != NULL)) {\
       args.assign(passed_argv, passed_argv + argc);\
     }\
-    Napi::Value res = (callback).Call(Napi::Value(context), args);             \
-    if (res.IsEmpty()) return __VA_ARGS__;
+    try {\
+        Napi::Value res = (callback).Call(Napi::Value(context), args);\
+        if (res.IsEmpty()) return __VA_ARGS__;\
+    } catch (const Napi::Error&) {\
+        /* During Node.js/Electron shutdown, when using NAPI_CPP_EXCEPTIONS,*/\
+				/* we must take care to not throw any exceptions. */\
+        /* But when napi_call_function returns napi_cannot_run_js */\
+        /* this throws a C++ exception, when NAPI_CPP_EXCEPTIONS is enabled. */\
+        if (g_env_shutting_down.load()) {\
+             /* We need to silently ignore exceptions during shutdown. */\
+            return __VA_ARGS__;\
+        }\
+        /* Real rror - re-throw to propagate it */\
+        throw;\
+    }
 
 #define WORK_DEFINITION(name)                                                  \
     Napi::Value name(const Napi::CallbackInfo& info);                          \
@@ -204,4 +222,4 @@ inline bool OtherIsInt(Napi::Number source) {
     backup->Process();                                                         \
     backup->db->Process();
 
-#endif
+#endif

package/src/node_sqlite3.cc

@@ -2,6 +2,7 @@
 #include <sstream>
 #include <cstring>
 #include <string>
+#include <atomic>
 #include <sqlite3.h>
 
 #include "macros.h"
@@ -11,11 +12,21 @@
 
 using namespace node_sqlite3;
 
+// Global flag set when the environment is shutting down.
+std::atomic<bool> g_env_shutting_down{false};
+
+static void EnvCleanupHook(void* /*data*/) {
+    g_env_shutting_down.store(true);
+}
+
 namespace {
 
 Napi::Object RegisterModule(Napi::Env env, Napi::Object exports) {
     Napi::HandleScope scope(env);
 
+    // Register cleanup hook to detect shutdown
+    napi_add_env_cleanup_hook(env, EnvCleanupHook, nullptr);
+
     Database::Init(env, exports);
     Statement::Init(env, exports);
     Backup::Init(env, exports);