fix(docs): update documentation for changeset application and backup return types; enhance clarity on SQLite threading modes and API references

Author: mceachen

doc/advanced-patterns.md

@@ -318,8 +318,8 @@ session.close();
 
 // Apply changes to another database
 const replicaDb = new DatabaseSync("replica.db");
-const result = replicaDb.applyChangeset(changeset);
-console.log(`Applied ${result.changesApplied} changes`);
+const success = replicaDb.applyChangeset(changeset);
+console.log(`Changeset applied: ${success}`);
 
 db.close();
 replicaDb.close();
@@ -345,15 +345,17 @@ function syncDatabases(primaryPath, replicaPath) {
   session.close();
 
   // Apply to replica with conflict handling
-  const result = replica.applyChangeset(changeset, {
-    onConflict: (conflict) => {
-      console.log(`Conflict detected:`);
-      console.log(`  Table: ${conflict.table}`);
-      console.log(`  Type: ${conflict.type}`);
-      console.log(`  Old value: ${JSON.stringify(conflict.oldRow)}`);
-      console.log(`  New value: ${JSON.stringify(conflict.newRow)}`);
-
-      // Conflict resolution strategies:
+  const success = replica.applyChangeset(changeset, {
+    onConflict: (conflictType) => {
+      // conflictType is a number indicating the type of conflict:
+      // - SQLITE_CHANGESET_DATA: Row exists but values differ
+      // - SQLITE_CHANGESET_NOTFOUND: Row not found in target
+      // - SQLITE_CHANGESET_CONFLICT: Primary key conflict
+      // - SQLITE_CHANGESET_CONSTRAINT: Constraint violation
+      // - SQLITE_CHANGESET_FOREIGN_KEY: Foreign key violation
+      console.log(`Conflict detected, type: ${conflictType}`);
+
+      // Conflict resolution strategies (return one of these):
       // - SQLITE_CHANGESET_OMIT: Skip this change
       // - SQLITE_CHANGESET_REPLACE: Apply the change anyway
       // - SQLITE_CHANGESET_ABORT: Stop applying changes
@@ -362,108 +364,55 @@ function syncDatabases(primaryPath, replicaPath) {
     },
   });
 
-  console.log(`Sync complete: ${result.changesApplied} changes applied`);
+  console.log(`Sync complete: ${success ? "succeeded" : "aborted"}`);
 
   primary.close();
   replica.close();
 }
 ```
 
-### Undo/Redo Implementation
+### Change Tracking Example
 
-```javascript
-class UndoRedoManager {
-  constructor(db) {
-    this.db = db;
-    this.undoStack = [];
-    this.redoStack = [];
-    this.session = null;
-  }
-
-  startTracking() {
-    if (this.session) {
-      this.endTracking();
-    }
-    this.session = this.db.createSession();
-  }
-
-  endTracking(description) {
-    if (!this.session) return;
-
-    const changeset = this.session.changeset();
-    if (changeset.length > 0) {
-      this.undoStack.push({
-        description,
-        changeset,
-        inverse: this.session.changesetInvert(changeset),
-      });
-      this.redoStack = []; // Clear redo stack on new change
-    }
-
-    this.session.close();
-    this.session = null;
-  }
-
-  undo() {
-    const entry = this.undoStack.pop();
-    if (!entry) return false;
-
-    // Apply inverse changeset
-    this.db.applyChangeset(entry.inverse);
-
-    // Move to redo stack
-    this.redoStack.push(entry);
-
-    return true;
-  }
+Sessions track changes that can be applied to other databases for synchronization:
 
-  redo() {
-    const entry = this.redoStack.pop();
-    if (!entry) return false;
-
-    // Apply original changeset
-    this.db.applyChangeset(entry.changeset);
-
-    // Move back to undo stack
-    this.undoStack.push(entry);
-
-    return true;
-  }
+```javascript
+const { DatabaseSync } = require("@photostructure/sqlite");
 
-  getHistory() {
-    return {
-      undo: this.undoStack.map((e) => e.description),
-      redo: this.redoStack.map((e) => e.description),
-    };
-  }
-}
+const sourceDb = new DatabaseSync("source.db");
+const targetDb = new DatabaseSync("target.db");
 
-// Usage
-const db = new DatabaseSync("document.db");
-const undoRedo = new UndoRedoManager(db);
+// Create a session to track changes on the source database
+const session = sourceDb.createSession({ table: "documents" });
 
-// Track a change
-undoRedo.startTracking();
-db.prepare("UPDATE document SET content = ? WHERE id = ?").run(
-  "New content",
+// Make changes to the source
+sourceDb.prepare("UPDATE documents SET content = ? WHERE id = ?").run(
+  "Updated content",
   1,
 );
-undoRedo.endTracking("Update document content");
+sourceDb.prepare("INSERT INTO documents (content) VALUES (?)").run(
+  "New document",
+);
+
+// Get the changeset
+const changeset = session.changeset();
+session.close();
 
-// Track another change
-undoRedo.startTracking();
-db.prepare("INSERT INTO document (content) VALUES (?)").run("Another document");
-undoRedo.endTracking("Add new document");
+// Apply changes to target database
+const success = targetDb.applyChangeset(changeset, {
+  onConflict: (conflictType) => {
+    // Handle conflicts as needed
+    return constants.SQLITE_CHANGESET_REPLACE;
+  },
+});
 
-// Undo last change
-undoRedo.undo();
-console.log("Undid: Add new document");
+console.log(`Sync ${success ? "succeeded" : "failed"}`);
 
-// Redo
-undoRedo.redo();
-console.log("Redid: Add new document");
+sourceDb.close();
+targetDb.close();
 ```
 
+> **Note:** The `changesetInvert()` function for creating inverse changesets is not currently exposed in the JavaScript API. For undo/redo functionality, consider storing the original data before modifications or using SQLite triggers to maintain a history table.
+
 ## Performance Optimization
 
 ### URI Configuration for Performance

doc/api-reference.md

@@ -212,10 +212,10 @@ db.aggregate("custom_avg", {
 #### backup()
 
 ```typescript
-backup(destination: string, options?: BackupOptions): Promise<void>
+backup(destination: string, options?: BackupOptions): Promise<number>
 ```
 
-Creates a backup of the database.
+Creates a backup of the database. Returns the total number of pages backed up.
 
 **Options:**
 
@@ -271,15 +271,26 @@ session.close();
 #### applyChangeset()
 
 ```typescript
-applyChangeset(changeset: Uint8Array, options?: ChangesetOptions): ApplyResult
+applyChangeset(changeset: Buffer, options?: ChangesetApplyOptions): boolean
 ```
 
-Applies a changeset to the database.
+Applies a changeset to the database. Returns `true` if successful, `false` if aborted.
+
+**Options:**
+
+```typescript
+interface ChangesetApplyOptions {
+  onConflict?: (conflictType: number) => number; // Returns resolution constant
+  filter?: (tableName: string) => boolean; // Filter which tables to apply
+}
+```
 
 ```javascript
-const result = db.applyChangeset(changeset, {
-  onConflict: (conflict) => {
-    console.log(`Conflict on table ${conflict.table}`);
+const success = db.applyChangeset(changeset, {
+  onConflict: (conflictType) => {
+    // conflictType is one of: SQLITE_CHANGESET_DATA, SQLITE_CHANGESET_NOTFOUND,
+    // SQLITE_CHANGESET_CONFLICT, SQLITE_CHANGESET_CONSTRAINT, SQLITE_CHANGESET_FOREIGN_KEY
+    console.log(`Conflict type: ${conflictType}`);
     return constants.SQLITE_CHANGESET_REPLACE;
   },
 });
@@ -314,16 +325,17 @@ db.loadExtension("./custom.so", "sqlite3_custom_init");
 
 ### Properties
 
-#### location
+#### location()
 
 ```typescript
-readonly location: string
+location(dbName?: string): string | null
 ```
 
-The path or URI of the database file.
+Returns the file path of the database, or `null` for in-memory databases.
 
 ```javascript
-console.log(db.location); // "myapp.db"
+console.log(db.location()); // "myapp.db"
+console.log(db.location("main")); // "myapp.db"
 ```
 
 ## StatementSync

doc/extending-sqlite.md

@@ -311,20 +311,21 @@ const userPrefs = db
 
 ### Window Functions
 
-Aggregate functions can be used as window functions in SQLite:
+Aggregate functions can be used as window functions in SQLite. For full window function support with framed windows (using `OVER (ORDER BY ...)`), you should provide an `inverse` function that reverses the effect of `step`:
 
 ```javascript
-// Cumulative sum aggregate
+// Cumulative sum aggregate with inverse for window function support
 db.aggregate("cumsum", {
   start: 0,
   step: (sum, value) => sum + (value || 0),
+  inverse: (sum, value) => sum - (value || 0), // Required for window functions
 });
 
 // Use as window function
 const results = db
   .prepare(
     `
-  SELECT 
+  SELECT
     date,
     amount,
     cumsum(amount) OVER (ORDER BY date) as running_total
@@ -335,6 +336,8 @@ const results = db
   .all(accountId);
 ```
 
+> **Note:** Without the `inverse` function, the aggregate will still work but may be less efficient for certain window frame types.
+
 ## Loading Extensions
 
 SQLite supports loadable extensions to add functionality at runtime.

doc/features.md

@@ -14,7 +14,7 @@ Comprehensive list of features and capabilities in @photostructure/sqlite.
 
 ## SQLite Version
 
-This package includes SQLite 3.50.4 with extensive compile-time options enabled. For complete build flag documentation, comparison with Node.js, and customization options, see [Build Flags & Configuration](./build-flags.md).
+This package includes SQLite 3.51.1 with extensive compile-time options enabled. For complete build flag documentation, comparison with Node.js, and customization options, see [Build Flags & Configuration](./build-flags.md).
 
 ## Enabled SQLite Features
 
@@ -36,8 +36,7 @@ This package includes SQLite 3.50.4 with extensive compile-time options enabled.
 - `SQLITE_ENABLE_RTREE` - R\*Tree spatial indexing
 - `SQLITE_ENABLE_GEOPOLY` - GeoJSON and polygon functions
 - `SQLITE_ENABLE_MATH_FUNCTIONS` - Math functions (sin, cos, sqrt, etc.)
-- `SQLITE_ENABLE_REGEXP` - REGEXP operator support
-- `SQLITE_ENABLE_SOUNDEX` - Soundex algorithm
+- `SQLITE_SOUNDEX` - Soundex algorithm
 
 ### Session Extension
 

doc/internal/worker-implementation.md

@@ -22,10 +22,10 @@ Worker thread support is **fully implemented and working** in @photostructure/sq
 SQLite supports three threading modes:
 
 - **Single-thread** (`SQLITE_THREADSAFE=0`): No thread safety, one thread only
-- **Multi-thread** (`SQLITE_THREADSAFE=2`): Multiple threads, separate connections per thread ✅ **CURRENT**
-- **Serialized** (`SQLITE_THREADSAFE=1`): Full thread safety with mutexes (default)
+- **Multi-thread** (`SQLITE_THREADSAFE=2`): Multiple threads, separate connections per thread
+- **Serialized** (`SQLITE_THREADSAFE=1`): Full thread safety with mutexes (default) ✅ **CURRENT**
 
-**Current Configuration:** Using `SQLITE_THREADSAFE=2` (multi-thread mode) - the correct choice for worker threads where each thread gets its own database connection.
+**Current Configuration:** Using the default `SQLITE_THREADSAFE=1` (serialized mode). This provides full thread safety with mutex protection, which is safe for worker threads where each thread creates its own database connection.
 
 ### Implemented Components
 

doc/library-comparison.md

@@ -36,7 +36,7 @@ When choosing a SQLite library for Node.js, you have several excellent options.
 
 ### 🏷️ [`node:sqlite`](https://nodejs.org/docs/latest/api/sqlite.html) — Node.js Built-in Module
 
-_The official SQLite module included with Node.js 25.0.0+ (experimental)_
+_The official SQLite module included with Node.js 22.5.0+ (experimental)_
 
 **✨ Pros:**
 
@@ -47,9 +47,8 @@ _The official SQLite module included with Node.js 25.0.0+ (experimental)_
 
 **⚠️ Cons:**
 
-- **Experimental status** — Not yet stable for production use
-- **Requires Node.js 25.0.0+** — Won't work on older versions
-- **Flag required** — Must use `--experimental-sqlite` to enable
+- **Experimental status** — Not yet stable for production use (Stability: 1.1 - Active development)
+- **Requires Node.js 22.5.0+** — Won't work on older versions
 - **API may change** — Breaking changes possible before stable release
 - **Limited real-world usage** — Few production deployments to learn from
 
@@ -108,8 +107,8 @@ _The original asynchronous SQLite binding for Node.js_
 | Feature                  | @photostructure/sqlite | node:sqlite   | better-sqlite3   | sqlite3       |
 | ------------------------ | ---------------------- | ------------- | ---------------- | ------------- |
 | **API Compatibility**    | node:sqlite            | -             | Custom           | Custom        |
-| **Min Node.js Version**  | 20.0.0                 | 25.0.0        | 14.0.0           | 10.0.0        |
-| **Experimental Flag**    | ❌ Not needed          | ✅ Required   | ❌ Not needed    | ❌ Not needed |
+| **Min Node.js Version**  | 20.0.0                 | 22.5.0        | 14.0.0           | 10.0.0        |
+| **Experimental Flag**    | ❌ Not needed          | ❌ Not needed | ❌ Not needed    | ❌ Not needed |
 | **Synchronous API**      | ✅                     | ✅            | ✅               | ❌            |
 | **Asynchronous API**     | ❌                     | ❌            | ❌               | ✅            |
 | **TypeScript Types**     | ✅ Built-in            | ✅ Built-in   | ✅ Via @types    | ✅ Via @types |

doc/migrating-from-better-sqlite3.md

@@ -161,13 +161,10 @@ const result = db.prepare("PRAGMA cache_size").get();
 
 ### Features Only in better-sqlite3
 
-- ❌ `.transaction()` helper method
-- ❌ `.pragma()` convenience method
-- ❌ `.backup()` method (different API)
-- ❌ Virtual table support
-- ❌ `.loadExtension()` method
+- ❌ `.transaction()` helper method (use manual `BEGIN`/`COMMIT`/`ROLLBACK`)
+- ❌ `.pragma()` convenience method (use `db.exec("PRAGMA ...")` or `db.prepare("PRAGMA ...").get()`)
 - ❌ `.serialize()` method
-- ❌ `.defaultSafeIntegers()` method
+- ❌ `.defaultSafeIntegers()` method (use `stmt.setReadBigInts()` instead)
 - ❌ `.unsafeMode()` method
 
 ### Features Only in @photostructure/sqlite

doc/migrating-from-node-sqlite.md

@@ -7,7 +7,7 @@
 Simply change your import statement:
 
 ```javascript
-// Before: Using Node.js built-in SQLite (requires Node.js 25.0.0+ and --experimental-sqlite flag)
+// Before: Using Node.js built-in SQLite (available in Node.js 22.5.0+)
 const { DatabaseSync } = require("node:sqlite");
 
 // After: Using @photostructure/sqlite (works on Node.js 20+ without any flags)
@@ -40,7 +40,7 @@ node app.js
 
 ### Broader Node.js Version Support
 
-- **node:sqlite**: Requires Node.js 25.0.0 or higher
+- **node:sqlite**: Available in Node.js 22.5.0+ (experimental status)
 - **@photostructure/sqlite**: Works with Node.js 20.0.0 or higher
 
 ### Same API, Same Behavior

doc/reference/sqlite-api-advanced.md

@@ -1,5 +1,7 @@
 # SQLite Advanced Features API Reference
 
+> **⚠️ Important Note:** This documentation describes the **underlying SQLite C library API**, not the JavaScript API exposed by `@photostructure/sqlite`. Most functions documented here (like `sqlite3_blob_open()`, `sqlite3_wal_checkpoint_v2()`) are **NOT directly callable from JavaScript**. Some features like backup and sessions are exposed through the JavaScript API - see [API Reference](../api-reference.md) and [Advanced Patterns](../advanced-patterns.md).
+
 This document covers SQLite's advanced APIs including backup operations, blob I/O, sessions, and threading features. This is a machine-generated summary of documentation found on sqlite.org used as a reference during development.
 
 ## Table of Contents

doc/reference/sqlite-api-core.md

@@ -1,5 +1,7 @@
 # SQLite Core API Reference
 
+> **⚠️ Important Note:** This documentation describes the **underlying SQLite C library API**, not the JavaScript API exposed by `@photostructure/sqlite`. These C functions are **NOT directly callable from JavaScript**. For the JavaScript API, see [API Reference](../api-reference.md).
+
 This document covers the fundamental SQLite C/C++ APIs for database connections, basic operations, and error handling. This is a machine-generated summary of documentation found on sqlite.org used as a reference during development.
 
 ## Table of Contents