feat(backup): implement standalone backup function with options and tests

Author: mceachen

doc/api-reference.md

@@ -4,12 +4,67 @@ Complete API documentation for @photostructure/sqlite. This package provides 100
 
 ## Table of Contents
 
+- [Module Exports](#module-exports)
 - [DatabaseSync](#databasesync)
 - [StatementSync](#statementsync)
 - [Types and Interfaces](#types-and-interfaces)
 - [Constants](#constants)
 - [Error Handling](#error-handling)
 
+## Module Exports
+
+The module exports the following items that match `node:sqlite`:
+
+```typescript
+import {
+  DatabaseSync, // Main database class
+  StatementSync, // Prepared statement class
+  Session, // Session class for changesets
+  backup, // Standalone backup function
+  constants, // SQLite constants
+} from "@photostructure/sqlite";
+```
+
+### backup()
+
+```typescript
+backup(
+  sourceDb: DatabaseSync,
+  destination: string | Buffer | URL,
+  options?: BackupOptions
+): Promise<number>
+```
+
+Standalone function to create a backup of a database. This function is equivalent to calling `db.backup()` on a database instance, but allows passing the source database as a parameter.
+
+**Parameters:**
+
+- `sourceDb` - The database instance to back up
+- `destination` - Path to the backup file (string, Buffer, or file: URL)
+- `options` - Optional backup configuration
+
+**Returns:** A Promise that resolves to the total number of pages backed up.
+
+```javascript
+import { DatabaseSync, backup } from "@photostructure/sqlite";
+
+const db = new DatabaseSync("source.db");
+
+// Using standalone function
+await backup(db, "backup.db");
+
+// Equivalent to:
+await db.backup("backup.db");
+
+// With options
+await backup(db, "backup.db", {
+  rate: 10,
+  progress: ({ totalPages, remainingPages }) => {
+    console.log(`${totalPages - remainingPages}/${totalPages} pages copied`);
+  },
+});
+```
+
 ## DatabaseSync
 
 The main database class for synchronous SQLite operations.
@@ -37,7 +92,7 @@ interface DatabaseSyncOptions {
   readOnly?: boolean; // Open in read-only mode (default: false)
   enableForeignKeyConstraints?: boolean; // Enable foreign keys (default: true)
   enableDoubleQuotedStringLiterals?: boolean; // Allow double-quoted strings (default: false)
-  timeout?: number; // Busy timeout in ms (default: 5000)
+  timeout?: number; // Busy timeout in ms (default: 0)
   allowExtension?: boolean; // Allow loading extensions (default: false)
 }
 ```
@@ -222,6 +277,7 @@ Creates a backup of the database. Returns the total number of pages backed up.
 ```typescript
 interface BackupOptions {
   source?: string; // Source database name (default: 'main')
+  target?: string; // Target database name (default: 'main')
   rate?: number; // Pages per iteration (default: 100)
   progress?: (info: { totalPages: number; remainingPages: number }) => void;
 }

src/binding.cpp

@@ -200,7 +200,54 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
 
   exports.Set("constants", constants);
 
-  // TODO: Add backup function
+  // Add standalone backup() function (Node.js API compatibility)
+  // Signature: backup(sourceDb, destination, options?) -> Promise
+  Napi::Function backupFunc = Napi::Function::New(
+      env,
+      [](const Napi::CallbackInfo &info) -> Napi::Value {
+        Napi::Env env = info.Env();
+
+        // Validate and unwrap DatabaseSync instance
+        DatabaseSync *db = nullptr;
+        if (info.Length() >= 1 && info[0].IsObject()) {
+          try {
+            db = DatabaseSync::Unwrap(info[0].As<Napi::Object>());
+          } catch (...) {
+            // Fall through to error below
+          }
+        }
+        if (db == nullptr) {
+          Napi::TypeError::New(
+              env, "The \"sourceDb\" argument must be a DatabaseSync object")
+              .ThrowAsJavaScriptException();
+          return env.Undefined();
+        }
+
+        // Validate destination path is provided
+        if (info.Length() < 2) {
+          Napi::TypeError::New(env, "The \"destination\" argument is required")
+              .ThrowAsJavaScriptException();
+          return env.Undefined();
+        }
+
+        // Delegate to instance method: db.backup(destination, options?)
+        std::vector<napi_value> args;
+        for (size_t i = 1; i < info.Length(); i++) {
+          args.push_back(info[i]);
+        }
+        Napi::Function backupMethod =
+            db->Value().Get("backup").As<Napi::Function>();
+        return backupMethod.Call(db->Value(), args);
+      },
+      "backup");
+
+  // Set function name and length properties (Node.js compatibility)
+  backupFunc.DefineProperty(Napi::PropertyDescriptor::Value(
+      "name", Napi::String::New(env, "backup"), napi_enumerable));
+  backupFunc.DefineProperty(Napi::PropertyDescriptor::Value(
+      "length", Napi::Number::New(env, 2), napi_enumerable));
+
+  exports.Set("backup", backupFunc);
 
   return exports;
 }

src/index.ts

@@ -204,5 +204,52 @@ export { SQLTagStore };
  */
 export const constants: SqliteConstants = binding.constants;
 
+/**
+ * Options for the backup() function.
+ */
+export interface BackupOptions {
+  /** Number of pages to be transmitted in each batch of the backup. @default 100 */
+  rate?: number;
+  /** Name of the source database. Can be 'main' or any attached database. @default 'main' */
+  source?: string;
+  /** Name of the target database. Can be 'main' or any attached database. @default 'main' */
+  target?: string;
+  /** Callback function that will be called with progress information. */
+  progress?: (info: { totalPages: number; remainingPages: number }) => void;
+}
+
+/**
+ * Standalone function to make a backup of a database.
+ *
+ * This function matches the Node.js `node:sqlite` module API which exports
+ * `backup()` as a standalone function in addition to the `db.backup()` method.
+ *
+ * @param sourceDb The database to backup from.
+ * @param destination The path where the backup will be created.
+ * @param options Optional configuration for the backup operation.
+ * @returns A promise that resolves when the backup is completed.
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseSync, backup } from '@photostructure/sqlite';
+ *
+ * const db = new DatabaseSync('./source.db');
+ * await backup(db, './backup.db');
+ *
+ * // With options
+ * await backup(db, './backup.db', {
+ *   rate: 10,
+ *   progress: ({ totalPages, remainingPages }) => {
+ *     console.log(`Progress: ${totalPages - remainingPages}/${totalPages}`);
+ *   }
+ * });
+ * ```
+ */
+export const backup: (
+  sourceDb: DatabaseSyncInstance,
+  destination: string | Buffer | URL,
+  options?: BackupOptions,
+) => Promise<number> = binding.backup;
+
 // Default export for CommonJS compatibility
 export default binding as SqliteModule;

src/sqlite_impl.cpp

@@ -2563,17 +2563,17 @@ std::set<BackupJob *> BackupJob::active_job_instances_;
 
 // BackupJob Implementation
 BackupJob::BackupJob(Napi::Env env, DatabaseSync *source,
-                     const std::string &destination_path,
-                     const std::string &source_db, const std::string &dest_db,
-                     int pages, Napi::Function progress_func,
+                     std::string destination_path, std::string source_db,
+                     std::string dest_db, int pages,
+                     Napi::Function progress_func,
                      Napi::Promise::Deferred deferred)
     : Napi::AsyncProgressWorker<BackupProgress>(
           !progress_func.IsEmpty() && !progress_func.IsUndefined()
               ? progress_func
               : Napi::Function::New(env, [](const Napi::CallbackInfo &) {})),
-      source_(source), destination_path_(destination_path),
-      source_db_(source_db), dest_db_(dest_db), pages_(pages),
-      deferred_(deferred) {
+      source_(source), destination_path_(std::move(destination_path)),
+      source_db_(std::move(source_db)), dest_db_(std::move(dest_db)),
+      pages_(pages), deferred_(deferred) {
   if (!progress_func.IsEmpty() && !progress_func.IsUndefined()) {
     progress_func_ = Napi::Reference<Napi::Function>::New(progress_func);
   }
@@ -2822,8 +2822,9 @@ Napi::Value DatabaseSync::Backup(const Napi::CallbackInfo &info) {
   }
 
   // Create and schedule backup job
-  BackupJob *job = new BackupJob(env, this, destination_path.value(), source_db,
-                                 target_db, rate, progress_func, deferred);
+  BackupJob *job = new BackupJob(env, this, std::move(destination_path).value(),
+                                 std::move(source_db), std::move(target_db),
+                                 rate, progress_func, deferred);
 
   // Queue the async work - AsyncWorker will delete itself when complete
   job->Queue();

src/sqlite_impl.h

@@ -351,10 +351,9 @@ struct BackupProgress {
 // Backup job for asynchronous database backup
 class BackupJob : public Napi::AsyncProgressWorker<BackupProgress> {
 public:
-  BackupJob(Napi::Env env, DatabaseSync *source,
-            const std::string &destination_path, const std::string &source_db,
-            const std::string &dest_db, int pages, Napi::Function progress_func,
-            Napi::Promise::Deferred deferred);
+  BackupJob(Napi::Env env, DatabaseSync *source, std::string destination_path,
+            std::string source_db, std::string dest_db, int pages,
+            Napi::Function progress_func, Napi::Promise::Deferred deferred);
   ~BackupJob();
 
   void Execute(const ExecutionProgress &progress) override;

src/types/database-sync-options.ts

@@ -24,7 +24,7 @@ export interface DatabaseSyncOptions {
   readonly enableDoubleQuotedStringLiterals?: boolean;
   /**
    * Sets the busy timeout in milliseconds.
-   * @default 5000
+   * @default 0
    */
   readonly timeout?: number;
   /** If true, enables loading of SQLite extensions. @default false */

test/api-compatibility.test.ts

@@ -49,6 +49,9 @@ const _hasDatabaseSync: typeof OurSqlite.DatabaseSync = OurSqlite.DatabaseSync;
 const _hasStatementSync: typeof OurSqlite.StatementSync =
   OurSqlite.StatementSync;
 
+// Check that standalone backup function is exported
+const _hasBackup: typeof OurSqlite.backup = OurSqlite.backup;
+
 // Check that our interfaces correspond to node:sqlite interfaces
 // Note: We use different names but should have compatible structure
 
@@ -309,6 +312,27 @@ function _checkSessionClass() {
   }
 }
 
+// Check standalone backup function signature
+function _checkBackupFunction() {
+  // The standalone backup function should match node:sqlite's export
+  const _backup: (
+    sourceDb: InstanceType<typeof OurSqlite.DatabaseSync>,
+    destination: string | Buffer | URL,
+    options?: OurSqlite.BackupOptions,
+  ) => Promise<number> = OurSqlite.backup;
+
+  // Verify our BackupOptions type has the right shape
+  const _opts: OurSqlite.BackupOptions = {
+    rate: 100,
+    source: "main",
+    target: "main",
+    progress: ({ totalPages, remainingPages }) => {
+      const _t: number = totalPages;
+      const _r: number = remainingPages;
+    },
+  };
+}
+
 // Check constructor signatures
 function _checkConstructorSignatures() {
   // DatabaseSync constructors
@@ -399,6 +423,27 @@ describe("API Compatibility", () => {
       expect(Object.keys(OurSqlite.constants).length).toBe(65);
     });
   });
+
+  describe("standalone backup() function compatibility", () => {
+    it("exports backup as a function", () => {
+      expect(typeof OurSqlite.backup).toBe("function");
+    });
+
+    it("backup has correct name property", () => {
+      expect(OurSqlite.backup.name).toBe("backup");
+    });
+
+    it("backup has correct length property (2 parameters)", () => {
+      expect(OurSqlite.backup.length).toBe(2);
+    });
+
+    it("backup matches node:sqlite export", () => {
+      // Verify our backup function matches node:sqlite's backup
+      expect(typeof NodeSqlite.backup).toBe("function");
+      expect(OurSqlite.backup.name).toBe(NodeSqlite.backup.name);
+      expect(OurSqlite.backup.length).toBe(NodeSqlite.backup.length);
+    });
+  });
 });
 
 export {}; // Make this a module