Clarified the expectations around new vs existing actor & context and how different contexts are expected to interact.

Author: johnclayton

README.md

@@ -16,7 +16,7 @@ for person in people {
 
 // Or a background context
 Task.detached {
-    await modelContainer.queryActor().perform { _ in
+    await modelContainer.createQueryActor().perform { _ in
         let people = Query<Person>()
             .include(#Predicate { $0.age >= 18 } )
             .sortBy(\.age)
@@ -217,7 +217,7 @@ We also expose an async `perform` functions on a SwiftQuery's default actor that
 implicitly use `QueryActor` to run queries:
 
 ```swift
-await modelContainer.queryActor().perform { _ in
+await modelContainer.createQueryActor().perform { _ in
     let allJills = Person
         .include(#Predicate { $0.name == "Jill" })
         .results()
@@ -232,7 +232,7 @@ await modelContainer.queryActor().perform { _ in
 Or, to return a value:
 
 ```swift
-let count = await modelContainer.queryActor().perform { _ in
+let count = await modelContainer.createQueryActor().perform { _ in
     Query<Person>()
     .include(#Predicate { $0.age >= 18 } )
     .count()

Sources/SwiftQuery/Fetch+Concurrency.swift

@@ -47,7 +47,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Get the oldest person concurrently
-    /// await container.queryActor().perform { _ in
+    /// await container.createQueryActor().perform { _ in
     ///     let oldest = try Person.sortBy(\.age).last()
     ///     print("Oldest person: \(oldest?.name ?? "None")")
     /// }
@@ -69,7 +69,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Fetch all adults concurrently
-    /// await container.queryActor().perform { _ in
+    /// await container.createQueryActor().perform { _ in
     ///     let adults = try Person.include(#Predicate { $0.age >= 18 }).results()
     ///     print("Found \(adults.count) adults")
     /// }
@@ -94,7 +94,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Process large result set in batches concurrently
-    /// await container.queryActor().perform { _ in
+    /// 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
@@ -130,7 +130,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Get count of large result set efficiently
-    /// let count = try await container.queryActor().perform { _ in
+    /// let count = try await container.createQueryActor().perform { _ in
     ///     try Person.sortBy(\.name).fetchedResults { results in
     ///         results.count
     ///     }
@@ -158,7 +158,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Count adults concurrently
-    /// let adultCount = try await container.queryActor().perform { _ in
+    /// let adultCount = try await container.createQueryActor().perform { _ in
     ///     try Person.include(#Predicate { $0.age >= 18 }).count()
     /// }
     /// ```
@@ -179,7 +179,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Check if any minors exist concurrently
-    /// let hasMinors = try await container.queryActor().perform { _ in
+    /// let hasMinors = try await container.createQueryActor().perform { _ in
     ///     try !Person.include(#Predicate { $0.age < 18 }).isEmpty()
     /// }
     /// ```
@@ -202,7 +202,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Find or create admin user concurrently
-    /// try await container.queryActor().perform { actor in
+    /// try await container.createQueryActor().perform { actor in
     ///     try Person
     ///         .include(#Predicate { $0.role == "admin" })
     ///         .findOrCreate(
@@ -242,7 +242,7 @@ public extension Query {
     /// ## Example
     /// ```swift
     /// // Delete inactive users concurrently
-    /// await container.queryActor().perform { _ in
+    /// await container.createQueryActor().perform { _ in
     ///     try Person.include(#Predicate { $0.isInactive }).delete()
     /// }
     /// ```

Sources/SwiftQuery/QueryActor.swift

@@ -47,7 +47,7 @@ public actor QueryActor: Sendable {
 
 public extension ModelContainer {
     /// Creates a `QueryActor` associated with this model container.
-    func queryActor() -> QueryActor {
+    func createQueryActor() -> QueryActor {
         .init(modelContainer: self)
     }
 }