Add sectioning to @FetchAll

Package.swift

@@ -51,7 +51,7 @@ let package = Package(
     .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.18.4"),
     .package(
       url: "https://github.com/pointfreeco/swift-structured-queries",
-      from: "0.33.0",
+      from: "0.34.0",
       traits: [
         .trait(
           name: "LazyInitializableByDefault",

Package@swift-6.0.swift

@@ -28,7 +28,7 @@ let package = Package(
     .package(url: "https://github.com/pointfreeco/swift-dependencies", from: "1.9.0"),
     .package(url: "https://github.com/pointfreeco/swift-sharing", from: "2.3.0"),
     .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.18.4"),
-    .package(url: "https://github.com/pointfreeco/swift-structured-queries", from: "0.31.0"),
+    .package(url: "https://github.com/pointfreeco/swift-structured-queries", from: "0.34.0"),
     .package(url: "https://github.com/pointfreeco/xctest-dynamic-overlay", from: "1.5.0"),
   ],
   targets: [

Sources/SQLiteData/Documentation.docc/Articles/Fetching.md

@@ -11,6 +11,7 @@ rows, or fetch a single row (_e.g._, an aggregate computation), or if you want t
 queries in a single transaction.
 
   * [`@FetchAll`](#FetchAll)
+    * [Sectioning](#Sectioning)
   * [`@FetchOne`](#FetchOne)
   * [`@Fetch`](#Fetch)
 
@@ -145,6 +146,55 @@ This is a very efficient query that selects only the bare essentials of data tha
 needs to do its job. This kind of query is a lot more cumbersome to perform in SwiftData because
 you must construct a dedicated `FetchDescriptor` value and set its `propertiesToFetch`.
 
+#### Sectioning
+
+It is also possible to group the results of a query into sections by providing a `sectionBy:`
+expression, similar to SwiftData's `@Query(sectionBy:)`. For example, given a `Reminder` table
+with a string `category` column:
+
+```swift
+@FetchAll(Reminder.order(by: \.title), sectionBy: \.category)
+var reminders
+```
+
+The projected value's ``FetchAll/sections`` property groups results into a
+``ResultsSectionCollection``, which can be used to drive a sectioned list:
+
+```swift
+List {
+  ForEach($reminders.sections) { section in
+    Section(section.name ?? "Uncategorized") {
+      ForEach(section) { reminder in
+        Text(reminder.title)
+      }
+    }
+  }
+}
+```
+
+The section expression is prepended to the query's `ORDER BY` clause and evaluated by the database,
+which groups results into a section for each of its distinct values. Sections are ordered by the
+expression, and elements within a section follow the query's order. The expression can be ordered
+explicitly to control the direction and `NULL` ordering of sections:
+
+```swift
+@FetchAll(Reminder.order(by: \.title), sectionBy: { $0.category.desc() })
+var reminders
+```
+
+The expression is not limited to columns: any string SQL expression can be used to section a query,
+and its value names each section:
+
+```swift
+@FetchAll(
+  Reminder.order(by: \.title),
+  sectionBy: {
+    Case().when($0.dueDate.isNot(nil), then: "Scheduled").else("Unscheduled").desc()
+  }
+)
+var reminders
+```
+
 [sq-safe-sql-strings]: https://swiftpackageindex.com/pointfreeco/swift-structured-queries/~/documentation/structuredqueriescore/safesqlstrings
 [structured-queries-gh]: https://github.com/pointfreeco/swift-structured-queries
 [structured-queries-docs]: https://swiftpackageindex.com/pointfreeco/swift-structured-queries/main/documentation/structuredqueriescore/

Sources/SQLiteData/Documentation.docc/Extensions/FetchAll.md

@@ -10,6 +10,15 @@
 - ``init(wrappedValue:_:database:)``
 - ``load(_:database:)``
 
+### Sectioning data
+
+- ``init(wrappedValue:sectionBy:database:)``
+- ``init(wrappedValue:_:sectionBy:database:)``
+- ``load(_:sectionBy:database:)``
+- ``sections``
+- ``ResultsSectionCollection``
+- ``ResultsSection``
+
 ### Accessing state
 
 - ``wrappedValue``
@@ -21,7 +30,10 @@
 
 - ``init(wrappedValue:database:animation:)``
 - ``init(wrappedValue:_:database:animation:)``
+- ``init(wrappedValue:sectionBy:database:animation:)``
+- ``init(wrappedValue:_:sectionBy:database:animation:)``
 - ``load(_:database:animation:)``
+- ``load(_:sectionBy:database:animation:)``
 
 ### Combine integration
 
@@ -31,7 +43,10 @@
 
 - ``init(wrappedValue:database:scheduler:)``
 - ``init(wrappedValue:_:database:scheduler:)``
+- ``init(wrappedValue:sectionBy:database:scheduler:)``
+- ``init(wrappedValue:_:sectionBy:database:scheduler:)``
 - ``load(_:database:scheduler:)``
+- ``load(_:sectionBy:database:scheduler:)``
 
 ### Sharing infrastructure