Better @Table/@Selection composition: nested column groupings, enums, and more

Sources/StructuredQueries/Documentation.docc/StructuredQueries.md

@@ -26,6 +26,7 @@ StructuredQueries also ships SQLite-specific helpers:
 
 - ``Table(_:)``
 - ``Column(_:as:primaryKey:)``
+- ``Columns(primaryKey:)``
 - ``Ephemeral()``
 - ``Selection()``
 - ``sql(_:as:)``

Sources/StructuredQueries/Macros.swift

@@ -17,7 +17,7 @@ import StructuredQueriesCore
   named(schemaName),
   named(tableName)
 )
-@attached(member, names: named(Draft), named(TableColumns))
+@attached(member, names: named(Draft), named(Selection), named(TableColumns))
 @attached(memberAttribute)
 public macro Table(
   _ name: String = "",
@@ -36,7 +36,7 @@ public macro Table(
 ///     that don't have a single representation in SQL, like `Date` and `UUID`.
 ///   - generated: Allows to declare the column as a read-only database computed column, making it
 ///     available for queries but not for updates.
-///   - primaryKey: The column is its table's auto-incrementing primary key.
+///   - primaryKey: The column is its table's primary key.
 @attached(peer)
 public macro Column(
   _ name: String = "",
@@ -49,6 +49,19 @@ public macro Column(
     type: "ColumnMacro"
   )
 
+/// Customizes a group of columns generated by the ``/StructuredQueriesCore/Table`` protocol.
+///
+/// - Parameters primaryKey: These columns are the table's composite primary key.
+@attached(peer)
+public macro Columns(
+  // as representableType: (any QueryRepresentable.Type)? = nil,
+  primaryKey: Bool = false
+) =
+  #externalMacro(
+    module: "StructuredQueriesMacros",
+    type: "ColumnsMacro"
+  )
+
 /// Tells StructuredQueries not to consider the annotated property a column of the table.
 ///
 /// Like SwiftData's `@Transient` macro, but for SQL.
@@ -96,6 +109,10 @@ public macro Ephemeral() =
   named(init(decoder:))
 )
 @attached(member, names: named(Columns))
+@available(iOS, deprecated: 9999, renamed: "Table")
+@available(macOS, deprecated: 9999, renamed: "Table")
+@available(tvOS, deprecated: 9999, renamed: "Table")
+@available(watchOS, deprecated: 9999, renamed: "Table")
 public macro Selection() =
   #externalMacro(
     module: "StructuredQueriesMacros",

Sources/StructuredQueriesCore/Bind.swift

@@ -2,7 +2,7 @@
 ///
 /// It is not common to interact with this type directly. A value of this type is returned from the
 /// `#bind` macro.
-public struct BindQueryExpression<QueryValue: QueryBindable>: QueryExpression {
+public struct BindQueryExpression<QueryValue: QueryRepresentable & QueryExpression>: QueryExpression {
   public let base: QueryValue
 
   public init(

Sources/StructuredQueriesCore/ColumnGroup.swift

@@ -0,0 +1,92 @@
+/// A group of table columns.
+///
+/// Don't create instances of this value directly. Instead, use the `@Table` and `@Columns` macros
+/// to generate values of this type.
+@dynamicMemberLookup
+public struct ColumnGroup<Root: Table, Values: Table>: _TableColumnExpression
+where Values.QueryOutput == Values {
+  public typealias Value = Values
+
+  public var _names: [String] { Values.TableColumns.allColumns.map(\.name) }
+
+  public typealias QueryValue = Values
+
+  public static func allColumns(keyPath: KeyPath<Root, Values>) -> [any TableColumnExpression] {
+    return Values.TableColumns.allColumns.map { column in
+      func open<R, V>(
+        _ column: some TableColumnExpression<R, V>
+      ) -> any TableColumnExpression {
+        let keyPath = keyPath.appending(
+          path: unsafeDowncast(column.keyPath, to: KeyPath<Values, V.QueryOutput>.self)
+        )
+        return TableColumn<Root, V>(
+          column.name,
+          keyPath: keyPath,
+          default: column.defaultValue
+        )
+      }
+      return open(column)
+    }
+  }
+
+  public static func writableColumns(
+    keyPath: KeyPath<Root, Values>
+  ) -> [any WritableTableColumnExpression] {
+    return Values.TableColumns.writableColumns.map { column in
+      func open<R, V>(
+        _ column: some WritableTableColumnExpression<R, V>
+      ) -> any WritableTableColumnExpression {
+        let keyPath = keyPath.appending(
+          path: unsafeDowncast(column.keyPath, to: KeyPath<Values, V.QueryOutput>.self)
+        )
+        return TableColumn<Root, V>(
+          column.name,
+          keyPath: keyPath,
+          default: column.defaultValue
+        )
+      }
+      return open(column)
+    }
+  }
+
+  public let keyPath: KeyPath<Root, Values>
+
+  public init(keyPath: KeyPath<Root, Values>) {
+    self.keyPath = keyPath
+  }
+
+  public var queryFragment: QueryFragment {
+    ColumnGroup.allColumns(keyPath: keyPath).map(\.queryFragment).joined(separator: ", ")
+  }
+
+  public subscript<Member>(
+    dynamicMember keyPath: KeyPath<Values.TableColumns, TableColumn<Values, Member>>
+  ) -> TableColumn<Root, Member> {
+    let column = Values.columns[keyPath: keyPath]
+    return TableColumn<Root, Member>(
+      column.name,
+      keyPath: self.keyPath.appending(path: column.keyPath),
+      default: column.defaultValue
+    )
+  }
+
+  public subscript<Member>(
+    dynamicMember keyPath: KeyPath<Values.TableColumns, GeneratedColumn<Values, Member>>
+  ) -> GeneratedColumn<Root, Member> {
+    let column = Values.columns[keyPath: keyPath]
+    return GeneratedColumn<Root, Member>(
+      column.name,
+      keyPath: self.keyPath.appending(path: column.keyPath),
+      default: column.defaultValue
+    )
+  }
+
+  public subscript<Member>(
+    dynamicMember keyPath: KeyPath<Values.TableColumns, ColumnGroup<Values, Member>>
+  ) -> ColumnGroup<Root, Member> {
+    let column = Values.columns[keyPath: keyPath]
+    return ColumnGroup<Root, Member>(
+      keyPath: self.keyPath.appending(path: column.keyPath)
+    )
+  }
+}

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

@@ -6,9 +6,9 @@ or recursive queries of trees and graphs.
 ## Overview
 
 One can build [common table expressions][] (commonly referred to as CTEs) by using the ``With``
-statement, along with the `@Table` and `@Selection` macros. CTEs allow you to refactor complex
-queries into smaller pieces, and they allow you to execute recursive queries that can traverse
-tree-like and graph-like tables.
+statement, along with the `@Table` macro. CTEs allow you to refactor complex queries into smaller
+pieces, and they allow you to execute recursive queries that can traverse tree-like and graph-like
+tables.
 
 [common table expressions]: https://sqlite.org/lang_with.html
 
@@ -47,15 +47,17 @@ selecting only lists whose average priority of reminders is greater than 1.5 int
 that can then be used in another query.
 
 One can define a new type that represents the data you want to pre-compute as a CTE, and you
-annotate the type with both `@Table` and `@Selection`:
+annotate the type with the `@Table`:
 
 ```swift
-@Table @Selection
+@Table
 struct HighPriorityRemindersList {
   let id: RemindersList.ID
 }
 ```
 
+You can think of this as a "virtual table" of sorts, rather than an actual database table.
+
 Then you can select into this table in the first trailing closure of ``With``:
 
 ```swift
@@ -171,7 +173,7 @@ As a simple example let's construct a query that selects the numbers from 1 to 1
 by defining a CTE data type that holds the data we want to compute:
 
 ```swift
-@Table @Selection
+@Table
 struct Counts {
   let value: Int
 }
@@ -263,13 +265,13 @@ This constructs the CTE table from which we can select and limit to the first 10
 The previous query was a simple example of what is known as a "[recurrence relation][]."
 Another example of a recurrence relation is the Fibonacci sequence, where each term in
 the sequence is the sum of the previous two terms. We can construct a query to compute the
-first 10 Fibonacci numbers by first defining a table selection data type that holds an index
-and its corresponding Fibonacci number, as well as the previous Fibonacci number:
+first 10 Fibonacci numbers by first defining a data type that holds an index and its corresponding
+Fibonacci number, as well as the previous Fibonacci number:
 
 [recurrence relation]: https://en.wikipedia.org/wiki/Recurrence_relation
 
 ```swift
-@Table @Selection
+@Table
 private struct Fibonacci {
   let n: Int
   let prevFib: Int

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

@@ -766,11 +766,11 @@ struct ReminderResult: QueryRepresentable {
 )
 ```
 
-There is also a way to streamline providing the ``QueryRepresentable`` conformance. You can apply the
-`@Selection` macro to your type to generate that conformance for you automatically:
+There is also a way to streamline providing the ``QueryRepresentable`` conformance. You can use the
+`@Table` to describe the datatype you want to decode:
 
 ```swift
-@Selection
+@Table
 struct ReminderResult {
   let title: String
   let isCompleted: Bool
@@ -784,4 +784,7 @@ struct ReminderResult {
 )
 ```
 
+The `@Table` macro can be used to describe any table-like entity. This includes virtual tables,
+database views, common table expressions, and even groups of columns that you'd like to decode.
+
 See <doc:SafeSQLStrings> for more information about the `#sql` macro.

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

@@ -261,17 +261,21 @@ you can use the ``Table/unscoped`` property:
 
 It will often be the case that you want to select very specific data from your database and then
 decode that data into a custom Swift data type. For example, if you are displaying a list of
-reminders and only need their titles for the list, it would be wasteful to decode an array of
-all reminder data. The `@Selection` macro allows you to define a custom data type of only the
-fields you want to decode:
+reminders and only need their titles for the list, it would be wasteful to decode an array of all
+reminder data. The `@Table` macro allows you to define a custom data type of only the fields you
+want to decode:
 
 ```swift
-@Selection
+@Table
 struct ReminderTitle {
   let title: String
 }
 ```
 
+> Note: The `@Table` macro can be used to describe not only database tables, but a number of
+> table-like things, including virtual tables, database views, common table expressions, and even
+> simply groups of columns you'd like to decode together.
+
 Then when selecting the columns for your query you can use this data type:
 
 @Row {
@@ -297,10 +301,10 @@ Then when selecting the columns for your query you can use this data type:
 }
 
 As another example, consider the query that selects all reminders lists with the count of reminders
-in each list. A selection data type can be defined like so:
+in each list. A data type can be defined like so:
 
 ```swift
-@Selection
+@Table
 struct RemindersListWithCount {
   let remindersCount: Int
   let remindersList: RemindersList

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

@@ -108,10 +108,10 @@ To add (or remove) a `DISTINCT` clause from a selection, use ``Select/distinct(_
 }
 
 To bundle selected columns up into a custom data type, you can annotate a struct of decoded results
-with the `@Selection` macro:
+with the `@Table` macro:
 
 ```swift
-@Selection
+@Table
 struct ReminderResult {
   let title: String
   let isCompleted: Bool

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

@@ -31,7 +31,9 @@
 - ``TableColumns``
 - ``TableColumn``
 - ``TableColumnExpression``
+- ``ColumnGroup``
 - ``TableDefinition``
+- ``TableExpression``
 
 ### Scoping
 

Sources/StructuredQueriesCore/Never.swift

@@ -7,6 +7,12 @@ extension Never: Table {
     public static var writableColumns: [any WritableTableColumnExpression] { [] }
   }
 
+  public struct Selection: TableExpression {
+    public typealias QueryValue = Never
+
+    public var allColumns: [any QueryExpression] { [] }
+  }
+
   public static var columns: TableColumns {
     TableColumns()
   }

Sources/StructuredQueriesCore/Operators.swift

@@ -1,4 +1,4 @@
-extension QueryExpression where QueryValue: QueryBindable {
+extension QueryExpression where QueryValue: _OptionalPromotable {
   /// A predicate expression indicating whether two query expressions are equal.
   ///
   /// ```swift
@@ -241,7 +241,7 @@ public func != <QueryValue: QueryBindable>(
   SQLQueryExpression(lhs).isNot(rhs)
 }
 
-extension QueryExpression where QueryValue: QueryBindable {
+extension QueryExpression where QueryValue: _OptionalPromotable {
   /// Returns a predicate expression indicating whether the value of the first expression is less
   /// than that of the second expression.
   ///
@@ -697,7 +697,7 @@ extension QueryExpression where QueryValue == String {
   /// - Parameter collation: A collating sequence name.
   /// - Returns: An expression that is compared using the given collating sequence.
   public func collate(_ collation: Collation) -> some QueryExpression<QueryValue> {
-    BinaryOperator(lhs: self, operator: "COLLATE", rhs: collation)
+    SQLQueryExpression("\(self) COLLATE \(collation)")
   }
 
   /// A predicate expression from this string expression matched against another _via_ the `GLOB`
@@ -816,7 +816,7 @@ extension SQLQueryExpression<String> {
   }
 }
 
-extension QueryExpression where QueryValue: QueryBindable {
+extension QueryExpression where QueryValue: QueryExpression {
   /// Returns a predicate expression indicating whether the expression is in a sequence.
   ///
   /// - Parameter expression: A sequence of expressions.
@@ -850,11 +850,7 @@ extension QueryExpression where QueryValue: QueryBindable {
     _ lowerBound: some QueryExpression<QueryValue>,
     and upperBound: some QueryExpression<QueryValue>
   ) -> some QueryExpression<Bool> {
-    BinaryOperator(
-      lhs: self,
-      operator: "BETWEEN",
-      rhs: SQLQueryExpression("\(lowerBound) AND \(upperBound)")
-    )
+    SQLQueryExpression("\(self) BETWEEN \(lowerBound) AND \(upperBound)")
   }
 }
 
@@ -952,7 +948,7 @@ struct BinaryOperator<QueryValue>: QueryExpression {
   }
 
   var queryFragment: QueryFragment {
-    "(\(lhs) \(`operator`) \(rhs))"
+    "(\(lhs)) \(`operator`) (\(rhs))"
   }
 }
 
@@ -976,15 +972,15 @@ private struct LikeOperator<
   }
 }
 
-extension Sequence where Element: QueryExpression, Element.QueryValue: QueryBindable {
+extension Sequence where Element: QueryExpression, Element.QueryValue: QueryExpression {
   fileprivate typealias Expression = _SequenceExpression<Self>
 }
 
 private struct _SequenceExpression<S: Sequence>: QueryExpression
-where S.Element: QueryExpression, S.Element.QueryValue: QueryBindable {
+where S.Element: QueryExpression, S.Element.QueryValue: QueryExpression {
   typealias QueryValue = S
   let queryFragment: QueryFragment
   init(elements: S) {
-    queryFragment = "(\(elements.map(\.queryFragment).joined(separator: ", ")))"
+    queryFragment = elements.map { "(\($0.queryFragment))" }.joined(separator: ", ")
   }
 }