Combine

Author: wickwirew

Sources/Feather/Query+Combine.swift

@@ -98,16 +98,21 @@ public struct QueryPublisher<Output>: Publisher {
 }
 
 public extension Query {
-    /// Returns a Combine publisher to observes the query
+    /// Returns a Combine publisher that will fire once
+    /// and then observe changes as the database changes.
     ///
     /// - Parameter input: The input for the query
-    /// - Returns: A p
+    /// - Returns: A combine publisher
     func publisher(with input: Input) -> QueryPublisher<Output> {
         QueryPublisher(query: self.with(input: input))
     }
 }
 
 public extension Query where Input == () {
+    /// Returns a Combine publisher that will fire once
+    /// and then observe changes as the database changes.
+    ///
+    /// - Returns: A combine publisher
     func publisher() -> QueryPublisher<Output> {
         QueryPublisher(query: self)
     }

Sources/Feather/Query.swift

@@ -14,19 +14,54 @@
 /// we can pass in a different `Query` with the same input
 /// and output as a mock.
 public protocol Query<Input, Output>: Sendable {
+    /// The type the query takes as an input
     associatedtype Input: Sendable
+    /// The type the query returns as an output
     associatedtype Output: Sendable
 
+    /// Executes the query
+    ///
+    /// - Parameter input: The query's input
+    /// - Returns: The query's output
     func execute(with input: Input) async throws -> Output
 
+    
+    /// Observes the query's value over time. When the database
+    /// changes new values will automatically be refreshed.
+    ///
+    /// The `QueryObservation` is an `AsyncSequence` and can
+    /// be observed with a for loop.
+    ///
+    /// ```swift
+    /// for try await value in query.observe() {
+    ///     print(value)
+    /// }
+    /// ```
+    ///
+    /// - Parameter input: The query's input
+    /// - Returns: The observation.
     func observe(with input: Input) -> any QueryObservation<Output>
 }
 
 public extension Query where Input == () {
+    /// Executes the query
     func execute() async throws -> Output {
         return try await execute(with: ())
     }
 
+    /// Observes the query's value over time. When the database
+    /// changes new values will automatically be refreshed.
+    ///
+    /// The `QueryObservation` is an `AsyncSequence` and can
+    /// be observed with a for loop.
+    ///
+    /// ```swift
+    /// for try await value in query.observe() {
+    ///     print(value)
+    /// }
+    /// ```
+    ///
+    /// - Returns: The observation.
     func observe() -> any QueryObservation<Output> {
         return observe(with: ())
     }

Tests/FeatherTests/MapTests.swift

@@ -19,9 +19,10 @@ struct MapTests {
     }
 
     @Test func mapTransformsOutput_Observation() async throws {
-        let query = Queries.Just<(), Int>(100)
+        let query = Queries.Just<(), Int>(100).map(\.description)
+        
         var count = 0
-        for try await output in query.map(\.description).observe() {
+        for try await output in query.observe() {
             count += 1
             #expect(output == "100")
         }