Add QueryExpression<Optional>.map,flatMap (#80)

* Add `QueryExpression<Optional>.map,flatMap`

This PR adds helpers that make it a little easier to work with optional
query expressions in a builder.

For example, if you want to execute a `LIKE` operator on an optional
string, you currently have to resort to one of the following
workarounds:

```swift
.where { ($0.title ?? "").like("%foo%") }
// or:
.where { #sql("\($0.title) LIKE '%foo%') }
```

This PR introduces `map` and `flatMap` operations on optional
`QueryExpression`s that unwraps the expression, giving you additional
flexibility in how you express your builder code:

```swift
.where { $0.title.map { $0.like("%foo%") } ?? false }
```

While this is more code than the above options, some may prefer its
readability, and should we merge the other optional helpers from #61, it
could be further shortened:

```swift
.where { $0.title.map { $0.like("%foo%") } }
```

* tests

Author: stephencelis

Sources/StructuredQueriesCore/Documentation.docc/Extensions/QueryExpression.md

@@ -28,3 +28,8 @@
 
 - ``jsonArrayLength()``
 - ``jsonGroupArray(order:filter:)``
+
+### Optionality
+
+- ``map(_:)``
+- ``flatMap(_:)``

Sources/StructuredQueriesCore/Optional.swift

@@ -137,3 +137,43 @@ where Wrapped.TableColumns: PrimaryKeyedTableDefinition {
     self[dynamicMember: \.primaryKey]
   }
 }
+
+extension QueryExpression where QueryValue: _OptionalProtocol {
+  /// Creates and optionalizes a new expression from this one by applying an unwrapped version of
+  /// this expression to a given closure.
+  ///
+  /// ```swift
+  /// Reminder.where {
+  ///   $0.dueDate.map { $0 > Date() }
+  /// }
+  /// // SELECT … FROM "reminders"
+  /// // WHERE "reminders"."dueDate" > '2018-01-29 00:08:00.000'
+  /// ```
+  ///
+  /// - Parameter transform: A closure that takes an unwrapped version of this expression.
+  /// - Returns: The result of the transform function, optionalized.
+  public func map<T>(
+    _ transform: (SQLQueryExpression<QueryValue.Wrapped>) -> some QueryExpression<T>
+  ) -> some QueryExpression<T?> {
+    SQLQueryExpression(transform(SQLQueryExpression(queryFragment)).queryFragment)
+  }
+
+  /// Creates a new optional expression from this one by applying an unwrapped version of this
+  /// expression to a given closure.
+  ///
+  /// ```swift
+  /// Reminder.select {
+  ///   $0.dueDate.flatMap { $0.max() }
+  /// }
+  /// // SELECT max("reminders"."dueDate") FROM "reminders"
+  /// // => [Date?]
+  /// ```
+  ///
+  /// - Parameter transform: A closure that takes an unwrapped version of this expression.
+  /// - Returns: The result of the transform function.
+  public func flatMap<T>(
+    _ transform: (SQLQueryExpression<QueryValue.Wrapped>) -> some QueryExpression<T?>
+  ) -> some QueryExpression<T?> {
+    SQLQueryExpression(transform(SQLQueryExpression(queryFragment)).queryFragment)
+  }
+}

Tests/StructuredQueriesTests/SelectTests.swift

@@ -1170,6 +1170,50 @@ extension SnapshotTests {
         """
       }
     }
+
+    @Test func optionalMapAndFlatMap() {
+      do {
+        let query: some Statement<Bool?> = Reminder.select {
+          $0.priority.map { $0 < Priority.high }
+        }
+        assertQuery(query) {
+          """
+          SELECT ("reminders"."priority" < 3)
+          FROM "reminders"
+          """
+        } results: {
+          """
+          ┌───────┐
+          │ nil   │
+          │ nil   │
+          │ false │
+          │ nil   │
+          │ nil   │
+          │ false │
+          │ true  │
+          │ false │
+          │ nil   │
+          │ true  │
+          └───────┘
+          """
+        }
+      }
+      do {
+        let query: some Statement<Int?> = Reminder.select { $0.priority.flatMap { $0.max() } }
+        assertQuery(query) {
+          """
+          SELECT max("reminders"."priority")
+          FROM "reminders"
+          """
+        } results: {
+          """
+          ┌───┐
+          │ 3 │
+          └───┘
+          """
+        }
+      }
+    }
   }
 }