@softr/sdk 0.0.27 → 0.0.29

package/skills/softr-sdk/record-queries/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: record-queries
+description: >-
+  Fetch records from a Softr datasource with defineQuery, ds.list and ds.get:
+  the where and orderBy callbacks, field names of your own choosing, the
+  20-record default and 100-record cap, nextOffset pagination, and scoping a
+  read to the signed-in visitor. Use when putting datasource records on a page,
+  in a table, a list or a detail view, when filtering or sorting them, or when a
+  read comes back empty, unsorted or missing a field. Reads only: creating,
+  updating and deleting records is record-mutations, and aggregating them into
+  totals or chart rows is charts-and-metrics.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.29
+---
+
+**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. `defineQuery` 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 { defineQuery } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+```
+
+`ds` is server-only. `defineQuery` only declares a read, so it ships on the root entrypoint and the declaration can sit anywhere.
+
+## Declare the read
+
+Every read takes a query: which datasource, which fields, who it is for.
+
+```ts
+const publishedPosts = defineQuery({
+  id: 'publishedPosts',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: {
+    title: 'fZk3Qm9pLw2Xa1',      // SINGLE_LINE_TEXT
+    published: 'Ru7bVx2cNq0Ed9',  // CHECKBOX
+    publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
+    views: 'mB4kQ8yTn1sWc7',      // NUMBER
+  },
+  permission: { userGroup: 'ALL_USERS' },
+})
+```
+
+- `id` is the name the person building the app sees, so `publishedPosts`, not `q1`. It must be unique across the app: no two declarations may share one, queries and mutations counted together.
+- `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.
+- The keys of `fields` are names you choose. The values are field ids, opaque strings the table's schema gives you: `get_table` returns them for a Softr table, `list_data_source_table_fields` for a table on a connected database. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
+- `permission` declares who may run the query, and the SDK enforces it:
+  - `{ userGroup: 'ALL_USERS' }`: everyone, signed out included.
+  - `{ userGroup: 'NON_LOGGED_IN_USERS' }`: signed-out visitors only.
+  - `{ userGroup: 'LOGGED_IN_USERS' }`: any signed-in visitor, narrowed to particular groups with `userGroupIds: ['00000000-0000-0000-0000-00000000000a']`.
+- Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
+
+A query 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. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.
+
+## Core Patterns
+
+### List records
+
+```ts
+const listPublishedPosts = createServerFn().handler(async () => {
+  return await ds
+    .list(publishedPosts)
+    .where((q) => q.published.is(true))
+    .orderBy((q) => q.publishedAt.desc)
+    .limit(50)
+})
+```
+
+Returns `{ records, total, nextOffset }`. Each record is `{ id, fields }`, with `fields` keyed by the query's own names: every declared field is present, `null` when empty, and a field the query does not declare is not returned. `ds.list(publishedPosts)` with no calls chained returns the first 20 records. `limit` is clamped to 100, so more than a hundred records means paginating.
+
+### Filter with the `where` callback
+
+`q` is the argument the callback is handed, not an import. It carries one handle per declared field, offering 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')),
+  ),
+)
+```
+
+Calling `.where` more than once ands the filters together, which is how a fixed scope and a user-supplied filter combine. Only the query's own fields can be filtered or sorted on, so a field you need in a `where` belongs in `fields` even when the page never displays it. Load [references/filters-and-sorting.md](./references/filters-and-sorting.md) when you need an operator this page does not show, or when a filter is rejected.
+
+### Sort
+
+```ts
+.orderBy((q) => q.publishedAt.desc)
+.orderBy((q) => [q.views.desc, q.title.asc])   // array for tie-breakers
+```
+
+### Get one record
+
+```ts
+const post = await ds.get(publishedPosts, { 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, and a record that does not match reads as `null` too:
+
+```ts
+const post = await ds
+  .get(publishedPosts, { id: postId })
+  .where((q) => q.published.is(true))
+```
+
+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(publishedPosts).limit(50)
+if (first.nextOffset !== null) {
+  const second = await ds.list(publishedPosts).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 myInvoices = defineQuery({
+  id: 'myInvoices',
+  datasource: '00000000-0000-0000-0000-000000000001',
+  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))
+})
+```
+
+The SDK enforces `permission`, so a visitor outside the declared audience never reaches the records. Which of those records belong to one visitor is a separate question, and the `where` above answers it: a group says nothing about who owns a row, so a per-visitor read filters on `context.user`. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+
+A read the datasource turns down 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
+
+`softr-env.d.ts`, the generated file at the app root, types records, filters and sorts from every registered datasource. It follows the data on its own: nothing to run, nothing to edit. It checks the ids you wrote rather than handing them to you, so ask the schema for a field id and open the file only when a declaration will not compile.
+
+
+## References
+
+- [references/filters-and-sorting.md](./references/filters-and-sorting.md): every filter operator by field type, group nesting and the sort handles. Load it when the operator you want is not in this file, or when a filter is rejected.
+- [references/field-types.md](./references/field-types.md): the value shape every Softr field type reads back as. Load it when rendering a field whose shape you are unsure of, or when a value is not the string you expected.
+- [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
+- [record-mutations/SKILL.md](../record-mutations/SKILL.md): creating, updating and deleting them

package/skills/softr-sdk/record-queries/references/field-types.md

@@ -0,0 +1,63 @@
+# Softr field types and what their values look like
+
+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`.
+
+```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 | null }          // 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: {
+  id: string | null
+  filename: string | null
+  type: string | null
+  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
+```
+
+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 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
+<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.
+
+**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/record-queries/references/filters-and-sorting.md

@@ -0,0 +1,146 @@
+# Filters and sorting
+
+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](#shape)
+- [Operators by field type](#operators-by-field-type): [text](#text-fields), [number](#number-fields), [checkbox](#checkbox-fields), [date](#date-fields), [choice](#choice-fields), [multi-value](#multi-value-fields), [user](#user-fields), [attachment and date range](#attachment-and-date-range-fields)
+- [Combining](#combining)
+- [Sorting](#sorting)
+- [Errors](#errors)
+
+## Shape
+
+```ts
+await ds
+  .list(publishedPosts)
+  .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 to 100
+  .offset(null)                               // a previous result's nextOffset
+```
+
+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
+
+The handle for each field carries the operators its declared type supports, taken from the generated `softr-env.d.ts`.
+
+### Text fields
+
+`SINGLE_LINE_TEXT`, `LONG_TEXT`, `URL`, `EMAIL`, `PHONE`, `ADDRESS`, `LOCATION`, `TIME`, `BUTTON`, `RECORD_ID`.
+
+| 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 |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### Number fields
+
+`NUMBER`, `PERCENT`, `CURRENCY`, `PROGRESS`, `RATING`, `DURATION`, `COUNT`, `AUTONUMBER`.
+
+| Call | Meaning |
+| --- | --- |
+| `.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 |
+
+### Checkbox fields
+
+| 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`.
+
+| 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 |
+| `.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`.
+
+| 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
+
+Any generated type with a `[]` suffix: multi-selects, multi-entry linked records.
+
+| 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 |
+
+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
+```
+
+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')),
+  ),
+)
+```
+
+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) => q.title.asc)
+.orderBy((q) => [q.publishedAt.desc, q.title.asc])
+```
+
+Each field carries `.asc` and `.desc` handles and nothing else. An array applies sorts in order. Repeated `.orderBy` calls append.
+
+## 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 |
+| `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 query does not declare |

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.27
+  library_version: 0.0.29
 ---
 
 **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.
@@ -57,7 +57,7 @@ defineVisibility({ userGroup: 'NON_LOGGED_IN_USERS' })  // signed-out only: logi
 defineVisibility({ userGroup: 'LOGGED_IN_USERS' })      // any signed-in visitor
 defineVisibility({                                      // those groups only
   userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
 })
 ```
 
@@ -117,7 +117,7 @@ import { defineVisibility, isAccessError, isForbiddenError } from '@softr/sdk'
 
 const visibility = defineVisibility({
   userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
 })
 
 export const Route = createFileRoute('/_app/billing')({
@@ -156,5 +156,5 @@ Reach for `assert()` when the route wants the error thrown for it, and `check(co
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a guard has just admitted
-- [reading-records/SKILL.md](../reading-records/SKILL.md): a guard covers the page, not the server function behind it
+- [record-queries/SKILL.md](../record-queries/SKILL.md): a guard covers the page, not the server function behind it
 - [auth/SKILL.md](../auth/SKILL.md): `NON_LOGGED_IN_USERS` and the sign-in flow it fronts

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.27
----
-
-**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