feat: add session support for SQLite changesets

- Introduced Session class to manage SQLite changesets.
- Implemented methods for creating sessions, generating changesets, and patchsets.
- Added error handling for session lifecycle and database state.
- Enhanced DatabaseSync with methods to create sessions and apply changesets.
- Implemented tests for session functionality, including changeset generation and conflict resolution.

Author: mceachen

TODO.md

@@ -54,7 +54,7 @@ This document tracks the remaining tasks to complete the SQLite extraction from
   **MEDIUM PRIORITY - Advanced Features:**
 
   - [ ] **Backup functionality**: Complete `BackupJob` class and `backup()` method
-  - [ ] **SQLite sessions**: `createSession()`, `applyChangeset()` methods
+  - ✅ **SQLite sessions**: `createSession()`, `applyChangeset()` methods - Complete with full test coverage
   - [ ] **Enhanced location method**: `location(dbName?: string)` for attached databases
   - ✅ **Advanced parameter binding**: Bare named parameters (`{id: 1}` → `:id`)
 
@@ -85,7 +85,7 @@ This document tracks the remaining tasks to complete the SQLite extraction from
   - ✅ **Aggregate functions** - 10/10 tests passing (all functionality working)
   - ✅ Transaction persistence across sessions
   - ✅ Large dataset operations (optimized with transactions)
-  - [ ] SQLite sessions and changesets
+  - ✅ SQLite sessions and changesets - 21 comprehensive tests
   - [ ] Extension loading
   - [ ] Backup/restore operations
 - ✅ **Error handling tests**
@@ -403,13 +403,19 @@ scripts/
    - ✅ **Security model**: Two-step process (allowExtension + enableLoadExtension)
    - ✅ **Comprehensive tests**: 14 tests covering all security and API aspects
 
-6. **🚧 Advanced Features** (Next Priority)
+6. **✅ SQLite Sessions** (COMPLETED!)
+
+   - ✅ **SQLite sessions** (`createSession()`, `applyChangeset()`) - Complete with 21 tests
+   - ✅ **Session class** with changeset/patchset generation
+   - ✅ **Changeset application** with conflict and filter callbacks
+   - ✅ **Session constants** (SQLITE*CHANGESET*\*)
+
+7. **🚧 Advanced Features** (Next Priority)
 
-   - [ ] **SQLite sessions** (`createSession()`, `applyChangeset()`)
    - [ ] **Backup functionality** (`backup()` function)
    - [ ] **Enhanced location method**: `location(dbName?: string)` for attached databases
 
-7. **🚧 Performance & Compatibility** (Low Priority)
+8. **🚧 Performance & Compatibility** (Low Priority)
    - [ ] Benchmark against alternatives
    - [ ] Node.js compatibility verification
    - [ ] Memory leak testing
@@ -425,8 +431,8 @@ scripts/
 ## 🏆 **Success Metrics Achieved**
 
 - ✅ **Core SQLite operations working** (CREATE, INSERT, SELECT, UPDATE, DELETE)
-- ✅ **Advanced SQLite features working** (user functions, aggregates, and iterators all fully functional)
-- ✅ **127 tests passing** with comprehensive coverage across all features:
+- ✅ **Advanced SQLite features working** (user functions, aggregates, iterators, and sessions all fully functional)
+- ✅ **155 tests passing** with comprehensive coverage across all features:
   - ✅ 13 basic database tests
   - ✅ 13 configuration option tests
   - ✅ 8 user-defined function tests
@@ -437,6 +443,7 @@ scripts/
   - ✅ 17 Node.js compatibility tests
   - ✅ 7 double-quoted string literals tests
   - ✅ 14 extension loading tests
+  - ✅ 28 SQLite session tests (with changeset content verification!)
 - ✅ **All core data types supported** (INTEGER, REAL, TEXT, BLOB, NULL, BigInt)
 - ✅ **Error handling working** for invalid SQL and operations
 - ✅ **Memory management working** with proper cleanup and N-API references

src/binding.cpp

@@ -9,6 +9,7 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
   DatabaseSync::Init(env, exports);
   StatementSync::Init(env, exports);
   StatementSyncIterator::Init(env, exports);
+  Session::Init(env, exports);
 
   // Add SQLite constants
   Napi::Object constants = Napi::Object::New(env);
@@ -32,6 +33,18 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
   constants.Set("SQLITE_OPEN_SHAREDCACHE", Napi::Number::New(env, SQLITE_OPEN_SHAREDCACHE));
   constants.Set("SQLITE_OPEN_PRIVATECACHE", Napi::Number::New(env, SQLITE_OPEN_PRIVATECACHE));
   constants.Set("SQLITE_OPEN_WAL", Napi::Number::New(env, SQLITE_OPEN_WAL));
+  
+  // Changeset/session constants
+  constants.Set("SQLITE_CHANGESET_OMIT", Napi::Number::New(env, SQLITE_CHANGESET_OMIT));
+  constants.Set("SQLITE_CHANGESET_REPLACE", Napi::Number::New(env, SQLITE_CHANGESET_REPLACE));
+  constants.Set("SQLITE_CHANGESET_ABORT", Napi::Number::New(env, SQLITE_CHANGESET_ABORT));
+  
+  constants.Set("SQLITE_CHANGESET_DATA", Napi::Number::New(env, SQLITE_CHANGESET_DATA));
+  constants.Set("SQLITE_CHANGESET_NOTFOUND", Napi::Number::New(env, SQLITE_CHANGESET_NOTFOUND));
+  constants.Set("SQLITE_CHANGESET_CONFLICT", Napi::Number::New(env, SQLITE_CHANGESET_CONFLICT));
+  constants.Set("SQLITE_CHANGESET_CONSTRAINT", Napi::Number::New(env, SQLITE_CHANGESET_CONSTRAINT));
+  constants.Set("SQLITE_CHANGESET_FOREIGN_KEY", Napi::Number::New(env, SQLITE_CHANGESET_FOREIGN_KEY));
+  
   exports.Set("constants", constants);
 
   // TODO: Add backup function

src/index.ts

@@ -73,6 +73,45 @@ export interface AggregateOptions {
   readonly varargs?: boolean;
 }
 
+export interface SessionOptions {
+  /** The table to track changes for. If omitted, all tables are tracked. */
+  readonly table?: string;
+  /** The database name. @default "main" */
+  readonly db?: string;
+}
+
+export interface Session {
+  /**
+   * Generate a changeset containing all changes recorded by the session.
+   * @returns A Buffer containing the changeset data.
+   */
+  changeset(): Buffer;
+  /**
+   * Generate a patchset containing all changes recorded by the session.
+   * @returns A Buffer containing the patchset data.
+   */
+  patchset(): Buffer;
+  /**
+   * Close the session and release its resources.
+   */
+  close(): void;
+}
+
+export interface ChangesetApplyOptions {
+  /**
+   * Function called when a conflict is detected during changeset application.
+   * @param conflictType The type of conflict (SQLITE_CHANGESET_CONFLICT, etc.)
+   * @returns One of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_REPLACE, or SQLITE_CHANGESET_ABORT
+   */
+  readonly onConflict?: (conflictType: number) => number;
+  /**
+   * Function called to filter which tables to apply changes to.
+   * @param tableName The name of the table
+   * @returns true to include the table, false to skip it
+   */
+  readonly filter?: (tableName: string) => boolean;
+}
+
 export interface Database {
   readonly location: string;
   readonly isOpen: boolean;
@@ -103,8 +142,19 @@ export interface Database {
    * @param options Configuration object containing step function and other settings.
    */
   aggregate(name: string, options: AggregateOptions): void;
-  createSession(table?: string): any;
-  applyChangeset(changeset: Uint8Array, options?: any): void;
+  /**
+   * Create a new session to record database changes.
+   * @param options Optional configuration for the session.
+   * @returns A Session object for recording changes.
+   */
+  createSession(options?: SessionOptions): Session;
+  /**
+   * 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;
   enableLoadExtension(enable: boolean): void;
   loadExtension(path: string, entryPoint?: string): void;
 
@@ -121,10 +171,20 @@ export interface SqliteModule {
     sql: string,
     options?: StatementOptions,
   ) => PreparedStatement;
+  Session: new () => Session;
   constants: {
     SQLITE_OPEN_READONLY: number;
     SQLITE_OPEN_READWRITE: number;
     SQLITE_OPEN_CREATE: number;
+    // Changeset constants
+    SQLITE_CHANGESET_OMIT: number;
+    SQLITE_CHANGESET_REPLACE: number;
+    SQLITE_CHANGESET_ABORT: number;
+    SQLITE_CHANGESET_DATA: number;
+    SQLITE_CHANGESET_NOTFOUND: number;
+    SQLITE_CHANGESET_CONFLICT: number;
+    SQLITE_CHANGESET_CONSTRAINT: number;
+    SQLITE_CHANGESET_FOREIGN_KEY: number;
     // ... more constants
   };
   backup(
@@ -161,6 +221,7 @@ export const DatabaseSync =
   binding.DatabaseSync as SqliteModule["DatabaseSync"];
 export const StatementSync =
   binding.StatementSync as SqliteModule["StatementSync"];
+export const Session = binding.Session as SqliteModule["Session"];
 export const constants = binding.constants as SqliteModule["constants"];
 export const backup = binding.backup as SqliteModule["backup"];