wip

Author: stephencelis

README.md

@@ -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)
 

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

@@ -22,7 +22,7 @@ that represent those database definitions.
     * [RawRepresentable](#RawRepresentable)
     * [JSON](#JSON)
     * [Tagged identifiers](#Tagged-identifiers)
-* [Primary keyed tables](#Primary-keyed-tables)
+* [Primary-keyed tables](#Primary-keyed-tables)
 * [Grouped columns](#Grouped-columns)
 * [Ephemeral columns](#Ephemeral-columns)
 * [Generated columns](#Generated-columns)
@@ -321,7 +321,7 @@ struct RemindersList: Identifiable {
 }
 ```
 
-### Primary keyed tables
+### Primary-keyed tables
 
 It is possible to let the `@Table` macro know which field of your data type is the primary
 key for the table in the database, and doing so unlocks new APIs for inserting, updating, and
@@ -330,6 +330,7 @@ primary key, or you can explicitly specify it with the `primaryKey:` argument of
 macro:
 
 ```swift
+@Table
 struct Book {
   @Column(primaryKey: true)
   let isbn: String
@@ -443,6 +444,7 @@ database. Such properties must have a default value, and can be specified using
 macro:
 
 ```swift
+@Table
 struct Book {
   @Column(primaryKey: true)
   let isbn: String

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

@@ -293,7 +293,7 @@ Or you can populate an entire record from the freshly-inserted database:
 ### Upserting drafts
 
 At times your application may want to provide the same business logic for creating a new record and
-editing an existing one. Your primary keyed table's `Draft` type can be used for these kinds of
+editing an existing one. Your primary-keyed table's `Draft` type can be used for these kinds of
 flows, and it is possible to create a draft from an existing value using ``TableDraft/init(_:)``:
 
 ```swift

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

@@ -1,11 +1,11 @@
-# Primary keyed tables
+# Primary-keyed tables
 
 Learn how tables with a primary key get extra tools when it comes to inserting, updating, and
 deleting records.
 
 ## Overview
 
-A primary keyed table is one that has a column whose value is unique for the entire table. The most
+A primary-keyed table is one that has a column whose value is unique for the entire table. The most
 common example is an "id" column that holds an integer, UUID, or some other kind of identifier.
 Typically such columns are also initialized by the database so that when inserting rows into the
 table you do not need to specify the primary key. The library provides extra tools that make it
@@ -126,7 +126,7 @@ Or even get back the entire newly inserted row:
 }
 
 At times your application may want to provide the same business logic for creating a new record and
-editing an existing one. Your primary keyed table's `Draft` type can be used for these kinds of
+editing an existing one. Your primary-keyed table's `Draft` type can be used for these kinds of
 flows, and it is possible to create a draft from an existing value using ``TableDraft/init(_:)``:
 
 ```swift
@@ -141,10 +141,10 @@ ReminderForm(
 )
 ```
 
-### Selects, updates, upserts and deletions
+### Selects, updates, upserts, and deletions
 
-Primary keyed tables are also given special APIs for selecting, updating and deleting existing rows
-in the table based on their primary key. For example, every primary keyed table is given a special
+Primary-keyed tables are also given special APIs for selecting, updating and deleting existing rows
+in the table based on their primary key. For example, every primary-keyed table is given a special
 ``PrimaryKeyedTable/find(_:)`` static method for fetching a record by its primary key:
 
 @Row {

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

@@ -1,6 +1,6 @@
 # ``StructuredQueriesCore/PrimaryKeyedTable``
 
-A primary keyed table is one that has a column whose value is unique for the entire table. The most
+A primary-keyed table is one that has a column whose value is unique for the entire table. The most
 common example is an "id" column that holds an integer, UUID, or some other kind of identifier.
 Typically such columns are also initialized by the database so that when inserting rows into the
 table you do not need to specify the primary key. The library provides extra tools that make it
@@ -117,7 +117,7 @@ Reminder
 
 ### Updates and deletions
 
-Primary keyed tables are also given special APIs for updating and deleting existing rows in the
+Primary-keyed tables are also given special APIs for updating and deleting existing rows in the
 table based on their primary key. For example, the ``PrimaryKeyedTable/update(_:)`` method
 allows one to update all the fields of a row with the corresponding primary key:
 

Sources/StructuredQueriesCore/Operators.swift

@@ -1,4 +1,4 @@
-extension QueryExpression where QueryValue: _OptionalPromotable {
+extension QueryExpression where QueryValue: QueryRepresentable {
   /// A predicate expression indicating whether two query expressions are equal.
   ///
   /// ```swift
@@ -77,9 +77,10 @@ extension QueryExpression where QueryValue: _OptionalPromotable {
   ///
   /// - Parameter other: An expression to compare this one to.
   /// - Returns: A predicate expression.
-  public func `is`(
-    _ other: some QueryExpression<QueryValue._Optionalized>
-  ) -> some QueryExpression<Bool> {
+  public func `is`<Other: QueryRepresentable>(
+    _ other: some QueryExpression<Other>
+  ) -> some QueryExpression<Bool>
+  where QueryValue._Optionalized.Wrapped == Other._Optionalized.Wrapped {
     BinaryOperator(lhs: self, operator: "IS", rhs: other)
   }
 
@@ -93,9 +94,10 @@ extension QueryExpression where QueryValue: _OptionalPromotable {
   ///
   /// - Parameter other: An expression to compare this one to.
   /// - Returns: A predicate expression.
-  public func isNot(
+  public func isNot<Other: QueryRepresentable>(
     _ other: some QueryExpression<QueryValue._Optionalized>
-  ) -> some QueryExpression<Bool> {
+  ) -> some QueryExpression<Bool>
+  where QueryValue._Optionalized.Wrapped == Other._Optionalized.Wrapped {
     BinaryOperator(lhs: self, operator: "IS NOT", rhs: other)
   }
 }
@@ -104,6 +106,34 @@ private func isNull<Value>(_ expression: some QueryExpression<Value>) -> Bool {
   (expression as? any _OptionalProtocol).map { $0._wrapped == nil } ?? false
 }
 
+extension QueryExpression where QueryValue: QueryRepresentable & QueryExpression {
+  @_documentation(visibility: private)
+  public func `is`(
+    _ other: _Null<QueryValue>
+  ) -> some QueryExpression<Bool> {
+    BinaryOperator(lhs: self, operator: "IS", rhs: other)
+  }
+
+  @_documentation(visibility: private)
+  public func isNot(
+    _ other: _Null<QueryValue>
+  ) -> some QueryExpression<Bool> {
+    BinaryOperator(lhs: self, operator: "IS NOT", rhs: other)
+  }
+}
+
+public struct _Null<Wrapped: QueryExpression>: QueryExpression {
+  public typealias QueryValue = Wrapped?
+  public var queryFragment: QueryFragment {
+    Wrapped?.none.queryFragment
+  }
+}
+
+extension _Null: ExpressibleByNilLiteral {
+  public init(nilLiteral: ()) {}
+}
+
+// TODO: Remove this when we correctly unwrap `TableColumns` in `join` conditions.
 extension QueryExpression where QueryValue: QueryRepresentable & _OptionalProtocol {
   @_documentation(visibility: private)
   public func eq(_ other: some QueryExpression<QueryValue.Wrapped>) -> some QueryExpression<Bool> {
@@ -140,33 +170,6 @@ extension QueryExpression where QueryValue: QueryRepresentable & _OptionalProtoc
   }
 }
 
-extension QueryExpression where QueryValue: QueryRepresentable & QueryExpression {
-  @_documentation(visibility: private)
-  public func `is`(
-    _ other: _Null<QueryValue>
-  ) -> some QueryExpression<Bool> {
-    BinaryOperator(lhs: self, operator: "IS", rhs: other)
-  }
-
-  @_documentation(visibility: private)
-  public func isNot(
-    _ other: _Null<QueryValue>
-  ) -> some QueryExpression<Bool> {
-    BinaryOperator(lhs: self, operator: "IS NOT", rhs: other)
-  }
-}
-
-public struct _Null<Wrapped: QueryExpression>: QueryExpression {
-  public typealias QueryValue = Wrapped?
-  public var queryFragment: QueryFragment {
-    Wrapped?.none.queryFragment
-  }
-}
-
-extension _Null: ExpressibleByNilLiteral {
-  public init(nilLiteral: ()) {}
-}
-
 // NB: This overload is required due to an overload resolution bug of 'Updates[dynamicMember:]'.
 @_disfavoredOverload
 @_documentation(visibility: private)

Sources/StructuredQueriesCore/PrimaryKeyed.swift

@@ -20,7 +20,7 @@ public protocol TableDraft: Table {
 
   typealias PrimaryKey = PrimaryTable.PrimaryKey
 
-  /// Creates a draft from a primary keyed table.
+  /// Creates a draft from a primary-keyed table.
   init(_ primaryTable: PrimaryTable)
 }
 

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

@@ -75,7 +75,7 @@ struct Row {
 This allows the query to serialize the associated rows into JSON, which are then deserialized into
 a `Row` type. To construct such a query you can use the
 ``StructuredQueriesCore/PrimaryKeyedTableDefinition/jsonGroupArray(distinct:order:filter:)``
-property that is defined on the columns of primary keyed tables:
+property that is defined on the columns of primary-keyed tables:
 
 ```swift
 RemindersList

Tests/StructuredQueriesTests/CommonTableExpressionTests.swift

@@ -384,7 +384,7 @@ extension SnapshotTests {
               all: true,
               Employee
                 .select { EmployeeReport.Columns(id: $0.id, height: $0.height, name: $0.name) }
-                .join(EmployeeReport.all) { $0.bossID.eq($1.id) }
+                .join(EmployeeReport.all) { $0.bossID.is($1.id) }
             )
         } query: {
           EmployeeReport
@@ -397,7 +397,7 @@ extension SnapshotTests {
             UNION ALL
           SELECT "employees"."id" AS "id", "employees"."height" AS "height", "employees"."name" AS "name"
           FROM "employees"
-          JOIN "employeeReports" ON ("employees"."bossID") = ("employeeReports"."id")
+          JOIN "employeeReports" ON ("employees"."bossID") IS ("employeeReports"."id")
         )
         SELECT avg("employeeReports"."height")
         FROM "employeeReports"

Tests/StructuredQueriesTests/SelectTests.swift

@@ -472,14 +472,14 @@ extension SnapshotTests {
 
       assertQuery(
         Reminder.all
-          .fullJoin(User.all) { $0.assignedUserID.eq($1.id) }
+          .fullJoin(User.all) { $0.assignedUserID.is($1.id) }
           .select { ($0.title, $1.name) }
           .limit(2)
       ) {
         """
         SELECT "reminders"."title", "users"."name"
         FROM "reminders"
-        FULL JOIN "users" ON ("reminders"."assignedUserID") = ("users"."id")
+        FULL JOIN "users" ON ("reminders"."assignedUserID") IS ("users"."id")
         LIMIT 2
         """
       } results: {