Merge remote-tracking branch 'origin/main' into coding-keys

Author: mbrandonw

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     name: macOS
     strategy:
       matrix:
-        xcode: ["26.2"]
+        xcode: ["26.6"]
     runs-on: macos-26
     steps:
       - uses: actions/checkout@v5

Sources/StructuredQueries/Macros.swift

@@ -210,12 +210,6 @@ 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.
-///   - lazyInitializable: Optionalize this column group in the generated `Draft` type so it can be
-///     initialized later (by you, or by the database on insert).
 @available(*, deprecated, renamed: "Column")
 @attached(peer)
 public macro Columns(

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

@@ -254,8 +254,8 @@ Notice that you can return any number of orders for the query as a tuple, and yo
 which orders are in a descending versus ascending fashion.
 
 And finally, suppose we wanted to further customize the above query by limiting the results to 10
-rows and selecting the 2nd page of results. This can be done using the ``Table/limit(_:offset:)``
-method:
+rows and selecting the 2nd page of results. This can be done using the ``Table/limit(_:)``
+and ``Table/offset(_:)`` methods:
 
 @Row {
   @Column {
@@ -272,7 +272,8 @@ method:
          $0.priority.desc(),
          $0.title)
       }
-      .limit(10, offset: 10)
+      .limit(10)
+      .offset(10)
     // => [String]
     ```
   }

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

@@ -40,6 +40,7 @@ Explore the full list of available functions below.
 
 - ``QueryExpression/??(_:_:)``
 - ``QueryExpression/ifnull(_:)``
+- ``QueryExpression/nullif(_:)``
 
 ### Bytes
 

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

@@ -691,7 +691,8 @@ enum Ordering {
 
 ### Paginating results
 
-The `limit(_:offset:)` function is used to change a query's `LIMIT` and `OFFSET` clauses.
+The `limit(_:)` and `offset(_:)` functions are used to change a query's `LIMIT` and `OFFSET`
+clauses.
 
 @Row {
   @Column {
@@ -710,7 +711,9 @@ The `limit(_:offset:)` function is used to change a query's `LIMIT` and `OFFSET`
 @Row {
   @Column {
     ```swift
-    Reminder.limit(10, offset: 10)
+    Reminder
+      .limit(10)
+      .offset(10)
     ```
   }
   @Column {
@@ -721,53 +724,62 @@ The `limit(_:offset:)` function is used to change a query's `LIMIT` and `OFFSET`
   }
 }
 
-Multiple chained calls to `limit` will override the limit and offset to the last call, using the
-existing offset if none is provided:
+Multiple chained calls will override the clause of the last call:
 
 @Row {
   @Column {
     ```swift
     Reminder
-      .limit(10, offset: 10)
+      .limit(10)
+      .offset(10)
       .limit(20)
     ```
   }
   @Column {
     ```sql
     SELECT … FROM "reminders"
-    LIMIT 20
+    LIMIT 20 OFFSET 10
     ```
   }
 }
 
+Passing `nil` will leave the clause untouched, which makes it easy to apply a limit or offset from
+optional data:
+
 @Row {
   @Column {
     ```swift
+    let offset: Int? = nil
     Reminder
       .limit(10)
-      .limit(20, offset: 20)
+      .offset(offset)
     ```
   }
   @Column {
     ```sql
     SELECT … FROM "reminders"
-    LIMIT 20 OFFSET 20
+    LIMIT 10
     ```
   }
 }
 
+And both functions have result builder variants that can build the clause from the query's tables,
+where producing no expression is equivalent to passing `nil`:
+
 @Row {
   @Column {
     ```swift
-    Reminder
-      .limit(10, offset: 10)
-      .limit(20, offset: 20)
+    Reminder.limit { _ in
+      if isPaginated {
+        pageSize
+      }
+    }
     ```
   }
   @Column {
     ```sql
     SELECT … FROM "reminders"
-    LIMIT 20 OFFSET 20
+    LIMIT 10
     ```
   }
 }

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

@@ -16,7 +16,8 @@
 - ``group(by:)``
 - ``having(_:)``
 - ``order(by:)``
-- ``limit(_:offset:)``
+- ``limit(_:)``
+- ``offset(_:)``
 - ``count(filter:)``
 - ``find(_:)``
 

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

@@ -15,7 +15,8 @@
 - ``group(by:)``
 - ``having(_:)``
 - ``order(by:)``
-- ``limit(_:offset:)``
+- ``limit(_:)``
+- ``offset(_:)``
 - ``count(filter:)``
 - ``insert(_:values:onConflict:where:doUpdate:where:)``
 - ``insert(_:select:onConflict:where:doUpdate:where:)``

Sources/StructuredQueriesCore/Internal/Deprecations.swift

@@ -1,5 +1,109 @@
 import Foundation
 
+// NB: Deprecated after 0.33.3:
+
+extension Table {
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public static func limit(
+    _ maxLength: (TableColumns) -> some QueryExpression<Int>,
+    offset: ((TableColumns) -> some QueryExpression<Int>)?
+  ) -> SelectOf<Self> {
+    Where().limit(maxLength, offset: offset)
+  }
+
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public static func limit(_ maxLength: Int, offset: Int?) -> SelectOf<Self> {
+    Where().limit(maxLength, offset: offset)
+  }
+}
+
+extension Where {
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public func limit(
+    _ maxLength: (From.TableColumns) -> some QueryExpression<Int>,
+    offset: ((From.TableColumns) -> some QueryExpression<Int>)?
+  ) -> SelectOf<From> {
+    asSelect().limit(maxLength, offset: offset)
+  }
+
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public func limit(_ maxLength: Int, offset: Int?) -> SelectOf<From> {
+    asSelect().limit(maxLength, offset: offset)
+  }
+}
+
+extension Select {
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public func limit<each J: Table>(
+    _ maxLength: (From.TableColumns, repeat (each J).TableColumns) -> some QueryExpression<Int>,
+    offset: ((From.TableColumns, repeat (each J).TableColumns) -> any QueryExpression<Int>)?
+  ) -> Self
+  where Joins == (repeat each J) {
+    limit(maxLength(From.columns, repeat (each J).columns))
+      .offset(offset?(From.columns, repeat (each J).columns))
+  }
+
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public func limit(
+    _ maxLength: (From.TableColumns, Joins.TableColumns) -> some QueryExpression<Int>,
+    offset: ((From.TableColumns, Joins.TableColumns) -> any QueryExpression<Int>)?
+  ) -> Self
+  where Joins: Table {
+    limit(maxLength(From.columns, Joins.columns))
+      .offset(offset?(From.columns, Joins.columns))
+  }
+
+  @available(*, deprecated, message: "Use 'limit(_:)' and 'offset(_:)', instead.")
+  public func limit<each J: Table>(_ maxLength: Int, offset: Int?) -> Self
+  where Joins == (repeat each J) {
+    limit(maxLength).offset(offset)
+  }
+}
+
+// NB: Deprecated after 0.33.1:
+
+extension QueryExpression where QueryValue == String {
+  @available(*, deprecated, message: "Prefer 'like(\"\\(other)%\")' instead")
+  public func hasPrefix(_ other: some StringProtocol) -> some QueryExpression<Bool> {
+    like("\(other)%")
+  }
+
+  @available(*, deprecated, message: "Prefer 'like(\"%\\(other)\")' instead")
+  public func hasSuffix(_ other: some StringProtocol) -> some QueryExpression<Bool> {
+    like("%\(other)")
+  }
+
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Prefer 'like(\"%\\(other)%\")' instead")
+  public func contains(_ other: some StringProtocol) -> some QueryExpression<Bool> {
+    return like("%\(other)%")
+  }
+}
+
+extension Sequence where Element: QueryBindable {
+  @available(*, deprecated, message: "Prefer 'element.in(self)' instead")
+  public func contains(
+    _ element: some QueryExpression<Element.QueryValue>
+  ) -> some QueryExpression<Bool> {
+    element.in(self)
+  }
+}
+
+extension ClosedRange where Bound: QueryBindable {
+  @available(
+    *,
+    deprecated,
+    message: "Prefer 'element.between(lowerBound, and: upperBound)' instead"
+  )
+  public func contains(
+    _ element: some QueryExpression<Bound.QueryValue>
+  ) -> some QueryExpression<Bool> {
+    element.between(lowerBound, and: upperBound)
+  }
+}
+
 // NB: Deprecated after 0.32.0:
 
 extension TableDraft {

Sources/StructuredQueriesCore/Operators.swift

@@ -707,52 +707,6 @@ extension QueryExpression where QueryValue == String {
   ) -> some QueryExpression<Bool> {
     LikeOperator(string: self, pattern: "\(pattern)", escape: escape)
   }
-
-  /// A predicate expression from this string expression matched against another _via_ the `LIKE`
-  /// operator given a prefix.
-  ///
-  /// ```swift
-  /// Reminder.where { $0.title.hasPrefix("get") }
-  /// // SELECT … FROM "reminders" WHERE ("reminders"."title" LIKE 'get%')
-  /// ```
-  ///
-  /// - Parameter other: A string expression describing the prefix.
-  /// - Returns: A predicate expression.
-  @available(*, deprecated, message: "Prefer 'like(\"\\(other)%\")' instead")
-  public func hasPrefix(_ other: some StringProtocol) -> some QueryExpression<Bool> {
-    like("\(other)%")
-  }
-
-  /// A predicate expression from this string expression matched against another _via_ the `LIKE`
-  /// operator given a suffix.
-  ///
-  /// ```swift
-  /// Reminder.where { $0.title.hasSuffix("get") }
-  /// // SELECT … FROM "reminders" WHERE ("reminders"."title" LIKE '%get')
-  /// ```
-  ///
-  /// - Parameter other: A string expression describing the suffix.
-  /// - Returns: A predicate expression.
-  @available(*, deprecated, message: "Prefer 'like(\"%\\(other)\")' instead")
-  public func hasSuffix(_ other: some StringProtocol) -> some QueryExpression<Bool> {
-    like("%\(other)")
-  }
-
-  /// A predicate expression from this string expression matched against another _via_ the `LIKE`
-  /// operator given an infix.
-  ///
-  /// ```swift
-  /// Reminder.where { $0.title.contains("get") }
-  /// // SELECT … FROM "reminders" WHERE ("reminders"."title" LIKE '%get%')
-  /// ```
-  ///
-  /// - Parameter other: A string expression describing the infix.
-  /// - Returns: A predicate expression.
-  @_disfavoredOverload
-  @available(*, deprecated, message: "Prefer 'like(\"%\\(other)%\")' instead")
-  public func contains(_ other: some StringProtocol) -> some QueryExpression<Bool> {
-    return like("%\(other)%")
-  }
 }
 
 extension SQLQueryExpression<String> {
@@ -855,42 +809,6 @@ extension QueryExpression where QueryValue: QueryExpression {
   }
 }
 
-extension Sequence where Element: QueryBindable {
-  /// Returns a predicate expression indicating whether the sequence contains the given expression.
-  ///
-  /// An alias for ``QueryExpression/in(_:)``, flipped.
-  ///
-  /// - Parameter element: An element.
-  /// - Returns: A predicate expression indicating whether the expression is in this sequence
-  @available(*, deprecated, message: "Prefer 'element.in(self)' instead")
-  public func contains(
-    _ element: some QueryExpression<Element.QueryValue>
-  ) -> some QueryExpression<Bool> {
-    element.in(self)
-  }
-}
-
-extension ClosedRange where Bound: QueryBindable {
-  /// Returns a predicate expression indicating whether the given expression is contained within
-  /// this range.
-  ///
-  /// An alias for ``QueryExpression/between(_:and:)``, flipped.
-  ///
-  /// - Parameter element: An element.
-  /// - Returns: A predicate expression indicating whether the given element is between this range's
-  ///   bounds.
-  @available(
-    *,
-    deprecated,
-    message: "Prefer 'element.between(lowerBound, and: upperBound)' instead"
-  )
-  public func contains(
-    _ element: some QueryExpression<Bound.QueryValue>
-  ) -> some QueryExpression<Bool> {
-    element.between(lowerBound, and: upperBound)
-  }
-}
-
 extension Statement where QueryValue: QueryBindable {
   /// Returns a predicate expression indicating whether this subquery contains the given element.
   ///