@softr/sdk 0.0.25 → 0.0.26-alpha-0

package/skills/softr-sdk/reading-records/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: reading-records
 description: >-
-  Fetch records from a Softr datasource inside a server function: ds.list and
-  ds.get from @softr/sdk/server, the q query builder (q.text, q.number,
-  q.boolean, q.date, q.array, q.and, q.or, q.asc, q.desc), q.select field
-  aliasing, filtering, sorting, the 20-record default and 100-record cap, and
-  nextOffset pagination. Reads only. Mutations, workflows, integrations, metrics
-  and chart data are not covered.
+  Fetch records from a Softr datasource inside a server function: declaring a
+  read with defineAction, ds.list and ds.get from @softr/sdk/server, the where
+  and orderBy callbacks, field aliases, the 20-record default and 100-record
+  cap, and nextOffset pagination. Reads only. Mutations, workflows,
+  integrations, charts and metrics are not covered.
 metadata:
   type: sub-skill
   library: softr-sdk
@@ -23,53 +22,37 @@ metadata:
 
 ```ts
 import { createServerFn } from '@tanstack/react-start'
+import { defineAction } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
-import { q } from '@softr/sdk'
 ```
 
-Every `ds` call names its datasource by an opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id, and it is never derived from the table's name — `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
+`ds` is server-only. `defineAction` only declares data operations, so it ships on the root entrypoint and the declaration can sit anywhere.
 
-**The datasource id must be a string literal at the call site.** Do not assign it to a variable and pass the variable. Write the UUID directly as the first argument:
+## Declare the read
 
-```ts
-// correct
-ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { ... })
-
-// wrong
-const POSTS = '8ffb4814-b028-4496-b679-7face2167ebc'
-ds.list(POSTS, { ... })
-```
-
-A record comes back as `{ id: string; fields: Record<string, unknown> }`. When you write a TypeScript type for the fields, the shape of each value depends on the Softr field type — see [references/field-types.md](./references/field-types.md) for the full mapping.
-
-## Typing record fields
-
-Declare a local type for the records you fetch using `SoftrRecord<Fields>`. Use the shapes from the field-types reference, not guesses from the field name. The most common mistake is treating SELECT and LINKED_RECORD fields as strings — they are objects:
+Every `ds` call takes an action: which datasource, which fields, who may run it.
 
 ```ts
-import type { SoftrRecord } from '@softr/sdk'
-
-type Product = SoftrRecord<{
-  name: string                            // SINGLE_LINE_TEXT
-  price: number | null                    // CURRENCY
-  category: { id: string; label: string } // SELECT — not a string
-  supplier: { id: string; label: string } // LINKED_RECORD — not a string
-}>
+const publishedPosts = defineAction({
+  id: 'publishedPosts',
+  datasource: '8ffb4814-b028-4496-b679-7face2167ebc',
+  operation: 'read',
+  fields: {
+    title: 'fZk3Qm9pLw2Xa1',      // SINGLE_LINE_TEXT
+    published: 'Ru7bVx2cNq0Ed9',  // CHECKBOX
+    publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
+    views: 'mB4kQ8yTn1sWc7',      // NUMBER
+  },
+  permission: { userGroup: 'ALL_USERS' },
+})
 ```
 
-`SoftrRecord<Fields>` is shorthand for `{ id: string; fields: Fields }` — the `Fields` type parameter constrains every value to `JsonValue`, so TypeScript rejects non-serializable types like `Date` objects.
-
-Cast at the `ds.list` call using the `ListResult` generic so the type flows through the loader automatically:
+- `datasource` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name. `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
+- The keys of `fields` are names you choose. The values are field ids, opaque strings copied from `softr-env.d.ts` (see [Typing](#typing)) or the table's schema. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
+- `permission` declares who may run the action.
+- Declare at module scope, every property a literal. The build reads the declaration without executing it, so a computed id, a shared constant or a spread does not work.
 
-```ts
-import type { ListResult, SoftrRecord } from '@softr/sdk'
-
-const fetchProducts = createServerFn().handler(() =>
-  ds.list('3c1e8a52-6f0d-4b7e-9a21-5d84c0f7b2e6', { select, limit: 100 }) as Promise<ListResult<Product>>
-)
-```
-
-`loaderData` is then already typed as `ListResult<Product>` — no second cast needed in the component. All the shapes in [references/field-types.md](./references/field-types.md) satisfy the `JsonValue` constraint.
+An action fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types.
 
 ## Core Patterns
 
@@ -77,73 +60,62 @@ const fetchProducts = createServerFn().handler(() =>
 
 ```ts
 const listPublishedPosts = createServerFn().handler(async () => {
-  return await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
-    select: q.select({
-      title: 'fZk3Qm9pLw2Xa1',
-      author: 'mB4kQ8yTn1sWc7',
-      published: 'Ru7bVx2cNq0Ed9',
-      publishedAt: 'Xp2dLh6vKz9Fa3',
-    }),
-    where: q.boolean('published').is(true),
-    orderBy: q.desc('publishedAt'),
-    limit: 50,
-  })
+  return await ds
+    .list(publishedPosts)
+    .where((q) => q.published.is(true))
+    .orderBy((q) => q.publishedAt.desc)
+    .limit(50)
 })
 ```
 
-Returns `{ records, total, nextOffset }`. `ds.list(POSTS)` on its own returns the first 20 records with their raw field ids. `limit` defaults to 20 and is clamped to 100. A larger number is silently reduced, so more than a hundred records means paginating.
-
-**Filtering or sorting requires a `select`, and it has to cover every field you name.** `where` and `orderBy` speak aliases, so without a map to translate through they throw at request time. That is why `published` is in the map above even though the table never displays it.
+Returns `{ records, total, nextOffset }`. Each record is `{ id, fields }`, with `fields` keyed by the action's own names: every declared field is present, `null` when empty, and a field the action does not declare is not returned. `ds.list(publishedPosts)` with no calls chained returns the first 20 records. `limit` is clamped to 100; a larger number is silently reduced, so more than a hundred records means paginating.
 
-### Name the fields with `select`
+### Filter with the `where` callback
 
-Softr field ids are opaque strings (`fZk3Qm9pLw2Xa1`), copied from the table's schema. `q.select` maps your own names onto them, and those names are what the rest of the call speaks:
+The callback is handed one handle per declared field, carrying only the operators that field's type supports, plus `$and` and `$or`:
 
 ```ts
-const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
-
-await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
-  select,
-  where: q.number('views').gt(100),   // alias, not Ru7bVx2cNq0Ed9
-  orderBy: q.asc('title'),            // alias here too
-})
-// records[0].fields is { title: ..., views: ... }
+await ds.list(publishedPosts).where((q) =>
+  q.$and(
+    q.published.is(true),
+    q.views.gte(100),
+    q.$or(q.title.contains('cafe'), q.title.startsWith('The')),
+  ),
+)
 ```
 
-Once `select` is present it is the whole vocabulary. The returned record carries exactly those keys, and any field you filter or sort on must appear in the map.
+Calling `.where` more than once ands the filters together, which is how a fixed scope and a user-supplied filter combine. Only the action's own fields can be filtered or sorted on; a field you need in a `where` must be in the action's `fields`, even when the page never displays it. The full operator matrix is in [references/query-builder.md](./references/query-builder.md).
 
-### Get one record
+### Sort
 
 ```ts
-const post = await ds.get('8ffb4814-b028-4496-b679-7face2167ebc', { id: postId })
-if (post === null) throw notFound()
+.orderBy((q) => q.publishedAt.desc)
+.orderBy((q) => [q.views.desc, q.title.asc])   // array for tie-breakers
 ```
 
-A record that does not exist comes back as `null`, not an error.
+### Get one record
 
-The type also accepts `{ where }` instead of `{ id }`, but there is no way to pass a `select` alongside it, so the filter cannot be translated and the call throws. Fetch one record by id, or use `ds.list` with a `limit` of 1 when you need to find it by a field.
+```ts
+const post = await ds.get(publishedPosts, { id: postId })
+if (post === null) throw notFound()
+```
 
-### Filter with `q`
+A record that does not exist comes back as `null`, not an error. A chained `.where` narrows which record the id may resolve to. A record that does not match reads as `null`, the same as one that does not exist:
 
 ```ts
-where: q.and(
-  q.text('status').is('active'),
-  q.number('amount').gte(100),
-  q.or(
-    q.text('owner').is(user.id),
-    q.array('collaborators').hasAllOf([user.id]),
-  ),
-)
+const post = await ds
+  .get(publishedPosts, { id: postId })
+  .where((q) => q.published.is(true))
 ```
 
-Five field types, `q.text`, `q.number`, `q.boolean`, `q.date` and `q.array`, combined with `q.and` and `q.or`. The full operator matrix is in [references/query-builder.md](./references/query-builder.md).
+There is no `orderBy`, `limit` or `offset` on a get. To find a record by a field instead of its id, use `ds.list` with a `limit` of 1.
 
 ### Paginate
 
 ```ts
-const first = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50 })
+const first = await ds.list(publishedPosts).limit(50)
 if (first.nextOffset !== null) {
-  const second = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50, offset: first.nextOffset })
+  const second = await ds.list(publishedPosts).limit(50).offset(first.nextOffset)
 }
 ```
 
@@ -152,13 +124,18 @@ if (first.nextOffset !== null) {
 ### Scope the read to the visitor
 
 ```ts
+const myInvoices = defineAction({
+  id: 'myInvoices',
+  datasource: 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93',
+  operation: 'read',
+  fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
 const listMyInvoices = createServerFn().handler(async ({ context }) => {
   if (!context.user) throw new Error('Not signed in')
-
-  return await ds.list('e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93', {
-    select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
-    where: q.text('owner').is(context.user.id),
-  })
+  const userId = context.user.id
+  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
 })
 ```
 
@@ -168,9 +145,16 @@ A server function is its own endpoint, reachable whether or not the visitor ever
 
 A read the visitor is not allowed to make throws rather than coming back empty, and it throws a plain `Error` carrying the status. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.
 
+## Typing
+
+Records, filters and sorts are typed from `softr-env.d.ts`, the generated file at the app root describing every datasource registered on the application. Regenerate it with `npx @softr/sdk generate` after the data changes. With it in place, field ids autocomplete inside `fields`, each `where` handle offers only its field's operators, and `records[0].fields` carries real value types with no cast anywhere. Without it everything still runs, but field values type as `unknown` and every handle offers every operator.
+
+What each Softr field type reads back as is in [references/field-types.md](./references/field-types.md). The two most commonly mistyped: SELECT and LINKED_RECORD values are `{ id, label }` objects, never plain strings. Render the `label`; filter by the `id`.
+
 ## References
 
-- [references/field-types.md](./references/field-types.md): TypeScript shape for every Softr field type
-- [references/query-builder.md](./references/query-builder.md): every `q` field type and operator
+- [references/query-builder.md](./references/query-builder.md): every filter operator, by field type
+- [references/field-types.md](./references/field-types.md): the value shape every Softr field type reads back as
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to scope a query
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): deciding who sees the page the records land on
+- [charts-and-metrics/SKILL.md](../charts-and-metrics/SKILL.md): aggregating records instead of listing them

package/skills/softr-sdk/reading-records/references/field-types.md

@@ -1,70 +1,63 @@
-# Softr field types — TypeScript shapes
+# Softr field types and what their values look like
 
-When you write a TypeScript type for a record's fields, use these shapes. The field's **type** (shown in the datasource metadata or described by the user) determines the shape, not the field's name.
+The generated `softr-env.d.ts` is the authority for your own tables: it types every field of every registered datasource, choice ids included, with the field's name and constraints in a docstring. This reference is the general mapping behind it, for reading a record's values without opening that file.
 
-```ts
-// Simple scalar types
-SINGLE_LINE_TEXT: string
-LONG_TEXT: string
-EMAIL: string
-PHONE: string
-URL: string
-ADDRESS: string
-LOCATION: string
-BUTTON: string
-RECORD_ID: string
-DATETIME: string       // ISO timestamp string
-DATE: string           // ISO date string
-TIME: string
-CREATED_AT: string
-UPDATED_AT: string
-CHECKBOX: string | boolean
-AUTONUMBER: number | null
-NUMBER: number | null
-PERCENT: number | null
-CURRENCY: number | null
-PROGRESS: number | null
-DURATION: number | null
-COUNT: number | null
-RATING: string | number | null
-FORMULA: string | number
-
-// Object types — these are NOT plain strings
-SELECT: { id: string; label: string }
-LINKED_RECORD: { id: string; label: string }
+Three rules cover nullability:
 
-DATE_RANGE: { from: string; to: string }
+- Every field reads back present, `null` when it is empty. Nothing is optional.
+- A multi-entry field is an array, empty rather than `null`.
+- A `CHECKBOX` is a boolean, `false` rather than `null`.
 
+```ts
+// Strings
+SINGLE_LINE_TEXT, LONG_TEXT, ADDRESS, LOCATION, BUTTON, RECORD_ID: string
+EMAIL, PHONE, URL: string
+DATETIME: string            // ISO timestamp, or an ISO date at date precision
+CREATED_AT, UPDATED_AT: string
+TIME: string                // '09:30:00'
+CREATED_BY, UPDATED_BY: string
+
+// Numbers
+NUMBER, PERCENT, CURRENCY, PROGRESS, DURATION, COUNT, RATING, AUTONUMBER: number
+
+// Booleans
+CHECKBOX: boolean
+
+// Objects. These are NOT plain strings
+SELECT: { id: string; label: string }                 // generated with literal id and label unions
+LINKED_RECORD: { id: string; label: string | null }   // label is the linked record's primary field
+DATE_RANGE: { from: string; to: string }
+USER: { id: string; name: string; email: string; avatarUrl: string | null }
 ATTACHMENT: {
-  filename: string | null | undefined
-  id: string | null | undefined
-  type: string | null | undefined
+  id: string | null
+  filename: string | null
+  type: string | null
   url: string
+  expiresAt: string | null
+  size?: number
   thumbnails?: Array<{ size: 'small' | 'medium' | 'large'; url: string }>
 }
 
-USER: { avatarUrl: string | null; id: string; name: string; email: string }
-
-CREATED_BY: string | string[] | { avatarUrl: string | null; id: string; name: string; email: string }
-UPDATED_BY: string | string[] | { avatarUrl: string | null; id: string; name: string; email: string }
-
-// These depend on what the linked field/aggregation resolves to
-LOOKUP: unknown
-ROLLUP: unknown
+// Computed fields read as whatever they return
+FORMULA, LOOKUP, ROLLUP: the returned field's shape, resolved in softr-env.d.ts
 ```
 
+Every scalar above is `| null` on the record unless the field allows multiple entries, in which case the value is an `Array<...>` of the scalar.
+
 ## The non-obvious ones
 
-**SELECT and LINKED_RECORD** are the most commonly mistyped. They are never a plain string — always `{ id: string; label: string }`. To display the value, use `.label`. To filter or compare, use `.id`.
+**SELECT and LINKED_RECORD** are the most commonly mistyped. They are never a plain string, always an `{ id, label }` object. To display the value, use `.label`. To filter or compare, use `.id`. A generated SELECT narrows both to the field's own choices as literal unions.
 
 ```tsx
 // Correct
 <td>{record.fields.status?.label}</td>
 
-// Wrong — status is not a string
+// Wrong: status is not a string
 <td>{record.fields.status}</td>
 ```
 
-**CHECKBOX** can be either a string (`'true'` / `'false'`) or a boolean depending on the datasource. Type it as `string | boolean` and coerce when needed: `!!record.fields.active`.
+**DURATION** is seconds, whatever format the field displays in.
+
+**DATETIME at date precision** is generated as a `DATE` field and holds `'2026-03-14'`, not a timestamp.
 
-**CREATED_BY / UPDATED_BY** can be a plain id string, an array of ids, or a full user object. Narrow before using.
+**LOOKUP and FORMULA** take the shape of what they resolve to, so two lookups on one table can have entirely different types. Read the generated type rather than guessing from the field name.

package/skills/softr-sdk/reading-records/references/query-builder.md

@@ -1,30 +1,27 @@
-# `q`, the query builder
+# Filters and sorting
 
-Every filter, sort and field map passed to `ds` is built with `q`, imported from `@softr/sdk`. Filters and sorts built any other way are rejected at runtime.
-
-```ts
-import { q } from '@softr/sdk'
-```
+Every filter and sort is built inside the callback `where` or `orderBy` hands you. A filter built any other way is rejected at request time.
 
 ## Shape
 
 ```ts
-await ds.list(datasourceId, {
-  select: q.select({ alias: '<field id>', ... }),   // optional field map
-  where: <one filter, or q.and/q.or of filters>,
-  orderBy: q.asc('alias') | [q.desc('a'), q.asc('b')],
-  limit: number,                                // default 20, clamped down to 100
-  offset: number | null,
-})
+await ds
+  .list(action)
+  .where((q) => q.status.is('active'))        // one filter, or a $and/$or of filters
+  .orderBy((q) => q.title.asc)                // or an array of handles
+  .limit(20)                                  // default 20, clamped down to 100
+  .offset(null)                               // a previous result's nextOffset
 ```
 
-`where` takes exactly one value. For more than one condition, wrap them in `q.and(...)` or `q.or(...)`.
+A `where` callback returns exactly one value. For more than one condition, wrap them in `q.$and(...)` or `q.$or(...)`, or call `.where` again: repeated calls are anded.
+
+## Operators by field type
 
-## Field types and operators
+The handle for each field carries the operators its declared type supports, taken from the generated `softr-env.d.ts`. A field with no generated type gets every operator.
 
-Pick the builder that matches the field's type. The type travels with the operator and decides how the value is compared.
+### Text fields
 
-### `q.text(field)`
+`SINGLE_LINE_TEXT`, `LONG_TEXT`, `URL`, `EMAIL`, `PHONE`, `ADDRESS`, `LOCATION`, `TIME`, `BUTTON`, `RECORD_ID`.
 
 | Call | Meaning |
 | --- | --- |
@@ -35,52 +32,56 @@ Pick the builder that matches the field's type. The type travels with the operat
 | `.endsWith(value: string)` | Suffix match |
 | `.isOneOf(values: string[])` | Equal to any of |
 | `.isNoneOf(values: string[])` | Equal to none of |
-| `.hasAllOf(values: string[])` | Contains all of |
-| `.isEmpty()` | No value |
-| `.isNotEmpty()` | Has a value |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### Number fields
 
-### `q.number(field)`
+`NUMBER`, `PERCENT`, `CURRENCY`, `PROGRESS`, `RATING`, `DURATION`, `COUNT`, `AUTONUMBER`.
 
 | Call | Meaning |
 | --- | --- |
-| `.is(value: number)` | Equal |
-| `.isNot(value: number)` | Not equal |
-| `.gt(value: number)` | Greater than |
-| `.gte(value: number)` | Greater than or equal |
-| `.lt(value: number)` | Less than |
-| `.lte(value: number)` | Less than or equal |
+| `.is(value: number)` / `.isNot(value: number)` | Equal / not equal |
+| `.gt(value)` / `.gte(value)` / `.lt(value)` / `.lte(value)` | Comparisons |
 | `.between(start: number, end: number)` | Inclusive range |
 | `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
 
-Takes JavaScript numbers.
-
-### `q.boolean(field)`
+### Checkbox fields
 
 | Call | Meaning |
 | --- | --- |
-| `.is(value: boolean)` | Equal |
-| `.isNot(value: boolean)` | Not equal |
+| `.is(value: boolean)` / `.isNot(value: boolean)` | Equal / not equal |
 | `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
 
-### `q.date(field)`
+### Date fields
+
+`DATE`, `DATETIME`, `CREATED_AT`, `UPDATED_AT`.
 
 | Call | Meaning |
 | --- | --- |
-| `.is(value: string)` | On that date |
-| `.isNot(value: string)` | Not on that date |
-| `.gt(value: string)` | After |
-| `.gte(value: string)` | On or after |
-| `.lt(value: string)` | Before |
-| `.lte(value: string)` | On or before |
-| `.between(start: string, end: string)` | Inclusive range |
-| `.isNotBetween(start: string, end: string)` | Outside the range |
+| `.is(value: string)` / `.isNot(value: string)` | On / not on that date |
+| `.gt(value)` / `.gte(value)` | After / on or after |
+| `.lt(value)` / `.lte(value)` | Before / on or before |
+| `.between(start, end)` | Inclusive range |
+| `.isNotBetween(start, end)` | Outside the range |
 | `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
 
 Every value is an ISO date string, either `'2026-01-31'` or a full timestamp. A `Date` instance is not accepted. Call `.toISOString()` first.
 
-### `q.array(field)`
+### Choice fields
+
+`SELECT`, `LINKED_RECORD`, `CREATED_BY`, `UPDATED_BY`.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value)` / `.isNot(value)` | Equal / not equal |
+| `.isOneOf(values)` / `.isNoneOf(values)` | Any of / none of |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+Values are choice ids, never labels. A generated SELECT narrows the argument to the field's own choice ids, so a label or a typo is a type error. A LINKED_RECORD compares against the linked record's id.
+
+### Multi-value fields
 
-For multi-value fields: linked records, multi-selects, collaborators.
+Any generated type with a `[]` suffix: multi-selects, multi-entry linked records.
 
 | Call | Meaning |
 | --- | --- |
@@ -90,21 +91,30 @@ For multi-value fields: linked records, multi-selects, collaborators.
 | `.hasAllOf(values: string[])` | Contains all of |
 | `.isEmpty()` / `.isNotEmpty()` | Empty / non-empty |
 
+Values are the members' ids, as with choice fields.
+
+### User fields
+
+`USER` offers `.is`, `.isNot`, `.contains`, `.isEmpty` and `.isNotEmpty`.
+
+### Attachment and date range fields
+
+`ATTACHMENT` and `DATE_RANGE` have no single value to compare, so they offer only `.isEmpty()` and `.isNotEmpty()`.
+
 ## Combining
 
 ```ts
-q.and(...filters)   // all must match
-q.or(...filters)    // any may match
+q.$and(...filters)   // all must match
+q.$or(...filters)    // any may match
 ```
 
 Both take filters or nested groups:
 
 ```ts
-where: q.and(
-  q.text('status').is('active'),
-  q.or(
-    q.number('amount').gte(1000),
-    q.array('tags').hasAllOf(['priority']),
+.where((q) =>
+  q.$and(
+    q.status.is('active'),
+    q.$or(q.amount.gte(1000), q.title.contains('priority')),
   ),
 )
 ```
@@ -114,31 +124,17 @@ Nesting goes two levels, a group inside a group. A third level throws `Cannot ne
 ## Sorting
 
 ```ts
-orderBy: q.asc('title')
-orderBy: [q.desc('publishedAt'), q.asc('title')]
+.orderBy((q) => q.title.asc)
+.orderBy((q) => [q.publishedAt.desc, q.title.asc])
 ```
 
-Sorts are applied in array order.
-
-## Field maps
-
-```ts
-const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
-```
-
-`q.select` maps names you choose onto Softr field ids — opaque strings copied from the table's schema. Two rules follow from that:
-
-1. The returned record carries exactly the keys in the map. A field left out is not returned, and no error is raised.
-2. `where` and `orderBy` name aliases, and every one of them must be in the map. A name that is not throws `Could not find an alias for subject "..."` at request time, and so does a `where` or `orderBy` passed with no `select` at all.
-
-So `select` must list every field the query touches, not just the ones being displayed.
+Each field carries `.asc` and `.desc` handles and nothing else. An array applies sorts in order. Repeated `.orderBy` calls append.
 
 ## Errors
 
 | Message | Cause |
 | --- | --- |
-| `Filters cannot be constructed manually. Use the 'q' helper.` | A `where` value built as a plain object |
-| `orderBy conditions cannot be constructed manually. Use the 'q' helper.` | An `orderBy` value not from `q.asc` / `q.desc` |
+| `a filter must come from the callback a read hands you` | A `where` value built as a plain object |
+| `a sort must come from the callback a read hands you` | An `orderBy` value not from the callback's `.asc` / `.desc` handles |
 | `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
-| `Could not find an alias for subject "..."` | A sort field missing from `select`, or an `orderBy` with no `select` at all |
-| `Could not find an alias for subject "undefined"` | The same thing on a filter, which does not report the field name |
+| A `TypeError` reading an operator off `undefined` | Filtering or sorting on a field the action does not declare |

package/dist/core/datasource.d.ts

@@ -1,31 +0,0 @@
-import { ChartOptions, ChartResult, CreateOptions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrRecord, UpdateOptions } from "../types.js";
-
-//#region src/core/datasource.d.ts
-declare function listRecords<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options?: Omit<ListOptions, 'select'> & {
-  select?: Sel;
-}): Promise<ListResult<SoftrRecord<RecordFieldsFor<Id, Sel>>>>;
-declare function getRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<GetOptions, 'select'> & {
-  select?: Sel;
-}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>> | null>;
-declare function createRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<CreateOptions, 'select' | 'data'> & {
-  select?: Sel;
-  data: Partial<RecordFieldsFor<Id, Sel>>;
-}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>>>;
-declare function updateRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<UpdateOptions, 'select' | 'data'> & {
-  select?: Sel;
-  data: Partial<RecordFieldsFor<Id, Sel>>;
-}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>>>;
-declare function deleteRecord(datasourceId: string, id: string): Promise<void>;
-declare function getMetric(datasourceId: string, options: MetricOptions): Promise<MetricResult>;
-declare function getChart(datasourceId: string, options: ChartOptions): Promise<ChartResult>;
-declare const ds: {
-  list: typeof listRecords;
-  get: typeof getRecord;
-  create: typeof createRecord;
-  update: typeof updateRecord;
-  delete: typeof deleteRecord;
-  metric: typeof getMetric;
-  chart: typeof getChart;
-};
-//#endregion
-export { ds };