@homeofthings/sqlite3 6.3.1 → 7.0.0

package/deps/sqlite3.gyp

@@ -47,40 +47,15 @@
   },
 
   'targets': [
-    {
-      'target_name': 'action_before_build',
-      'type': 'none',
-      'hard_dependency': 1,
-      'actions': [
-        {
-          'action_name': 'unpack_sqlite_dep',
-          'inputs': [
-            './sqlite-autoconf-<@(sqlite_version).tar.gz'
-          ],
-          'outputs': [
-            '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/sqlite3.c'
-          ],
-          'action': ['node','./extract.js','./sqlite-autoconf-<@(sqlite_version).tar.gz','<(SHARED_INTERMEDIATE_DIR)']
-        }
-      ],
-      'direct_dependent_settings': {
-        'include_dirs': [
-          '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/',
-        ]
-      },
-    },
     {
       'target_name': 'sqlite3',
       'type': 'static_library',
-      'include_dirs': [ '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/' ],
-      'dependencies': [
-        'action_before_build'
-      ],
+      'include_dirs': [ './sqlite-amalgamation-<@(sqlite_version)/' ],
       'sources': [
-        '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/sqlite3.c'
+        './sqlite-amalgamation-<@(sqlite_version)/sqlite3.c'
       ],
       'direct_dependent_settings': {
-        'include_dirs': [ '<(SHARED_INTERMEDIATE_DIR)/sqlite-autoconf-<@(sqlite_version)/' ],
+        'include_dirs': [ './sqlite-amalgamation-<@(sqlite_version)/' ],
         'defines': [
           'SQLITE_THREADSAFE=1',
           'HAVE_USLEEP=1',
@@ -106,9 +81,6 @@
         'SQLITE_ENABLE_DBSTAT_VTAB=1',
         'SQLITE_ENABLE_MATH_FUNCTIONS'
       ],
-      'export_dependent_settings': [
-        'action_before_build',
-      ],
       'conditions': [
         ["sqlite_magic != ''", {
             'defines': [
@@ -118,4 +90,4 @@
       ],
     }
   ]
-}
+}

package/lib/promise/database.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { Database } = require('../sqlite3.js');
+const { Database } = require('../sqlite3-callback.js');
 const { SqliteStatement } = require('./statement');
 const { SqliteBackup } = require('./backup');
 
@@ -324,9 +324,18 @@ class SqliteDatabase {
     /**
    * 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();
@@ -341,7 +350,10 @@ class SqliteDatabase {
     }
 
     /**
-   * Begin a transaction
+   * 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>}
    */

package/lib/promise/index.d.ts

@@ -0,0 +1 @@
+export { SqliteDatabase, SqliteStatement, SqliteBackup, SqlRunResult } from '../sqlite3';

package/lib/promise/index.mjs

@@ -0,0 +1,9 @@
+/**
+ * ESM wrapper for the Promise-based API of @homeofthings/sqlite3
+ *
+ * Usage:
+ *   import { SqliteDatabase } from '@homeofthings/sqlite3/promise';
+ *   const db = await SqliteDatabase.open(':memory:');
+ */
+
+export { SqliteDatabase, SqliteStatement, SqliteBackup } from './index.js';

package/lib/promise/statement.js

@@ -60,6 +60,10 @@ class SqliteStatement {
     /**
    * 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() {

package/lib/sqlite3-binding.js

@@ -1 +1 @@
-module.exports = require('bindings')('node_sqlite3.node');
+module.exports = require('node-gyp-build')(require('path').join(__dirname, '..'));

package/lib/sqlite3-callback.js

@@ -0,0 +1,207 @@
+const path = require('path');
+const sqlite3 = require('./sqlite3-binding.js');
+const EventEmitter = require('events').EventEmitter;
+module.exports = exports = sqlite3;
+
+function normalizeMethod (fn) {
+    return function (sql) {
+        let errBack;
+        const args = Array.prototype.slice.call(arguments, 1);
+
+        if (typeof args[args.length - 1] === 'function') {
+            const callback = args[args.length - 1];
+            errBack = function(err) {
+                if (err) {
+                    callback(err);
+                }
+            };
+        }
+        const statement = new Statement(this, sql, errBack);
+        return fn.call(this, statement, args);
+    };
+}
+
+function inherits(target, source) {
+    for (const k in source.prototype)
+        target.prototype[k] = source.prototype[k];
+}
+
+sqlite3.cached = {
+    Database: function(file, a, b) {
+        if (file === '' || file === ':memory:') {
+            // Don't cache special databases.
+            return new Database(file, a, b);
+        }
+
+        let db;
+        file = path.resolve(file);
+
+        if (!sqlite3.cached.objects[file]) {
+            db = sqlite3.cached.objects[file] = new Database(file, a, b);
+        }
+        else {
+            // Make sure the callback is called.
+            db = sqlite3.cached.objects[file];
+            const callback = (typeof a === 'number') ? b : a;
+            if (typeof callback === 'function') {
+                function cb() { callback.call(db, null); }
+                if (db.open) process.nextTick(cb);
+                else db.once('open', cb);
+            }
+        }
+
+        return db;
+    },
+    objects: {}
+};
+
+
+const Database = sqlite3.Database;
+const Statement = sqlite3.Statement;
+const Backup = sqlite3.Backup;
+
+inherits(Database, EventEmitter);
+inherits(Statement, EventEmitter);
+inherits(Backup, EventEmitter);
+
+// Database#prepare(sql, [bind1, bind2, ...], [callback])
+Database.prototype.prepare = normalizeMethod(function(statement, params) {
+    return params.length
+        ? statement.bind.apply(statement, params)
+        : statement;
+});
+
+// Database#run(sql, [bind1, bind2, ...], [callback])
+Database.prototype.run = normalizeMethod(function(statement, params) {
+    statement.run.apply(statement, params).finalize();
+    return this;
+});
+
+// Database#get(sql, [bind1, bind2, ...], [callback])
+Database.prototype.get = normalizeMethod(function(statement, params) {
+    statement.get.apply(statement, params).finalize();
+    return this;
+});
+
+// Database#all(sql, [bind1, bind2, ...], [callback])
+Database.prototype.all = normalizeMethod(function(statement, params) {
+    statement.all.apply(statement, params).finalize();
+    return this;
+});
+
+// Database#each(sql, [bind1, bind2, ...], [callback], [complete])
+Database.prototype.each = normalizeMethod(function(statement, params) {
+    statement.each.apply(statement, params).finalize();
+    return this;
+});
+
+Database.prototype.map = normalizeMethod(function(statement, params) {
+    statement.map.apply(statement, params).finalize();
+    return this;
+});
+
+// Database#backup(filename, [callback])
+// Database#backup(filename, destName, sourceName, filenameIsDest, [callback])
+Database.prototype.backup = function() {
+    let backup;
+    if (arguments.length <= 2) {
+        // By default, we write the main database out to the main database of the named file.
+        // This is the most likely use of the backup api.
+        backup = new Backup(this, arguments[0], 'main', 'main', true, arguments[1]);
+    } else {
+        // Otherwise, give the user full control over the sqlite3_backup_init arguments.
+        backup = new Backup(this, arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
+    }
+    // Per the sqlite docs, exclude the following errors as non-fatal by default.
+    backup.retryErrors = [sqlite3.BUSY, sqlite3.LOCKED];
+    return backup;
+};
+
+Statement.prototype.map = function() {
+    const params = Array.prototype.slice.call(arguments);
+    const callback = params.pop();
+    params.push(function(err, rows) {
+        if (err) return callback(err);
+        const result = {};
+        if (rows.length) {
+            const keys = Object.keys(rows[0]);
+            const key = keys[0];
+            if (keys.length > 2) {
+                // Value is an object
+                for (let i = 0; i < rows.length; i++) {
+                    result[rows[i][key]] = rows[i];
+                }
+            } else {
+                const value = keys[1];
+                // Value is a plain value
+                for (let i = 0; i < rows.length; i++) {
+                    result[rows[i][key]] = rows[i][value];
+                }
+            }
+        }
+        callback(err, result);
+    });
+    return this.all.apply(this, params);
+};
+
+let isVerbose = false;
+
+const supportedEvents = [ 'trace', 'profile', 'change' ];
+
+Database.prototype.addListener = Database.prototype.on = function(type) {
+    const val = EventEmitter.prototype.addListener.apply(this, arguments);
+    if (supportedEvents.indexOf(type) >= 0) {
+        this.configure(type, true);
+    }
+    return val;
+};
+
+Database.prototype.removeListener = function(type) {
+    const val = EventEmitter.prototype.removeListener.apply(this, arguments);
+    if (supportedEvents.indexOf(type) >= 0 && !this._events[type]) {
+        this.configure(type, false);
+    }
+    return val;
+};
+
+Database.prototype.removeAllListeners = function(type) {
+    const val = EventEmitter.prototype.removeAllListeners.apply(this, arguments);
+    if (supportedEvents.indexOf(type) >= 0) {
+        this.configure(type, false);
+    }
+    return val;
+};
+
+// Save the stack trace over EIO callbacks.
+sqlite3.verbose = function() {
+    if (!isVerbose) {
+        const trace = require('./trace');
+        [
+            'prepare',
+            'get',
+            'run',
+            'all',
+            'each',
+            'map',
+            'close',
+            'exec'
+        ].forEach(function (name) {
+            trace.extendTrace(Database.prototype, name);
+        });
+        [
+            'bind',
+            'get',
+            'run',
+            'all',
+            'each',
+            'map',
+            'reset',
+            'finalize',
+        ].forEach(function (name) {
+            trace.extendTrace(Statement.prototype, name);
+        });
+        isVerbose = true;
+    }
+
+    return sqlite3;
+};

package/lib/sqlite3.d.ts

@@ -220,6 +220,11 @@ export interface sqlite3 {
     verbose(): this;
 }
 
+// Default export for ESM consumers
+// CJS: const sqlite3 = require('@homeofthings/sqlite3')
+// ESM: import sqlite3 from '@homeofthings/sqlite3'
+export default sqlite3;
+
 // Promise-based wrapper classes
 
 /**
@@ -265,7 +270,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 +320,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/lib/sqlite3.js

@@ -1,213 +1,13 @@
-const path = require('path');
-const sqlite3 = require('./sqlite3-binding.js');
-const EventEmitter = require('events').EventEmitter;
-module.exports = exports = sqlite3;
+// Main entry point: re-exports the callback API and adds Promise-based wrapper classes.
+// The callback API is in sqlite3-callback.js to avoid circular dependencies
+// (promise modules require sqlite3-callback.js, not this file).
 
-function normalizeMethod (fn) {
-    return function (sql) {
-        let errBack;
-        const args = Array.prototype.slice.call(arguments, 1);
-
-        if (typeof args[args.length - 1] === 'function') {
-            const callback = args[args.length - 1];
-            errBack = function(err) {
-                if (err) {
-                    callback(err);
-                }
-            };
-        }
-        const statement = new Statement(this, sql, errBack);
-        return fn.call(this, statement, args);
-    };
-}
-
-function inherits(target, source) {
-    for (const k in source.prototype)
-        target.prototype[k] = source.prototype[k];
-}
-
-sqlite3.cached = {
-    Database: function(file, a, b) {
-        if (file === '' || file === ':memory:') {
-            // Don't cache special databases.
-            return new Database(file, a, b);
-        }
-
-        let db;
-        file = path.resolve(file);
-
-        if (!sqlite3.cached.objects[file]) {
-            db = sqlite3.cached.objects[file] = new Database(file, a, b);
-        }
-        else {
-            // Make sure the callback is called.
-            db = sqlite3.cached.objects[file];
-            const callback = (typeof a === 'number') ? b : a;
-            if (typeof callback === 'function') {
-                function cb() { callback.call(db, null); }
-                if (db.open) process.nextTick(cb);
-                else db.once('open', cb);
-            }
-        }
-
-        return db;
-    },
-    objects: {}
-};
-
-
-const Database = sqlite3.Database;
-const Statement = sqlite3.Statement;
-const Backup = sqlite3.Backup;
-
-inherits(Database, EventEmitter);
-inherits(Statement, EventEmitter);
-inherits(Backup, EventEmitter);
-
-// Database#prepare(sql, [bind1, bind2, ...], [callback])
-Database.prototype.prepare = normalizeMethod(function(statement, params) {
-    return params.length
-        ? statement.bind.apply(statement, params)
-        : statement;
-});
-
-// Database#run(sql, [bind1, bind2, ...], [callback])
-Database.prototype.run = normalizeMethod(function(statement, params) {
-    statement.run.apply(statement, params).finalize();
-    return this;
-});
-
-// Database#get(sql, [bind1, bind2, ...], [callback])
-Database.prototype.get = normalizeMethod(function(statement, params) {
-    statement.get.apply(statement, params).finalize();
-    return this;
-});
-
-// Database#all(sql, [bind1, bind2, ...], [callback])
-Database.prototype.all = normalizeMethod(function(statement, params) {
-    statement.all.apply(statement, params).finalize();
-    return this;
-});
-
-// Database#each(sql, [bind1, bind2, ...], [callback], [complete])
-Database.prototype.each = normalizeMethod(function(statement, params) {
-    statement.each.apply(statement, params).finalize();
-    return this;
-});
-
-Database.prototype.map = normalizeMethod(function(statement, params) {
-    statement.map.apply(statement, params).finalize();
-    return this;
-});
-
-// Database#backup(filename, [callback])
-// Database#backup(filename, destName, sourceName, filenameIsDest, [callback])
-Database.prototype.backup = function() {
-    let backup;
-    if (arguments.length <= 2) {
-        // By default, we write the main database out to the main database of the named file.
-        // This is the most likely use of the backup api.
-        backup = new Backup(this, arguments[0], 'main', 'main', true, arguments[1]);
-    } else {
-        // Otherwise, give the user full control over the sqlite3_backup_init arguments.
-        backup = new Backup(this, arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
-    }
-    // Per the sqlite docs, exclude the following errors as non-fatal by default.
-    backup.retryErrors = [sqlite3.BUSY, sqlite3.LOCKED];
-    return backup;
-};
-
-Statement.prototype.map = function() {
-    const params = Array.prototype.slice.call(arguments);
-    const callback = params.pop();
-    params.push(function(err, rows) {
-        if (err) return callback(err);
-        const result = {};
-        if (rows.length) {
-            const keys = Object.keys(rows[0]);
-            const key = keys[0];
-            if (keys.length > 2) {
-                // Value is an object
-                for (let i = 0; i < rows.length; i++) {
-                    result[rows[i][key]] = rows[i];
-                }
-            } else {
-                const value = keys[1];
-                // Value is a plain value
-                for (let i = 0; i < rows.length; i++) {
-                    result[rows[i][key]] = rows[i][value];
-                }
-            }
-        }
-        callback(err, result);
-    });
-    return this.all.apply(this, params);
-};
-
-let isVerbose = false;
-
-const supportedEvents = [ 'trace', 'profile', 'change' ];
-
-Database.prototype.addListener = Database.prototype.on = function(type) {
-    const val = EventEmitter.prototype.addListener.apply(this, arguments);
-    if (supportedEvents.indexOf(type) >= 0) {
-        this.configure(type, true);
-    }
-    return val;
-};
-
-Database.prototype.removeListener = function(type) {
-    const val = EventEmitter.prototype.removeListener.apply(this, arguments);
-    if (supportedEvents.indexOf(type) >= 0 && !this._events[type]) {
-        this.configure(type, false);
-    }
-    return val;
-};
-
-Database.prototype.removeAllListeners = function(type) {
-    const val = EventEmitter.prototype.removeAllListeners.apply(this, arguments);
-    if (supportedEvents.indexOf(type) >= 0) {
-        this.configure(type, false);
-    }
-    return val;
-};
-
-// Save the stack trace over EIO callbacks.
-sqlite3.verbose = function() {
-    if (!isVerbose) {
-        const trace = require('./trace');
-        [
-            'prepare',
-            'get',
-            'run',
-            'all',
-            'each',
-            'map',
-            'close',
-            'exec'
-        ].forEach(function (name) {
-            trace.extendTrace(Database.prototype, name);
-        });
-        [
-            'bind',
-            'get',
-            'run',
-            'all',
-            'each',
-            'map',
-            'reset',
-            'finalize',
-        ].forEach(function (name) {
-            trace.extendTrace(Statement.prototype, name);
-        });
-        isVerbose = true;
-    }
-
-    return sqlite3;
-};
+const sqlite3 = require('./sqlite3-callback.js');
 
 // Export Promise-based wrapper classes
 const { SqliteDatabase, SqliteStatement, SqliteBackup } = require('./promise');
 sqlite3.SqliteDatabase = SqliteDatabase;
 sqlite3.SqliteStatement = SqliteStatement;
 sqlite3.SqliteBackup = SqliteBackup;
+
+module.exports = exports = sqlite3;

package/lib/sqlite3.mjs

@@ -0,0 +1,78 @@
+/**
+ * ESM wrapper for @homeofthings/sqlite3
+ *
+ * This module provides ESM (ECMAScript Module) entry points that delegate
+ *
+ * Usage:
+ *   // Default import
+ *   import sqlite3 from '@homeofthings/sqlite3';
+ *
+ *   // Named imports
+ *   import { Database, OPEN_CREATE } from '@homeofthings/sqlite3';
+ */
+
+import sqlite3 from './sqlite3.js';
+
+export default sqlite3;
+
+export const {
+    OPEN_READONLY,
+    OPEN_READWRITE,
+    OPEN_CREATE,
+    OPEN_FULLMUTEX,
+    OPEN_SHAREDCACHE,
+    OPEN_PRIVATECACHE,
+    OPEN_URI,
+    VERSION,
+    SOURCE_ID,
+    VERSION_NUMBER,
+    OK,
+    ERROR,
+    INTERNAL,
+    PERM,
+    ABORT,
+    BUSY,
+    LOCKED,
+    NOMEM,
+    READONLY,
+    INTERRUPT,
+    IOERR,
+    CORRUPT,
+    NOTFOUND,
+    FULL,
+    CANTOPEN,
+    PROTOCOL,
+    EMPTY,
+    SCHEMA,
+    TOOBIG,
+    CONSTRAINT,
+    MISMATCH,
+    MISUSE,
+    NOLFS,
+    AUTH,
+    FORMAT,
+    RANGE,
+    NOTADB,
+    LIMIT_LENGTH,
+    LIMIT_SQL_LENGTH,
+    LIMIT_COLUMN,
+    LIMIT_EXPR_DEPTH,
+    LIMIT_COMPOUND_SELECT,
+    LIMIT_VDBE_OP,
+    LIMIT_FUNCTION_ARG,
+    LIMIT_ATTACHED,
+    LIMIT_LIKE_PATTERN_LENGTH,
+    LIMIT_VARIABLE_NUMBER,
+    LIMIT_TRIGGER_DEPTH,
+    LIMIT_WORKER_THREADS,
+    cached,
+    RunResult,
+    Statement,
+    Database,
+    Backup,
+    SqlRunResult,
+    SqliteDatabase,
+    SqliteStatement,
+    SqliteBackup,
+    verbose
+} = sqlite3;