@softr/sdk 0.0.28 → 0.0.29

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

@@ -1,176 +0,0 @@
----
-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, and
-  chart/metric aggregations (ds.chart, ds.metric) are not covered.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.28
----
-
-**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.
-
-# Reading records
-
-`ds` reads records out of a Softr datasource, from the server only.
-
-## Setup
-
-```ts
-import { createServerFn } from '@tanstack/react-start'
-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.
-
-**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:
-
-```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
-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
-}>
-```
-
-`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:
-
-```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
-
-### List records
-
-```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,
-  })
-})
-```
-
-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.
-
-### Name the fields with `select`
-
-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
-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('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.
-
-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
-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]),
-  ),
-)
-```
-
-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('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50 })
-if (first.nextOffset !== null) {
-  const second = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50, offset: first.nextOffset })
-}
-```
-
-`nextOffset` is `null` when there are no more pages. `total` is the count of all matching records, not the count returned.
-
-### Scope the read to the visitor
-
-```ts
-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),
-  })
-})
-```
-
-See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
-
-A server function is its own endpoint, reachable whether or not the visitor ever matched the route that displays the data. A route's visibility rule decides who sees a page. The server function decides for itself who gets the records.
-
-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.
-
-## 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
-- [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

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

@@ -1,70 +0,0 @@
-# Softr field types — TypeScript shapes
-
-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
-// 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 }
-
-ATTACHMENT: {
-  filename: string | null | undefined
-  id: string | null | undefined
-  type: string | null | undefined
-  url: string
-  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
-```
-
-## 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`.
-
-```tsx
-// Correct
-<td>{record.fields.status?.label}</td>
-
-// 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`.
-
-**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,144 +0,0 @@
-# `q`, the query builder
-
-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(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,
-})
-```
-
-`where` takes exactly one value. For more than one condition, wrap them in `q.and(...)` or `q.or(...)`.
-
-## Field types and operators
-
-Pick the builder that matches the field's type. The type travels with the operator and decides how the value is compared.
-
-### `q.text(field)`
-
-| Call | Meaning |
-| --- | --- |
-| `.is(value: string)` | Exactly equal |
-| `.isNot(value: string)` | Not equal |
-| `.contains(value: string)` | Substring match |
-| `.startsWith(value: string)` | Prefix match |
-| `.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 |
-
-### `q.number(field)`
-
-| 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 |
-| `.between(start: number, end: number)` | Inclusive range |
-| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
-
-Takes JavaScript numbers.
-
-### `q.boolean(field)`
-
-| Call | Meaning |
-| --- | --- |
-| `.is(value: boolean)` | Equal |
-| `.isNot(value: boolean)` | Not equal |
-| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
-
-### `q.date(field)`
-
-| 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 |
-| `.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)`
-
-For multi-value fields: linked records, multi-selects, collaborators.
-
-| Call | Meaning |
-| --- | --- |
-| `.is(values: string[])` | Exactly this set |
-| `.isOneOf(values: string[])` | Contains at least one of |
-| `.isNoneOf(values: string[])` | Contains none of |
-| `.hasAllOf(values: string[])` | Contains all of |
-| `.isEmpty()` / `.isNotEmpty()` | Empty / non-empty |
-
-## Combining
-
-```ts
-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']),
-  ),
-)
-```
-
-Nesting goes two levels, a group inside a group. A third level throws `Cannot nest filter groups more than three levels deep.` Flatten by distributing the outer condition rather than nesting further.
-
-## Sorting
-
-```ts
-orderBy: q.asc('title')
-orderBy: [q.desc('publishedAt'), q.asc('title')]
-```
-
-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 |
-| --- | --- |
-| `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 |
-| `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 |