@@ -28,78 +28,137 @@ public protocol Query<Input, Output>: Sendable {
2828 /// if those tables changed.
2929 var watchedTables : Set < String > { get }
3030
31- /// Executes the query
32- ///
33- /// - Parameters:
34- /// - input: The query's input
35- /// - tx: The transaction to run the query in
36- /// - Returns: The query's output
37- func execute(
38- with input: Input ,
39- tx: borrowing Transaction
40- ) throws -> Output
41-
42- /// Observes the query's value over time. When the database
43- /// changes new values will automatically be refreshed.
44- ///
45- /// The `QueryObservation` is an `AsyncSequence` and can
46- /// be observed with a for loop.
31+ /// Executes the query once within the given transaction.
4732 ///
33+ /// Example:
4834 /// ```swift
49- /// for try await value in query.observe() {
50- /// print(value)
35+ /// try await queries.begin(.read) { tx in
36+ /// let user = try userQuery.execute(with: 42, tx: tx)
37+ /// print("Fetched user:", user)
5138 /// }
5239 /// ```
5340 ///
54- /// - Parameter input: The query's input
55- /// - Returns: The observation.
56- func observe( with input: Input ) -> any QueryObservation < Output >
41+ /// - Parameters:
42+ /// - input: The query input or parameters to use for execution.
43+ /// - tx: The active transaction in which the query will be executed.
44+ /// - Returns: The decoded `Output` of the query.
45+ /// - Throws: An error if the query fails to execute or if the results
46+ /// cannot be decoded into the expected type.
47+ func execute( with input: Input , tx: borrowing Transaction ) throws -> Output
48+
49+ /// Initializes a QueryObservation that watches the database for
50+ /// changes on anything that affects the query and emits changes
51+ /// overtime.
52+ ///
53+ /// This likely will not be used directly yet using `observe` instead.
54+ func observation( with input: Input ) -> any QueryObservation < Output >
5755}
5856
5957public extension Query {
58+ /// Executes the query once and returns the result.
59+ ///
60+ /// Example:
61+ /// ```swift
62+ /// let user = try await userQuery.execute(with: 42, tx: tx)
63+ /// ```
64+ ///
65+ /// - Parameters:
66+ /// - input: The query input or parameters to use for execution.
67+ /// - tx: The active transaction in which the query will be executed.
68+ /// - Returns: The decoded `Output` of the query.
69+ /// - Throws: An error if the query fails to execute or if the results
70+ /// cannot be decoded into the expected type.
6071 func execute( with input: Input ) async throws -> Output {
6172 try await connection. begin ( transactionKind) { tx in
6273 try execute ( with: input, tx: tx)
6374 }
6475 }
6576
66- func observe( with input: Input ) -> any QueryObservation < Output > {
67- return DatabaseQueryObservation (
77+ func observation( with input: Input ) -> any QueryObservation < Output > {
78+ // By default just return a DatabaseQueryObservation
79+ DatabaseQueryObservation (
6880 query: self ,
6981 input: input,
7082 watchedTables: watchedTables,
7183 connection: connection
7284 )
7385 }
86+
87+ /// Observes the results of a database query and streams updates as the
88+ /// underlying data changes.
89+ ///
90+ /// This method returns an `AsyncSequence` that first yields the current
91+ /// results of the query, then continues to emit new values whenever the
92+ /// relevant database tables are modified. Use this when you need to react
93+ /// to live changes in the database.
94+ ///
95+ /// Example:
96+ /// ```swift
97+ /// for await row in query.observe(with: input) {
98+ /// print("Row updated:", row)
99+ /// }
100+ /// ```
101+ ///
102+ /// - Parameter input: The query or input definition used to fetch results.
103+ /// - Returns: A `QueryStream` sequence of `Output` values that reflect
104+ /// both the initial results and subsequent changes.
105+ func observe( with input: Input ) -> QueryStream < Output > {
106+ QueryStream ( observation ( with: input) )
107+ }
74108}
75109
76110public extension Query where Input == ( ) {
77- /// Executes the query in the given transaction
78- /// - Parameter tx: The transaction to execute the query in
79- /// - Returns: The query's output
111+ /// Executes the query once within the given transaction.
112+ ///
113+ /// Example:
114+ /// ```swift
115+ /// try await queries.begin(.read) { tx in
116+ /// let user = try userQuery.execute(tx: tx)
117+ /// print("Fetched user:", user)
118+ /// }
119+ /// ```
120+ ///
121+ /// - Parameters:
122+ /// - tx: The active transaction in which the query will be executed.
123+ /// - Returns: The decoded `Output` of the query.
124+ /// - Throws: An error if the query fails to execute or if the results
125+ /// cannot be decoded into the expected type.
80126 func execute( tx: borrowing Transaction ) throws -> Output {
81127 return try execute ( with: ( ) , tx: tx)
82128 }
83129
84- /// Executes the query
130+ /// Executes the query once and returns the result.
131+ ///
132+ /// Example:
133+ /// ```swift
134+ /// let user = try await userQuery.execute()
135+ /// ```
136+ ///
137+ /// - Returns: The decoded `Output` of the query.
138+ /// - Throws: An error if the query fails to execute or if the results
139+ /// cannot be decoded into the expected type.
85140 func execute( ) async throws -> Output {
86141 return try await execute ( with: ( ) )
87142 }
88143
89- /// Observes the query's value over time. When the database
90- /// changes new values will automatically be refreshed .
144+ /// Observes the results of a database query and streams updates as the
145+ /// underlying data changes .
91146 ///
92- /// The `QueryObservation` is an `AsyncSequence` and can
93- /// be observed with a for loop.
147+ /// This method returns an `AsyncSequence` that first yields the current
148+ /// results of the query, then continues to emit new values whenever the
149+ /// relevant database tables are modified. Use this when you need to react
150+ /// to live changes in the database.
94151 ///
152+ /// Example:
95153 /// ```swift
96- /// for try await value in query.observe() {
97- /// print(value )
154+ /// for await row in query.observe() {
155+ /// print("Row updated:", row )
98156 /// }
99157 /// ```
100158 ///
101- /// - Returns: The observation.
102- func observe( ) -> any QueryObservation < Output > {
159+ /// - Returns: A `QueryStream` sequence of `Output` values that reflect
160+ /// both the initial results and subsequent changes.
161+ func observe( ) -> QueryStream < Output > {
103162 return observe ( with: ( ) )
104163 }
105164}
0 commit comments