@softr/sdk 0.0.28 → 0.0.30-alpha.0

package/skills/softr-sdk/data-mutations/SKILL.md

@@ -1,138 +0,0 @@
----
-name: data-mutations
-description: >-
-  Create, update and delete records in a Softr datasource from inside a server
-  function: ds.create, ds.update and ds.delete from @softr/sdk/server, the data
-  payload key, select field aliasing on the way in and out, and what each call
-  returns or throws. Writes only. Reads, metrics and chart data 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 — 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.
-
-# Writing records
-
-`ds` writes records to a Softr datasource, from the server only.
-
-## Setup
-
-```ts
-import { createServerFn } from '@tanstack/react-start'
-import { z } from 'zod'
-import { ds } from '@softr/sdk/server'
-import { q } from '@softr/sdk'
-```
-
-Pass a zod schema straight to `.validator`. Start accepts it and types `data` from it.
-
-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 never derived from the table's name. Field ids are opaque too (`fZk3Qm9pLw2Xa1`, not `fld_<name>`) and come from the table's schema.
-
-**The datasource id must be a string literal at the call site.**
-
-## Core Patterns
-
-### Create a record
-
-```ts
-const NewProject = z.object({ name: z.string(), status: z.string() })
-
-const createProject = createServerFn({ method: 'POST' })
-  .validator(NewProject)
-  .handler(async ({ data }) =>
-    ds.create('8ffb4814-b028-4496-b679-7face2167ebc', {
-      data,
-      select: q.select({ name: 'fZk3Qm9pLw2Xa1', status: 'Ru7bVx2cNq0Ed9' }),
-    }),
-  )
-```
-
-Resolves to `{ id, fields }`, and on a Softr table `fields` holds **only the keys you wrote** — not the rest of the record. See "What a write answers with" below.
-
-**The payload key is `data`, not `fields`.** A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`. `CreateOptions` requires it, so a call keyed by `fields` does not type-check.
-
-**`data` speaks whatever `select` maps.** The keys above are the schema's own names because `select` maps them to field ids, which is why the validated input can go straight through. With no `select`, `data` has to be keyed by raw field ids instead.
-
-### Update a record
-
-```ts
-const Rename = z.object({ id: z.string(), name: z.string() })
-
-const renameProject = createServerFn({ method: 'POST' })
-  .validator(Rename)
-  .handler(async ({ data }) =>
-    ds.update('8ffb4814-b028-4496-b679-7face2167ebc', {
-      id: data.id,
-      data: { name: data.name },
-      select: q.select({ name: 'fZk3Qm9pLw2Xa1' }),
-    }),
-  )
-```
-
-The record id is its own option, so keep it out of `data`.
-
-`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. An empty `id` throws.
-
-### What a write answers with
-
-`create` and `update` resolve to `{ id, fields }`, but `fields` is **not the record**. On a Softr table it carries only the keys you sent, aliased through `select`; a status change answers with `{ id, fields: { status } }` and nothing else. (Other datasource types may answer with more. Rely on neither.)
-
-So the answer is a receipt, not a replacement for what the page holds. Putting it where a loader-fetched record was blanks every column you did not write. Two honest ways to show the result:
-
-- **A quick change to one field** — a status select, a card dragged to another column, an archive toggle — is optimistic: change that one field in your own state immediately, keep the rest of the record as the loader gave it, save in the background, and on a rejected write restore the old value with a clear message. Do not `router.invalidate()` or re-fetch after a successful write; the local change is already what the user sees.
-- **A saved form, or anything that changes several fields**, refreshes the route's data — `router.invalidate()`, see `@tanstack/router-core#router-core/data-loading` — so the list or detail re-reads through its own `select`.
-
-Do not re-read the one record with `ds.get` for either: it takes no `select`, so it answers with raw field ids.
-
-### Writing a choice field
-
-A `SELECT` or `LINKED_RECORD` field reads back as `{ id, label }` (see [field-types](../reading-records/references/field-types.md)). Writing one accepts the option's `id`, its `label`, or `{ id, label }`, matched case-insensitively.
-
-**A value that matches no option is not an error — it silently adds a new option to the field.** A typo'd label leaves a junk choice in the schema. So write `{ label }` (or the `{ id, label }` you read), copy labels from the table's schema verbatim, and never invent one.
-
-### Delete a record
-
-```ts
-const RecordId = z.object({ id: z.string() })
-
-const deleteProject = createServerFn({ method: 'POST' })
-  .validator(RecordId)
-  .handler(async ({ data }) => ds.delete('8ffb4814-b028-4496-b679-7face2167ebc', data.id))
-```
-
-**`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
-
-### Naming fields with `select`
-
-`select` works in both directions on a write. Going in, it turns your names into Softr field ids. Coming back, it turns the returned field ids into your names. Without it, `data` has to be keyed by raw field ids and the returned record answers with them too.
-
-The map has to cover every key in `data`. A key it does not map is not translated, so the write does not land on the field you meant.
-
-### Writing on behalf of the visitor
-
-Stamping a record with who created it, or scoping an update to the person making it, reads the visitor off the handler's `context`. That is [current-user](../current-user/SKILL.md)'s subject, including the null guest and how Start types it. Load that skill rather than looking for it here.
-
-## Failure Modes
-
-**A datasource id built from a name.** `'ds_projects'`, the table id, or the table's name glued to a uuid are not datasource ids. The id is the opaque UUID assigned when the table was registered on the application; copy it from there. Anything else fails at request time as not found or forbidden.
-
-**A datasource id stored in a variable.** Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
-
-**A write that sends `fields`.** The option is `data`. Only typecheck catches this, so it survives any run that does not typecheck.
-
-**A key missing from `select`.** The key is not translated, so the field it was meant for is not the field written. Check the map covers every key rather than trusting the call to complain.
-
-**A write with no `select` and your own key names.** Without a map, `data` must be keyed by raw field ids.
-
-**Passing an options object to `delete`.** The second argument is the id itself. `delete` throws when the record cannot be deleted.
-
-**Expecting `select` on a read-then-write round trip.** `ds.get` takes no `select`, so a record fetched by id answers with raw field ids. Load `reading-records` before pairing a read with a write.
-
-**Reading the visitor from somewhere other than `context`.** There is nothing to import. See [current-user](../current-user/SKILL.md).
-
-## References
-
-- [reading-records/SKILL.md](../reading-records/SKILL.md): fetching the record a write is about to change
-- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to stamp or scope a write

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 |