Merge remote-tracking branch 'origin/main' into temp-triggers

Author: mbrandonw

Sources/StructuredQueriesCore/AggregateFunctions.swift

@@ -84,7 +84,7 @@ where QueryValue: _OptionalPromotable, QueryValue._Optionalized.Wrapped == Strin
   }
 }
 
-extension QueryExpression where QueryValue: QueryBindable {
+extension QueryExpression where QueryValue: QueryBindable & _OptionalPromotable {
   /// A maximum aggregate of this expression.
   ///
   /// ```swift
@@ -96,7 +96,7 @@ extension QueryExpression where QueryValue: QueryBindable {
   /// - Returns: A maximum aggregate of this expression.
   public func max(
     filter: (some QueryExpression<Bool>)? = Bool?.none
-  ) -> some QueryExpression<Int?> {
+  ) -> some QueryExpression<QueryValue._Optionalized.Wrapped?> {
     AggregateFunction("max", [queryFragment], filter: filter?.queryFragment)
   }
 
@@ -111,7 +111,7 @@ extension QueryExpression where QueryValue: QueryBindable {
   /// - Returns: A minimum aggregate of this expression.
   public func min(
     filter: (some QueryExpression<Bool>)? = Bool?.none
-  ) -> some QueryExpression<Int?> {
+  ) -> some QueryExpression<QueryValue._Optionalized.Wrapped?> {
     AggregateFunction("min", [queryFragment], filter: filter?.queryFragment)
   }
 }
@@ -170,7 +170,7 @@ where QueryValue: _OptionalPromotable, QueryValue._Optionalized.Wrapped: Numeric
   ///
   /// ```swift
   /// Item.select { $0.price.total() }
-  /// // SELECT sum("items"."price") FROM "items"
+  /// // SELECT total("items"."price") FROM "items"
   /// ```
   ///
   /// - Parameters:

Sources/StructuredQueriesCore/Documentation.docc/Articles/QueryCookbook.md

@@ -349,7 +349,7 @@ table. For example, querying for all reminders lists along with an array of the
 list. We'd like to be able to query for this data and decode it into a collection of values
 from the following data type:
 
-```struct
+```swift
 struct Row {
   let remindersList: RemindersList
   let reminders: [Reminder]
@@ -395,7 +395,7 @@ Another way to do this is to use the `@Selection` macro described above
 (<doc:QueryCookbook#Custom-selections>), along with a ``Swift/Decodable/JSONRepresentation`` of the
 collection of reminders you want to load for each list:
 
-```struct
+```swift
 @Selection
 struct Row {
   let remindersList: RemindersList
@@ -414,7 +414,7 @@ columns of [primary keyed tables](<doc:PrimaryKeyedTables>):
 
 ```swift
 RemindersList
-  .join(Reminder.all) { $0.id.eq($1.remindersListID) }
+  .leftJoin(Reminder.all) { $0.id.eq($1.remindersListID) }
   .select {
     Row.Columns(
       remindersList: $0,
@@ -423,8 +423,63 @@ RemindersList
   }
 ```
 
+> Note: There are 2 important things to note about this query:
+>
+> * Since not every reminders list will have a reminder associated with it, we are using a
+>   ``Select/leftJoin(_:on:)``. That will make sure to select all lists no matter what.
+> * The left join introduces _optional_ reminders, but we are using a special overload of
+>   `jsonGroupArray` on optionals that automatically filters out `nil` reminders and unwraps them.
+
 This allows you to fetch all of the data in a single SQLite query and decode the data into a
 collection of `Row` values. There is an extra cost associated with decoding the JSON object,
 but that cost may be smaller than executing multiple SQLite requests and transforming the data
 into `Row` manually, not to mention the additional code you need to write and maintain to process
 the data.
+
+It is even possible to load multiple associations at once. For example, suppose that there is a
+`Milestone` table that is associated with a `RemindersList`:
+
+```swift
+@Table
+struct Milestone: Identifiable, Codable {
+  let id: Int
+  var title = ""
+  var remindersListID: RemindersList.ID
+}
+```
+
+And suppose you would like to fetch all `RemindersList`s along with the collection of all milestones
+and reminders associated with the list:
+
+```struct
+@Selection
+struct Row {
+  let remindersList: RemindersList
+  @Column(as: [Milestone].JSONRepresentation.self)
+  let milestones: [Milestone]
+  @Column(as: [Reminder].JSONRepresentation.self)
+  let reminders: [Reminder]
+}
+```
+
+It is possible to do this using two left joins and two `jsonGroupArray`s:
+
+```swift
+RemindersList
+  .leftJoin(Milestone.all) { $0.id.eq($1.remindersListID) }
+  .leftJoin(Reminder.all) { $0.id.eq($2.remindersListID) }
+  .select {
+    Row.Columns(
+      remindersList: $0,
+      milestones: $1.jsonGroupArray(isDistinct: true),
+      reminders: $2.jsonGroupArray(isDistinct: true)
+    )
+  }
+```
+
+> Note: Because we are now joining two independent tables to `RemindersList`, we will get duplicate
+> entries for all pairs of reminders with milestones. To remove those duplicates we use the
+> `isDistinct` option for `jsonGroupArray`.
+
+This will now load all reminders lists with all of their reminders and milestones in one single
+SQL query.

Sources/StructuredQueriesCore/Operators.swift

@@ -192,7 +192,7 @@ public func == <QueryValue: _OptionalProtocol>(
   lhs: any QueryExpression<QueryValue>,
   rhs: some QueryExpression<QueryValue.Wrapped>
 ) -> some QueryExpression<Bool> {
-  BinaryOperator(lhs: lhs, operator: isNull(lhs) ? "IS" : "=", rhs: rhs)
+  BinaryOperator(lhs: lhs, operator: "IS", rhs: rhs)
 }
 
 // NB: This overload is required due to an overload resolution bug of 'Updates[dynamicMember:]'.
@@ -202,7 +202,7 @@ public func != <QueryValue: _OptionalProtocol>(
   lhs: any QueryExpression<QueryValue>,
   rhs: some QueryExpression<QueryValue.Wrapped>
 ) -> some QueryExpression<Bool> {
-  BinaryOperator(lhs: lhs, operator: isNull(lhs) ? "IS NOT" : "<>", rhs: rhs)
+  BinaryOperator(lhs: lhs, operator: "IS NOT", rhs: rhs)
 }
 
 // NB: This overload is required due to an overload resolution bug of 'Updates[dynamicMember:]'.
@@ -211,7 +211,7 @@ public func == <QueryValue: _OptionalProtocol>(
   lhs: any QueryExpression<QueryValue>,
   rhs: some QueryExpression<QueryValue>
 ) -> some QueryExpression<Bool> {
-  BinaryOperator(lhs: lhs, operator: isNull(lhs) || isNull(rhs) ? "IS" : "=", rhs: rhs)
+  BinaryOperator(lhs: lhs, operator: "IS", rhs: rhs)
 }
 
 // NB: This overload is required due to an overload resolution bug of 'Updates[dynamicMember:]'.
@@ -220,7 +220,7 @@ public func != <QueryValue: _OptionalProtocol>(
   lhs: any QueryExpression<QueryValue>,
   rhs: some QueryExpression<QueryValue>
 ) -> some QueryExpression<Bool> {
-  BinaryOperator(lhs: lhs, operator: isNull(lhs) || isNull(rhs) ? "IS NOT" : "<>", rhs: rhs)
+  BinaryOperator(lhs: lhs, operator: "IS NOT", rhs: rhs)
 }
 
 // NB: This overload is required due to an overload resolution bug of 'Updates[dynamicMember:]'.

Sources/StructuredQueriesCore/PrimaryKeyed.swift

@@ -22,6 +22,24 @@ public protocol TableDraft: Table {
   init(_ primaryTable: PrimaryTable)
 }
 
+extension TableDraft {
+  public static subscript(
+    dynamicMember keyPath: KeyPath<PrimaryTable.Type, some Statement<PrimaryTable>>
+  ) -> some Statement<Self> {
+    SQLQueryExpression("\(PrimaryTable.self[keyPath: keyPath])")
+  }
+
+  public static subscript(
+    dynamicMember keyPath: KeyPath<PrimaryTable.Type, some SelectStatementOf<PrimaryTable>>
+  ) -> SelectOf<Self> {
+    unsafeBitCast(PrimaryTable.self[keyPath: keyPath].asSelect(), to: SelectOf<Self>.self)
+  }
+
+  public static var all: SelectOf<Self> {
+    unsafeBitCast(PrimaryTable.all.asSelect(), to: SelectOf<Self>.self)
+  }
+}
+
 /// A type representing a database table's columns.
 ///
 /// Don't conform to this protocol directly. Instead, use the `@Table` and `@Column` macros to
@@ -38,6 +56,14 @@ where QueryValue: PrimaryKeyedTable {
   var primaryKey: TableColumn<QueryValue, PrimaryKey> { get }
 }
 
+extension TableDefinition where QueryValue: TableDraft {
+  public subscript<Member>(
+    dynamicMember keyPath: KeyPath<QueryValue.PrimaryTable.TableColumns, Member>
+  ) -> Member {
+    QueryValue.PrimaryTable.columns[keyPath: keyPath]
+  }
+}
+
 extension PrimaryKeyedTableDefinition {
   /// A query expression representing the number of rows in this table.
   ///
@@ -60,6 +86,22 @@ extension PrimaryKeyedTable {
   }
 }
 
+extension TableDraft {
+  /// A where clause filtered by a primary key.
+  ///
+  /// - Parameter primaryKey: A primary key identifying a table row.
+  /// - Returns: A `WHERE` clause.
+  public static func find(
+    _ primaryKey: PrimaryTable.TableColumns.PrimaryKey.QueryOutput
+  ) -> Where<Self> {
+    Self.where { _ in
+      PrimaryTable.columns.primaryKey.eq(
+        PrimaryTable.TableColumns.PrimaryKey(queryOutput: primaryKey)
+      )
+    }
+  }
+}
+
 extension Where where From: PrimaryKeyedTable {
   /// Adds a primary key condition to a where clause.
   ///
@@ -70,6 +112,40 @@ extension Where where From: PrimaryKeyedTable {
   }
 }
 
+extension Where where From: TableDraft {
+  /// Adds a primary key condition to a where clause.
+  ///
+  /// - Parameter primaryKey: A primary key.
+  /// - Returns: A where clause with the added primary key.
+  public func find(_ primaryKey: From.PrimaryTable.TableColumns.PrimaryKey.QueryOutput) -> Self {
+    self.where { _ in
+      From.PrimaryTable.columns.primaryKey.eq(
+        From.PrimaryTable.TableColumns.PrimaryKey(queryOutput: primaryKey)
+      )
+    }
+  }
+}
+
+extension Select where From: PrimaryKeyedTable {
+  /// A select statement filtered by a primary key.
+  ///
+  /// - Parameter primaryKey: A primary key identifying a table row.
+  /// - Returns: A select statement filtered by the given key.
+  public func find(_ primaryKey: From.TableColumns.PrimaryKey.QueryOutput) -> Self {
+    self.and(From.find(primaryKey))
+  }
+}
+
+extension Select where From: TableDraft {
+  /// A select statement filtered by a primary key.
+  ///
+  /// - Parameter primaryKey: A primary key identifying a table row.
+  /// - Returns: A select statement filtered by the given key.
+  public func find(_ primaryKey: From.PrimaryTable.TableColumns.PrimaryKey.QueryOutput) -> Self {
+    self.and(From.find(primaryKey))
+  }
+}
+
 extension Update where From: PrimaryKeyedTable {
   /// An update statement filtered by a primary key.
   ///
@@ -80,6 +156,20 @@ extension Update where From: PrimaryKeyedTable {
   }
 }
 
+extension Update where From: TableDraft {
+  /// An update statement filtered by a primary key.
+  ///
+  /// - Parameter primaryKey: A primary key identifying a table row.
+  /// - Returns: An update statement filtered by the given key.
+  public func find(_ primaryKey: From.PrimaryTable.TableColumns.PrimaryKey.QueryOutput) -> Self {
+    self.where { _ in
+      From.PrimaryTable.columns.primaryKey.eq(
+        From.PrimaryTable.TableColumns.PrimaryKey(queryOutput: primaryKey)
+      )
+    }
+  }
+}
+
 extension Delete where From: PrimaryKeyedTable {
   /// A delete statement filtered by a primary key.
   ///
@@ -90,12 +180,16 @@ extension Delete where From: PrimaryKeyedTable {
   }
 }
 
-extension Select where From: PrimaryKeyedTable {
-  /// A select statement filtered by a primary key.
+extension Delete where From: TableDraft {
+  /// A delete statement filtered by a primary key.
   ///
   /// - Parameter primaryKey: A primary key identifying a table row.
-  /// - Returns: A select statement filtered by the given key.
-  public func find(_ primaryKey: From.TableColumns.PrimaryKey.QueryOutput) -> Self {
-    self.and(From.find(primaryKey))
+  /// - Returns: A delete statement filtered by the given key.
+  public func find(_ primaryKey: From.PrimaryTable.TableColumns.PrimaryKey.QueryOutput) -> Self {
+    self.where { _ in
+      From.PrimaryTable.columns.primaryKey.eq(
+        From.PrimaryTable.TableColumns.PrimaryKey(queryOutput: primaryKey)
+      )
+    }
   }
 }

Sources/StructuredQueriesCore/QueryFragmentBuilder.swift

@@ -27,6 +27,12 @@ extension QueryFragmentBuilder<Bool> {
   ) -> [QueryFragment] {
     [expression.queryFragment]
   }
+
+  public static func buildExpression(
+    _ expression: some QueryExpression<some _OptionalPromotable<Bool?>>
+  ) -> [QueryFragment] {
+    [expression.queryFragment]
+  }
 }
 
 extension QueryFragmentBuilder<()> {