Better support for optionals in queries

  * Predicates (`where` and `having`) can return optional booleans.
  * Add `QueryExpression<Optional>.map` for optionally building queries
    on non-optional values.

For example, a comparison that might use the `#sql` macro as an escape
hatch can more safely and succinctly use `map`:

```diff
 Reminder.where {
-  #sql("\($0.dueDate) < \(Date())")
+  $0.dueDate.map { $0 < Date() }
 }
```

Author: stephencelis

Sources/StructuredQueriesCore/Optional.swift

@@ -133,3 +133,11 @@ where Wrapped.TableColumns: PrimaryKeyedTableDefinition {
     self[dynamicMember: \.primaryKey]
   }
 }
+
+extension QueryExpression where QueryValue: _OptionalProtocol {
+  public func map<T>(
+    _ transform: (SQLQueryExpression<QueryValue.Wrapped>) -> some QueryExpression<T>
+  ) -> some QueryExpression<T?> {
+    SQLQueryExpression(transform(SQLQueryExpression(queryFragment)).queryFragment)
+  }
+}

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<()> {

Sources/StructuredQueriesCore/Statements/Delete.swift

@@ -48,7 +48,9 @@ public struct Delete<From: Table, Returning> {
   ///
   /// - Parameter keyPath: A key path to a Boolean expression to filter by.
   /// - Returns: A statement with the added predicate.
-  public func `where`(_ keyPath: KeyPath<From.TableColumns, some QueryExpression<Bool>>) -> Self {
+  public func `where`(
+    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<some _OptionalPromotable<Bool?>>>
+  ) -> Self {
     var update = self
     update.where.append(From.columns[keyPath: keyPath].queryFragment)
     return update
@@ -64,7 +66,9 @@ public struct Delete<From: Table, Returning> {
   /// - Parameter predicate: A closure that returns a Boolean expression to filter by.
   /// - Returns: A statement with the added predicate.
   @_disfavoredOverload
-  public func `where`(_ predicate: (From.TableColumns) -> some QueryExpression<Bool>) -> Self {
+  public func `where`(
+    _ predicate: (From.TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
+  ) -> Self {
     var update = self
     update.where.append(predicate(From.columns).queryFragment)
     return update

Sources/StructuredQueriesCore/Statements/Select.swift

@@ -241,7 +241,7 @@ extension Table {
   ///   columns.
   /// - Returns: A select statement that is filtered by the given predicate.
   public static func having(
-    _ predicate: (TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> SelectOf<Self> {
     Where().having(predicate)
   }
@@ -1103,7 +1103,7 @@ extension Select {
   /// - Parameter keyPath: A key path from this select's table to a Boolean expression to filter by.
   /// - Returns: A new select statement that appends the given predicate to its `WHERE` clause.
   public func `where`(
-    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<Bool>>
+    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<some _OptionalPromotable<Bool?>>>
   ) -> Self
   where Joins == () {
     var select = self
@@ -1118,7 +1118,9 @@ extension Select {
   /// - Returns: A new select statement that appends the given predicate to its `WHERE` clause.
   @_disfavoredOverload
   public func `where`<each J: Table>(
-    _ predicate: (From.TableColumns, repeat (each J).TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns, repeat (each J).TableColumns) -> some QueryExpression<
+      some _OptionalPromotable<Bool?>
+    >
   ) -> Self
   where Joins == (repeat each J) {
     var select = self
@@ -1222,7 +1224,9 @@ extension Select {
   /// - Returns: A new select statement that appends the given predicate to its `HAVING` clause.
   @_disfavoredOverload
   public func having<each J: Table>(
-    _ predicate: (From.TableColumns, repeat (each J).TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns, repeat (each J).TableColumns) -> some QueryExpression<
+      some _OptionalPromotable<Bool?>
+    >
   ) -> Self
   where Joins == (repeat each J) {
     var select = self

Sources/StructuredQueriesCore/Statements/SelectStatement.swift

@@ -47,7 +47,7 @@ public typealias SelectStatementOf<From: Table, each Join: Table> =
 
 extension SelectStatement {
   public static func `where`<From>(
-    _ predicate: (From.TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> Self
   where Self == Where<From> {
     Self(predicates: [predicate(From.columns).queryFragment])

Sources/StructuredQueriesCore/Statements/Update.swift

@@ -105,7 +105,9 @@ public struct Update<From: Table, Returning> {
   ///
   /// - Parameter keyPath: A key path to a Boolean expression to filter by.
   /// - Returns: A statement with the added predicate.
-  public func `where`(_ keyPath: KeyPath<From.TableColumns, some QueryExpression<Bool>>) -> Self {
+  public func `where`(
+    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<some _OptionalPromotable<Bool?>>>
+  ) -> Self {
     var update = self
     update.where.append(From.columns[keyPath: keyPath].queryFragment)
     return update
@@ -117,7 +119,7 @@ public struct Update<From: Table, Returning> {
   /// - Returns: A statement with the added predicate.
   @_disfavoredOverload
   public func `where`(
-    _ predicate: (From.TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> Self {
     var update = self
     update.where.append(predicate(From.columns).queryFragment)

Sources/StructuredQueriesCore/Statements/Where.swift

@@ -20,7 +20,7 @@ extension Table {
   /// - Parameter keyPath: A key path to a Boolean expression to filter by.
   /// - Returns: A `WHERE` clause.
   public static func `where`(
-    _ keyPath: KeyPath<TableColumns, some QueryExpression<Bool>>
+    _ keyPath: KeyPath<TableColumns, some QueryExpression<some _OptionalPromotable<Bool?>>>
   ) -> Where<Self> {
     Where(predicates: [columns[keyPath: keyPath].queryFragment])
   }
@@ -33,7 +33,7 @@ extension Table {
   /// - Returns: A `WHERE` clause.
   @_disfavoredOverload
   public static func `where`(
-    _ predicate: (TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> Where<Self> {
     Where(predicates: [predicate(columns).queryFragment])
   }
@@ -285,7 +285,7 @@ extension Where: SelectStatement {
   /// - Parameter keyPath: A key path to a Boolean expression to filter by.
   /// - Returns: A where clause with the added predicate.
   public func `where`(
-    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<Bool>>
+    _ keyPath: KeyPath<From.TableColumns, some QueryExpression<some _OptionalPromotable<Bool?>>>
   ) -> Self {
     var `where` = self
     `where`.predicates.append(From.columns[keyPath: keyPath].queryFragment)
@@ -298,7 +298,7 @@ extension Where: SelectStatement {
   /// - Returns: A where clause with the added predicate.
   @_disfavoredOverload
   public func `where`(
-    _ predicate: (From.TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> Self {
     var `where` = self
     `where`.predicates.append(predicate(From.columns).queryFragment)
@@ -408,7 +408,7 @@ extension Where: SelectStatement {
 
   /// A select statement for the filtered table with the given `HAVING` clause.
   public func having(
-    _ predicate: (From.TableColumns) -> some QueryExpression<Bool>
+    _ predicate: (From.TableColumns) -> some QueryExpression<some _OptionalPromotable<Bool?>>
   ) -> SelectOf<From> {
     asSelect().having(predicate)
   }