@homeofthings/sqlite3 6.2.0 → 6.3.0

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/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.0",
   "homepage": "https://github.com/gms1/node-sqlite3",
   "author": {
     "name": "Mapbox",
@@ -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);