wip

Author: stephencelis

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

@@ -392,7 +392,7 @@ let rows = remindersLists.map { remindersList in
 
 This can work, but it's incredibly inefficient, a lot of boilerplate, and prone to mistakes. And
 this is doing work that SQL actually excels at. In fact, the condition inside the `filter` looks
-suspiciously like a join constraint, which should give us a hint that what we are doing is not 
+suspiciously like a join constraint, which should give us a hint that what we are doing is not
 quite right.
 
 A better way to do this is to use the `@Selection` macro described above
@@ -411,23 +411,23 @@ struct Row {
 > Note: `Reminder` must conform to `Codable` to be able to use ``JSONRepresentation``.
 
 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 
-``PrimaryKeyedTableDefinition/jsonGroupArray`` property that is defined on the columns of 
- [primary keyed tables](<doc:PrimaryKeyedTables>):
+a `Row` type. To construct such a query you can use the
+``PrimaryKeyedTableDefinition/jsonGroupArray(order:filter:)`` property that is defined on the
+columns of [primary keyed tables](<doc:PrimaryKeyedTables>):
 
 ```swift
 RemindersList
   .join(Reminder.all) { $0.id.eq($1.remindersListID) }
-  .select { 
+  .select {
     Row.Columns(
       remindersList: $0,
-      reminders: $1.jsonGroupArray
+      reminders: $1.jsonGroupArray()
     )
   }
 ```
 
-This allows you to fetch all of the data in a single SQLite query and decode the data into a 
-collection of `Row` values. There is an extra cost associated with decoding the JSON object, 
+This allows you to fetch all of the data in a single SQLite query and decode the data into a
+collection of `Row` values. There is an extra cost associated with decoding the JSON object,
 but that cost may be smaller than executing multiple SQLite requests and transforming the data
 into `Row` manually, not to mention the additional code you need to write and maintain to process
 the data.

Sources/StructuredQueriesCore/SQLite/JSONFunctions.swift

@@ -59,7 +59,7 @@ extension PrimaryKeyedTableDefinition where QueryValue: Codable & Sendable {
   ///       .select {
   ///         Row.Columns(
   ///           remindersList: $0,
-  ///           reminders: $1.jsonGroupArray
+  ///           reminders: $1.jsonGroupArray()
   ///         )
   ///       }
   ///     ```
@@ -85,13 +85,15 @@ extension PrimaryKeyedTableDefinition where QueryValue: Codable & Sendable {
   /// }
   ///
   /// > Note: If the primary key of the row is NULL, then the object is omitted from the array.
-  public var jsonGroupArray: some QueryExpression<JSONRepresentation<[QueryValue]>> {
-    SQLQueryExpression(
-      "json_group_array(\(jsonObject)) filter(where \(self.primaryKey.isNot(nil)))"
-    )
+  public func jsonGroupArray(
+    order: (some QueryExpression)? = Bool?.none,
+    filter: (some QueryExpression<Bool>)? = Bool?.none
+  ) -> some QueryExpression<JSONRepresentation<[QueryValue]>> {
+    let filter = filter.map { primaryKey.isNot(nil) && $0 } ?? primaryKey.isNot(nil)
+    return jsonObject.jsonGroupArray(order: order, filter: filter)
   }
 
-  private var jsonObject: some QueryExpression<JSONRepresentation<QueryValue>> {
+  private var jsonObject: some QueryExpression<QueryValue> {
     func open<TableColumn: TableColumnExpression>(_ column: TableColumn) -> QueryFragment {
       switch TableColumn.QueryValue.self {
       case is Bool.Type:

Tests/StructuredQueriesTests/JSONFunctionsTests.swift

@@ -112,21 +112,21 @@ extension SnapshotTests {
             ReminderRow.Columns(
               assignedUser: user,
               reminder: reminder,
-              tags: #sql("\(tag.jsonGroupArray)")
+              tags: #sql("\(tag.jsonGroupArray())")
             )
           }
           .limit(2)
       ) {
         """
-        SELECT "users"."id", "users"."name" AS "assignedUser", "reminders"."id", "reminders"."assignedUserID", "reminders"."dueDate", "reminders"."isCompleted", "reminders"."isFlagged", "reminders"."notes", "reminders"."priority", "reminders"."remindersListID", "reminders"."title" AS "reminder", json_group_array(iif(("tags"."id" IS NULL), NULL, json_object('id', json_quote("tags"."id"), 'name', json_quote("tags"."name")))) filter(where ("tags"."id" IS NOT NULL)) AS "tags"
+        SELECT "users"."id", "users"."name" AS "assignedUser", "reminders"."id", "reminders"."assignedUserID", "reminders"."dueDate", "reminders"."isCompleted", "reminders"."isFlagged", "reminders"."notes", "reminders"."priority", "reminders"."remindersListID", "reminders"."title" AS "reminder", json_group_array(iif(("tags"."id" IS NULL), NULL, json_object('id', json_quote("tags"."id"), 'name', json_quote("tags"."name")))) FILTER (WHERE coalesce(NULL, ("tags"."id" IS NOT NULL))) AS "tags"
         FROM "reminders"
         LEFT JOIN "reminderTags" ON ("reminders"."id" = "reminderTags"."reminderID")
         LEFT JOIN "tags" ON ("reminderTags"."tagID" = "tags"."id")
         LEFT JOIN "users" ON ("reminders"."assignedUserID" = "users"."id")
         GROUP BY "reminders"."id"
         LIMIT 2
         """
-      }results: {
+      } results: {
         """
         ┌──────────────────────────────────────────────┐
         │ ReminderRow(                                 │
@@ -194,20 +194,20 @@ extension SnapshotTests {
           .select { remindersList, reminder in
             RemindersListRow.Columns(
               remindersList: remindersList,
-              reminders: #sql("\(reminder.jsonGroupArray)")
+              reminders: #sql("\(reminder.jsonGroupArray())")
             )
           }
           .limit(1)
       ) {
         """
-        SELECT "remindersLists"."id", "remindersLists"."color", "remindersLists"."name" AS "remindersList", json_group_array(iif(("reminders"."id" IS NULL), NULL, json_object('id', json_quote("reminders"."id"), 'assignedUserID', json_quote("reminders"."assignedUserID"), 'dueDate', json_quote("reminders"."dueDate"), 'isCompleted', iif("reminders"."isCompleted" = 0, json('false'), json('true')), 'isFlagged', iif("reminders"."isFlagged" = 0, json('false'), json('true')), 'notes', json_quote("reminders"."notes"), 'priority', json_quote("reminders"."priority"), 'remindersListID', json_quote("reminders"."remindersListID"), 'title', json_quote("reminders"."title")))) filter(where ("reminders"."id" IS NOT NULL)) AS "reminders"
+        SELECT "remindersLists"."id", "remindersLists"."color", "remindersLists"."name" AS "remindersList", json_group_array(iif(("reminders"."id" IS NULL), NULL, json_object('id', json_quote("reminders"."id"), 'assignedUserID', json_quote("reminders"."assignedUserID"), 'dueDate', json_quote("reminders"."dueDate"), 'isCompleted', iif("reminders"."isCompleted" = 0, json('false'), json('true')), 'isFlagged', iif("reminders"."isFlagged" = 0, json('false'), json('true')), 'notes', json_quote("reminders"."notes"), 'priority', json_quote("reminders"."priority"), 'remindersListID', json_quote("reminders"."remindersListID"), 'title', json_quote("reminders"."title")))) FILTER (WHERE coalesce(NULL, ("reminders"."id" IS NOT NULL))) AS "reminders"
         FROM "remindersLists"
         LEFT JOIN "reminders" ON ("remindersLists"."id" = "reminders"."remindersListID")
         WHERE NOT ("reminders"."isCompleted")
         GROUP BY "remindersLists"."id"
         LIMIT 1
         """
-      }results: {
+      } results: {
         """
         ┌────────────────────────────────────────────────┐
         │ RemindersListRow(                              │