@softr/sdk 0.0.26-alpha-0 → 0.0.26

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

@@ -1,15 +1,16 @@
 ---
 name: reading-records
 description: >-
-  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.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.26
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `q` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -22,37 +23,53 @@ metadata:
 
 ```ts
 import { createServerFn } from '@tanstack/react-start'
-import { defineAction } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
+import { q } from '@softr/sdk'
 ```
 
-`ds` is server-only. `defineAction` only declares data operations, so it ships on the root entrypoint and the declaration can sit anywhere.
+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.
 
-## Declare the read
+**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:
 
-Every `ds` call takes an action: which datasource, which fields, who may run it.
+```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:
 
 ```ts
-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' },
-})
+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
+}>
 ```
 
-- `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.
+`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:
 
-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.
+```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.
 
 ## Core Patterns
 
@@ -60,62 +77,73 @@ An action fixes the table and the columns, not the rows: filters, sorting and pa
 
 ```ts
 const listPublishedPosts = createServerFn().handler(async () => {
-  return await ds
-    .list(publishedPosts)
-    .where((q) => q.published.is(true))
-    .orderBy((q) => q.publishedAt.desc)
-    .limit(50)
+  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,
+  })
 })
 ```
 
-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.
-
-### Filter with the `where` callback
+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.
 
-The callback is handed one handle per declared field, carrying only the operators that field's type supports, plus `$and` and `$or`:
-
-```ts
-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')),
-  ),
-)
-```
+**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.
 
-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).
+### Name the fields with `select`
 
-### Sort
+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:
 
 ```ts
-.orderBy((q) => q.publishedAt.desc)
-.orderBy((q) => [q.views.desc, q.title.asc])   // array for tie-breakers
+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: ... }
 ```
 
+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.
+
 ### Get one record
 
 ```ts
-const post = await ds.get(publishedPosts, { id: postId })
+const post = await ds.get('8ffb4814-b028-4496-b679-7face2167ebc', { id: postId })
 if (post === null) throw notFound()
 ```
 
-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:
+A record that does not exist comes back as `null`, not an error.
+
+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.
+
+### Filter with `q`
 
 ```ts
-const post = await ds
-  .get(publishedPosts, { id: postId })
-  .where((q) => q.published.is(true))
+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]),
+  ),
+)
 ```
 
-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.
+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).
 
 ### Paginate
 
 ```ts
-const first = await ds.list(publishedPosts).limit(50)
+const first = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50 })
 if (first.nextOffset !== null) {
-  const second = await ds.list(publishedPosts).limit(50).offset(first.nextOffset)
+  const second = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50, offset: first.nextOffset })
 }
 ```
 
@@ -124,18 +152,13 @@ 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')
-  const userId = context.user.id
-  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
+
+  return await ds.list('e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93', {
+    select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
+    where: q.text('owner').is(context.user.id),
+  })
 })
 ```
 
@@ -145,16 +168,9 @@ 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/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
+- [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
 - [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,63 +1,70 @@
-# Softr field types and what their values look like
+# Softr field types — TypeScript shapes
 
-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.
-
-Three rules cover nullability:
-
-- 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`.
+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.
 
 ```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
+// 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 }
+
 DATE_RANGE: { from: string; to: string }
-USER: { id: string; name: string; email: string; avatarUrl: string | null }
+
 ATTACHMENT: {
-  id: string | null
-  filename: string | null
-  type: string | null
+  filename: string | null | undefined
+  id: string | null | undefined
+  type: string | null | undefined
   url: string
-  expiresAt: string | null
-  size?: number
   thumbnails?: Array<{ size: 'small' | 'medium' | 'large'; url: string }>
 }
 
-// Computed fields read as whatever they return
-FORMULA, LOOKUP, ROLLUP: the returned field's shape, resolved in softr-env.d.ts
-```
+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 }
 
-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.
+// These depend on what the linked field/aggregation resolves to
+LOOKUP: unknown
+ROLLUP: unknown
+```
 
 ## The non-obvious ones
 
-**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.
+**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`.
 
 ```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>
 ```
 
-**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.
+**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`.
 
-**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.
+**CREATED_BY / UPDATED_BY** can be a plain id string, an array of ids, or a full user object. Narrow before using.

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

@@ -1,27 +1,30 @@
-# Filters and sorting
+# `q`, the query builder
 
-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.
+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'
+```
 
 ## Shape
 
 ```ts
-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
+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,
+})
 ```
 
-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
+`where` takes exactly one value. For more than one condition, wrap them in `q.and(...)` or `q.or(...)`.
 
-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.
+## Field types and operators
 
-### Text fields
+Pick the builder that matches the field's type. The type travels with the operator and decides how the value is compared.
 
-`SINGLE_LINE_TEXT`, `LONG_TEXT`, `URL`, `EMAIL`, `PHONE`, `ADDRESS`, `LOCATION`, `TIME`, `BUTTON`, `RECORD_ID`.
+### `q.text(field)`
 
 | Call | Meaning |
 | --- | --- |
@@ -32,56 +35,52 @@ The handle for each field carries the operators its declared type supports, take
 | `.endsWith(value: string)` | Suffix match |
 | `.isOneOf(values: string[])` | Equal to any of |
 | `.isNoneOf(values: string[])` | Equal to none of |
-| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
-
-### Number fields
+| `.hasAllOf(values: string[])` | Contains all of |
+| `.isEmpty()` | No value |
+| `.isNotEmpty()` | Has a value |
 
-`NUMBER`, `PERCENT`, `CURRENCY`, `PROGRESS`, `RATING`, `DURATION`, `COUNT`, `AUTONUMBER`.
+### `q.number(field)`
 
 | Call | Meaning |
 | --- | --- |
-| `.is(value: number)` / `.isNot(value: number)` | Equal / not equal |
-| `.gt(value)` / `.gte(value)` / `.lt(value)` / `.lte(value)` | Comparisons |
+| `.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 |
 | `.between(start: number, end: number)` | Inclusive range |
 | `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
 
-### Checkbox fields
+Takes JavaScript numbers.
 
-| Call | Meaning |
-| --- | --- |
-| `.is(value: boolean)` / `.isNot(value: boolean)` | Equal / not equal |
-| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
-
-### Date fields
-
-`DATE`, `DATETIME`, `CREATED_AT`, `UPDATED_AT`.
+### `q.boolean(field)`
 
 | Call | Meaning |
 | --- | --- |
-| `.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 |
+| `.is(value: boolean)` | Equal |
+| `.isNot(value: boolean)` | Not equal |
 | `.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.
-
-### Choice fields
-
-`SELECT`, `LINKED_RECORD`, `CREATED_BY`, `UPDATED_BY`.
+### `q.date(field)`
 
 | Call | Meaning |
 | --- | --- |
-| `.is(value)` / `.isNot(value)` | Equal / not equal |
-| `.isOneOf(values)` / `.isNoneOf(values)` | Any of / none of |
+| `.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 |
 | `.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.
+Every value is an ISO date string, either `'2026-01-31'` or a full timestamp. A `Date` instance is not accepted. Call `.toISOString()` first.
 
-### Multi-value fields
+### `q.array(field)`
 
-Any generated type with a `[]` suffix: multi-selects, multi-entry linked records.
+For multi-value fields: linked records, multi-selects, collaborators.
 
 | Call | Meaning |
 | --- | --- |
@@ -91,30 +90,21 @@ Any generated type with a `[]` suffix: multi-selects, multi-entry linked records
 | `.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) =>
-  q.$and(
-    q.status.is('active'),
-    q.$or(q.amount.gte(1000), q.title.contains('priority')),
+where: q.and(
+  q.text('status').is('active'),
+  q.or(
+    q.number('amount').gte(1000),
+    q.array('tags').hasAllOf(['priority']),
   ),
 )
 ```
@@ -124,17 +114,31 @@ Nesting goes two levels, a group inside a group. A third level throws `Cannot ne
 ## Sorting
 
 ```ts
-.orderBy((q) => q.title.asc)
-.orderBy((q) => [q.publishedAt.desc, q.title.asc])
+orderBy: q.asc('title')
+orderBy: [q.desc('publishedAt'), q.asc('title')]
 ```
 
-Each field carries `.asc` and `.desc` handles and nothing else. An array applies sorts in order. Repeated `.orderBy` calls append.
+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.
 
 ## Errors
 
 | Message | Cause |
 | --- | --- |
-| `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 |
+| `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` |
 | `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
-| A `TypeError` reading an operator off `undefined` | Filtering or sorting on a field the action does not declare |
+| `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 |

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.25
+  library_version: 0.0.26
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/dist/codegen/fetch-metadata.js

@@ -1,46 +0,0 @@
-import { panic } from "../assertions.js";
-
-//#region src/codegen/fetch-metadata.ts
-function metadataSourceFromEnv(env = process.env) {
-	const missing = [
-		"SOFTR_STUDIO_API_URL",
-		"SOFTR_DATASOURCE_API_URL",
-		"SOFTR_APPLICATION_ID",
-		"SOFTR_STUDIO_TOKEN"
-	].filter((name) => !env[name]?.trim());
-	if (missing.length > 0) panic(`Cannot read the app's schema: ${missing.join(", ")} is not set.`);
-	return {
-		studioApiUrl: withoutTrailingSlash(env.SOFTR_STUDIO_API_URL),
-		datasourceApiUrl: withoutTrailingSlash(env.SOFTR_DATASOURCE_API_URL),
-		applicationId: env.SOFTR_APPLICATION_ID,
-		token: env.SOFTR_STUDIO_TOKEN
-	};
-}
-async function fetchSoftrEnvInput(source) {
-	const { studioApiUrl, datasourceApiUrl, applicationId, token } = source;
-	const registered = await apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token);
-	return {
-		datasources: await Promise.all(registered.map(async ({ name, datasource }) => {
-			return {
-				...await apiFetch(`${datasourceApiUrl}/v1/datasource/vibe/applications/${applicationId}/datasources/${datasource.id}/metadata`, token),
-				id: datasource.id,
-				name
-			};
-		})),
-		userGroupIds: null
-	};
-}
-async function apiFetch(url, token) {
-	const response = await fetch(url, { headers: {
-		accept: "application/json",
-		Authorization: `Bearer ${token}`
-	} }).catch(() => panic(`Could not reach ${url}`));
-	if (!response.ok) panic(`${url} answered ${response.status}`);
-	return await response.json();
-}
-function withoutTrailingSlash(url) {
-	return url.replace(/\/+$/, "");
-}
-
-//#endregion
-export { fetchSoftrEnvInput, metadataSourceFromEnv };