Better @Table/@Selection composition: nested column groupings, enums, and more (#184)

* Incorporate `@Selection` logic into `@Table`

The `@Selection` and `@Table` type overlap in many ways, but there is
no reason why `@Selection`'s `Columns` type should ever be omitted from
`@Table`, and so this PR introduces the machinery for just that.

Draft for now because there's much to discuss:

  - Should we deprecate `@Selection` entirely, and push people to use
    `@Table` for everything? It might be a little weird, but we've
    already blurred the line with CTEs and database views that maybe we
    should consider `@Table` to mean groups of columns that can be
    assembled in Swift. It's also less library code to
    maintain/document, though it is _more_ code generation (arguably not
    a ton, but who knows the impact on the compiler/binary).

  - Or should we keep `@Selection` around as a lightweight subset of
    `@Table`?

      - If so, should we somehow compose our macro code better, so that
        `@Table` calls down to `@Selection`?

      - Or should it still live in a parallel world, but be updated to
        use some formal machinery, like the `TableExpression` protocol
        introduced in this PR.

* wip

* Support tuple operations with `Table` records

* Support nested tables

* fixes

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Basic docs pass

* wip

* Fixes

* wip

* fixes

* wip

* wip

* db function support

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Infer multi-column when possible

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Docs and tests

* wip

* wip

* wip

* wip

* wip

* wip

* wip

---------

Co-authored-by: Brandon Williams <[email protected]>

Author: stephencelis

Package.resolved

@@ -3,6 +3,12 @@
 import CompilerPluginSupport
 import PackageDescription
 
+#if canImport(FoundationEssentials)
+  import FoundationEssentials
+#else
+  import Foundation
+#endif
+
 let package = Package(
   name: "swift-structured-queries",
   platforms: [
@@ -34,13 +40,17 @@ let package = Package(
     ),
   ],
   traits: [
+    .trait(
+      name: "StructuredQueriesCasePaths",
+      description: "Introduce enum table support to StructuredQueries."
+    ),
     .trait(
       name: "StructuredQueriesTagged",
-      description: "Introduce StructuredQueries conformances to the swift-tagged package.",
-      enabledTraits: []
-    )
+      description: "Introduce StructuredQueries conformances to the swift-tagged package."
+    ),
   ],
   dependencies: [
+    .package(url: "https://github.com/pointfreeco/swift-case-paths", from: "1.0.0"),
     .package(url: "https://github.com/pointfreeco/swift-custom-dump", from: "1.3.3"),
     .package(url: "https://github.com/pointfreeco/swift-dependencies", from: "1.8.1"),
     .package(url: "https://github.com/pointfreeco/swift-macro-testing", from: "0.6.3"),
@@ -61,6 +71,11 @@ let package = Package(
       name: "StructuredQueriesCore",
       dependencies: [
         .product(name: "IssueReporting", package: "xctest-dynamic-overlay"),
+        .product(
+          name: "CasePaths",
+          package: "swift-case-paths",
+          condition: .when(traits: ["StructuredQueriesCasePaths"])
+        ),
         .product(
           name: "Tagged",
           package: "swift-tagged",
@@ -141,6 +156,19 @@ let package = Package(
   swiftLanguageModes: [.v6]
 )
 
+// NB: For local testing in Xcode:
+// if true {
+if ProcessInfo.processInfo.environment["SPI_GENERATE_DOCS"] != nil {
+  package.traits.insert(
+    .default(
+      enabledTraits: [
+        "StructuredQueriesCasePaths",
+        "StructuredQueriesTagged",
+      ]
+    )
+  )
+}
+
 let swiftSettings: [SwiftSetting] = [
   .enableUpcomingFeature("MemberImportVisibility")
   // .unsafeFlags([

Package.swift

@@ -155,7 +155,7 @@ comfortable with the library:
 
   * [Getting started](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/gettingstarted)
   * [Defining your schema](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/definingyourschema)
-  * [Primary keyed tables](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/primarykeyedtables)
+  * [Primary-keyed tables](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/primarykeyedtables)
   * [Safe SQL strings](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/safesqlstrings)
   * [Query cookbook](https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/querycookbook)
 
@@ -174,19 +174,19 @@ As well as more comprehensive example usage:
 ## Demos
 
 There are a number of sample applications that demonstrate how to use StructuredQueries in the
-[SharingGRDB](https://github.com/pointfreeco/sharing-grdb) repo. Check out
-[this](https://github.com/pointfreeco/sharing-grdb/tree/main/Examples) directory to see them all,
+[SQLiteData](https://github.com/pointfreeco/sqlite-data) repo. Check out
+[this](https://github.com/pointfreeco/sqlite-data/tree/main/Examples) directory to see them all,
 including:
 
-  * [Case Studies](https://github.com/pointfreeco/sharing-grdb/tree/main/Examples/CaseStudies):
+  * [Case Studies](https://github.com/pointfreeco/sqlite-data/tree/main/Examples/CaseStudies):
     A number of case studies demonstrating the built-in features of the library.
 
-  * [Reminders](https://github.com/pointfreeco/sharing-grdb/tree/main/Examples/Reminders): A rebuild
+  * [Reminders](https://github.com/pointfreeco/sqlite-data/tree/main/Examples/Reminders): A rebuild
     of Apple's [Reminders][reminders-app-store] app that uses a SQLite database to model the
     reminders, lists and tags. It features many advanced queries, such as searching, and stats
     aggregation.
 
-  * [SyncUps](https://github.com/pointfreeco/sharing-grdb/tree/main/Examples/SyncUps): We also
+  * [SyncUps](https://github.com/pointfreeco/sqlite-data/tree/main/Examples/SyncUps): We also
     rebuilt Apple's [Scrumdinger][scrumdinger] demo application using modern, best practices for
     SwiftUI development, including using this library to query and persist state using SQLite.
 
@@ -198,8 +198,8 @@ including:
 StructuredQueries is built with the goal of supporting any SQL database (SQLite, MySQL, Postgres,
 _etc._), but is currently tuned to work with SQLite. It currently has one official driver:
 
-  * [SharingGRDB](https://github.com/pointfreeco/sharing-grdb): A lightweight replacement for
-    SwiftData and the `@Query` macro. SharingGRDB includes `StructuredQueriesGRDB`, a library that
+  * [SQLiteData](https://github.com/pointfreeco/sqlite-data): A lightweight replacement for
+    SwiftData and the `@Query` macro. SQLiteData includes `StructuredQueriesGRDB`, a library that
     integrates this one with the popular [GRDB](https://github.com/groue/GRDB.swift) SQLite library.
 
 If you are interested in building a StructuredQueries integration for another database library,
@@ -220,7 +220,7 @@ it's as simple as adding it to your `Package.swift`:
 
 ``` swift
 dependencies: [
-  .package(url: "https://github.com/pointfreeco/swift-structured-queries", from: "0.17.0"),
+  .package(url: "https://github.com/pointfreeco/swift-structured-queries", from: "0.22.0"),
 ]
 ```
 
@@ -231,16 +231,21 @@ And then adding the product to any target that needs access to the library:
 ```
 
 If you are on Swift 6.1 or greater, you can enable package traits that extend the library with
-support for other libraries. For example, you can introduce type-safe identifiers to your tables
-_via_ [Tagged](https://github.com/pointfreeco/swift-tagged) by enabling the
-`StructuredQueriesTagged` trait:
+support for other libraries:
+
+  * `StructuredQueriesCasePaths`: Adds support for single-table inheritance _via_ "enum" tables by
+    leveraging the [CasePaths](https://github.com/pointfreeco/swift-case-paths) library.
+
+  * `StructuredQueriesTagged`: Adds support for type-safe identifiers _via_
+    the [Tagged](https://github.com/pointfreeco/swift-tagged) library.
 
 ```diff
  dependencies: [
    .package(
      url: "https://github.com/pointfreeco/swift-structured-queries",
-     from: "0.17.0",
+     from: "0.22.0",
 +    traits: [
++      "StructuredQueriesCasePaths",
 +      "StructuredQueriesTagged",
 +    ]
    ),

README.md

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

Sources/StructuredQueries/Documentation.docc/StructuredQueries.md

@@ -2,22 +2,25 @@ import StructuredQueriesCore
 
 /// Defines and implements a conformance to the ``/StructuredQueriesCore/Table`` protocol.
 ///
-/// - Parameter name: The table's name. Defaults to a lower-camel-case pluralization of the type,
-///   _e.g._ `RemindersList` becomes `"remindersLists"`.
+/// - Parameters
+///   - name: The table's name. Defaults to a lower-camel-case pluralization of the type,
+///     _e.g._ `RemindersList` becomes `"remindersLists"`.
+///   - schemaName: The table's schema name.
 @attached(
   extension,
   conformances: Table,
   PartialSelectStatement,
   PrimaryKeyedTable,
   names: named(From),
   named(columns),
+  named(_columnWidth),
   named(init(_:)),
   named(init(decoder:)),
   named(QueryValue),
   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 = "",
@@ -28,38 +31,7 @@ public macro Table(
     type: "TableMacro"
   )
 
-/// Customizes a column generated by the ``/StructuredQueriesCore/Table`` protocol.
-///
-/// - Parameters:
-///   - name: The column's name. Defaults to the property's name, _e.g._ 'id' becomes `"id"`.
-///   - representableType: A type that represents the property type in a query expression. For types
-///     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.
-@attached(peer)
-public macro Column(
-  _ name: String = "",
-  as representableType: (any QueryRepresentable.Type)? = nil,
-  generated: GeneratedColumnStorage? = nil,
-  primaryKey: Bool = false
-) =
-  #externalMacro(
-    module: "StructuredQueriesMacros",
-    type: "ColumnMacro"
-  )
-
-/// Tells StructuredQueries not to consider the annotated property a column of the table.
-///
-/// Like SwiftData's `@Transient` macro, but for SQL.
-@attached(peer)
-public macro Ephemeral() =
-  #externalMacro(
-    module: "StructuredQueriesMacros",
-    type: "EphemeralMacro"
-  )
-
-/// Defines the ability for a type to be selected from a query.
+/// Defines a "selection" of columns that can be decoded from a query.
 ///
 /// When selecting tables and fields from a query, this data is bundled up into a tuple:
 ///
@@ -87,19 +59,77 @@ public macro Ephemeral() =
 /// // [RemindersListWithReminderCount]
 /// ```
 ///
-/// The ``Table(_:)`` and `@Selection` macros can be composed together to describe a virtual table
-/// or common table expression.
+/// > Tip: `@Selection`s can also be used to build up common table expressions.
+///
+/// - Parameter name: The selection's name, _i.e._ for a common table expression. Defaults to a
+///   lower-camel-case pluralization of the type, _e.g._ `RemindersList` becomes `"remindersLists"`.
 @attached(
   extension,
   conformances: _Selection,
-  names: named(Columns),
-  named(init(decoder:))
+  Table,
+  PartialSelectStatement,
+  PrimaryKeyedTable,
+  names: named(From),
+  named(columns),
+  named(_columnWidth),
+  named(init(_:)),
+  named(init(decoder:)),
+  named(QueryValue),
+  named(schemaName),
+  named(tableName)
 )
-@attached(member, names: named(Columns))
-public macro Selection() =
+@attached(member, names: named(Draft), named(Selection), named(TableColumns))
+@attached(memberAttribute)
+public macro Selection(
+  _ name: String = ""
+) =
+  #externalMacro(
+    module: "StructuredQueriesMacros",
+    type: "TableMacro"
+  )
+
+/// Customizes a column generated by the ``/StructuredQueriesCore/Table`` protocol.
+///
+/// - Parameters:
+///   - name: The column's name. Defaults to the property's name, _e.g._ 'id' becomes `"id"`.
+///   - representableType: A type that represents the property type in a query expression. For types
+///     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 primary key.
+@attached(peer)
+public macro Column(
+  _ name: String = "",
+  as representableType: (any QueryRepresentable.Type)? = nil,
+  generated: GeneratedColumnStorage? = nil,
+  primaryKey: Bool = false
+) =
+  #externalMacro(
+    module: "StructuredQueriesMacros",
+    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: "SelectionMacro"
+    type: "ColumnsMacro"
+  )
+
+/// Tells StructuredQueries not to consider the annotated property a column of the table.
+///
+/// Like SwiftData's `@Transient` macro, but for SQL.
+@attached(peer)
+public macro Ephemeral() =
+  #externalMacro(
+    module: "StructuredQueriesMacros",
+    type: "EphemeralMacro"
   )
 
 /// Explicitly bind a value to a query.

Sources/StructuredQueries/Macros.swift

@@ -2,7 +2,8 @@
 ///
 /// 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(