@photostructure/sqlite 0.3.0 → 0.5.0

package/src/sqlite_impl.h

@@ -14,6 +14,7 @@
 #include <stdexcept>
 #include <string>
 #include <thread>
+#include <unordered_map>
 
 // Include our shims
 #include "shims/base_object.h"
@@ -31,6 +32,7 @@ class DatabaseSync;
 class StatementSync;
 class StatementSyncIterator;
 class Session;
+class BackupJob;
 
 // Per-worker instance data
 struct AddonData {
@@ -43,8 +45,19 @@ struct AddonData {
   Napi::FunctionReference statementSyncConstructor;
   Napi::FunctionReference statementSyncIteratorConstructor;
   Napi::FunctionReference sessionConstructor;
+
+  // Cached Object.create function for creating objects with null prototype
+  Napi::FunctionReference objectCreateFn;
+
+  // ValueStorage data
+  std::mutex value_storage_mutex;
+  std::unordered_map<int32_t, Napi::Reference<Napi::Value>> value_storage;
+  std::atomic<int32_t> next_value_id{0};
 };
 
+// Helper to create an object with null prototype (matches Node.js behavior)
+Napi::Object CreateObjectWithNullPrototype(Napi::Env env);
+
 // Worker thread support functions
 void RegisterDatabaseInstance(Napi::Env env, DatabaseSync *database);
 void UnregisterDatabaseInstance(Napi::Env env, DatabaseSync *database);
@@ -103,6 +116,9 @@ public:
   bool get_enable_defensive() const { return defensive_; }
   void set_enable_defensive(bool flag) { defensive_ = flag; }
 
+  bool get_open_uri() const { return open_uri_; }
+  void set_open_uri(bool flag) { open_uri_ = flag; }
+
 private:
   std::string location_;
   bool read_only_ = false;
@@ -113,7 +129,8 @@ private:
   bool return_arrays_ = false;
   bool allow_bare_named_params_ = true;
   bool allow_unknown_named_params_ = false;
-  bool defensive_ = false;
+  bool defensive_ = true; // Node.js v25+ defaults to true
+  bool open_uri_ = false;
 };
 
 // Main database class
@@ -175,6 +192,12 @@ public:
   void RemoveSession(Session *session);
   void DeleteAllSessions();
 
+  // Backup management - prevents use-after-free when database is closed
+  // during an active backup operation
+  void AddBackup(BackupJob *backup);
+  void RemoveBackup(BackupJob *backup);
+  void FinalizeBackups();
+
   // Error handling for user functions
   void SetIgnoreNextSQLiteError(bool ignore) {
     ignore_next_sqlite_error_ = ignore;
@@ -192,7 +215,7 @@ public:
     return deferred_authorizer_exception_.has_value();
   }
   const std::string &GetDeferredAuthorizerException() const {
-    return deferred_authorizer_exception_.value();
+    return *deferred_authorizer_exception_;
   }
 
 private:
@@ -207,6 +230,8 @@ private:
   std::map<std::string, std::unique_ptr<StatementSync>> prepared_statements_;
   std::set<Session *> sessions_;      // Track all active sessions
   mutable std::mutex sessions_mutex_; // Protect sessions_ for thread safety
+  std::set<BackupJob *> backups_;     // Track all active backup jobs
+  mutable std::mutex backups_mutex_;  // Protect backups_ for thread safety
   std::thread::id creation_thread_;
   napi_env env_;                          // Store for cleanup purposes
   bool ignore_next_sqlite_error_ = false; // For user function error handling
@@ -218,12 +243,16 @@ private:
   // Authorization callback storage
   std::unique_ptr<Napi::FunctionReference> authorizer_callback_;
 
+  // Environment cleanup hook - called before environment teardown
+  static void CleanupHook(void *arg);
+
   // Store database-level defaults for statement options
   DatabaseOpenConfiguration config_;
 
   bool ValidateThread(Napi::Env env) const;
   friend class Session;
   friend class StatementSync;
+  friend class BackupJob;
 };
 
 // Statement class
@@ -268,10 +297,6 @@ private:
   void Reset();
 
   DatabaseSync *database_ = nullptr;
-  // Strong reference to database object to prevent GC while statement exists.
-  // This fixes use-after-free when database is GC'd before its statements.
-  // See: https://github.com/nodejs/node/pull/56840
-  Napi::ObjectReference database_ref_;
   sqlite3_stmt *statement_ = nullptr;
   std::string source_sql_;
   bool finalized_ = false;
@@ -287,6 +312,7 @@ private:
   std::optional<std::map<std::string, std::string>> bare_named_params_;
 
   bool ValidateThread(Napi::Env env) const;
+  friend class DatabaseSync;
   friend class StatementSyncIterator;
 };
 
@@ -302,6 +328,7 @@ public:
   // Iterator methods
   Napi::Value Next(const Napi::CallbackInfo &info);
   Napi::Value Return(const Napi::CallbackInfo &info);
+  Napi::Value ToArray(const Napi::CallbackInfo &info);
 
 private:
   void SetStatement(StatementSync *stmt);
@@ -363,10 +390,15 @@ public:
 
   Napi::Promise GetPromise() { return deferred_.Promise(); }
 
-private:
+public:
+  // Cleanup is called by FinalizeBackups when database is closing
   void Cleanup();
+  // Called by FinalizeBackups to prevent double-unregistration in destructor
+  void ClearSource() { source_ = nullptr; }
 
+private:
   DatabaseSync *source_;
+  sqlite3 *source_connection_; // Captured at construction to avoid race
   std::string destination_path_;
   std::string source_db_;
   std::string dest_db_;
@@ -381,6 +413,13 @@ private:
   Napi::FunctionReference progress_func_;
   Napi::Promise::Deferred deferred_;
 
+  // Error from progress callback (set on main thread, checked in OnOK)
+  std::optional<std::string> progress_error_;
+
+  // Environment cleanup hook - called before environment teardown
+  static void CleanupHook(void *arg);
+  napi_env env_;
+
   static std::atomic<int> active_jobs_;
   static std::mutex active_jobs_mutex_;
   static std::set<BackupJob *> active_job_instances_;

package/src/transaction.ts

@@ -0,0 +1,178 @@
+import type { DatabaseSyncInstance } from "./types/database-sync-instance";
+import type { TransactionFunction, TransactionMode } from "./types/transaction";
+
+/**
+ * Internal counter for generating unique savepoint names.
+ * Using a global counter ensures uniqueness even with deeply nested transactions.
+ */
+let savepointCounter = 0;
+
+/**
+ * Creates a transaction-wrapped version of a function.
+ *
+ * When the returned function is called, it will:
+ * 1. Begin a transaction (or create a savepoint if already in a transaction)
+ * 2. Execute the wrapped function
+ * 3. Commit the transaction (or release the savepoint) on success
+ * 4. Rollback the transaction (or rollback to savepoint) on error
+ *
+ * The wrapped function **must not** return a Promise. SQLite transactions are
+ * synchronous, and allowing async operations would leave the transaction open
+ * across event loop ticks, which is dangerous and can cause deadlocks.
+ *
+ * @example
+ * ```typescript
+ * const db = new DatabaseSync(':memory:');
+ * db.exec('CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)');
+ *
+ * const insert = db.prepare('INSERT INTO items (name) VALUES (?)');
+ *
+ * // Create a transaction function
+ * const insertMany = db.transaction((names: string[]) => {
+ *   for (const name of names) {
+ *     insert.run(name);
+ *   }
+ *   return names.length;
+ * });
+ *
+ * // Execute - automatically wrapped in BEGIN/COMMIT
+ * const count = insertMany(['Alice', 'Bob', 'Charlie']);
+ * console.log(count); // 3
+ *
+ * // If an error occurs, automatically rolls back
+ * try {
+ *   insertMany(['Dave', 'FAIL']); // Assume this throws
+ * } catch (e) {
+ *   // Transaction was rolled back, Dave was not inserted
+ * }
+ *
+ * // Use different transaction modes
+ * insertMany.immediate(['Eve']); // BEGIN IMMEDIATE
+ * insertMany.exclusive(['Frank']); // BEGIN EXCLUSIVE
+ * ```
+ *
+ * @param db - The database connection
+ * @param fn - The function to wrap in a transaction
+ * @returns A transaction function with `.deferred`, `.immediate`, and `.exclusive` variants
+ */
+export function createTransaction<F extends (...args: any[]) => any>(
+  db: DatabaseSyncInstance,
+  fn: F,
+): TransactionFunction<F> {
+  if (typeof fn !== "function") {
+    throw new TypeError("Expected first argument to be a function");
+  }
+
+  // Create all four variants
+  const variants = {
+    deferred: createVariant(db, fn, "deferred"),
+    immediate: createVariant(db, fn, "immediate"),
+    exclusive: createVariant(db, fn, "exclusive"),
+  };
+
+  // The default function uses DEFERRED mode (SQLite's default)
+  const defaultFn = variants.deferred as TransactionFunction<F>;
+
+  // Set up the variant properties on each function
+  // Each variant has access to all other variants
+  for (const variant of Object.values(variants)) {
+    Object.defineProperties(variant, {
+      deferred: { value: variants.deferred, enumerable: true },
+      immediate: { value: variants.immediate, enumerable: true },
+      exclusive: { value: variants.exclusive, enumerable: true },
+      database: { value: db, enumerable: true },
+    });
+  }
+
+  return defaultFn;
+}
+
+/**
+ * Creates a single transaction variant for a specific mode.
+ */
+function createVariant<F extends (...args: any[]) => any>(
+  db: DatabaseSyncInstance,
+  fn: F,
+  mode: TransactionMode,
+): (...args: Parameters<F>) => ReturnType<F> {
+  const beginStatement = getBeginStatement(mode);
+
+  return function transactionWrapper(
+    this: unknown,
+    ...args: Parameters<F>
+  ): ReturnType<F> {
+    // Check if we're already in a transaction (nested transaction)
+    const isNested = db.isTransaction;
+
+    let begin: string;
+    let commit: string;
+    let rollback: string;
+
+    if (isNested) {
+      // Use savepoints for nested transactions
+      // The savepoint name uses backticks to allow special characters
+      // and a counter to ensure uniqueness
+      const savepointName = `\`_txn_${++savepointCounter}\``;
+      begin = `SAVEPOINT ${savepointName}`;
+      commit = `RELEASE ${savepointName}`;
+      rollback = `ROLLBACK TO ${savepointName}`;
+    } else {
+      // Top-level transaction
+      begin = beginStatement;
+      commit = "COMMIT";
+      rollback = "ROLLBACK";
+    }
+
+    // Begin the transaction or savepoint
+    db.exec(begin);
+
+    try {
+      // Execute the wrapped function
+      const result = fn.apply(this, args);
+
+      // Check for promises - async functions break transaction semantics
+      if (result !== null && typeof result === "object" && "then" in result) {
+        throw new TypeError(
+          "Transaction function must not return a Promise. " +
+            "SQLite transactions are synchronous and cannot span across async operations. " +
+            "Use synchronous code within transactions.",
+        );
+      }
+
+      // Commit the transaction or release the savepoint
+      db.exec(commit);
+
+      return result;
+    } catch (error) {
+      // Only attempt rollback if we're still in a transaction
+      // (SQLite may have already rolled back due to constraint violations, etc.)
+      if (db.isTransaction) {
+        db.exec(rollback);
+        // For nested transactions, we also need to release the savepoint
+        // after rolling back to it (the savepoint still exists after ROLLBACK TO)
+        if (isNested) {
+          db.exec(commit);
+        }
+      }
+
+      throw error;
+    }
+  };
+}
+
+/**
+ * Returns the appropriate BEGIN statement for a transaction mode.
+ */
+function getBeginStatement(mode: TransactionMode): string {
+  switch (mode) {
+    case "deferred":
+      return "BEGIN DEFERRED";
+    case "immediate":
+      return "BEGIN IMMEDIATE";
+    case "exclusive":
+      return "BEGIN EXCLUSIVE";
+    default:
+      // TypeScript should catch this, but just in case
+      throw new Error(`Unknown transaction mode: ${mode}`);
+  }
+}

package/src/types/database-sync-instance.ts

@@ -88,13 +88,18 @@ export interface DatabaseSyncInstance {
    * ```
    */
   createTagStore(capacity?: number): SQLTagStoreInstance;
+
   /**
    * Apply a changeset to the database.
    * @param changeset The changeset data to apply.
    * @param options Optional configuration for applying the changeset.
    * @returns true if successful, false if aborted.
    */
-  applyChangeset(changeset: Buffer, options?: ChangesetApplyOptions): boolean;
+  applyChangeset(
+    changeset: Uint8Array,
+    options?: ChangesetApplyOptions,
+  ): boolean;
+
   /**
    * Enables or disables the loading of SQLite extensions.
    * @param enable If true, enables extension loading. If false, disables it.
@@ -159,45 +164,6 @@ export interface DatabaseSyncInstance {
       | null,
   ): void;
 
-  /**
-   * Makes a backup of the database. This method abstracts the sqlite3_backup_init(),
-   * sqlite3_backup_step() and sqlite3_backup_finish() functions.
-   *
-   * The backed-up database can be used normally during the backup process. Mutations
-   * coming from the same connection will be reflected in the backup right away.
-   * However, mutations from other connections will cause the backup process to restart.
-   *
-   * @param path The path where the backup will be created. If the file already exists, the contents will be overwritten.
-   * @param options Optional configuration for the backup operation.
-   * @param options.rate Number of pages to be transmitted in each batch of the backup. @default 100
-   * @param options.source Name of the source database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE. @default 'main'
-   * @param options.target Name of the target database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE. @default 'main'
-   * @param options.progress Callback function that will be called with the number of pages copied and the total number of pages.
-   * @returns A promise that resolves when the backup is completed and rejects if an error occurs.
-   *
-   * @example
-   * // Basic backup
-   * await db.backup('./backup.db');
-   *
-   * @example
-   * // Backup with progress
-   * await db.backup('./backup.db', {
-   *   rate: 10,
-   *   progress: ({ totalPages, remainingPages }) => {
-   *     console.log(`Progress: ${totalPages - remainingPages}/${totalPages}`);
-   *   }
-   * });
-   */
-  backup(
-    path: string | Buffer | URL,
-    options?: {
-      rate?: number;
-      source?: string;
-      target?: string;
-      progress?: (info: { totalPages: number; remainingPages: number }) => void;
-    },
-  ): Promise<number>;
-
   /** Dispose of the database resources using the explicit resource management protocol. */
   [Symbol.dispose](): void;
 }

package/src/types/pragma-options.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for the pragma() method.
+ *
+ * @see https://sqlite.org/pragma.html
+ */
+export interface PragmaOptions {
+  /**
+   * When true, returns only the first column of the first row.
+   * This is useful for pragmas that return a single value.
+   *
+   * @default false
+   *
+   * @example
+   * ```typescript
+   * // Without simple: returns [{ cache_size: -16000 }]
+   * db.pragma('cache_size');
+   *
+   * // With simple: returns -16000
+   * db.pragma('cache_size', { simple: true });
+   * ```
+   */
+  readonly simple?: boolean;
+}

package/src/types/statement-sync-instance.ts

@@ -1,3 +1,39 @@
+/**
+ * Metadata about a column in a prepared statement's result set.
+ * Matches Node.js sqlite module's StatementColumnMetadata.
+ */
+export interface StatementColumnMetadata {
+  /**
+   * The unaliased name of the column in the origin table, or `null` if the
+   * column is the result of an expression or subquery.
+   * This property is the result of `sqlite3_column_origin_name()`.
+   */
+  column: string | null;
+  /**
+   * The unaliased name of the origin database, or `null` if the column is
+   * the result of an expression or subquery.
+   * This property is the result of `sqlite3_column_database_name()`.
+   */
+  database: string | null;
+  /**
+   * The name assigned to the column in the result set of a SELECT statement.
+   * This property is the result of `sqlite3_column_name()`.
+   */
+  name: string;
+  /**
+   * The unaliased name of the origin table, or `null` if the column is
+   * the result of an expression or subquery.
+   * This property is the result of `sqlite3_column_table_name()`.
+   */
+  table: string | null;
+  /**
+   * The declared data type of the column, or `null` if the column is
+   * the result of an expression or subquery.
+   * This property is the result of `sqlite3_column_decltype()`.
+   */
+  type: string | null;
+}
+
 /**
  * A prepared SQL statement that can be executed multiple times with different parameters.
  * This interface represents an instance of the StatementSync class.
@@ -7,8 +43,6 @@ export interface StatementSyncInstance {
   readonly sourceSQL: string;
   /** The expanded SQL string with bound parameters, if expandedSQL option was set. */
   readonly expandedSQL: string | undefined;
-  /** Whether this statement has been finalized. */
-  readonly finalized: boolean;
   /**
    * This method executes a prepared statement and returns an object.
    * @param parameters Optional named and anonymous parameters to bind to the statement.
@@ -59,15 +93,7 @@ export interface StatementSyncInstance {
   setReturnArrays(returnArrays: boolean): void;
   /**
    * Returns an array of objects, each representing a column in the statement's result set.
-   * Each object has a 'name' property for the column name and a 'type' property for the SQLite type.
-   * @returns Array of column metadata objects.
-   */
-  columns(): Array<{ name: string; type?: string }>;
-  /**
-   * Finalizes the prepared statement and releases its resources.
-   * Called automatically by Symbol.dispose.
+   * @returns Array of column metadata objects with name, column, database, table, and type.
    */
-  finalize(): void;
-  /** Dispose of the statement resources using the explicit resource management protocol. */
-  [Symbol.dispose](): void;
+  columns(): StatementColumnMetadata[];
 }

package/src/types/transaction.ts

@@ -0,0 +1,72 @@
+import type { DatabaseSyncInstance } from "./database-sync-instance";
+
+/**
+ * Transaction isolation modes supported by SQLite.
+ *
+ * @see https://sqlite.org/lang_transaction.html
+ */
+export type TransactionMode = "deferred" | "immediate" | "exclusive";
+
+/**
+ * A function wrapped in a transaction. When called, it automatically:
+ * - Begins a transaction (or savepoint if nested)
+ * - Executes the wrapped function
+ * - Commits on success, rolls back on error
+ *
+ * The function also has variants for different transaction modes accessible as
+ * properties (`.deferred`, `.immediate`, `.exclusive`).
+ *
+ * **Note:** Each variant is itself a `TransactionFunction` with circular
+ * references to all other variants. This matches better-sqlite3's behavior
+ * where you can chain variants like `txn.deferred.immediate()` - the last
+ * variant in the chain determines the actual transaction mode used.
+ *
+ * @example
+ * ```typescript
+ * const insertMany = db.transaction((items: Item[]) => {
+ *   for (const item of items) insert.run(item);
+ *   return items.length;
+ * });
+ *
+ * // Use default mode (DEFERRED)
+ * insertMany([{ id: 1 }, { id: 2 }]);
+ *
+ * // Use IMMEDIATE mode for write transactions
+ * insertMany.immediate([{ id: 3 }, { id: 4 }]);
+ *
+ * // Use EXCLUSIVE mode for exclusive access
+ * insertMany.exclusive([{ id: 5 }, { id: 6 }]);
+ * ```
+ */
+export interface TransactionFunction<F extends (...args: any[]) => any> {
+  /**
+   * Execute the wrapped function within a transaction using the default mode (DEFERRED).
+   */
+  (...args: Parameters<F>): ReturnType<F>;
+
+  /**
+   * Execute with DEFERRED transaction mode.
+   * The database lock is not acquired until the first read or write operation.
+   * This is the default SQLite behavior.
+   */
+  readonly deferred: TransactionFunction<F>;
+
+  /**
+   * Execute with IMMEDIATE transaction mode.
+   * Acquires a write lock immediately, blocking other writers.
+   * Recommended for transactions that will write to prevent SQLITE_BUSY errors.
+   */
+  readonly immediate: TransactionFunction<F>;
+
+  /**
+   * Execute with EXCLUSIVE transaction mode.
+   * Acquires an exclusive lock immediately, blocking all other connections.
+   * Use sparingly as it prevents all concurrent access.
+   */
+  readonly exclusive: TransactionFunction<F>;
+
+  /**
+   * The database connection this transaction function is bound to.
+   */
+  readonly database: DatabaseSyncInstance;
+}