@homeofthings/sqlite3 6.3.0 → 6.4.0

package/README.md

@@ -20,7 +20,7 @@ Asynchronous, non-blocking [SQLite3](https://sqlite.org/) bindings for [Node.js]
  - [Extension support](https://github.com/gms1/node-sqlite3/wiki/API#databaseloadextensionpath-callback), including bundled support for the [json1 extension](https://www.sqlite.org/json1.html)
  - Big test suite
  - Written in modern C++ and tested for memory leaks
- - Bundles SQLite v3.51.3, or you can build using a local SQLite
+ - Bundles SQLite v3.53.0, or you can build using a local SQLite
 
 # Installing
 
@@ -245,6 +245,34 @@ npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher
 npm test
 ```
 
+# Benchmarks
+
+## Driver Comparison
+
+The `tools/benchmark-drivers` directory contains a comprehensive benchmark suite comparing different SQLite drivers for Node.js:
+
+```bash
+cd tools/benchmark-drivers
+npm install
+node index.js
+```
+
+This compares `@homeofthings/sqlite3` against other popular SQLite drivers:
+- `better-sqlite3` - Synchronous, high-performance
+- `node:sqlite` - Built-in Node.js SQLite (v22.6.0+)
+
+See [tools/benchmark-drivers/README.md](tools/benchmark-drivers/README.md) for details.
+
+**Key insight**: Async drivers like `@homeofthings/sqlite3` show lower raw throughput but provide better event loop availability, allowing other operations to proceed concurrently. Sync drivers block the event loop completely.
+
+## Internal Benchmarks
+
+Internal performance benchmarks are available in `tools/benchmark-internal`:
+
+```bash
+node tools/benchmark-internal/run.js
+```
+
 # Contributors
 
 * [Daniel Lockyer](https://github.com/daniellockyer)
@@ -269,7 +297,9 @@ Thanks to [Orlando Vazquez](https://github.com/orlandov),
 [Eric Fredricksen](https://github.com/grumdrig) and
 [Ryan Dahl](https://github.com/ry) for their SQLite bindings for node, and to mraleph on Freenode's #v8 for answering questions.
 
-This module was originally created by [Mapbox](https://mapbox.com/) & is now maintained by [Ghost](https://ghost.org).
+This module was originally created by [Mapbox](https://mapbox.com/), then it was taken over by [Ghost](https://ghost.org), but was then deprecated without prior notice, so that the original is no longer maintained. See [TryGhost/node-sqlite3](https://github.com/TryGhost/node-sqlite3)
+
+I still hope that it will eventually be taken over by a larger organization, but in the meantime, I'm trying to maintain this fork here.
 
 # Changelog
 

package/deps/common-sqlite.gypi

@@ -1,6 +1,6 @@
 {
   'variables': {
-      'sqlite_version%':'3510300',
+      'sqlite_version%':'3530000',
       "toolset%":'',
   },
   'target_defaults': {

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,517 @@
+/**
+ * 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
+   *
+   * IMPORTANT: SQLite provides isolation between different database connections,
+   * but NOT between operations on the same connection. If you need concurrent
+   * transactions with proper isolation, use separate SqliteDatabase instances.
+   *
+   * Note: This uses BEGIN IMMEDIATE TRANSACTION which acquires a write lock
+   * immediately. If another connection holds a write lock, this will fail
+   * with SQLITE_BUSY error.
+   *
+   * @template T
+   * @param {() => Promise<T>} callback - The callback to run in transaction
+   * @returns {Promise<T>} A promise that resolves to the callback result
+   * @see https://www.sqlite.org/isolation.html
+   */
+    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 using BEGIN IMMEDIATE TRANSACTION
+   *
+   * This acquires a write lock immediately, preventing deadlocks by
+   * failing fast if another connection holds the lock (SQLITE_BUSY).
+   *
+   * @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,185 @@
+/**
+ * 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)
+   *
+   * IMPORTANT: You MUST finalize all prepared statements before closing the database.
+   * If you attempt to close a database with unfinalized statements, you will get:
+   * SQLITE_BUSY: unable to close due to unfinalised statements
+   *
+   * @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

@@ -265,7 +265,22 @@ export class SqliteDatabase {
     serialize(callback?: () => void): void;
     parallelize(callback?: () => void): void;
 
+    /**
+     * Run callback inside a database transaction.
+     *
+     * IMPORTANT: SQLite provides isolation between different database connections,
+     * but NOT between operations on the same connection. For concurrent transactions
+     * with proper isolation, use separate SqliteDatabase instances.
+     *
+     * Uses BEGIN IMMEDIATE TRANSACTION which acquires a write lock immediately.
+     * @see https://www.sqlite.org/isolation.html
+     */
     transactionalize<T>(callback: () => Promise<T>): Promise<T>;
+
+    /**
+     * Begin a transaction using BEGIN IMMEDIATE TRANSACTION.
+     * Acquires write lock immediately - fails with SQLITE_BUSY if lock unavailable.
+     */
     beginTransaction(): Promise<void>;
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
@@ -300,6 +315,11 @@ export class SqliteStatement {
         callback?: (err: Error | null, row: T) => void,
     ): Promise<number>;
 
+    /**
+     * Finalizes the statement.
+     * IMPORTANT: You MUST finalize all prepared statements before closing the database.
+     * Otherwise you will get SQLITE_BUSY: unable to close due to unfinalised statements
+     */
     finalize(): Promise<void>;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeofthings/sqlite3",
   "description": "Asynchronous, non-blocking SQLite3 bindings",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "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": {
@@ -52,7 +52,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",
-    "globals": "^17.4.0",
+    "globals": "^17.5.0",
     "mocha": "11.7.5",
     "nyc": "^18.0.0",
     "prebuild": "13.0.1",