Demo and Docs cleanup

Author: stevensJourney

Demo/GRDB Demo/GRDB Demo.xcodeproj/project.pbxproj

@@ -41,6 +41,16 @@
 			name = "Embed Frameworks";
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		BEED7BE72E9007A5007C187A /* Embed Watch Content */ = {
+			isa = PBXCopyFilesBuildPhase;
+			buildActionMask = 2147483647;
+			dstPath = "$(CONTENTS_FOLDER_PATH)/Watch";
+			dstSubfolderSpec = 16;
+			files = (
+			);
+			name = "Embed Watch Content";
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXCopyFilesBuildPhase section */
 
 /* Begin PBXFileReference section */
@@ -135,6 +145,7 @@
 				BE1EABA22E7B075D00D0A0A7 /* Frameworks */,
 				BE1EABA32E7B075D00D0A0A7 /* Resources */,
 				BE1EABEE2E7C26DD00D0A0A7 /* Embed Frameworks */,
+				BEED7BE72E9007A5007C187A /* Embed Watch Content */,
 			);
 			buildRules = (
 			);

Demo/GRDB Demo/GRDB Demo/GRDB_DemoApp.swift

@@ -4,7 +4,6 @@ import PowerSync
 import PowerSyncGRDB
 import SwiftUI
 
-@Observable
 class Databases {
     let grdb: DatabasePool
     let powerSync: PowerSyncDatabaseProtocol
@@ -37,23 +36,25 @@ func openDatabase()
         schema: schema
     )
 
-    guard let grdb = try? DatabasePool(
-        path: dbUrl.path,
-        configuration: config
-    ) else {
-        fatalError("Could not open database")
-    }
+    do {
+        let grdb = try DatabasePool(
+            path: dbUrl.path,
+            configuration: config
+        )
 
-    let powerSync = openPowerSyncWithGRDB(
-        pool: grdb,
-        schema: schema,
-        identifier: "test"
-    )
+        let powerSync = openPowerSyncWithGRDB(
+            pool: grdb,
+            schema: schema,
+            identifier: "test.sqlite"
+        )
 
-    return Databases(
-        grdb: grdb,
-        powerSync: powerSync
-    )
+        return Databases(
+            grdb: grdb,
+            powerSync: powerSync
+        )
+    } catch {
+        fatalError("Could not open database: \(error)")
+    }
 }
 
 @main

Sources/PowerSync/Kotlin/KotlinPowerSyncDatabaseImpl.swift

@@ -67,7 +67,7 @@ final class KotlinPowerSyncDatabaseImpl: PowerSyncDatabaseProtocol,
             batch: base
         )
     }
-    
+
     func getCrudTransactions() -> any CrudTransactions {
         return KotlinCrudTransactions(db: kotlinDatabase)
     }
@@ -388,7 +388,7 @@ final class KotlinPowerSyncDatabaseImpl: PowerSyncDatabaseProtocol,
     }
 }
 
-func openKotlinDBWithFactory(
+func openKotlinDBDefault(
     schema: Schema,
     dbFilename: String,
     logger: DatabaseLogger

Sources/PowerSync/PowerSyncDatabase.swift

@@ -14,13 +14,28 @@ public func PowerSyncDatabase(
     dbFilename: String = DEFAULT_DB_FILENAME,
     logger: (any LoggerProtocol) = DefaultLogger()
 ) -> PowerSyncDatabaseProtocol {
-    return openKotlinDBWithFactory(
+    return openKotlinDBDefault(
         schema: schema,
         dbFilename: dbFilename,
         logger: DatabaseLogger(logger)
     )
 }
 
+/// Opens a PowerSync database using an existing SQLite connection pool.
+///
+/// - Parameters:
+///   - schema: The database schema describing the tables, indexes and other
+///     structure required by PowerSync.
+///   - pool: An active `SQLiteConnectionPoolProtocol` that provides connections
+///     to the underlying SQLite database. The pool must remain valid for the
+///     lifetime of the returned database instance.
+///   - identifier: A unique identifier for this database instance. This is
+///     typically used to isolate multiple database
+///     instances in the same process.
+///   - logger: Optional logging implementation. Defaults to `DefaultLogger()`.
+///
+/// - Returns: A `PowerSyncDatabaseProtocol` that wraps the opened database and
+///   exposes PowerSync functionality backed by the provided connection pool.
 public func OpenedPowerSyncDatabase(
     schema: Schema,
     pool: any SQLiteConnectionPoolProtocol,

Sources/PowerSync/Utils/withSession.swift

@@ -5,40 +5,50 @@ public struct WithSessionResult<ResultType: Sendable>: Sendable {
     public let affectedTables: Set<String>
 }
 
-/// Executes an action within a SQLite database connection session and handles its result.
+/// Executes an action within a SQLite database connection session and
+/// returns a `WithSessionResult` containing the action result and the set of
+/// tables that were affected during the session.
 ///
-/// The Raw SQLite connection is only available in some niche scenarios.
+/// The raw SQLite connection is only available in some niche scenarios. This helper is
+/// intended for internal use.
 ///
-/// - Executes the provided action in a SQLite session
-/// - Handles success/failure results
-/// - Tracks table updates during execution
-/// - Provides type-safe result handling
+/// - The provided `action` is executed inside a database session.
+/// - Any success or failure from the `action` is captured in
+///   `WithSessionResult.blockResult`.
+/// - The set of updated table names is returned in
+///   `WithSessionResult.affectedTables`.
 ///
 /// Example usage:
 /// ```swift
-/// try withSession(db: database) {
-///     return try someOperation()
-/// } onComplete: { result, updates in
-///     switch result {
-///     case .success(let value):
-///         print("Operation succeeded with: \(value)")
-///     case .failure(let error):
-///         print("Operation failed: \(error)")
-///     }
+/// let result = try withSession(db: database) {
+///     // perform database work and return a value
+///     try someOperation()
 /// }
+///
+/// switch result.blockResult {
+/// case .success(let value):
+///     print("Operation succeeded with: \(value)")
+/// case .failure(let error):
+///     print("Operation failed: \(error)")
+/// }
+///
+/// print("Updated tables: \(result.affectedTables)")
 /// ```
 ///
 /// - Parameters:
-///   - db: The database connection pointer
-///   - action: The operation to execute within the session
-///   - onComplete: Callback that receives the operation result and set of updated tables
-/// - Throws: Errors from session initialization or execution
+///   - db: The raw SQLite connection pointer used to open the session.
+///   - action: The operation to execute within the session. Its return value is
+///     propagated into `WithSessionResult.blockResult` on success.
+/// - Returns: A `WithSessionResult` containing the action's result and the set
+///   of affected table names.
+/// - Throws: Any error thrown while establishing the session or executing the
+///   provided `action`.
 public func withSession<ReturnType>(
     db: OpaquePointer,
-    action: @escaping () throws -> ReturnType,
+    action: @escaping () throws -> ReturnType
 ) throws -> WithSessionResult<ReturnType> {
     return try kotlinWithSession(
         db: db,
-        action: action,
+        action: action
     )
 }

Sources/PowerSyncGRDB/Connections/GRDBConnectionPool.swift

@@ -37,16 +37,6 @@ actor GRDBConnectionPool: SQLiteConnectionPoolProtocol {
         tableUpdatesContinuation = tempContinuation
     }
 
-    func processPowerSyncUpdates(_ updates: Set<String>) async throws {
-        try await pool.write { database in
-            for table in updates {
-                try database.notifyChanges(in: Table(table))
-            }
-        }
-        // Pass the updates to the output stream
-        tableUpdatesContinuation?.yield(updates)
-    }
-
     func read(
         onConnection: @Sendable @escaping (SQLiteConnectionLease) throws -> Void
     ) async throws {
@@ -66,15 +56,25 @@ actor GRDBConnectionPool: SQLiteConnectionPoolProtocol {
                 throw PowerSyncGRDBError.connectionUnavailable
             }
 
-            return try withSession(
+            let sessionResult = try withSession(
                 db: pointer,
             ) {
                 try onConnection(
                     GRDBConnectionLease(database: database)
                 )
             }
+           
+            return sessionResult
         }
+        // Notify PowerSync of these changes
         tableUpdatesContinuation?.yield(result.affectedTables)
+        // Notify GRDB, this needs to be a write (transaction)
+        try await  pool.write { database in
+            // Notify GRDB about these changes
+            for table in result.affectedTables {
+                try database.notifyChanges(in: Table(table))
+            }
+        }
     }
 
     func withAllConnections(

Tests/PowerSyncTests/ConnectTests.swift

@@ -18,7 +18,7 @@ final class ConnectTests: XCTestCase {
             ),
         ])
 
-        database = openKotlinDBWithFactory(
+        database = openKotlinDBDefault(
             schema: schema,
             dbFilename: ":memory:",
             logger: DatabaseLogger(DefaultLogger())

Tests/PowerSyncTests/CrudTests.swift

@@ -19,7 +19,7 @@ final class CrudTests: XCTestCase {
             ),
         ])
 
-        database = openKotlinDBWithFactory(
+        database = openKotlinDBDefault(
             schema: schema,
             dbFilename: ":memory:",
             logger: DatabaseLogger(DefaultLogger())
@@ -199,7 +199,7 @@ final class CrudTests: XCTestCase {
         let finalValidationBatch = try await database.getCrudBatch(limit: 100)
         XCTAssertNil(finalValidationBatch)
     }
-    
+
     func testCrudTransactions() async throws {
         func insertInTransaction(size: Int) async throws {
             try await database.writeTransaction { tx in
@@ -211,30 +211,30 @@ final class CrudTests: XCTestCase {
                 }
             }
         }
-        
+
         // Before inserting any data, the iterator should be empty.
         for try await _ in database.getCrudTransactions() {
             XCTFail("Unexpected transaction")
         }
-        
+
         try await insertInTransaction(size: 5)
         try await insertInTransaction(size: 10)
         try await insertInTransaction(size: 15)
-        
+
         var batch = [CrudEntry]()
         var lastTx: CrudTransaction? = nil
         for try await tx in database.getCrudTransactions() {
             batch.append(contentsOf: tx.crud)
             lastTx = tx
-            
-            if (batch.count >= 10) {
+
+            if batch.count >= 10 {
                 break
             }
         }
-        
+
         XCTAssertEqual(batch.count, 15)
         try await lastTx!.complete()
-        
+
         let finalTx = try await database.getNextCrudTransaction()
         XCTAssertEqual(finalTx!.crud.count, 15)
     }

Tests/PowerSyncTests/Kotlin/KotlinPowerSyncDatabaseImplTests.swift

@@ -71,7 +71,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
 
     func testGetError() async throws {
         do {
-            let _ = try await database.get(
+            _ = try await database.get(
                 sql: "SELECT id, name, email FROM usersfail WHERE id = ?",
                 parameters: ["1"]
             ) { cursor in
@@ -116,7 +116,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
 
     func testGetOptionalError() async throws {
         do {
-            let _ = try await database.getOptional(
+            _ = try await database.getOptional(
                 sql: "SELECT id, name, email FROM usersfail WHERE id = ?",
                 parameters: ["1"]
             ) { cursor in
@@ -140,7 +140,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
             parameters: ["1", "Test User", "[email protected]"]
         )
         do {
-            let _ = try await database.getOptional(
+            _ = try await database.getOptional(
                 sql: "SELECT id, name, email FROM users WHERE id = ?",
                 parameters: ["1"]
             ) { _ throws in
@@ -181,7 +181,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
 
     func testGetAllError() async throws {
         do {
-            let _ = try await database.getAll(
+            _ = try await database.getAll(
                 sql: "SELECT id, name, email FROM usersfail WHERE id = ?",
                 parameters: ["1"]
             ) { cursor in
@@ -505,7 +505,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
         let testWriter = TestLogWriterAdapter()
         let logger = DefaultLogger(minSeverity: LogSeverity.debug, writers: [testWriter])
 
-        let db2 = openKotlinDBWithFactory(
+        let db2 = openKotlinDBDefault(
             schema: schema,
             dbFilename: ":memory:",
             logger: DatabaseLogger(logger)
@@ -526,7 +526,7 @@ final class KotlinPowerSyncDatabaseImplTests: XCTestCase {
         let testWriter = TestLogWriterAdapter()
         let logger = DefaultLogger(minSeverity: LogSeverity.error, writers: [testWriter])
 
-        let db2 = openKotlinDBWithFactory(
+        let db2 = openKotlinDBDefault(
             schema: schema,
             dbFilename: ":memory:",
             logger: DatabaseLogger(logger)

Tests/PowerSyncTests/Kotlin/SqlCursorTests.swift

@@ -65,7 +65,7 @@ final class SqlCursorTests: XCTestCase {
             ])
         ])
 
-        database = openKotlinDBWithFactory(
+        database = openKotlinDBDefault(
             schema: schema,
             dbFilename: ":memory:",
             logger: DatabaseLogger(DefaultLogger())