@codecks/fetch 0.1.5 → 0.1.7

package/schema/query-syntax.md

@@ -0,0 +1,184 @@
+# Query Syntax Reference
+
+## Basic Query
+
+```ts
+const {fetchFromRoot, fetchInstance} = buildFetchersWithSimpleLoader({
+  token: "your-api-token",
+});
+
+// Fetch from root entry points
+const result = await fetchFromRoot({
+  account: {fields: ["name", "subdomain"]},
+});
+// result.account.name, result.account.subdomain
+
+// Fetch a specific instance by model + ID
+const card = await fetchInstance("card", cardId, {
+  fields: ["title", "status", "effort"],
+});
+// card.title, card.status, card.effort
+```
+
+## Field Selection
+
+`fields` is an array of field names to include in the response.
+Key fields (like `cardId` for card, `id` for most models) are always returned.
+The meta fields `~model` and `~key` are always included.
+
+```ts
+{fields: ["title", "status", "createdAt"]}
+```
+
+## Nested Relations
+
+Use `relations` to traverse the object graph:
+
+```ts
+const result = await fetchFromRoot({
+  account: {
+    fields: ["name"],
+    relations: {
+      cards: {
+        fields: ["title", "status"],
+        relations: {
+          assignee: {fields: ["name"]},
+          deck: {fields: ["title"]},
+        },
+      },
+    },
+  },
+});
+```
+
+## hasMany Variants
+
+hasMany relations support different query types:
+
+### Default (array)
+```ts
+{cards: {fields: ["title", "status"]}}
+// returns: cards: Array<{title, status, ...}>
+```
+
+### count
+```ts
+{cards: {type: "count", as: "cardCount"}}
+// returns: cardCount: number
+```
+
+### exists
+```ts
+{cards: {type: "exists", as: "hasCards"}}
+// returns: hasCards: boolean
+```
+
+### first
+```ts
+{cards: {type: "first", as: "latestCard", orderBy: "-createdAt", fields: ["title"]}}
+// returns: latestCard: {title, ...} | null
+```
+
+### Multiple variants of the same relation
+Pass an array of queries with `as` aliases:
+```ts
+{
+  cards: [
+    {as: "openCards", filter: {status: "started"}, fields: ["title"]},
+    {as: "cardCount", type: "count"},
+  ]
+}
+// returns: openCards: Array<...>, cardCount: number
+```
+
+## Filtering (hasMany only)
+
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      status: "started",                          // exact match
+      effort: {op: "gte", value: 3},              // comparison: lt, lte, gt, gte
+      assigneeId: {op: "eq", value: userId},      // equality: eq, neq (supports null)
+      tags: {op: "has", value: "bug"},             // array contains
+      title: {op: "contains", value: "search"},   // string contains
+      priority: {op: "in", value: ["high", "critical"]},  // in set
+    },
+  },
+}
+```
+
+### Logical operators
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      $or: [
+        {status: "started"},
+        {status: "done"},
+      ],
+    },
+  },
+}
+```
+
+### Filter by relation
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      assignee: {name: "Alice"},           // cards where assignee.name = "Alice"
+      "!deck": {isDeleted: "true"},        // negated: cards NOT in deleted decks
+    },
+  },
+}
+```
+
+## Ordering (hasMany only)
+
+```ts
+// Simple: field name, prefix with - for descending
+{cards: {fields: ["title"], orderBy: "createdAt"}}
+{cards: {fields: ["title"], orderBy: "-createdAt"}}
+
+// Multiple
+{cards: {fields: ["title"], orderBy: ["status", "-createdAt"]}}
+```
+
+## Pagination (hasMany only)
+
+A subset (`limit`/`offset`) requires an `orderBy` — the API rejects a subset
+without an order. `offset` is only meaningful together with `limit`. The types
+enforce this, so `limit` on its own is a compile error.
+
+```ts
+{cards: {fields: ["title"], orderBy: "-createdAt", limit: 10, offset: 20}}
+```
+
+## `fkAsArray` relations (limited capabilities)
+
+A handful of hasMany relations are stored server-side as a plain id-array column
+rather than a joined table. These are flagged as `fkAsArray` on their model
+pages and currently are:
+
+- `card`: `childCards`, `inDeps`, `outDeps`, `cardReferences`, `attachments`
+- `workflowItem`: `inDeps`, `outDeps`
+
+They support **only** plain selection (`fields` + nested `relations`) and the
+`count`/`exists` aggregates. `filter`, `orderBy`, `limit`, `offset`, and
+`type: "first"` are not supported (the API rejects them), and the types reflect
+that.
+
+```ts
+{childCards: {fields: ["cardId"]}}      // OK → array
+{childCards: {type: "count", as: "n"}}  // OK → number
+{childCards: {type: "exists", as: "hasChildren"}} // OK → boolean
+
+// compile errors:
+{childCards: {fields: ["cardId"], orderBy: "accountSeq"}}
+{childCards: {fields: ["cardId"], limit: 50, orderBy: "accountSeq"}}
+{childCards: {fields: ["cardId"], filter: {status: "started"}}}
+```