Updated interfaces for working with results from async query execution so that we no longer offer an operation closure to execute inside the actor's domain. It is now the responsibility of the caller to remain inside that domain.

Author: johnclayton

README.md

@@ -216,19 +216,19 @@ let jill = Person
 Where SwiftQuery really shines is it's automatic support for performing queries
 in a concurrency environment. The current isolation context is passed in to each function
 that performs a query, so if you have a custom model actor, you can freely perform
-queries inside the actor:
+queries and operate on the results inside the actor:
 
 ```swift
 @ModelActor
 actor MyActor {
     func promoteJill() throws {
-        if let jill = Person
+        let jill = Person
             .include(#Predicate { $0.name == "Jill" })
-            .first() 
-        {
-            jill.isPromoted = true
-            try modelContext.save()
-        }
+            .findOrCreate {
+                Person(name: "Jill")
+            }
+        jill.isPromoted = true
+        try modelContext.save()
     }
 }
 ```
@@ -249,7 +249,10 @@ await modelContainer.createQueryActor().perform { _ in
 }
 ``` 
 
-Or, to return a value:
+The results remain inside the actor's isolation
+domain so can be safely used within the closure. 
+
+If we need to produce a side effect for the query, we can return a value:
 
 ```swift
 let count = await modelContainer.createQueryActor().perform { _ in
@@ -259,7 +262,7 @@ let count = await modelContainer.createQueryActor().perform { _ in
 } 
 ```
 
-Note that models cannot be returned out of the actor's isolation context using this function; 
+> Note:  Models cannot be returned out of the actor's isolation context using this function; 
 only `Sendable` values can be transported across the boundary. This means the compiler 
 effectively makes it impossible to use the models returned from a query incorrectly in 
 a multi-context environment, thus guaranteeing the SwiftData concurrency contract at 

Sources/SwiftQuery/Fetch+Concurrency.swift

@@ -80,42 +80,6 @@ public extension Query {
         try isolation.modelContext.fetch(fetchDescriptor)
     }
 
-    /// Provides access to a lazily-evaluated collection of objects matching the
-    /// query via a closure from within a model actor's isolation context.
-    ///
-    /// - Parameters:
-    ///   - batchSize: Number of objects to fetch per batch. Defaults to 20.
-    ///   - isolation: The model actor to execute the query within. Defaults to `#isolation`
-    ///     which infers the current actor context.
-    ///   - operation: A closure that receives the `FetchResultsCollection` for processing within
-    ///     the actor's isolation domain.
-    /// - Throws: any SwiftData errors thrown during query execution
-    ///
-    /// ## Example
-    /// ```swift
-    /// // Process large result set in batches concurrently
-    /// await container.createQueryActor().perform { _ in
-    ///     try Person.sortBy(\.name).fetchedResults(batchSize: 50) { results in
-    ///         for person in results.prefix(100) {
-    ///             // Process first 100 results efficiently
-    ///             print(person.name)
-    ///         }
-    ///     }
-    /// }
-    /// ```
-    ///
-    /// - SeeAlso: `fetchedResults(in:batchSize:)`
-    func fetchedResults(
-        batchSize: Int = 20,
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<T>) -> Void
-    ) throws {
-        var descriptor = fetchDescriptor
-        descriptor.includePendingChanges = false
-        let results = try isolation.modelContext.fetch(descriptor, batchSize: batchSize)
-        operation(results)
-    }
-
     /// Returns a value computed from a lazily-evaluated collection of objects
     /// matching the query from within a model actor's isolation context.
     ///
@@ -136,15 +100,14 @@ public extension Query {
     ///     }
     /// }
     /// ```
-    func fetchedResults<Value>(
+    func fetchedResults(
         batchSize: Int = 20,
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<T>) -> Value
-    ) throws -> Value where Value: Sendable {
+        isolation: isolated (any ModelActor) = #isolation
+    ) throws -> FetchResultsCollection<T> {
         var descriptor = fetchDescriptor
         descriptor.includePendingChanges = false
         let results = try isolation.modelContext.fetch(descriptor, batchSize: batchSize)
-        return operation(results)
+        return results
     }
 
     /// Returns the number of objects matching the query from within a model actor's
@@ -189,46 +152,45 @@ public extension Query {
         try count(isolation: isolation) < 1
     }
 
-    /// Finds an existing object matching the query, or creates a new one if none exists,
-    /// then operates on it from within a model actor's isolation context.
+    /// Finds an existing object matching the query, or creates a new one if none exists.
+    ///
+    /// Can only be called from within the model actor itself because the returned results
+    /// must remain isolated.
+    ///
     ///
     /// - Parameters:
     ///   - isolation: The model actor to execute the query within. Defaults to `#isolation`
     ///     which infers the current actor context.
     ///   - body: Closure that creates a new object if none is found
-    ///   - operation: Closure that operates on the found or created object
     /// - Throws: `Error.missingPredicate` if the query has no predicate, or SwiftData errors
     ///
     /// ## Example
     /// ```swift
     /// // Find or create admin user concurrently
     /// try await container.createQueryActor().perform { actor in
-    ///     try Person
+    ///     let admin = try Person
     ///         .include(#Predicate { $0.role == "admin" })
     ///         .findOrCreate(
-    ///             body: { Person(name: "Administrator", role: "admin") },
-    ///             operation: { admin in
-    ///                 print("Admin user: \(admin.name)")
-    ///             }
+    ///             body: { Person(name: "Administrator", role: "admin") }
     ///         )
+    ///     print("Admin user: \(admin.name)")
     /// }
     /// ```
     ///
     /// - SeeAlso: `findOrCreate(in:body:)`
     func findOrCreate(
         isolation: isolated (any ModelActor) = #isolation,
-        body: () -> T,
-        operation: (T) -> Void
-    ) throws {
+        body: () -> T
+    ) throws -> T {
         guard predicate != nil else {
             throw Error.missingPredicate
         }
         if let found = try first() {
-            operation(found)
+            return found
         } else {
             let created = body()
             isolation.modelContext.insert(created)
-            operation(created)
+            return created
         }
     }
 

Sources/SwiftQuery/PersistentModel+Fetch.swift

@@ -42,38 +42,19 @@ extension PersistentModel {
         try query().results()
     }
 
-    /// Builds a query over this model type and invokes ``Query/fetchedResults(isolation:operation:)`` on that query.
+    /// Builds a query over this model type and invokes ``Query/fetchedResults(isolation:)`` on that query.
     static func fetchedResults(
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<Self>) -> Void
-    ) throws  {
-        try query().fetchedResults(operation: operation)
+        isolation: isolated (any ModelActor) = #isolation
+    ) throws -> FetchResultsCollection<Self>  {
+        try query().fetchedResults()
     }
 
-    /// Builds a query over this model type and invokes ``Query/fetchedResults(batchSize:isolation:operation:)`` on that query.
+    /// Builds a query over this model type and invokes ``Query/fetchedResults(batchSize:isolation:)`` on that query.
     static func fetchedResults(
         batchSize: Int,
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<Self>) -> Void
-    ) throws {
-        try query().fetchedResults(batchSize: batchSize, operation: operation)
-    }
-
-    /// Builds a query over this model type and invokes ``Query/fetchedResults(isolation:operation:)`` on that query.
-    static func fetchedResults<Value>(
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<Self>) -> Value
-    ) throws -> Value where Value: Sendable {
-        try query().fetchedResults(operation: operation)
-    }
-
-    /// Builds a query over this model type and invokes ``Query/fetchedResults(batchSize:isolation:operation:)`` on that query.
-    static func fetchedResults<Value>(
-        batchSize: Int,
-        isolation: isolated (any ModelActor) = #isolation,
-        operation: @Sendable (FetchResultsCollection<Self>) -> Value
-    ) throws -> Value where Value: Sendable {
-        try query().fetchedResults(batchSize: batchSize, operation: operation)
+        isolation: isolated (any ModelActor) = #isolation
+    ) throws -> FetchResultsCollection<Self> {
+        try query().fetchedResults(batchSize: batchSize)
     }
 
     /// Builds a query over this model type and invokes ``Query/count(isolation:)`` on that query.
@@ -89,9 +70,8 @@ extension PersistentModel {
     /// Builds a query over this model type and invokes ``Query/findOrCreate(isolation:body:operation:)`` on that query.
     static func findOrCreate(
         isolation: isolated (any ModelActor) = #isolation,
-        body: () -> Self,
-        operation: (Self) -> Void
-    ) throws {
-        try query().findOrCreate(body: body, operation: operation)
+        body: () -> Self
+    ) throws -> Self {
+        try query().findOrCreate(body: body)
     }
 }