@gregale/data 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +1031 -2
  3. package/dist/bulk.d.ts +61 -0
  4. package/dist/bulk.js +63 -0
  5. package/dist/client-fetch.d.ts +34 -0
  6. package/dist/client-fetch.js +62 -0
  7. package/dist/cursor-token.d.ts +53 -0
  8. package/dist/cursor-token.js +179 -0
  9. package/dist/cursor.d.ts +45 -0
  10. package/dist/cursor.js +78 -0
  11. package/dist/deadline.d.ts +19 -0
  12. package/dist/deadline.js +29 -0
  13. package/dist/errors.d.ts +17 -0
  14. package/dist/errors.js +68 -0
  15. package/dist/exact-numeric.d.ts +15 -0
  16. package/dist/exact-numeric.js +125 -0
  17. package/dist/index.d.ts +49 -0
  18. package/dist/index.js +39 -0
  19. package/dist/indexeddb-mutation-store.d.ts +12 -0
  20. package/dist/indexeddb-mutation-store.js +139 -0
  21. package/dist/json.d.ts +39 -0
  22. package/dist/json.js +39 -0
  23. package/dist/live/client.d.ts +192 -0
  24. package/dist/live/client.js +555 -0
  25. package/dist/live/index.d.ts +31 -0
  26. package/dist/live/index.js +28 -0
  27. package/dist/live/protocol.d.ts +125 -0
  28. package/dist/live/protocol.js +271 -0
  29. package/dist/live/react.d.ts +22 -0
  30. package/dist/live/react.js +59 -0
  31. package/dist/live/seal.d.ts +38 -0
  32. package/dist/live/seal.js +98 -0
  33. package/dist/live/sql.d.ts +11 -0
  34. package/dist/live/sql.js +58 -0
  35. package/dist/mutation-journal.d.ts +78 -0
  36. package/dist/mutation-journal.js +223 -0
  37. package/dist/numeric.d.ts +11 -0
  38. package/dist/numeric.js +40 -0
  39. package/dist/optimistic.d.ts +24 -0
  40. package/dist/optimistic.js +18 -0
  41. package/dist/reconcile.d.ts +28 -0
  42. package/dist/reconcile.js +28 -0
  43. package/dist/replay-key.d.ts +8 -0
  44. package/dist/replay-key.js +27 -0
  45. package/dist/response.d.ts +33 -0
  46. package/dist/response.js +29 -0
  47. package/dist/rpc.d.ts +20 -0
  48. package/dist/rpc.js +31 -0
  49. package/dist/storage-uploads.d.ts +63 -0
  50. package/dist/storage-uploads.js +104 -0
  51. package/dist/storage.d.ts +74 -0
  52. package/dist/storage.js +89 -0
  53. package/dist/validation.d.ts +26 -0
  54. package/dist/validation.js +40 -0
  55. package/dist/versioned-mutation.d.ts +28 -0
  56. package/dist/versioned-mutation.js +13 -0
  57. package/package.json +19 -4
package/README.md CHANGED
@@ -1,3 +1,1032 @@
1
- # Temporary Holding Version
1
+ # Gregale Data API client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@gregale/data` wraps PostgREST's typed client for Gregale application Data APIs.
4
+ The management SDK and account keys remain separate from application access.
5
+ This package is not published to npm. From an authorized checkout, run
6
+ `npm ci && npm run build && npm pack`, then install the produced tarball in
7
+ your application. The repository's existing SDK license/publication policy applies.
8
+ For a paired CLI/SDK artifact and a clean starter installation, use the
9
+ [Data API bundle workflow](../../docs/data-api-packaging.md).
10
+
11
+ ```ts
12
+ import { createDataClient } from '@gregale/data'
13
+ import type { Database } from './database.types.js'
14
+
15
+ const db = createDataClient<Database>({
16
+ url: 'https://my-data.gregale.dev',
17
+ accessToken: async () => auth.getAccessToken(),
18
+ }).schema('api')
19
+
20
+ const { data, error } = await db.from('notes').select('id,body').range(0, 19)
21
+ await db.from('notes').insert({subject: auth.user.id, body: 'Hello'})
22
+ ```
23
+
24
+ Generate `Database` with `gregale data-api types my-data --output
25
+ src/database.types.ts`. Use `--check` in CI to fail when your file differs
26
+ from the database. Refresh the serving schema cache after migrations with
27
+ `gregale data-api refresh my-data` and verify restart completion.
28
+
29
+ ### Public data without a session
30
+
31
+ When the owner enables [public reads or public RPCs](../../docs/data-api.md#public-reads),
32
+ create the client with `anonymous: true`. Requests then go out without an
33
+ `Authorization` header whenever there is no token:
34
+
35
+ ```ts
36
+ const visitor = createDataClient<Database>({ url: 'https://my-data.gregale.dev', anonymous: true }).schema('api')
37
+ const { data: products } = await visitor.from('products').select('id,name').limit(20)
38
+ const { data: results } = await visitor.rpc('search_products', { q: 'lamp' }, { get: true })
39
+ ```
40
+
41
+ Anonymous callers must call public RPCs with `{ get: true }`; a `POST` returns
42
+ `405 public_rpc_requires_get`. Arguments and results keep their generated
43
+ types.
44
+
45
+ One client can serve signed-in and signed-out visitors: with `anonymous: true`,
46
+ `accessToken` may return `null`, and the request is then anonymous. An empty
47
+ or malformed token still throws before any request is sent. Without
48
+ `anonymous: true`, a missing token always throws, so a broken session never
49
+ silently becomes anonymous access:
50
+
51
+ ```ts
52
+ const db = createDataClient<Database>({
53
+ url: 'https://my-data.gregale.dev',
54
+ anonymous: true,
55
+ accessToken: async () => (await auth.getSession())?.accessToken ?? null,
56
+ }).schema('api')
57
+ ```
58
+
59
+ Anonymous requests through `expectedSchemaFingerprint` reach the API on a
60
+ contract-pinned path, so the Data API does not mark them for the edge cache.
61
+
62
+ ### File storage
63
+
64
+ When the owner turns on [file storage](../../docs/data-api.md#file-storage),
65
+ `createStorageClient` takes the same options as `createDataClient`. The
66
+ owner's policies on `storage_objects` decide each upload, download and
67
+ removal:
68
+
69
+ ```ts
70
+ import { createStorageClient, StorageError } from '@gregale/data'
71
+
72
+ const files = createStorageClient({ url: 'https://my-data.gregale.dev', accessToken: () => session.accessToken }).from('uploads')
73
+ const stored = await files.upload(`${userId}/report.pdf`, file) // { bucket, name, owner, size, content_type, ... }
74
+ const response = await files.download(`${userId}/report.pdf`, { range: { start: 0, end: 1023 } })
75
+ const { url, expiresAt } = await files.signedUrl(`${userId}/report.pdf`)
76
+ await files.remove(`${userId}/report.pdf`)
77
+ ```
78
+
79
+ Refusals throw `StorageError` with the Data API's `code`, such as
80
+ `storage_forbidden` or `storage_not_found`. List files by querying
81
+ `storage_objects` with `createDataClient`, or follow the list with a live
82
+ read.
83
+
84
+ With the optional upload-session SQL installed, use `uploadResumable` to retain
85
+ checksummed progress and a durable completion receipt. Save the session ID from
86
+ `onSessionId` before dispatch, then pass `sessionId` with the same file after an interruption.
87
+ `getUpload` reconciles completion; `abortUpload` cancels unfinished work.
88
+ `expectedVersion` accepts the version from `head()` or a previous upload, `null`
89
+ for create-only, or omission for unconditional replacement. A conflict returns
90
+ 412; an unknown commit sets `StorageError.uncertain` and requires reconciliation.
91
+ See [setup, limits and examples](../../docs/data-api/workflows.md#resumable-storage-and-upload-receipts).
92
+
93
+ ### Lossless numeric reads
94
+
95
+ Generate types with `--numeric-mode lossless`, then pass
96
+ `numericMode: 'lossless'` to `createDataClient`. Every JSON number becomes its
97
+ original decimal string, including nested JSON and array elements. `liveRead`
98
+ inherits the same codec. The serving fingerprint stays unchanged; ordinary
99
+ clients retain number decoding. This is a read codec: decoded JSON columns do
100
+ not retain the number-versus-string token distinction for subsequent writes.
101
+ See [numeric examples](../../docs/data-api/workflows.md#exact-numeric-decoding).
102
+
103
+ ### Exact numeric writes
104
+
105
+ Generate `--numeric-mode exact` types and use `numericMode: 'exact'` to retain
106
+ JSON number-versus-string identity. Numbers decode to immutable `ExactNumber`
107
+ values, including RPC results, arrays, JSON columns and `liveRead` rows. Their
108
+ `source` holds the original literal; sending them back writes JSON numbers.
109
+ Use `parseExactJSON` / `stringifyExactJSON` for independent serialization.
110
+ See [round-trip examples](../../docs/data-api/workflows.md#exact-numeric-round-trips).
111
+
112
+ ### Live reads
113
+
114
+ A live read is a Data API read whose result stays current: it arrives once,
115
+ then changes as rows are written. Row-level security decides each row, as it
116
+ does for REST reads. Set it up once with
117
+ [`gregale data-api live enable`](../../docs/data-api.md#live-reads), which
118
+ prints the WebSocket URL and the database ID:
119
+
120
+ ```ts
121
+ import { LiveConnection, liveRead, liveSocket } from '@gregale/data/live'
122
+
123
+ const connection = new LiveConnection({ connect: liveSocket('wss://my-data.gregale.dev/__gregale/realtime/ENDPOINT_ID') })
124
+ const feed = connection.query({
125
+ database: DATABASE_ID,
126
+ token: () => session.accessToken,
127
+ ...liveRead(db.from('messages').select('id,body,author(name)').eq('channel_id', 7).order('id', { ascending: false }).limit(50)),
128
+ })
129
+ feed.subscribe(() => render(feed.getSnapshot().rows))
130
+ ```
131
+
132
+ `liveRead` takes the read's rows type from the generated contract, and rows
133
+ decode as the REST API returns them. Each read carries exactly one
134
+ credential:
135
+
136
+ - `token`, the signed-in user's token, called again before it expires;
137
+ - `anonymous: true`, for relations in the Data API's public-read allowlist;
138
+ - `serverKey` (with an optional `subject`) for trusted backends. Server keys
139
+ are refused from browsers.
140
+
141
+ React components use the hook from `@gregale/data/live/react` (React 18 or
142
+ later):
143
+
144
+ ```tsx
145
+ import { useLiveRead } from '@gregale/data/live/react'
146
+
147
+ const { rows, status } = useLiveRead(connection, { database: DATABASE_ID, anonymous: true, ...liveRead(visitor.from('products').select('id,name')) })
148
+ ```
149
+
150
+ The connection reconnects with backoff and resumes each read, keeping the
151
+ last rows meanwhile. `status` is `connecting` (also while reconnecting),
152
+ `live`, `stale` (the result could not be kept current, for example after a
153
+ credential expired) or `closed`.
154
+
155
+ For signed-in React reads, pass an `identityScope` that changes on login,
156
+ tenant switches or authorization changes. This closes the old subscription and
157
+ clears its rows immediately, including the render before effects run. Pass null
158
+ options on logout. Token refresh for the same identity does not need a new scope;
159
+ the token provider is called again. Never put a JWT in the scope value.
160
+
161
+ ```tsx
162
+ const options = session ? {
163
+ database: DATABASE_ID,
164
+ identityScope: session.scope,
165
+ token: () => session.accessToken,
166
+ ...liveRead(db.from('notes').select('id,body')),
167
+ } : null
168
+ const { rows } = useLiveRead(connection, options)
169
+ ```
170
+
171
+ ### Pin requests to the generated contract
172
+
173
+ Regenerated TypeScript files also export a runtime `schemaFingerprint` value.
174
+ Opt in to an exact serving-contract guard when a client must fail before data
175
+ access against a different deployment contract:
176
+
177
+ ```ts
178
+ import { schemaFingerprint, type Database } from './database.types.js'
179
+
180
+ const db = createDataClient<Database>({
181
+ url: 'https://my-data.gregale.dev',
182
+ accessToken: () => auth.getAccessToken(),
183
+ expectedSchemaFingerprint: schemaFingerprint,
184
+ }).schema('api')
185
+ ```
186
+
187
+ The SDK requires 64 lowercase hexadecimal characters and uses a guarded route
188
+ for every REST/RPC request. The gateway authenticates the token and rejects a
189
+ mismatch with HTTP 409 and `error.code === 'schema_contract_mismatch'` before
190
+ forwarding to PostgREST. HEAD responses have no error body; inspect their status.
191
+ An unavailable serving fingerprint returns 503. Older runtimes return 404;
192
+ the client never falls back to an unguarded request. Deploy a guard-capable
193
+ runtime before enabling the option. Ordinary clients retain their existing URLs.
194
+
195
+ Exact matching also rejects compatible additive changes. Update client types
196
+ and coordinate deployment using the existing sync/refresh workflow. The guard
197
+ compares the runtime's captured startup contract, not a live database inspection;
198
+ out-of-band DDL or engine-only cache reloads can make that observation stale.
199
+ It does not prove RLS, function-body or data compatibility. Guard failures do
200
+ not automatically replay writes or update the pinned fingerprint.
201
+
202
+ Owners can enable selected older client fingerprints using a serving-bound
203
+ `DATA_API_ACCEPTED_CONTRACTS` policy generated by
204
+ `gregale data-api diff --baseline old.json --current new.json --accept-contract accepted.json`.
205
+ The command requires zero structural breaking changes, including approved breaks.
206
+ Clients keep the same option; authentication and RLS still apply. See the
207
+ [rollout guide](../../docs/data-api.md#accept-older-clients-during-a-compatible-rollout)
208
+ for review, deployment and revocation.
209
+
210
+ Generated files also export `Tables<'notes'>`, `TablesInsert<'notes'>`,
211
+ `TablesUpdate<'notes'>`, and `Enums<'state'>`. `Tables` includes read-only views;
212
+ write helpers accept tables only and preserve generated-column restrictions.
213
+ An optional second parameter selects an exported schema, for example
214
+ `Tables<'items', 'other'>`. The default is `api` when available.
215
+
216
+ ```ts
217
+ import type { TablesInsert } from './database.types.js'
218
+ import type { QueryData, QueryResult, QueryError } from '@gregale/data'
219
+
220
+ const input: TablesInsert<'notes'> = { subject: auth.user.id, body: 'Hello' }
221
+ const query = db.from('notes').select('id,comments(id,body)')
222
+ type Rows = QueryData<typeof query>
223
+ type Response = QueryResult<typeof query>
224
+ type Error = QueryError<typeof query>
225
+ ```
226
+
227
+ `QueryData` removes the nullable error result and preserves nested projection
228
+ inference. `QueryResult` describes the full awaited response. `QueryError`
229
+ describes its non-null error type. The SDK also exports PostgREST single,
230
+ maybe-single and array response types.
231
+
232
+ For an existing application, install an approved bundle without copying starter
233
+ scripts:
234
+
235
+ ```sh
236
+ gregale data-api install --bundle /approved/data-api-bundle.json --directory .
237
+ # Use --client-directory web when package.json is in a project subdirectory.
238
+ gregale data-api install --restore --from /approved --directory .
239
+ ```
240
+
241
+ Commit the artifact pin, client package.json and lockfile together. Restore checks
242
+ both archive checksums and the committed npm integrity before installing locked
243
+ dependencies. This workflow uses approved artifacts; public npm publication
244
+ remains subject to the SDK publishing policy.
245
+
246
+ The token getter runs on each request. Requests omit browser cookies and refuse
247
+ redirects so access tokens stay at the configured API. The client preserves
248
+ PostgREST relation, insert, update, filter, projection and relationship inference.
249
+ Generated view relationships preserve readable, complete key projections,
250
+ including renamed columns and view chains in the same exposed schema. Aliased
251
+ embeds and FK hints use the normal PostgREST select syntax. Cardinality follows
252
+ the underlying key constraint; view column types remain nullable. Expressions
253
+ and partial keys have no inferred path, and ambiguous embeds can fail at runtime.
254
+ Approved same-schema computed relationships use generated `SetofOptions` for
255
+ source, target and cardinality. A `ROWS 1` function embeds an object or null,
256
+ while its direct RPC returns an array. Relation-set RPCs support typed nested
257
+ joins, projections and filters on their result relation. Upgrade the CLI/runtime
258
+ for normalized version 3 contracts; version 1/2 baselines remain readable.
259
+ See [the Data API guide](../../docs/data-api.md).
260
+
261
+ For JSON/JSONB paths, use explicit JSON aliases to preserve SQL nullability:
262
+
263
+ ```ts
264
+ import { selectJson, jsonText, jsonValue } from '@gregale/data'
265
+
266
+ const orders = await selectJson(db.from('orders'), 'id', {
267
+ status: jsonText('metadata', 'status'),
268
+ city: jsonText('metadata', 'delivery', 'city'),
269
+ details: jsonValue('metadata', 'details'),
270
+ first: jsonText('metadata', 'items', 0, 'name'),
271
+ }).eq('metadata->>status', 'paid')
272
+ // id retains its generated type; status/city/first are string | null.
273
+ // details is Json, including null; no arbitrary keys are inferred.
274
+ ```
275
+
276
+ The second argument is a literal normal select string, or `''` for JSON aliases
277
+ only. Keep JSON paths in the third argument: native JSON paths inside the base
278
+ selection retain the upstream SDK's inference, which can omit SQL nullability.
279
+ Alias names must be known to TypeScript and must not duplicate base fields.
280
+ Source columns are checked against the
281
+ generated row contract. Tables, views, write representations and relation-set
282
+ RPC builders work with the usual filters, ordering, `.single()`/`.maybeSingle()`
283
+ and error handling. Select again to replace the projection.
284
+
285
+ Paths accept nonempty string keys and safe integer array indexes, including
286
+ negative indexes. Numeric strings select object keys; numbers select array
287
+ positions. Names are quoted and URL-encoded by the SDK; quotes, backslashes and
288
+ control characters in names are rejected before sending. Missing paths, SQL
289
+ NULL and JSON null all yield null with `jsonText`. `jsonValue` preserves JSON
290
+ values, but HTTP JSON cannot distinguish extracted JSON null from SQL NULL.
291
+ Use database predicates when that distinction matters. See the guide for
292
+ JSONB `eq.null` versus SQL `is.null` and RLS examples.
293
+
294
+ Opted-in PostgreSQL functions appear in the generated `Functions` contract.
295
+ Call `db.rpc('function_name', { named_argument: value }).retry(false)` using an
296
+ application JWT. Gregale permits POST RPC only; omit `get` and `head` options.
297
+ Generated `CompositeTypes<'name'>` helpers describe named PostgreSQL composite
298
+ objects, including nested values and arrays. Approved RPCs use these types for
299
+ arguments and results; a composite result is an object and a SETOF result is an
300
+ array. Composite fields remain nullable, including domain attributes.
301
+ Arguments, defaults and results are inferred from the database. Each call is
302
+ one transaction. See the guide for opt-in comments, execution grants, supported
303
+ signatures, RLS and fresh-restart requirements.
304
+
305
+ For retry-safe note creation, the starter adds `create_note_with_tags_once`.
306
+ Retain one UUID and the same payload for a logical operation, then explicitly
307
+ replay with that key after an uncertain network outcome. Keys are user-scoped;
308
+ changed payloads return 409. The guide describes execution grants, receipt
309
+ retention, snapshot responses and deletion semantics.
310
+
311
+ Capture response diagnostics without wrapping fetch:
312
+
313
+ ```ts
314
+ const db = createDataClient<Database>({
315
+ url: 'https://my-data.gregale.dev',
316
+ accessToken: () => auth.getAccessToken(),
317
+ onResponse: ({ requestId, status, durationMs }) => {
318
+ console.info({ requestId, status, durationMs })
319
+ },
320
+ }).schema('api')
321
+ ```
322
+
323
+ `DataResponseInfo` is a readonly, runtime-frozen object containing only those
324
+ three fields. `requestId` is null when the header is missing, not exposed by CORS,
325
+ or not a UUID v4. No token, URL, query, headers, body or application identity is
326
+ passed to the callback. The SDK emits no logs unless your callback does so.
327
+
328
+ The callback runs once per HTTP response, including errors and individual retry
329
+ attempts, across reads, writes and RPCs. Duration is monotonic client time from
330
+ token lookup until fetch returns response headers; it excludes body consumption
331
+ and is not database execution or platform wake timing. The callback cannot read
332
+ or consume the response body. Network failures, cancellation before headers and
333
+ invalid tokens produce no callback when there is no HTTP response.
334
+
335
+ Callbacks may be synchronous or asynchronous. Exceptions and rejected promises
336
+ are ignored, and asynchronous completion is not awaited. Keep synchronous work
337
+ short; the request does not wait for asynchronous telemetry to finish. The hook
338
+ does not change retries, data, errors, counts or generated schema inference.
339
+
340
+ ### Runtime JSON validation
341
+
342
+ Use `validateJson` after checking the query error to validate selected fields.
343
+ It accepts synchronous objects with a `parse(unknown)` method, including Zod
344
+ schemas, and infers each field's result from the parser output. Validators are
345
+ application-owned; PostgreSQL JSON columns do not describe their internal shape.
346
+
347
+ ```ts
348
+ import { validateJson } from '@gregale/data'
349
+ import { z } from 'zod' // install in your application
350
+
351
+ const { data, error } = await query
352
+ if (error) throw error
353
+ const rows = validateJson(data, {
354
+ details: z.object({ count: z.number() }).nullable(),
355
+ })
356
+ ```
357
+
358
+ Arrays and single rows are supported. A null single-row result stays null; field
359
+ nulls go through the parser, so accept them explicitly with a nullable schema.
360
+ The helper copies rows and preserves unvalidated fields. Nested JSON validation
361
+ belongs inside your parser. Async parsers are unsupported.
362
+
363
+ Failures throw `JsonValidationError` with code `JSON_VALIDATION_FAILED`, the
364
+ selected `field`, and a zero-based `rowIndex` (null for a single row). Original
365
+ parser messages, causes and payloads are omitted. Validation runs locally after
366
+ the request and does not change PostgREST errors or database authorization.
367
+
368
+ ### Reusable cursor pagination
369
+
370
+ ```ts
371
+ import { cursorPage, cursorFrom } from '@gregale/data'
372
+
373
+ const order = [
374
+ { column: 'created_at', ascending: false, nullsFirst: false },
375
+ { column: 'id', ascending: false, unique: true },
376
+ ] as const
377
+ const { data, error } = await cursorPage(
378
+ db.from('notes').select('id,created_at,body'),
379
+ { order, size: 20 },
380
+ )
381
+ if (error) throw error
382
+ const after = data.length ? cursorFrom(data.at(-1)!, order) : undefined
383
+ // Supply after with the same order and filters on a fresh query for the next page.
384
+ ```
385
+
386
+ `cursorPage` preserves the selected result type and supports table/view reads,
387
+ filters, cancellation and native errors. Use a fresh array-returning select
388
+ builder without existing ordering, range or limits. Include every ordering
389
+ column in the selected row to extract its cursor. Ordering columns must be
390
+ simple names with scalar string, finite number, boolean or null values; JSON,
391
+ embedded fields and expression ordering are unsupported. Dates use their wire
392
+ strings. Defaults are ascending and nulls last, explicitly applied at every key.
393
+
394
+ The final ordering column must be non-null and unique within the filtered
395
+ result. Mark it `unique: true`; the application is responsible for this database
396
+ invariant. The helper cannot infer constraints from client types. Cursor values
397
+ are validated and quoted for PostgREST filter syntax, including commas, quotes
398
+ and backslashes. Cursor tuples are neither signed nor authorization tokens.
399
+
400
+ Keep filters, ordering and identity consistent across pages. RLS runs on every
401
+ request. Deleting the cursor row does not invalidate continuation; newer rows
402
+ before the cursor do not shift subsequent pages. This is not a snapshot across
403
+ requests: inserts after the cursor can appear, deleted rows disappear, and
404
+ changing ordering values can move rows. Stop when a page is empty. Large integer
405
+ keys must be represented without JavaScript precision loss by your application.
406
+ Existing server row caps can return fewer rows than the requested page size.
407
+
408
+ To fetch the previous page, use `before` with the cursor of the first displayed
409
+ row and keep the original ordering and filters:
410
+
411
+ ```ts
412
+ const previous = await cursorPage(
413
+ db.from('notes').select('id,body').eq('subject', 'alice'),
414
+ { order, size: 20, before: cursorFrom(firstDisplayedRow, order) },
415
+ )
416
+ if (previous.error) throw previous.error
417
+ const displayRows = [...previous.data].reverse()
418
+ ```
419
+
420
+ `before` returns the nearest preceding rows in reverse traversal order. Reverse
421
+ the returned array to display it in the original order. Use the same declared
422
+ `order` to extract each cursor; for another backward request, use the last row
423
+ of the raw response. `after` and `before` are mutually exclusive and invalid
424
+ cursors fail before the query builder is changed. Neither direction changes
425
+ RLS authorization or provides a snapshot across requests.
426
+
427
+ ### Request deadlines and cancellation
428
+
429
+ ```ts
430
+ import { dataRequest } from '@gregale/data'
431
+
432
+ const controller = new AbortController()
433
+ const result = await dataRequest(db.from('notes').select('id,body'), {
434
+ timeoutMs: 5000,
435
+ signal: controller.signal,
436
+ })
437
+ // Call controller.abort() when the screen closes or the filters change.
438
+ if (result.error?.code === 'request_timeout') { /* deadline exceeded */ }
439
+ if (result.error?.code === 'request_cancelled') { /* caller cancelled */ }
440
+ ```
441
+
442
+ `dataRequest` preserves the query's selected types and normal result shape.
443
+ The deadline covers asynchronous token lookup, transport and response-body
444
+ consumption. It disables automatic retries, clears its timer and removes its
445
+ caller-signal listener after completion. Server responses retain their original
446
+ status and error code. Cancellation and deadline failures have status `0` and
447
+ null data; use the normal result-returning query mode with this helper.
448
+
449
+ A client deadline stops waiting for a response. PostgREST does not guarantee
450
+ immediate SQL cancellation when the connection closes. Gregale's restricted SQL
451
+ role enforces a 15-second statement timeout; an already running query can occupy
452
+ a database connection until that limit. Cancelling a mutation does not prove it
453
+ rolled back: reconcile its outcome before retrying. The integration gate checks
454
+ that concurrent cancelled RPCs release their connections within the server
455
+ statement timeout and that subsequent reads succeed.
456
+
457
+ ### Optimistic concurrency
458
+
459
+ Use a database-managed version column to prevent stale edits from overwriting a
460
+ newer value. The [concurrent document example](../../examples/data-api-concurrency/README.md)
461
+ contains a trigger that increments the version for every update and a typed
462
+ edit/delete client.
463
+
464
+ ```ts
465
+ import { optimisticMutation } from '@gregale/data'
466
+
467
+ const result = await optimisticMutation(
468
+ db.from('documents').update({ body: editedBody })
469
+ .eq('id', document.id).eq('version', document.version)
470
+ .select('id,body,version'),
471
+ )
472
+ if (result.outcome === 'applied') {
473
+ document = result.row
474
+ } else if (result.outcome === 'conflict') {
475
+ // Reload the visible row and let the user review their edits.
476
+ } else {
477
+ // Preserve result.error and result.status; reconcile uncertain writes.
478
+ }
479
+ ```
480
+
481
+ The helper preserves selected row types and disables automatic retries. Use
482
+ `delete()` with the same primary-key/version filters for conditional deletion.
483
+ A stale, missing, deleted or RLS-hidden row produces the same `conflict` outcome;
484
+ a transport/server error remains an `error`. Include all primary-key columns,
485
+ and always call `select()` with an array result. The helper classifies the
486
+ response; the SQL predicate and version trigger enforce concurrency. It cannot
487
+ undo a mutation that targeted multiple rows. Use normal result-returning queries
488
+ rather than `single()` or `throwOnError()` with this helper.
489
+
490
+ ### Retrying uncertain writes safely
491
+
492
+ The [idempotent order example](../../examples/data-api-idempotency/README.md)
493
+ provides a typed `create_order_once` RPC backed by a subject/tenant/key unique
494
+ constraint and immutable stored response. Persist a UUID and the complete
495
+ operation payload before sending the first request, and reuse both after a
496
+ transport failure or deadline. Identical retries return the original row;
497
+ a changed total returns HTTP 409 with `PT409` and
498
+ `idempotency_payload_conflict`. A new key starts a new operation.
499
+
500
+ The example's typed client composes generated RPC arguments with `dataRequest`;
501
+ no generic retry wrapper or HTTP header can make arbitrary mutations idempotent.
502
+ The database transaction enforces the guarantee. See the example for permissions,
503
+ receipt retention and limitations on external side effects.
504
+
505
+ ### Read-only mutation recovery
506
+
507
+ Use an application's receipt lookup RPC to check a pending operation before
508
+ deciding whether to retry its write. The starter's append-only
509
+ `0011_note_receipt_lookup.sql` migration installs `read_note_create_receipt`;
510
+ apply the normal owner RPC permission workflow, refresh the API and regenerate
511
+ types. The idempotent-order example similarly adds `read_order_receipt`.
512
+ These authenticated RPCs derive identity from request claims, compare the original
513
+ key and payload, and return the stored original response without executing a write.
514
+
515
+ Given a pending note saved before the first attempt, use the same API and signed-in
516
+ identity and retain its original key, body and tag array:
517
+
518
+ ```ts
519
+ import { dataRequest, reconcileMutation } from '@gregale/data'
520
+
521
+ const response = await dataRequest(
522
+ db.rpc('read_note_create_receipt', {
523
+ idempotency_key: pending.key,
524
+ note_body: pending.body,
525
+ tag_names: pending.tags,
526
+ }).select('id,body,subject'),
527
+ { timeoutMs: 5000, signal },
528
+ )
529
+ const recovery = reconcileMutation(response, row =>
530
+ row.subject === pending.subject && row.body === pending.body,
531
+ )
532
+ if (recovery.outcome === 'confirmed') {
533
+ showSavedNote(recovery.row.id)
534
+ } else {
535
+ // Keep the pending key/payload. Review conflicts or check again explicitly.
536
+ }
537
+ ```
538
+
539
+ `reconcileMutation` classifies a completed lookup; it executes no query, polling
540
+ or retry. Its synchronous predicate binds the returned receipt to the original
541
+ operation and preserves projected row types. Confirm only the same API, subject,
542
+ tenant where applicable, key and full payload. The SQL lookup compares payload
543
+ fields that are not part of the returned projection. Use `validateRpcResponse`
544
+ first when the application also requires runtime response validation.
545
+
546
+ Results are `confirmed` with `row`, `payload_conflict` with the original error,
547
+ or `unresolved` with `reason` (`not_found`, `request_failed`, `invalid_receipt`,
548
+ `replay_expired`).
549
+ Status is preserved, as are request errors on unresolved failures. Malformed,
550
+ multiple or mismatched rows and predicate exceptions cannot confirm the write;
551
+ rejected data and predicate exceptions are omitted. Conflict classification
552
+ requires HTTP 409, `PT409` and `idempotency_payload_conflict` exactly.
553
+
554
+ No visible receipt can mean uncommitted work, a hidden operation or a purged
555
+ receipt. It never proves rollback and does not authorize a new write. Keep retry
556
+ explicit. For legacy contracts, purging ends the guarantee for that key and a
557
+ replay can create a duplicate. Confirmation describes the original committed
558
+ response, even if the business row was subsequently edited or deleted.
559
+
560
+ ### Opt-in v2 replay expiry
561
+
562
+ The starter's `0012_note_replay_expiry.sql` adds
563
+ `create_note_with_tags_once_v2` and `read_note_create_receipt_v2`. Apply the
564
+ migration, owner RPC grants and schema refresh, then regenerate types before
565
+ using these functions. Legacy functions keep their original retention contract.
566
+
567
+ ```ts
568
+ import { createReplayKeyV2, classifyDataError, dataRequest } from '@gregale/data'
569
+
570
+ // Save this entire operation under its original API and identity before sending.
571
+ const pending = {
572
+ contract: 'v2', subject: session.subject,
573
+ key: createReplayKeyV2(), body: 'hello', tags: ['work'],
574
+ }
575
+ const result = await dataRequest(db.rpc('create_note_with_tags_once_v2', {
576
+ idempotency_key: pending.key, note_body: pending.body, tag_names: pending.tags,
577
+ }), { timeoutMs: 5000 })
578
+ if (classifyDataError(result.error, { status: result.status })?.category === 'replay_expired') {
579
+ // Keep pending. Check the original receipt or resolve through business review.
580
+ // Never generate a replacement key automatically.
581
+ }
582
+ ```
583
+
584
+ Keys are UUIDv7 values using the client clock and Web Crypto randomness. V2 uses
585
+ the key's embedded timestamp plus **24 hours**, allowing at most **five minutes**
586
+ of future clock skew. Server wall time decides expiry, including after lock
587
+ waits; a slow client clock shortens the available window. Client timestamps are
588
+ not trusted to assert when an operation actually began. Preserve the exact key:
589
+ changing its timestamp or contract version creates another operation namespace.
590
+
591
+ Expired writes return HTTP 410, `PT410`, `idempotency_key_expired`, even after
592
+ receipt cleanup. `classifyDataError` exposes `replay_expired` with `reconcile`
593
+ guidance. The v2 lookup can still confirm a retained expired receipt; if missing,
594
+ the exact expiry response becomes `unresolved` / `replay_expired`. Expiry cannot
595
+ prove whether an earlier attempt committed. No helper retries or replaces keys.
596
+ Invalid UUID versions/variants return `PT400` / `idempotency_key_invalid`, and
597
+ timestamps beyond the clock allowance return `PT400` / `idempotency_key_in_future`.
598
+
599
+ The migration cleanup tool accepts `--contract v2` and deletes only receipts whose
600
+ key deadline has closed. Keep the fixed v2 window unchanged; a longer policy needs
601
+ a new version to avoid reviving purged keys. The guarantee covers this SQL
602
+ contract under an accurate database clock and retained database history. Owner
603
+ schema changes, restores that lose receipts and external effects need separate
604
+ recovery policies.
605
+
606
+ ### Versioned updates and deletes
607
+
608
+ The starter's `0013_note_mutation_receipts.sql` adds opt-in conditional writes
609
+ `update_note_once_v2` and `delete_note_once_v2`. Both require a UUIDv7 operation
610
+ key, note ID and expected version. Update additionally accepts `note_patch` with
611
+ only non-null `body` text and/or integer `priority`. Apply migrations and owner
612
+ RPC permissions, refresh the API, regenerate types and install the paired SDK.
613
+
614
+ ```ts
615
+ import { classifyVersionedMutation, createReplayKeyV2, dataRequest, reconcileMutation } from '@gregale/data'
616
+
617
+ // Persist args and original API/identity/contract/action before the first send.
618
+ const subject = session.subject
619
+ const args = {
620
+ idempotency_key: createReplayKeyV2(), note_id: note.id,
621
+ expected_version: note.version, note_patch: { body: 'edited' },
622
+ }
623
+ const matches = (row: { id: number; subject: string; version: number; body: string }) =>
624
+ row.id === args.note_id && row.subject === subject &&
625
+ row.version === args.expected_version + 1 && row.body === args.note_patch.body
626
+ const response = await dataRequest(
627
+ db.rpc('update_note_once_v2', args).select('id,subject,version,body'),
628
+ { timeoutMs: 5000 },
629
+ )
630
+ const outcome = classifyVersionedMutation(response, matches)
631
+
632
+ // For an uncertain write, check the original receipt explicitly.
633
+ const read = await dataRequest(
634
+ db.rpc('read_note_update_receipt_v2', args).select('id,subject,version,body'),
635
+ { timeoutMs: 5000 },
636
+ )
637
+ const recovery = reconcileMutation(read, matches)
638
+ ```
639
+
640
+ `classifyVersionedMutation` classifies a completed write result, without executing
641
+ or retrying anything. Its synchronous predicate preserves selected types and
642
+ binds the snapshot to the original operation. Outcomes are `applied` with the
643
+ original row, `version_conflict`, `payload_conflict`, or `unresolved` with the
644
+ existing reconciliation reasons. Only HTTP 409 / `PT409` /
645
+ `idempotency_version_conflict` becomes `version_conflict`; generic conflicts do
646
+ not acquire this meaning. Original errors/status are preserved. An empty success
647
+ result stays unresolved. Expiry remains unresolved with reason `replay_expired`.
648
+
649
+ For delete, call `delete_note_once_v2` and recover with
650
+ `read_note_delete_receipt_v2`, using key, note ID and expected version. Its receipt
651
+ contains the deleted snapshot with that same version. Update returns the stored
652
+ post-update version. Both lookups are read-only and remain useful after subsequent
653
+ edits/deletion; replay returns the saved response without reapplying the mutation.
654
+
655
+ Stale, absent and RLS-hidden rows share the version-conflict response. Failed
656
+ mutations leave no success receipt and reserve no key. A conflict alone cannot
657
+ confirm an earlier uncertain write. Preserve the original operation and never
658
+ automatically replace its key or expected version. Updates/deletes share a key
659
+ namespace, independent of creation; changing action, target, version or patch for
660
+ a successful key returns a payload conflict. The fixed v2 expiry/cleanup contract
661
+ also applies. Full setup and maintenance are documented in
662
+ [Data API recovery](../../docs/data-api.md#versioned-update-and-delete-recovery).
663
+
664
+ ### Bulk mutations with partial results
665
+
666
+ ```ts
667
+ import { bulkMutations } from '@gregale/data'
668
+
669
+ const results = await bulkMutations(edits, edit =>
670
+ db.from('documents').update({ body: edit.body })
671
+ .eq('id', edit.id).eq('version', edit.version).select('id,body,version'),
672
+ { batchSize: 100, concurrency: 2, timeoutMs: 5000, signal, onProgress },
673
+ )
674
+ ```
675
+
676
+ Each item runs once in its own transaction. `batchSize` is a scheduling window,
677
+ not an atomic database batch. Results preserve input order and selected row
678
+ types, distinguishing `applied`, `conflict`, `error`, `uncertain`, `skipped`, and
679
+ `invalid`. Cancellation skips queued items and aborts active requests. Progress
680
+ contains aggregate counts only; observer failures do not interrupt execution.
681
+
682
+ Reconcile uncertain writes before retrying. Use idempotent RPCs or versioned
683
+ conditional mutations where needed. A single normal `insert([...])` request
684
+ retains its existing atomic semantics. See the
685
+ [bulk document example](../../examples/data-api-bulk/README.md) for full outcomes,
686
+ transaction boundaries and retry guidance.
687
+
688
+ ### Classify errors for application recovery
689
+
690
+ ```ts
691
+ import { classifyDataError } from '@gregale/data'
692
+
693
+ const result = await db.from('notes').insert(input).retry(false)
694
+ const failure = classifyDataError(result.error, { status: result.status })
695
+ if (failure?.category === 'unique_violation') {
696
+ showValidationMessage('That value is already in use.')
697
+ }
698
+ ```
699
+
700
+ The helper returns `null` for a null/undefined error. Otherwise it returns frozen
701
+ metadata with `category`, `recovery`, `code`, `status`, and the unchanged, typed
702
+ `original` error. It also accepts errors caught from `throwOnError()`; omit status
703
+ when no response status is available. It never executes a request or changes
704
+ retry settings. `.retry(false)` in this example disables the underlying client's
705
+ retries explicitly.
706
+
707
+ | Category | Recognized code or fallback | Recovery guidance |
708
+ | --- | --- | --- |
709
+ | `unique_violation` | SQLSTATE `23505` | `change_input` |
710
+ | `foreign_key_violation` | SQLSTATE `23503` | `change_input` |
711
+ | `lock_conflict` | SQLSTATE `55P03` | `wait` |
712
+ | `deadlock` | SQLSTATE `40P01` | `wait` |
713
+ | `authentication` | `token_required`, `token_invalid`, `PGRST301`–`PGRST303`, HTTP 401 | `authenticate` |
714
+ | `permission_denied` | SQLSTATE `42501`, `origin_not_allowed`, HTTP 403 | `check_permissions` |
715
+ | `contract_mismatch` | `schema_contract_mismatch` | `refresh_contract` |
716
+ | `timeout` | `request_timeout`, `query_timeout`, `request_deadline_exceeded`, `data_api_sql_deadline_exceeded`, HTTP 504 | `reconcile` |
717
+ | `cancelled` | `request_cancelled`, SQLSTATE `57014` | `reconcile` |
718
+ | `response_too_large` | `response_too_large` | `reconcile` |
719
+ | `rate_limited` | `data_api_rate_limited`, HTTP 429 | `wait` |
720
+ | `concurrency_limited` | `data_api_concurrency_limited` | `wait` |
721
+ | `unavailable` | `data_api_unavailable`, `data_api_overloaded`, `serving_contract_unavailable`, `data_api_refresh_unavailable`, HTTP 503 | `check_service` |
722
+ | `no_response` | Status 0 with no recognized code | `reconcile` |
723
+ | `unknown` | Other errors | `inspect` |
724
+
725
+ Recognized codes take precedence over HTTP fallback. Messages, details and hints
726
+ never determine the category. Generic 409/`PT409` errors do not establish a
727
+ contract mismatch; SQLSTATE `57014` establishes cancellation, not its cause.
728
+ Pass the response status to classify SQL `PT503` maintenance errors as unavailable.
729
+ Native exceptions without a recognized code or supplied status remain unknown;
730
+ use `dataRequest()` for stable deadline/cancellation codes.
731
+
732
+ Recovery values are suggestions, not instructions to retry. Timeouts,
733
+ cancellation, response-size limits, missing responses, and service failures do not prove a mutation
734
+ rolled back. Reconcile writes or use an application-owned idempotency contract
735
+ before replaying them. `refresh_contract` means review the rollout and regenerate
736
+ appropriate client types; it does not automatically change a pinned fingerprint.
737
+ An empty RLS-filtered result is not a permission error. The preserved original
738
+ error and its code can contain application or database information: use curated
739
+ UI messages and do not blindly log or display the classification object.
740
+
741
+ New managed Data API logins default to a five-second lock timeout and retain the
742
+ 15-second statement timeout. `55P03` also covers NOWAIT refusal, so the category
743
+ does not prove which lock policy fired. An uncaught contention error rolls back
744
+ the failing request's transaction, including earlier transactional RPC writes;
745
+ sequences and external effects are excluded. It cannot establish whether an
746
+ earlier attempt committed. Wait and review the whole operation before explicit
747
+ retry, using its idempotency/receipt contract when needed. Normal and throwing
748
+ CRUD/RPC errors keep their original code and private details; neither category
749
+ causes automatic replay. Existing roles and open pools require the documented
750
+ credential-policy upgrade and reconnect workflow; an SDK update does not alter
751
+ SQL defaults. Pinned PostgREST 14.3 already retries deadlocks and serialization
752
+ failures within its SQL transaction machinery. A deadlock may resolve and return
753
+ success from a single HTTP request; the SDK classification applies if `40P01`
754
+ actually reaches the caller and does not disable or extend engine retries.
755
+
756
+ An owner can opt the updated runtime into SQL deadlines across internal transaction
757
+ retries after installing the matching database hooks. The fixed gateway expiry
758
+ caps each attempt's remaining SQL budget. A hook that observes expiry returns
759
+ `data_api_sql_deadline_exceeded`, classified as `timeout` / `reconcile`, including
760
+ `throwOnError()` errors. A main statement interrupted by PostgreSQL can instead
761
+ return `57014`; its category remains `cancelled`. An invalid/missing hook contract
762
+ is a server setup failure, not evidence of mutation success. The SDK adds no retry
763
+ or database installation behavior. Review the original operation/receipt before
764
+ explicit replay; HTTP cancellation alone cannot establish SQL completion.
765
+
766
+ The updated runtime limits normal REST/RPC bodies to 16 MiB, independently of
767
+ row count. Known oversized lengths return `502 response_too_large`; overflow
768
+ after headers closes the incomplete body and can instead produce status 0 /
769
+ `no_response`. Generic HTTP 502 errors remain `unknown`. Use `onResponse` to
770
+ retain the header request ID before body consumption and correlate gateway logs.
771
+ Reduce future projections/page sizes or RPC output, and reconcile writes before
772
+ replay: SQL can commit before the result is rejected. The SDK adds no retries.
773
+
774
+ Optional gateway user-rate limits return `429 data_api_rate_limited` with
775
+ `Retry-After: 1`. Budgets follow verified subjects across token rotation and
776
+ routes, and are local to each runtime. The stable gateway code establishes a
777
+ rejection before SQL dispatch; generic HTTP 429 alone does not. Recovery `wait`
778
+ means defer the next request decision; it adds no timers or automatic retries,
779
+ including for ordinary GET/POST queries and `throwOnError()`. Preserve uncertain
780
+ write reconciliation when the error comes from another service or SQL.
781
+
782
+ Optional `DATA_API_USER_CONCURRENCY` limits concurrent authenticated requests per
783
+ verified subject within one runtime. Rejections use
784
+ `429 data_api_concurrency_limited`, classified as `concurrency_limited` / `wait`.
785
+ Their `Retry-After` is advisory (one second for active work, up to 15 for uncertain
786
+ dispatch cooldown). The rejected call did not reach SQL, but an earlier call may
787
+ still be running or may have committed after cancellation. Review that earlier
788
+ outcome separately. The SDK adds no retries, timers or automatic mutation replay;
789
+ generic HTTP 429 continues to fall back to `rate_limited`.
790
+
791
+ ### Validate RPC arguments at runtime
792
+
793
+ Use `validatedRpc()` when inputs come from forms, JSON or JavaScript. Supply a
794
+ synchronous application-owned parser that returns the generated RPC argument
795
+ object, then construct the typed query in the callback:
796
+
797
+ ```ts
798
+ import { validatedRpc, classifyDataError } from '@gregale/data'
799
+
800
+ // Example approved RPC: create_note({ body: string }) -> note ID.
801
+ const noteArgs = {
802
+ parse(value: unknown): { body: string } {
803
+ if (!value || typeof value !== 'object' || !('body' in value) ||
804
+ typeof value.body !== 'string' || !value.body.trim()) {
805
+ throw new Error('Body is required')
806
+ }
807
+ return { body: value.body.trim() }
808
+ },
809
+ }
810
+
811
+ const outcome = await validatedRpc(formInput, noteArgs,
812
+ args => db.rpc('create_note', args).retry(false))
813
+ if (outcome.outcome === 'validation_failed') {
814
+ showValidationMessage('Enter a note body.')
815
+ } else {
816
+ const { data, error, status } = outcome.result
817
+ const failure = classifyDataError(error, { status })
818
+ // data retains the generated create_note return type.
819
+ }
820
+ ```
821
+
822
+ A compatible schema's `.parse()` method, such as a synchronous Zod parser, can
823
+ replace `noteArgs`. The parser owns required fields, unknown-key policy, defaults,
824
+ transformations and field-level UI validation. It must return an argument object;
825
+ null, arrays, primitives and asynchronous outputs are rejected. Empty objects
826
+ support zero-argument RPCs. Generated types check parser output against the chosen
827
+ RPC, including required arguments and value types. Select the appropriate schema
828
+ on `db` before calling the helper.
829
+
830
+ Invalid input returns `{ outcome: 'validation_failed', error }` with a
831
+ `RpcValidationError` and code `RPC_ARGUMENT_VALIDATION_FAILED`. No query callback,
832
+ token lookup or request runs. The error excludes input values and original parser
833
+ exceptions; obtain field feedback separately through your application's parser,
834
+ using its own disclosure policy.
835
+
836
+ Valid input returns `{ outcome: 'completed', result }`. Completed means the
837
+ callback was awaited, not that the database operation succeeded: inspect
838
+ `result.error` as usual. The helper preserves the original result by reference,
839
+ including null results and server/transport errors. `throwOnError()` and callback
840
+ exceptions propagate unchanged. The callback can apply projections, filters,
841
+ `.single()`, abort signals or `dataRequest()` without losing result inference.
842
+
843
+ The helper does not change retry settings. `.retry(false)` above explicitly
844
+ prevents automatic retries; write reconciliation and idempotency remain
845
+ application responsibilities. PostgreSQL constraints and RLS remain authoritative.
846
+ The helper does not clone parser input or output; application parsers own any
847
+ mutation they perform.
848
+
849
+ ### Validate entire RPC responses
850
+
851
+ Generated declarations describe expected responses; they do not validate received
852
+ JSON. Use `validateRpcResponse()` with a synchronous application-owned parser
853
+ after awaiting a direct RPC or a completed `validatedRpc()` result:
854
+
855
+ ```ts
856
+ import { validateRpcResponse, classifyDataError } from '@gregale/data'
857
+
858
+ // Example approved scalar RPC: count_notes() -> integer.
859
+ const result = await db.rpc('count_notes', {}).retry(false)
860
+ const checked = validateRpcResponse(result, {
861
+ parse(value: unknown): number {
862
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
863
+ throw new Error('Invalid count')
864
+ }
865
+ return value
866
+ },
867
+ })
868
+
869
+ if (checked.outcome === 'validated') {
870
+ const count: number = checked.result.data
871
+ } else if (checked.outcome === 'request_failed') {
872
+ const failure = classifyDataError(checked.result.error, {
873
+ status: checked.result.status,
874
+ })
875
+ } else {
876
+ // RPC_RESPONSE_VALIDATION_FAILED; the original HTTP status is retained.
877
+ showValidationMessage('The server returned an unexpected result.')
878
+ }
879
+ ```
880
+
881
+ The parser checks the entire `data` value: a scalar, JSON object, projected row or
882
+ row array. It owns validation, transformations, nullable handling and cloning.
883
+ Synchronous schema parsers such as Zod's `.parse()` are compatible. Null or
884
+ undefined successful data is passed through the parser, not silently skipped.
885
+ Async parser outputs are rejected. To validate individual JSON fields in an
886
+ already checked row result, the existing `validateJson()` remains available.
887
+
888
+ `validated` returns a shallow copy of the response with parser output in `data`
889
+ and `error: null`. The parser output determines the new data type; status, count
890
+ and other response metadata retain their original types and values.
891
+ `request_failed` returns the original response by reference without parsing when
892
+ it has an error or a non-2xx status, including transport/deadline failures.
893
+ `validation_failed` returns a `RpcResponseValidationError` with code
894
+ `RPC_RESPONSE_VALIDATION_FAILED` and the original HTTP status. It excludes rejected
895
+ data and the original parser exception. Its HTTP status can still be 200.
896
+
897
+ This helper executes no requests and changes no retry settings. A response
898
+ validation failure does not imply rollback: a mutation may already have committed.
899
+ Reconcile through reads or a reviewed idempotency contract before considering
900
+ another write; never automatically replay on a validation failure. Raw request
901
+ failure results may still contain private database errors. Use curated UI messages.
902
+ The helper does not mutate the original response itself, but parsers receive its
903
+ data by reference and are responsible for any mutation they perform.
904
+
905
+ ### Encrypted continuation tokens for server routes
906
+
907
+ Existing `cursorPage`/`cursorFrom` helpers use raw ordering values. For routes that
908
+ accept an untrusted continuation token, use `createCursorPager` on the server:
909
+
910
+ ```ts
911
+ import { createCursorPager } from '@gregale/data'
912
+
913
+ // Load a stable 32-byte random key from server-side configuration. Never send it
914
+ // to a browser or commit it. Reuse the pager across requests on this server.
915
+ const pager = await createCursorPager({ key: cursorKeyBytes, ttlMs: 15 * 60_000, maxPageSize: 100 })
916
+ const order = [
917
+ { column: 'created_at' },
918
+ { column: 'id', unique: true },
919
+ ] as const
920
+
921
+ // Derive scope from verified application identity/tenant/permission claims.
922
+ const page = await pager.page(
923
+ db.from('orders').select('id,created_at,total').eq('team_id', authenticatedTeamId),
924
+ {
925
+ order, size: 50,
926
+ scope: { identity: trustedIdentityScope, schemaFingerprint: currentSchemaFingerprint },
927
+ after: incomingContinuation,
928
+ },
929
+ )
930
+ // Return page.result and page.nextCursor to the caller. API errors remain in result.
931
+ ```
932
+
933
+ Ordering columns must appear in the selected projection and have scalar types.
934
+ A single primary key works with `[{ column: 'id', unique: true }]`; timestamp-plus-ID
935
+ ordering uses the example above. The final column must actually be non-null and
936
+ unique within the filtered result. The helper validates the declaration and values,
937
+ but does not inspect database constraints. Use a fresh GET array query with no root
938
+ order, limit, offset or range applied beforehand. Nested projection types are preserved.
939
+
940
+ Tokens use authenticated AES-GCM encryption with fresh random nonces. They bind the
941
+ actual query endpoint, schema, filter/projection parameters, ordering, page size,
942
+ identity scope and schema fingerprint. Refreshing a JWT need not change the scope;
943
+ include tenant and relevant permission/version claims in a server-derived scope.
944
+ Create the data client with `expectedSchemaFingerprint` matching the scope so the
945
+ gateway also rejects schema changes before executing a read. The scope alone does
946
+ not detect an unannounced gateway migration. The helper does not authenticate callers,
947
+ read claims from JWTs or replace RLS.
948
+ Keep the key exclusively on trusted servers. A browser should submit issued tokens
949
+ to your route; browser-only clients can continue using the raw keyset helpers.
950
+
951
+ The default TTL is 15 minutes (maximum one day), and default maximum page size is
952
+ 999. One additional row is fetched to determine continuation within Gregale's
953
+ 1,000-row response cap. Each page returns at most the requested size, with
954
+ `nextCursor`, `previousCursor`, `hasMore` and `direction`. `hasMore` describes the
955
+ current traversal direction. `before` returns nearest preceding rows in reverse
956
+ order, as with `cursorPage`; use `previousCursor` to continue backward and reverse
957
+ rows for normal display. Empty/error results return no continuations. First forward
958
+ pages have no previous cursor. Continuations describe boundaries, not guaranteed
959
+ nonempty pages if records are subsequently deleted.
960
+
961
+ Malformed/tampered tokens fail with `CursorPaginationError.code = 'invalid_cursor'`.
962
+ Expired tokens use `expired_cursor`; changed query, scope, ordering, page size or
963
+ schema uses `incompatible_cursor`. These failures occur before query execution.
964
+ Invalid options or malformed successful responses have separate codes. Key rotation
965
+ invalidates existing tokens; restart pagination rather than attempting an automatic
966
+ fallback. Tokens are bounded to 16 KiB and ordering to 16 columns. Cursor values
967
+ and filters are not exposed in plaintext tokens. Pagination does not provide a
968
+ snapshot across requests, and changing ordered values can still move rows between
969
+ pages. Index the filter and ordering columns and review plans with representative data.
970
+
971
+ ### Validating atomic batch receipts
972
+
973
+ For the starter's opt-in v2 batch RPC, use its `prepareNoteBatch` and
974
+ `noteBatchMatches` helpers with the paired generated types. `classifyVersionedMutation`
975
+ and `reconcileMutation` accept synchronous type guards, so validating the entire
976
+ one-row envelope narrows its nested JSON to typed ordered snapshots. Every item
977
+ must match before the result becomes `applied` or `confirmed`; classify completed
978
+ responses only. These helpers send no requests or retries.
979
+
980
+ The explicit RPC commits 1–100 distinct note updates/deletes atomically and
981
+ stores one receipt; SDK `bulkMutations` retains its separate-request semantics.
982
+ Retain the original API, identity, key, contract and ordered operation array for
983
+ read-only recovery. Expiry, absence and conflicts cannot alone resolve an earlier
984
+ uncertain request. See the [batch contract and example](../../docs/data-api.md#atomic-note-batch-recovery).
985
+
986
+ ### Durable mutation journals
987
+
988
+ `createMutationJournal` optionally saves an original prepared operation through
989
+ an application-supplied atomic store and synchronous lossless parser. Provide
990
+ its exact API URL, optional schema fingerprint, subject, tenant (or null), and
991
+ contract. Operations must include that context, one canonical UUIDv7 `key` and
992
+ the complete captured payload. The parser must return identical canonical JSON;
993
+ restoration cannot silently drop fields or replace a key. The generated v2
994
+ transaction client supplies this parser and an easier persistent wrapper.
995
+
996
+ Use `createIndexedDBMutationStore({databaseName:'my-app-data-mutations'})` in a
997
+ browser to opt into a dedicated, bounded store with strict transaction durability.
998
+ It opens lazily. `journal.prepare(slot,operation)` inserts only into an empty
999
+ stable slot. `journal.load(slot)` validates and freezes saved data without a
1000
+ request. `journal.dispatch(entry,send)` commits uncertainty before invoking the
1001
+ explicit callback once, returning its new `entry` and original `response`.
1002
+ Competing tabs cannot claim the same prepared revision. Storage failures prevent
1003
+ sending; callback errors leave the uncertain operation available through load.
1004
+
1005
+ `journal.reconcile(entry,response,matches)` classifies a completed response using
1006
+ the existing receipt contract/type guard. `journal.recover(entry,lookup,matches)`
1007
+ explicitly calls a receipt-read callback and classifies it. Neither performs
1008
+ retries or key replacement. They return `result`, `entry` and `persistence`:
1009
+ `saved`, `unchanged`, `conflict` or `storage_failed`. Proven server success remains
1010
+ in `result` even if a local confirmation marker cannot be committed. Empty,
1011
+ expired, conflicting and malformed receipts keep the original operation.
1012
+
1013
+ Only `journal.removeConfirmed(entry)` explicitly removes local records, with
1014
+ an atomic revision check. It cannot clear uncertainty or delete newer work from
1015
+ a reused slot. Handles belong to one journal instance; load new ones after
1016
+ restart. API/identity/tenant/contract/fingerprint mismatches and invalid records
1017
+ fail closed without returning or changing the saved operation.
1018
+
1019
+ Default bounds: 100 IndexedDB records, 8 MiB stored values, 1 MiB per record,
1020
+ 256 UTF-8 bytes per slot/database name and JSON depth 64. Count/byte budgets may
1021
+ be lowered. No automatic pruning, background polling or fallback storage is
1022
+ introduced. Applications intentionally persist payloads; their parser should
1023
+ allow only the prepared operation and exclude credentials/request options.
1024
+ Origin storage must remain available for recovery; clearing/evicting it or losing
1025
+ the device removes that local copy. A custom `MutationJournalStore` must implement
1026
+ durable atomic `compareExchange(slot,expected,next)` across its users; separate
1027
+ localStorage reads/writes do not provide that guarantee.
1028
+
1029
+ Errors use `MutationJournalError.code` with curated messages: storage_unavailable,
1030
+ storage_full, conflict, invalid_record, invalid_operation, context_mismatch,
1031
+ invalid_entry, not_prepared and not_confirmed. Original storage/parser exceptions
1032
+ and rejected payloads are omitted. See the [generated v2 integration](../../docs/data-api.md#durable-pending-operation-recovery).