@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.
- package/LICENSE +202 -0
- package/README.md +1031 -2
- package/dist/bulk.d.ts +61 -0
- package/dist/bulk.js +63 -0
- package/dist/client-fetch.d.ts +34 -0
- package/dist/client-fetch.js +62 -0
- package/dist/cursor-token.d.ts +53 -0
- package/dist/cursor-token.js +179 -0
- package/dist/cursor.d.ts +45 -0
- package/dist/cursor.js +78 -0
- package/dist/deadline.d.ts +19 -0
- package/dist/deadline.js +29 -0
- package/dist/errors.d.ts +17 -0
- package/dist/errors.js +68 -0
- package/dist/exact-numeric.d.ts +15 -0
- package/dist/exact-numeric.js +125 -0
- package/dist/index.d.ts +49 -0
- package/dist/index.js +39 -0
- package/dist/indexeddb-mutation-store.d.ts +12 -0
- package/dist/indexeddb-mutation-store.js +139 -0
- package/dist/json.d.ts +39 -0
- package/dist/json.js +39 -0
- package/dist/live/client.d.ts +192 -0
- package/dist/live/client.js +555 -0
- package/dist/live/index.d.ts +31 -0
- package/dist/live/index.js +28 -0
- package/dist/live/protocol.d.ts +125 -0
- package/dist/live/protocol.js +271 -0
- package/dist/live/react.d.ts +22 -0
- package/dist/live/react.js +59 -0
- package/dist/live/seal.d.ts +38 -0
- package/dist/live/seal.js +98 -0
- package/dist/live/sql.d.ts +11 -0
- package/dist/live/sql.js +58 -0
- package/dist/mutation-journal.d.ts +78 -0
- package/dist/mutation-journal.js +223 -0
- package/dist/numeric.d.ts +11 -0
- package/dist/numeric.js +40 -0
- package/dist/optimistic.d.ts +24 -0
- package/dist/optimistic.js +18 -0
- package/dist/reconcile.d.ts +28 -0
- package/dist/reconcile.js +28 -0
- package/dist/replay-key.d.ts +8 -0
- package/dist/replay-key.js +27 -0
- package/dist/response.d.ts +33 -0
- package/dist/response.js +29 -0
- package/dist/rpc.d.ts +20 -0
- package/dist/rpc.js +31 -0
- package/dist/storage-uploads.d.ts +63 -0
- package/dist/storage-uploads.js +104 -0
- package/dist/storage.d.ts +74 -0
- package/dist/storage.js +89 -0
- package/dist/validation.d.ts +26 -0
- package/dist/validation.js +40 -0
- package/dist/versioned-mutation.d.ts +28 -0
- package/dist/versioned-mutation.js +13 -0
- package/package.json +19 -4
package/README.md
CHANGED
|
@@ -1,3 +1,1032 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Gregale Data API client
|
|
2
2
|
|
|
3
|
-
|
|
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).
|