@revenexx/app-sdk 0.9.0 → 1.0.0
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/README.md +141 -35
- package/dist/{chunk-2BOFXTTC.js → chunk-73D37ZGB.js} +96 -6
- package/dist/chunk-73D37ZGB.js.map +1 -0
- package/dist/{errors-D7FGkghT.d.cts → errors-BPYDadk4.d.cts} +18 -6
- package/dist/{errors-D7FGkghT.d.ts → errors-BPYDadk4.d.ts} +18 -6
- package/dist/index.cjs +86 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10 -3
- package/dist/index.d.ts +10 -3
- package/dist/index.js +71 -81
- package/dist/index.js.map +1 -1
- package/dist/router/index.cjs +47 -17
- package/dist/router/index.cjs.map +1 -1
- package/dist/router/index.d.cts +27 -4
- package/dist/router/index.d.ts +27 -4
- package/dist/router/index.js +78 -15
- package/dist/router/index.js.map +1 -1
- package/package.json +1 -6
- package/dist/chunk-2BOFXTTC.js.map +0 -1
- package/dist/chunk-TUTGCI5D.js +0 -41
- package/dist/chunk-TUTGCI5D.js.map +0 -1
- package/dist/instrument.cjs +0 -75
- package/dist/instrument.cjs.map +0 -1
- package/dist/instrument.d.cts +0 -26
- package/dist/instrument.d.ts +0 -26
- package/dist/instrument.js +0 -7
- package/dist/instrument.js.map +0 -1
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ npm install @revenexx/app-sdk
|
|
|
18
18
|
## Data client
|
|
19
19
|
|
|
20
20
|
The client gives every entity the same methods — `list`, `page`, `get`,
|
|
21
|
-
`create`, `update`, `delete` — and the same query shape, independent of where
|
|
21
|
+
`create`, `update`, `updateIf`, `delete` — and the same query shape, independent of where
|
|
22
22
|
the data lives. Swap the *adapter* to move between environments:
|
|
23
23
|
|
|
24
24
|
| adapter | use it for | infrastructure |
|
|
@@ -67,6 +67,36 @@ await db.markets.list({
|
|
|
67
67
|
|
|
68
68
|
Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `is`.
|
|
69
69
|
|
|
70
|
+
### Conditional updates
|
|
71
|
+
|
|
72
|
+
`update` writes by id, whatever state the row is in. A state transition that
|
|
73
|
+
two writers can race — a sweep abandoning a `placing` order while a re-submit
|
|
74
|
+
places it — needs the write to hold only if the row is still where the App
|
|
75
|
+
last saw it. `updateIf(id, where, patch)` is that compare-and-set, in one
|
|
76
|
+
request:
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
const placed = await db.orders.updateIf(id, { status: 'placing' }, { status: 'placed' });
|
|
80
|
+
if (!placed) {
|
|
81
|
+
// Someone else moved it first (or it is gone). Re-read and decide.
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
- `where` is the query `where` shape above, ANDed with the id. Postgres
|
|
86
|
+
re-checks it on the locked row, so of two racing writers exactly one wins.
|
|
87
|
+
- It resolves to the updated row, or `null` when no row matched — gone,
|
|
88
|
+
invisible, or the condition no longer holds. One PATCH cannot tell these
|
|
89
|
+
apart, and a lost race is an outcome to branch on, not an error.
|
|
90
|
+
- An empty `where` (or a condition left `undefined`) is a `400`: that is an
|
|
91
|
+
unconditional update, and `update` is the method for it. An empty patch is
|
|
92
|
+
a `400` as with `update`.
|
|
93
|
+
- It needs the `update` permission. A custom adapter that does not implement
|
|
94
|
+
`updateIf` makes the call throw — the client does not emulate it as a read
|
|
95
|
+
followed by a write, because that is the race.
|
|
96
|
+
|
|
97
|
+
The same holds for a numeric guard: `updateIf(id, { committed: seen }, { committed: seen + amount })`,
|
|
98
|
+
retried on `null`, is an optimistic budget commit.
|
|
99
|
+
|
|
70
100
|
### Permissions
|
|
71
101
|
|
|
72
102
|
The methods available per entity follow your App manifest's `permissions`
|
|
@@ -77,7 +107,7 @@ catch permission gaps before deploy.
|
|
|
77
107
|
### Custom adapters
|
|
78
108
|
|
|
79
109
|
The adapter is a small interface (`list/get/create/update/remove`, optional
|
|
80
|
-
`page`). Register a new backend before constructing the client:
|
|
110
|
+
`page` and `updateIf`). Register a new backend before constructing the client:
|
|
81
111
|
|
|
82
112
|
```js
|
|
83
113
|
const { registerAdapter, createClient } = require('@revenexx/app-sdk');
|
|
@@ -117,8 +147,10 @@ What you get:
|
|
|
117
147
|
`c.tenant`, `c.header(name)`, `c.log(msg)`, `c.json(data, status)`.
|
|
118
148
|
- **Error mapping** — throw `HttpError` / `notFound()` / `badRequest()` /
|
|
119
149
|
`forbidden()` / `conflict()` for explicit statuses; database constraint
|
|
120
|
-
violations get the status they deserve (see below); data-client permission
|
|
121
|
-
|
|
150
|
+
violations get the status they deserve (see below); a data-client permission
|
|
151
|
+
refusal is a `403` (`not_permitted`); anything else is logged and answered as
|
|
152
|
+
`500 {"error":"internal error","code":"internal_error"}` — the thrown message
|
|
153
|
+
never reaches the caller.
|
|
122
154
|
- **A health route** — `GET /` answers with the App identity, status and the
|
|
123
155
|
registered routes (disable with `createApp({ health: false })`).
|
|
124
156
|
- **404/405 handling** — unknown paths list the available routes; known paths
|
|
@@ -153,6 +185,49 @@ mountCrud(app, db.locales, {
|
|
|
153
185
|
Options: `only: ['list', 'get']` restricts the mounted routes; `defaultLimit` /
|
|
154
186
|
`maxLimit` tune pagination bounds (defaults 50 / 200).
|
|
155
187
|
|
|
188
|
+
**List query keys are checked.** A list accepts the columns in `columns`, the
|
|
189
|
+
reserved keys `limit`, `offset`, `order` (exported as `RESERVED_LIST_QUERY_KEYS`)
|
|
190
|
+
and whatever the App declares in `queryParams`. Anything else is refused rather
|
|
191
|
+
than ignored — an ignored filter answers `200` with the *unfiltered* list:
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
GET /customers/segments?organization_id=o1
|
|
195
|
+
-> 400 {"error":"unknown list filter 'organization_id' — …","code":"unknown_filter",
|
|
196
|
+
"details":{"unknown":["organization_id"],"allowed":["code","id",…,"limit","offset","order"]}}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Parameters the App handles itself (a wrapping handler, middleware, a flag it
|
|
200
|
+
tolerates) go in `queryParams`; they are accepted and never become filters:
|
|
201
|
+
|
|
202
|
+
```js
|
|
203
|
+
mountCrud(app, db.accounts, {
|
|
204
|
+
path: '/punchout/accounts',
|
|
205
|
+
columns: ENTITIES.accounts.columns,
|
|
206
|
+
queryParams: ['include_inactive'],
|
|
207
|
+
});
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Without `columns`, only the reserved and declared keys are accepted. A list
|
|
211
|
+
that reads its own parameters can also stay a hand-written route
|
|
212
|
+
(`only: ['get', 'create', 'update', 'delete']` plus `app.get(base, …)`).
|
|
213
|
+
|
|
214
|
+
The `mock` adapter answers a `where` on an undeclared column the way PostgREST
|
|
215
|
+
does (`400 bad_request`), instead of an empty result.
|
|
216
|
+
|
|
217
|
+
**A column filter is an exact value.** A value that starts with a PostgREST
|
|
218
|
+
operator (`eq.`, `in.`, `not.`, …) is refused rather than matched literally —
|
|
219
|
+
`?sku=in.(a,b)` used to go out as `sku=eq.in.(a,b)` and answer `200` with zero
|
|
220
|
+
rows:
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
GET /products?sku=in.(a,b)
|
|
224
|
+
-> 400 {"error":"filter 'sku' carries an operator ('in.') — …","code":"unsupported_filter_operator",
|
|
225
|
+
"details":{"parameter":"sku"}}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Value lists are not supported by the generic list; a route that needs one reads
|
|
229
|
+
its own parameter (`queryParams`, or a hand-written list).
|
|
230
|
+
|
|
156
231
|
### Constraint violations
|
|
157
232
|
|
|
158
233
|
A database constraint doing its job is not a server fault. The data adapters
|
|
@@ -187,11 +262,11 @@ PostgREST reports a write that touched no row as `200 []`, and handing the
|
|
|
187
262
|
missing element back as if it were the record put an `undefined` into App code
|
|
188
263
|
that only blew up at `res.json()` time, as a 500 with a raw Node message:
|
|
189
264
|
|
|
190
|
-
| condition | answer | message |
|
|
191
|
-
|
|
192
|
-
| `update` with a patch carrying no fields | `400` | `request body must contain at least one field to update` |
|
|
193
|
-
| `update` matched no row (deleted, or invisible under RLS) | `404` | `not found` |
|
|
194
|
-
| `create` returned no representation | `500` | `the record was created but could not be read back` |
|
|
265
|
+
| condition | answer | code | message |
|
|
266
|
+
|---|---|---|---|
|
|
267
|
+
| `update` with a patch carrying no fields | `400` | `empty_update` | `request body must contain at least one field to update` |
|
|
268
|
+
| `update` matched no row (deleted, or invisible under RLS) | `404` | `not_found` | `not found` |
|
|
269
|
+
| `create` returned no representation | `500` | `empty_representation` | `the record was created but could not be read back` |
|
|
195
270
|
|
|
196
271
|
The empty-patch rule lives in the data client, not in `mountCrud`, so it holds
|
|
197
272
|
for hand-written route handlers too. It is enforced before the request leaves
|
|
@@ -202,20 +277,40 @@ automatically. An App that routes itself must honour `err.status` in its
|
|
|
202
277
|
catch-all (`isHttpError(err) ? err.status : 500`), or it will report a 400 as a
|
|
203
278
|
500 no matter what the SDK raises.
|
|
204
279
|
|
|
280
|
+
### Every refusal carries a code
|
|
281
|
+
|
|
282
|
+
From 1.0 every refusal the SDK raises — and every one an App raises through the
|
|
283
|
+
helpers — carries a stable `code` beside its message. Branch on the code, never
|
|
284
|
+
on the wording:
|
|
285
|
+
|
|
286
|
+
| code | status | raised by |
|
|
287
|
+
|---|---|---|
|
|
288
|
+
| `not_found` | 404 | `notFound()`, `mountCrud` for an unknown id or parent, `update` that matched no row |
|
|
289
|
+
| `bad_request` | 400 | `badRequest()` |
|
|
290
|
+
| `forbidden` | 403 | `forbidden()` |
|
|
291
|
+
| `conflict` | 409 | `conflict()` |
|
|
292
|
+
| `not_permitted` | 403 | an entity-client call the manifest does not grant |
|
|
293
|
+
| `empty_update` | 400 | `update` / `PUT` with nothing to update |
|
|
294
|
+
| `empty_condition` | 400 | `updateIf` with an empty `where` |
|
|
295
|
+
| `undefined_condition` | 400 | a `where` entry left `undefined`, on any read or `updateIf` |
|
|
296
|
+
| `unknown_filter`, `unsupported_filter_operator`, `invalid_value` | 400 | a mounted list's querystring |
|
|
297
|
+
| `missing_parameter` | 400 | a `mountCrud` route without its path parameter |
|
|
298
|
+
| `no_route` / `method_not_allowed` | 404 / 405 | the router |
|
|
299
|
+
| `internal_error` | 500 | anything thrown that is not an `HttpError` |
|
|
300
|
+
| `unique_violation`, `exclusion_violation`, `foreign_key_violation`, `not_null_violation`, `check_violation`, `invalid_value`, `bad_request`, `data_error` | 409 / 400 / 500 | the data plane (table above) |
|
|
301
|
+
|
|
302
|
+
A hand-built `new HttpError(status, message)` carries the code it is given, or none.
|
|
303
|
+
|
|
205
304
|
## Who is acting
|
|
206
305
|
|
|
207
306
|
`c.tenant` says whose data a request is for. `c.actor` says whose hand is on it.
|
|
208
307
|
|
|
209
308
|
```js
|
|
210
309
|
app.post('/procurement/pending-approvals/{id}/approve', async (c) => {
|
|
211
|
-
// A signature has to be proven. `asserted` is a tenant server's word for a
|
|
212
|
-
// customer it is acting for — right for attribution, not for authority.
|
|
213
|
-
if (!c.actor.authenticated()) throw forbidden('this decision needs a signed-in approver');
|
|
214
|
-
|
|
215
310
|
const approval = await db.pending_approvals.get(c.params.id);
|
|
216
|
-
// Compare two names, never two absences:
|
|
217
|
-
// approval nobody is named on has none either, so `!==` alone would
|
|
218
|
-
// two nulls agree.
|
|
311
|
+
// Compare two names, never two absences: a caller with no contact has none,
|
|
312
|
+
// and an approval nobody is named on has none either, so `!==` alone would
|
|
313
|
+
// let the two nulls agree.
|
|
219
314
|
if (!c.actor.contact || approval.approver_contact_id !== c.actor.contact) {
|
|
220
315
|
throw forbidden('this approval is not yours');
|
|
221
316
|
}
|
|
@@ -223,31 +318,42 @@ app.post('/procurement/pending-approvals/{id}/approve', async (c) => {
|
|
|
223
318
|
});
|
|
224
319
|
```
|
|
225
320
|
|
|
321
|
+
Note what this does **not** do: gate on `authenticated()`. Read the next section
|
|
322
|
+
before you write that line.
|
|
323
|
+
|
|
226
324
|
| field | is |
|
|
227
325
|
|---|---|
|
|
228
|
-
| `user` / `email` | the human the gateway authenticated, or `null` |
|
|
326
|
+
| `user` / `email` | the human the gateway authenticated, or `null`. `null` today |
|
|
229
327
|
| `contact` / `organization` | the `customers` contact they were resolved to, or `null` |
|
|
230
328
|
| `permissions`, `holds(p)` | what the tenant's role provider grants that contact |
|
|
231
329
|
| `trust` | `authenticated`, `asserted` or `none` |
|
|
232
330
|
| `plane` | `contact`, `operator` or `system` |
|
|
233
|
-
| `authenticated()` | shorthand for `trust === 'authenticated'` |
|
|
234
|
-
|
|
235
|
-
**
|
|
236
|
-
on behalf of a customer: it *asserts*
|
|
237
|
-
through the tenant's role provider, and
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
`
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
331
|
+
| `authenticated()` | shorthand for `trust === 'authenticated'`, and `false` for every caller today |
|
|
332
|
+
|
|
333
|
+
**One plane produces anybody today, and it is `asserted`.** A storefront call is
|
|
334
|
+
made by a server holding the tenant API key on behalf of a customer: it *asserts*
|
|
335
|
+
the person, the gateway resolves the name through the tenant's role provider, and
|
|
336
|
+
`trust` is `asserted`. That is enough to stop a malicious end user and never a
|
|
337
|
+
compromised BFF, the same boundary `X-Revenexx-Market` sits on, and the platform
|
|
338
|
+
accepts it deliberately everywhere.
|
|
339
|
+
|
|
340
|
+
**`authenticated` is not currently reachable, and you must not build authority on
|
|
341
|
+
it.** The value exists in the contract, `c.actor` reads it correctly, and the
|
|
342
|
+
gateway does not produce it: a bearer token there is deliberately equivalent to an
|
|
343
|
+
API key, so it proves the tenant rather than a person. The population on that
|
|
344
|
+
plane is mostly machines — a theme site renders every request on the tenant's
|
|
345
|
+
system service user, schedules fan out on the same subject, an operator working
|
|
346
|
+
in a customer tenant acts on its operator service user — and none of them is
|
|
347
|
+
somebody. `authenticated()` therefore answers `false` for every caller, which is
|
|
348
|
+
the honest answer rather than a gap to work around. An app that refuses
|
|
349
|
+
`asserted` refuses everyone.
|
|
350
|
+
|
|
351
|
+
**`plane` follows from the same fact.** `contact` is somebody the gateway
|
|
352
|
+
resolved; `system` is nobody at all, which is a schedule, a webhook, a service
|
|
353
|
+
token or any caller that named no one. `operator` would be an authenticated human
|
|
354
|
+
with no contact and is likewise not produced today. Treating "no contact
|
|
355
|
+
resolved" as "must be the platform" reads an unknown customer as an
|
|
356
|
+
administrator, which is the mistake the field exists to prevent.
|
|
251
357
|
|
|
252
358
|
Every field comes from headers the gateway sets itself and strips from anything
|
|
253
359
|
a caller sends, so none of this can be talked up from outside. Never take the
|
|
@@ -25,10 +25,80 @@ function isHttpError(err) {
|
|
|
25
25
|
const e = err;
|
|
26
26
|
return e.__isHttpError === true || e.name === "HttpError" && typeof e.status === "number";
|
|
27
27
|
}
|
|
28
|
-
var notFound = (message = "not found") => new HttpError(404, message);
|
|
29
|
-
var badRequest = (message = "bad request", details) => new HttpError(400, message, details);
|
|
30
|
-
var forbidden = (message = "forbidden") => new HttpError(403, message);
|
|
31
|
-
var conflict = (message = "conflict") => new HttpError(409, message);
|
|
28
|
+
var notFound = (message = "not found", options = {}) => new HttpError(404, message, void 0, { code: "not_found", ...options });
|
|
29
|
+
var badRequest = (message = "bad request", details, options = {}) => new HttpError(400, message, details, { code: "bad_request", ...options });
|
|
30
|
+
var forbidden = (message = "forbidden", options = {}) => new HttpError(403, message, void 0, { code: "forbidden", ...options });
|
|
31
|
+
var conflict = (message = "conflict", options = {}) => new HttpError(409, message, void 0, { code: "conflict", ...options });
|
|
32
|
+
|
|
33
|
+
// src/query.ts
|
|
34
|
+
var OPS = /* @__PURE__ */ new Set(["eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "is"]);
|
|
35
|
+
function toParams(query = {}) {
|
|
36
|
+
const params = new URLSearchParams();
|
|
37
|
+
const { where = {}, select, order, limit, offset } = query;
|
|
38
|
+
for (const [col, cond] of Object.entries(where)) {
|
|
39
|
+
if (Array.isArray(cond)) {
|
|
40
|
+
params.append(col, `in.(${cond.join(",")})`);
|
|
41
|
+
} else if (cond && typeof cond === "object" && typeof cond.op === "string") {
|
|
42
|
+
const c = cond;
|
|
43
|
+
if (!OPS.has(c.op)) throw new Error(`query: unsupported operator '${c.op}'`);
|
|
44
|
+
const v = Array.isArray(c.value) ? `(${c.value.join(",")})` : c.value;
|
|
45
|
+
params.append(col, `${c.op}.${v}`);
|
|
46
|
+
} else if (cond === null) {
|
|
47
|
+
params.append(col, "is.null");
|
|
48
|
+
} else {
|
|
49
|
+
params.append(col, `eq.${cond}`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
if (Array.isArray(select) && select.length) params.set("select", select.join(","));
|
|
53
|
+
if (order) params.set("order", /\.(asc|desc)$/.test(order) ? order : `${order}.asc`);
|
|
54
|
+
if (Number.isInteger(limit)) params.set("limit", String(limit));
|
|
55
|
+
if (Number.isInteger(offset)) params.set("offset", String(offset));
|
|
56
|
+
return params;
|
|
57
|
+
}
|
|
58
|
+
function matches(row, where = {}) {
|
|
59
|
+
for (const [col, cond] of Object.entries(where)) {
|
|
60
|
+
const val = row[col] ?? null;
|
|
61
|
+
if (Array.isArray(cond)) {
|
|
62
|
+
if (!cond.includes(val)) return false;
|
|
63
|
+
} else if (cond && typeof cond === "object" && typeof cond.op === "string") {
|
|
64
|
+
const c = cond;
|
|
65
|
+
if (!compare(val, c.op, c.value)) return false;
|
|
66
|
+
} else if (val !== cond) {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return true;
|
|
71
|
+
}
|
|
72
|
+
function compare(a, op, b) {
|
|
73
|
+
switch (op) {
|
|
74
|
+
case "eq":
|
|
75
|
+
return a === b;
|
|
76
|
+
case "neq":
|
|
77
|
+
return a !== b;
|
|
78
|
+
case "gt":
|
|
79
|
+
return a > b;
|
|
80
|
+
case "gte":
|
|
81
|
+
return a >= b;
|
|
82
|
+
case "lt":
|
|
83
|
+
return a < b;
|
|
84
|
+
case "lte":
|
|
85
|
+
return a <= b;
|
|
86
|
+
case "is":
|
|
87
|
+
return a === b;
|
|
88
|
+
case "in":
|
|
89
|
+
return Array.isArray(b) && b.includes(a);
|
|
90
|
+
case "like":
|
|
91
|
+
case "ilike": {
|
|
92
|
+
const re = new RegExp(
|
|
93
|
+
"^" + String(b).replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".") + "$",
|
|
94
|
+
op === "ilike" ? "i" : ""
|
|
95
|
+
);
|
|
96
|
+
return re.test(String(a));
|
|
97
|
+
}
|
|
98
|
+
default:
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
32
102
|
|
|
33
103
|
// src/settings.ts
|
|
34
104
|
var DEFAULT_GATEWAY_ENDPOINT = "https://api.revenexx.com";
|
|
@@ -173,7 +243,22 @@ function updateFields(patch) {
|
|
|
173
243
|
);
|
|
174
244
|
}
|
|
175
245
|
function assertUpdatable(patch) {
|
|
176
|
-
if (updateFields(patch).length === 0) throw badRequest(EMPTY_UPDATE_MESSAGE);
|
|
246
|
+
if (updateFields(patch).length === 0) throw badRequest(EMPTY_UPDATE_MESSAGE, void 0, { code: "empty_update" });
|
|
247
|
+
}
|
|
248
|
+
var EMPTY_CONDITION_MESSAGE = "a conditional update needs at least one condition in where";
|
|
249
|
+
function assertCondition(where) {
|
|
250
|
+
if (!where || typeof where !== "object" || Array.isArray(where) || Object.keys(where).length === 0) {
|
|
251
|
+
throw badRequest(EMPTY_CONDITION_MESSAGE, void 0, { code: "empty_condition" });
|
|
252
|
+
}
|
|
253
|
+
assertDefined(where);
|
|
254
|
+
}
|
|
255
|
+
function assertDefined(where) {
|
|
256
|
+
if (!where || typeof where !== "object") return;
|
|
257
|
+
for (const [col, cond] of Object.entries(where)) {
|
|
258
|
+
if (cond === void 0) {
|
|
259
|
+
throw badRequest(`where.${col} is undefined \u2014 a condition needs a value`, void 0, { code: "undefined_condition" });
|
|
260
|
+
}
|
|
261
|
+
}
|
|
177
262
|
}
|
|
178
263
|
|
|
179
264
|
export {
|
|
@@ -183,13 +268,18 @@ export {
|
|
|
183
268
|
badRequest,
|
|
184
269
|
forbidden,
|
|
185
270
|
conflict,
|
|
271
|
+
OPS,
|
|
272
|
+
toParams,
|
|
273
|
+
matches,
|
|
186
274
|
EMPTY_UPDATE_MESSAGE,
|
|
187
275
|
updateFields,
|
|
188
276
|
assertUpdatable,
|
|
277
|
+
assertCondition,
|
|
278
|
+
assertDefined,
|
|
189
279
|
DEFAULT_GATEWAY_ENDPOINT,
|
|
190
280
|
DEFAULT_SETTINGS_TTL_MS,
|
|
191
281
|
DEFAULT_SETTINGS_ERROR_TTL_MS,
|
|
192
282
|
DEFAULT_SETTINGS_TIMEOUT_MS,
|
|
193
283
|
createSettings
|
|
194
284
|
};
|
|
195
|
-
//# sourceMappingURL=chunk-
|
|
285
|
+
//# sourceMappingURL=chunk-73D37ZGB.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/errors.ts","../src/query.ts","../src/settings.ts","../src/patch.ts"],"sourcesContent":["/**\n * The one error representation every layer of the SDK agrees on.\n *\n * `HttpError` used to live in `./router/router.ts`. It moved here so the data\n * adapters can raise it too: an adapter that knows a PostgREST failure is a\n * duplicate key can say \"409\" without the router having to guess from a\n * message string.\n *\n * Two fields exist purely to keep internal database detail out of responses:\n * - `message` / `details` are the *client-facing* payload — always safe,\n * never derived from a database error body.\n * - `serverDetail` is the raw diagnosis. The router logs it and drops it; it\n * is never serialised into a response.\n */\n\nexport interface HttpErrorOptions {\n /** Stable machine-readable code (e.g. `unique_violation`). Safe to expose. */\n code?: string;\n /**\n * Raw diagnosis for server-side logs and traces only — may contain table and\n * constraint names. Never included in the HTTP response.\n */\n serverDetail?: unknown;\n}\n\n/** Throw inside a handler (or an adapter) to answer with a specific HTTP status. */\nexport class HttpError extends Error {\n readonly status: number;\n readonly details?: unknown;\n readonly code?: string;\n readonly serverDetail?: unknown;\n /**\n * Structural marker. `dist/index.cjs` and `dist/router/index.cjs` are separate\n * bundles, so an error thrown by the data client and caught by the router is\n * an instance of a *different* copy of this class — `instanceof` would be\n * false. Everything checks this flag via `isHttpError` instead.\n */\n readonly __isHttpError = true as const;\n\n constructor(status: number, message: string, details?: unknown, options: HttpErrorOptions = {}) {\n super(message);\n this.name = 'HttpError';\n this.status = status;\n if (details !== undefined) this.details = details;\n if (options.code !== undefined) this.code = options.code;\n if (options.serverDetail !== undefined) this.serverDetail = options.serverDetail;\n }\n}\n\n/** Duck-typed `instanceof HttpError` — survives the bundle split (see above). */\nexport function isHttpError(err: unknown): err is HttpError {\n if (!err || typeof err !== 'object') return false;\n const e = err as { __isHttpError?: unknown; name?: unknown; status?: unknown };\n return e.__isHttpError === true || (e.name === 'HttpError' && typeof e.status === 'number');\n}\n\n/*\n * The helpers carry a stable `code` (from 1.0), so every refusal the SDK or an App\n * raises through them is machine-readable. Pass `options.code` for a sharper one.\n */\nexport const notFound = (message = 'not found', options: HttpErrorOptions = {}): HttpError =>\n new HttpError(404, message, undefined, { code: 'not_found', ...options });\nexport const badRequest = (message = 'bad request', details?: unknown, options: HttpErrorOptions = {}): HttpError =>\n new HttpError(400, message, details, { code: 'bad_request', ...options });\nexport const forbidden = (message = 'forbidden', options: HttpErrorOptions = {}): HttpError =>\n new HttpError(403, message, undefined, { code: 'forbidden', ...options });\nexport const conflict = (message = 'conflict', options: HttpErrorOptions = {}): HttpError =>\n new HttpError(409, message, undefined, { code: 'conflict', ...options });\n","import type { Query, FilterOp, Row } from './types.js';\n\n/**\n * PostgREST query helpers. `toParams` serialises a query for the HTTP adapters;\n * `matches` applies the same `where` semantics in memory for the mock adapter —\n * keeping one shape means App code is identical across adapters.\n */\n\nexport const OPS: ReadonlySet<FilterOp> = new Set<FilterOp>(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike', 'in', 'is']);\n\n/** Serialise a query object to PostgREST URLSearchParams. */\nexport function toParams(query: Query = {}): URLSearchParams {\n const params = new URLSearchParams();\n const { where = {}, select, order, limit, offset } = query;\n\n for (const [col, cond] of Object.entries(where)) {\n if (Array.isArray(cond)) {\n params.append(col, `in.(${cond.join(',')})`);\n } else if (cond && typeof cond === 'object' && typeof (cond as { op?: unknown }).op === 'string') {\n const c = cond as { op: FilterOp; value: unknown };\n if (!OPS.has(c.op)) throw new Error(`query: unsupported operator '${c.op}'`);\n const v = Array.isArray(c.value) ? `(${c.value.join(',')})` : c.value;\n params.append(col, `${c.op}.${v}`);\n } else if (cond === null) {\n // `eq.null` compares against the string 'null'; the mock already reads a\n // null condition as \"is null\", and now the data plane does too.\n params.append(col, 'is.null');\n } else {\n params.append(col, `eq.${cond}`);\n }\n }\n\n if (Array.isArray(select) && select.length) params.set('select', (select as string[]).join(','));\n if (order) params.set('order', /\\.(asc|desc)$/.test(order) ? order : `${order}.asc`);\n if (Number.isInteger(limit)) params.set('limit', String(limit));\n if (Number.isInteger(offset)) params.set('offset', String(offset));\n\n return params;\n}\n\n/** In-memory predicate mirroring `toParams`' `where` semantics (mock adapter). */\nexport function matches(row: Row, where: Query['where'] = {}): boolean {\n for (const [col, cond] of Object.entries(where)) {\n // A column a row does not carry reads as null — in Postgres every row has\n // every column. Same as the PHP runtime.\n const val = row[col] ?? null;\n if (Array.isArray(cond)) {\n if (!cond.includes(val as never)) return false;\n } else if (cond && typeof cond === 'object' && typeof (cond as { op?: unknown }).op === 'string') {\n const c = cond as { op: FilterOp; value: unknown };\n if (!compare(val, c.op, c.value)) return false;\n } else if (val !== cond) {\n return false;\n }\n }\n return true;\n}\n\nfunction compare(a: unknown, op: FilterOp, b: unknown): boolean {\n switch (op) {\n case 'eq': return a === b;\n case 'neq': return a !== b;\n case 'gt': return (a as number) > (b as number);\n case 'gte': return (a as number) >= (b as number);\n case 'lt': return (a as number) < (b as number);\n case 'lte': return (a as number) <= (b as number);\n case 'is': return a === b;\n case 'in': return Array.isArray(b) && b.includes(a);\n case 'like':\n case 'ilike': {\n const re = new RegExp(\n '^' + String(b).replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&').replace(/%/g, '.*').replace(/_/g, '.') + '$',\n op === 'ilike' ? 'i' : '',\n );\n return re.test(String(a));\n }\n default: return false;\n }\n}\n","/**\n * App settings — the tenant's configuration for THIS app, read at runtime.\n *\n * An App declares its settings in `settings.json` (`{ settings: { <key>:\n * { type, scope, default, sensitive, ... } } }`). The cockpit renders that\n * schema, Console stores the tenant's chosen values, and the gateway resolves\n * the two into an effective map:\n *\n * GET {gateway}/v1/settings/apps/{app}[?market={code}]\n * -> { app, market, settings: { … }, masked: [ … ] }\n *\n * Resolution happens ON THE GATEWAY, and this reader does not second-guess it.\n * Per key, the gateway applies (api/internal/gateway/settings.go,\n * `resolveSettings`):\n *\n * 1. per-market override — only for settings declared `\"scope\": \"market\"`,\n * and only when `?market=` is sent\n * 2. stored tenant value — the flat value in `settings_values`\n * 3. schema default — the `default` from settings.json\n *\n * Settings flagged `sensitive` are never in `settings`; their keys are listed\n * in `masked` so a caller can tell \"not configured\" from \"not for you\".\n *\n * The `defaults` you pass here are a *fourth*, last-resort layer: they are what\n * the app runs on when the settings service cannot be reached, and they are\n * what types the resolved object. They never override a value the gateway\n * actually resolved — only a `null`/absent one.\n *\n * const settings = createSettings({\n * app: 'orders',\n * defaults: { auto_reserve: true, reservation_minutes: 30 },\n * });\n *\n * app.post('/orders', async (c) => {\n * const s = await settings.get(c); // market taken from the request\n * if (s.auto_reserve) { … }\n * });\n *\n * Or let the router own it — `createApp({ name, settings: { defaults } })`\n * gives every handler `await c.settings()`.\n *\n * Two properties make this safe to call on every request:\n *\n * - it FAILS OPEN. A gateway blip, a missing tenant, a timeout, an app that\n * declares no settings at all: you get the last good values if there are\n * any, otherwise your declared defaults. It never throws and never takes\n * the app down. Availability is the default; switching something off is\n * the deliberate act, and a deliberate act must not be the accident.\n * - it CACHES. Per (tenant, app, market), for a short TTL, with concurrent\n * reads sharing one in-flight request. A warm read is a Map lookup.\n */\n\n/** The platform gateway. Override with REVENEXX_GATEWAY_ENDPOINT. */\nexport const DEFAULT_GATEWAY_ENDPOINT = 'https://api.revenexx.com';\n\n/**\n * How long a resolved settings map stays warm in the process (ms).\n *\n * Settings are configuration, not data: a merchant flips one every few weeks.\n * The gateway keeps its own 30s cache in front of Console and drops it on a\n * NATS invalidation when values change, so this second layer is the only real\n * staleness — a cockpit change takes effect within a minute. That is the right\n * trade against the alternative, which is a gateway round trip on the hot path\n * of every single request.\n *\n * Override per reader (`ttlMs`) or per deployment (REVENEXX_SETTINGS_TTL_MS).\n */\nexport const DEFAULT_SETTINGS_TTL_MS = 60_000;\n\n/**\n * How long a FAILED read stays cached (ms). Short, because the failure is\n * usually transient and we want to recover quickly — but not zero, or an\n * unreachable gateway would put a doomed round trip on every request, which is\n * exactly the outage the fail-open is supposed to absorb.\n *\n * A 404 (\"app not installed or declares no settings\") is not a failure but a\n * stable answer, and is cached for the full TTL.\n */\nexport const DEFAULT_SETTINGS_ERROR_TTL_MS = 5_000;\n\n/** Request timeout (ms). A hung settings service must not hang the app. */\nexport const DEFAULT_SETTINGS_TIMEOUT_MS = 2_000;\n\nexport type SettingsDefaults = Record<string, unknown>;\n\n/**\n * The resolved map. Keys you declared in `defaults` keep their type; anything\n * else the manifest declares is still there, as `unknown`.\n */\nexport type ResolvedSettings<D extends SettingsDefaults = SettingsDefaults> = D & Record<string, unknown>;\n\n/**\n * Anything a request's tenant/token/market can be read from: the router's\n * `RouteContext`, the raw function context (`{ req: { headers } }`), or a bare\n * headers object.\n */\nexport interface SettingsSource {\n header?(name: string): string;\n tenant?: string | null;\n contextToken?: string;\n req?: { headers?: Record<string, string> | undefined } | undefined;\n headers?: Record<string, string> | undefined;\n}\n\nexport interface SettingsOptions<D extends SettingsDefaults = SettingsDefaults> {\n /**\n * The app whose settings to read. Defaults to REVENEXX_APP_NAME, which the\n * runtime sets — a deployed app usually needs no value here. `createApp`\n * passes its own `name`.\n */\n app?: string;\n /**\n * Last-resort values, and the type source. Use the same defaults your\n * settings.json declares: they are what the app runs on if the settings\n * service is unreachable.\n */\n defaults?: D;\n /** Gateway base URL. Default: REVENEXX_GATEWAY_ENDPOINT or the platform gateway. */\n endpoint?: string;\n /** Cache TTL in ms. Default: REVENEXX_SETTINGS_TTL_MS or 60_000. */\n ttlMs?: number;\n /** How long a failed read is cached, in ms. Default 5_000. */\n errorTtlMs?: number;\n /** Per-request timeout in ms. Default 2_000. */\n timeoutMs?: number;\n /** Environment to read from (tests). Default `process.env`. */\n env?: Record<string, string | undefined>;\n /** Fetch implementation (tests). Default `globalThis.fetch`. */\n fetchImpl?: typeof fetch;\n /**\n * Called when a read fails and the app falls back. Wire it to the function's\n * `error()` so a silent fallback is still visible. Must not throw.\n */\n onError?: (error: Error, info: { app: string; tenant: string; market: string | null }) => void;\n}\n\n/** A resolved read, with the provenance a caller occasionally needs. */\nexport interface SettingsSnapshot<D extends SettingsDefaults = SettingsDefaults> {\n app: string;\n tenant: string;\n /** The market the values were resolved for, or null for the tenant baseline. */\n market: string | null;\n settings: ResolvedSettings<D>;\n /** Keys that exist but are `sensitive`, so their values were withheld. */\n masked: string[];\n /** true when these values came from the gateway (fresh or cached). */\n resolved: boolean;\n /** Why the fallback happened, when `resolved` is false. */\n error?: string;\n}\n\nexport interface ReadOptions {\n /** Resolve for this market instead of the one on the request. `''` = tenant baseline. */\n market?: string;\n}\n\nexport interface SettingsReader<D extends SettingsDefaults = SettingsDefaults> {\n /** The effective settings for this request. Never throws. */\n get(source?: SettingsSource, options?: ReadOptions): Promise<ResolvedSettings<D>>;\n /** The same read, plus market/masked/provenance. */\n load(source?: SettingsSource, options?: ReadOptions): Promise<SettingsSnapshot<D>>;\n /** Drop the cache (tests, or right after writing settings). */\n clear(): void;\n}\n\ninterface Entry<D extends SettingsDefaults> {\n at: number;\n ttl: number;\n promise: Promise<SettingsSnapshot<D>>;\n}\n\ninterface GatewayResponse {\n settings?: Record<string, unknown>;\n masked?: unknown;\n}\n\n/** Case-insensitive header read across the three shapes we accept. */\nfunction headerOf(source: SettingsSource | undefined, name: string): string {\n if (!source) return '';\n if (typeof source.header === 'function') {\n const v = source.header(name);\n if (typeof v === 'string' && v !== '') return v;\n }\n const bags = [source.req?.headers, source.headers];\n const want = name.toLowerCase();\n for (const bag of bags) {\n if (!bag) continue;\n const direct = bag[name] ?? bag[want];\n if (typeof direct === 'string' && direct !== '') return direct;\n for (const [k, v] of Object.entries(bag)) {\n if (k.toLowerCase() === want && typeof v === 'string' && v !== '') return v;\n }\n }\n return '';\n}\n\n/**\n * Merge the gateway's resolved map over the declared defaults.\n *\n * A `null` from the gateway does NOT clobber a default: a setting the merchant\n * never touched and whose schema carries no default resolves to `null`, and a\n * caller should not have to null-check a key it declared a default for. A real\n * stored value — including `false`, `0` and `''` — always wins.\n */\nfunction mergeSettings<D extends SettingsDefaults>(\n defaults: D | undefined,\n resolved: Record<string, unknown> | undefined,\n): ResolvedSettings<D> {\n const out: Record<string, unknown> = { ...(defaults ?? {}) };\n for (const [key, value] of Object.entries(resolved ?? {})) {\n if (value !== null && value !== undefined) out[key] = value;\n else if (!(key in out)) out[key] = value ?? null;\n }\n return out as ResolvedSettings<D>;\n}\n\nfunction timeoutSignal(ms: number): AbortSignal | undefined {\n const factory = (AbortSignal as { timeout?: (ms: number) => AbortSignal }).timeout;\n if (typeof factory === 'function') return factory(ms);\n if (typeof AbortController !== 'function') return undefined;\n const controller = new AbortController();\n setTimeout(() => controller.abort(), ms).unref?.();\n return controller.signal;\n}\n\n/**\n * Build a settings reader for one app. Create it once at module scope — the\n * cache lives on the reader, and a per-request reader would cache nothing.\n */\nexport function createSettings<D extends SettingsDefaults = SettingsDefaults>(\n options: SettingsOptions<D> = {},\n): SettingsReader<D> {\n const env = options.env ?? process.env;\n const defaults = options.defaults;\n const ttlMs = options.ttlMs ?? Number(env.REVENEXX_SETTINGS_TTL_MS ?? DEFAULT_SETTINGS_TTL_MS);\n const errorTtlMs = options.errorTtlMs ?? DEFAULT_SETTINGS_ERROR_TTL_MS;\n const timeoutMs = options.timeoutMs ?? DEFAULT_SETTINGS_TIMEOUT_MS;\n const endpoint = String(options.endpoint || env.REVENEXX_GATEWAY_ENDPOINT || DEFAULT_GATEWAY_ENDPOINT).replace(\n /\\/+$/,\n '',\n );\n\n const cache = new Map<string, Entry<D>>();\n /** Last successful snapshot per key — served instead of defaults on a blip. */\n const lastGood = new Map<string, SettingsSnapshot<D>>();\n\n const appName = (): string => String(options.app || env.REVENEXX_APP_NAME || '').trim();\n\n const fallback = (app: string, tenant: string, market: string | null, error: string): SettingsSnapshot<D> => ({\n app,\n tenant,\n market,\n settings: mergeSettings(defaults, undefined),\n masked: [],\n resolved: false,\n error,\n });\n\n const report = (err: Error, info: { app: string; tenant: string; market: string | null }): void => {\n try {\n options.onError?.(err, info);\n } catch {\n /* an error reporter must never be the reason a request fails */\n }\n };\n\n async function request(app: string, tenant: string, token: string, market: string | null): Promise<SettingsSnapshot<D>> {\n const f = options.fetchImpl ?? globalThis.fetch;\n if (typeof f !== 'function') throw new Error('settings: no fetch available (Node >=18 or pass fetchImpl)');\n\n const qs = market ? `?market=${encodeURIComponent(market)}` : '';\n const headers: Record<string, string> = { Accept: 'application/json', 'X-Revenexx-Tenant': tenant };\n if (token) headers.Authorization = `Bearer ${token}`;\n\n const signal = timeoutSignal(timeoutMs);\n const res = await f(`${endpoint}/v1/settings/apps/${encodeURIComponent(app)}${qs}`, {\n method: 'GET',\n headers,\n ...(signal ? { signal } : {}),\n });\n const text = await res.text();\n if (!res.ok) {\n const err = new Error(`settings: ${res.status} for ${app}`) as Error & { status?: number };\n err.status = res.status;\n throw err;\n }\n const body = (text ? JSON.parse(text) : {}) as GatewayResponse;\n return {\n app,\n tenant,\n market,\n settings: mergeSettings(defaults, body.settings),\n masked: Array.isArray(body.masked) ? body.masked.filter((k): k is string => typeof k === 'string') : [],\n resolved: true,\n };\n }\n\n async function load(source?: SettingsSource, readOptions: ReadOptions = {}): Promise<SettingsSnapshot<D>> {\n const app = appName();\n const tenant = (source?.tenant ?? '') || headerOf(source, 'x-revenexx-tenant');\n const market = (readOptions.market ?? headerOf(source, 'x-revenexx-market')).trim() || null;\n\n // Nothing to ask with — answer from the defaults without a round trip.\n if (!app) return fallback('', tenant, market, 'no app name (pass `app` or set REVENEXX_APP_NAME)');\n if (!tenant) return fallback(app, '', market, 'no tenant on the request');\n\n const key = `${tenant}\u0000${app}\u0000${market ?? ''}`;\n const now = Date.now();\n const hit = cache.get(key);\n if (hit && now - hit.at < hit.ttl) return hit.promise;\n\n const token = (source?.contextToken ?? '') || headerOf(source, 'x-revenexx-context');\n const entry: Entry<D> = { at: now, ttl: ttlMs, promise: undefined as unknown as Promise<SettingsSnapshot<D>> };\n entry.promise = request(app, tenant, token, market)\n .then((snapshot) => {\n lastGood.set(key, snapshot);\n return snapshot;\n })\n .catch((err: unknown) => {\n const error = err instanceof Error ? err : new Error(String(err));\n // A 404 is the gateway saying \"this app is not installed, or declares\n // no settings\" — a stable answer, not a blip. Cache it for the full TTL\n // so an app without settings does not re-ask every five seconds.\n const status = (error as { status?: number }).status;\n entry.ttl = status === 404 ? ttlMs : errorTtlMs;\n report(error, { app, tenant, market });\n // Prefer the last values we genuinely resolved over the defaults: they\n // are the tenant's actual configuration, and a gateway blip is no\n // reason to silently revert a merchant's choices.\n const stale = lastGood.get(key);\n if (stale) return { ...stale, resolved: false, error: error.message };\n return fallback(app, tenant, market, error.message);\n });\n\n // Cached before it settles, so concurrent requests share one fetch.\n cache.set(key, entry);\n return entry.promise;\n }\n\n return {\n load,\n async get(source?: SettingsSource, readOptions?: ReadOptions): Promise<ResolvedSettings<D>> {\n return (await load(source, readOptions)).settings;\n },\n clear(): void {\n cache.clear();\n lastGood.clear();\n },\n };\n}\n","/**\n * What counts as an update.\n *\n * PostgREST answers a `PATCH` whose body carries no columns with `200 []` — no\n * error, no representation. The adapter then hands `rows[0]` (i.e. `undefined`)\n * back as the updated row, and the App serialises it: open-runtimes does\n * `Buffer.from(JSON.stringify(obj), 'utf8')`, and `JSON.stringify(undefined)`\n * is `undefined`, so Node throws\n *\n * TypeError [ERR_INVALID_ARG_TYPE]: The first argument must be of type string\n * or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object.\n * Received undefined\n *\n * which the App reports as a 500. A caller who sent nothing to update is told\n * the service is broken instead of what to send.\n *\n * The rule lives here, one level below the router, because not every App routes\n * its writes through `mountCrud`: `PUT /v1/greetings/{id}` and\n * `PUT /v1/payments/providers/{id}` are hand-written handlers that call\n * `db.<entity>.update()` directly, and they were the two endpoints that 500ed.\n * A guard in `mountCrud` alone only protects the Apps that happen to use it.\n */\n\nimport { badRequest } from './errors.js';\n\n/** The one wording every layer uses for \"you sent nothing to update\". */\nexport const EMPTY_UPDATE_MESSAGE = 'request body must contain at least one field to update';\n\n/**\n * The fields a patch would actually send. `undefined` values are excluded\n * because `JSON.stringify` drops them: `{ name: undefined }` reaches PostgREST\n * as `{}` and is exactly as empty as `{}` itself.\n */\nexport function updateFields(patch: unknown): string[] {\n if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return [];\n return Object.keys(patch as Record<string, unknown>).filter(\n (key) => (patch as Record<string, unknown>)[key] !== undefined,\n );\n}\n\n/** Throw a 400 when a patch carries nothing to write. */\nexport function assertUpdatable(patch: unknown): void {\n if (updateFields(patch).length === 0) throw badRequest(EMPTY_UPDATE_MESSAGE, undefined, { code: 'empty_update' });\n}\n\n/**\n * The one wording every layer uses for \"a conditional update with no condition\".\n *\n * `updateIf(id, {}, patch)` is an unconditional update spelled as a\n * conditional one — almost always a condition built from a variable that was\n * never set. Running it would let through the very race the caller reached\n * for `updateIf` to close, so it is refused; `update()` is the unconditional\n * write.\n */\nexport const EMPTY_CONDITION_MESSAGE = 'a conditional update needs at least one condition in where';\n\n/**\n * Throw a 400 when a `where` carries no condition, or one left `undefined`.\n *\n * An `undefined` entry is refused rather than dropped: dropping it would\n * quietly weaken the condition, and the two adapters would disagree about it\n * (`toParams` sends `eq.undefined`, `matches` compares against a missing key).\n */\nexport function assertCondition(where: unknown): void {\n if (!where || typeof where !== 'object' || Array.isArray(where) || Object.keys(where).length === 0) {\n throw badRequest(EMPTY_CONDITION_MESSAGE, undefined, { code: 'empty_condition' });\n }\n assertDefined(where);\n}\n\n/**\n * Throw a 400 when any `where` entry is `undefined` — on every read, not only a\n * conditional update. The two adapters disagree about one: `toParams` sends\n * `eq.undefined`, `matches` compares against a missing key. It is almost always\n * a variable that was never set, so it is refused rather than guessed at.\n */\nexport function assertDefined(where: unknown): void {\n if (!where || typeof where !== 'object') return;\n for (const [col, cond] of Object.entries(where as Record<string, unknown>)) {\n if (cond === undefined) {\n throw badRequest(`where.${col} is undefined — a condition needs a value`, undefined, { code: 'undefined_condition' });\n }\n }\n}\n"],"mappings":"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","names":[]}
|
|
@@ -15,8 +15,10 @@ type Filter = Scalar | Scalar[] | {
|
|
|
15
15
|
* serialise it to a PostgREST querystring, mock applies it in memory — so App
|
|
16
16
|
* code is identical regardless of where the data lives.
|
|
17
17
|
*/
|
|
18
|
+
/** A `where` clause: every entry must hold (AND). */
|
|
19
|
+
type Where<T = Record<string, unknown>> = Partial<Record<keyof T & string, Filter>> & Record<string, Filter>;
|
|
18
20
|
interface Query<T = Record<string, unknown>> {
|
|
19
|
-
where?:
|
|
21
|
+
where?: Where<T>;
|
|
20
22
|
select?: (keyof T & string)[] | string[];
|
|
21
23
|
order?: string;
|
|
22
24
|
limit?: number;
|
|
@@ -107,6 +109,11 @@ interface EmittedEvent {
|
|
|
107
109
|
* `page` is optional: adapters that can report a total (PostgREST `count=exact`,
|
|
108
110
|
* an in-memory store) implement it; others fall back to `list` only.
|
|
109
111
|
*
|
|
112
|
+
* `updateIf` is optional too, and for a stricter reason: a compare-and-set
|
|
113
|
+
* has to be one atomic write, so the client cannot emulate it as a read
|
|
114
|
+
* followed by an update — that is exactly the race it exists to close. An
|
|
115
|
+
* adapter without it makes `updateIf()` fail rather than degrade.
|
|
116
|
+
*
|
|
110
117
|
* `emit` and `emitted` are optional for the same reason — an adapter that
|
|
111
118
|
* cannot reach the event bus simply does not implement them, and the entity
|
|
112
119
|
* client says so rather than pretending the event went out.
|
|
@@ -118,6 +125,11 @@ interface Adapter {
|
|
|
118
125
|
create(entity: Entity, data: Row): Promise<Row>;
|
|
119
126
|
update(entity: Entity, id: string | number, patch: Row): Promise<Row>;
|
|
120
127
|
remove(entity: Entity, id: string | number): Promise<void>;
|
|
128
|
+
/**
|
|
129
|
+
* Update the row only if it still matches `where`; `null` when no row
|
|
130
|
+
* matched — gone, invisible, or the condition no longer holds.
|
|
131
|
+
*/
|
|
132
|
+
updateIf?(entity: Entity, id: string | number, where: Where, patch: Row): Promise<Row | null>;
|
|
121
133
|
page?(entity: Entity, query?: Query): Promise<Page>;
|
|
122
134
|
emit?(target: EmitTarget, data: Row, options: EmitOptions): Promise<EmitResult>;
|
|
123
135
|
/** What this adapter recorded instead of publishing (mock only). */
|
|
@@ -329,9 +341,9 @@ declare class HttpError extends Error {
|
|
|
329
341
|
}
|
|
330
342
|
/** Duck-typed `instanceof HttpError` — survives the bundle split (see above). */
|
|
331
343
|
declare function isHttpError(err: unknown): err is HttpError;
|
|
332
|
-
declare const notFound: (message?: string) => HttpError;
|
|
333
|
-
declare const badRequest: (message?: string, details?: unknown) => HttpError;
|
|
334
|
-
declare const forbidden: (message?: string) => HttpError;
|
|
335
|
-
declare const conflict: (message?: string) => HttpError;
|
|
344
|
+
declare const notFound: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
345
|
+
declare const badRequest: (message?: string, details?: unknown, options?: HttpErrorOptions) => HttpError;
|
|
346
|
+
declare const forbidden: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
347
|
+
declare const conflict: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
336
348
|
|
|
337
|
-
export { type Adapter as A, type ColumnDef as C, DEFAULT_GATEWAY_ENDPOINT as D, type EmitOptions as E, type Filter as F, HttpError as H, type Op as O, type Page as P, type Query as Q, type Row as R, type Scalar as S, type EmitResult as a, type EmittedEvent as b, type EventDescriptor as c, type Entity as d, DEFAULT_SETTINGS_ERROR_TTL_MS as e, DEFAULT_SETTINGS_TIMEOUT_MS as f, DEFAULT_SETTINGS_TTL_MS as g, type EmitTarget as h, type FilterOp as i, type HttpErrorOptions as j, type ReadOptions as k, type ResolvedSettings as l, type SettingsDefaults as m, type SettingsOptions as n, type SettingsReader as o, type SettingsSnapshot as p, type SettingsSource as q, createSettings as r, isHttpError as s, badRequest as t, conflict as u, forbidden as v, notFound as w };
|
|
349
|
+
export { type Adapter as A, type ColumnDef as C, DEFAULT_GATEWAY_ENDPOINT as D, type EmitOptions as E, type Filter as F, HttpError as H, type Op as O, type Page as P, type Query as Q, type Row as R, type Scalar as S, type Where as W, type EmitResult as a, type EmittedEvent as b, type EventDescriptor as c, type Entity as d, DEFAULT_SETTINGS_ERROR_TTL_MS as e, DEFAULT_SETTINGS_TIMEOUT_MS as f, DEFAULT_SETTINGS_TTL_MS as g, type EmitTarget as h, type FilterOp as i, type HttpErrorOptions as j, type ReadOptions as k, type ResolvedSettings as l, type SettingsDefaults as m, type SettingsOptions as n, type SettingsReader as o, type SettingsSnapshot as p, type SettingsSource as q, createSettings as r, isHttpError as s, badRequest as t, conflict as u, forbidden as v, notFound as w };
|
|
@@ -15,8 +15,10 @@ type Filter = Scalar | Scalar[] | {
|
|
|
15
15
|
* serialise it to a PostgREST querystring, mock applies it in memory — so App
|
|
16
16
|
* code is identical regardless of where the data lives.
|
|
17
17
|
*/
|
|
18
|
+
/** A `where` clause: every entry must hold (AND). */
|
|
19
|
+
type Where<T = Record<string, unknown>> = Partial<Record<keyof T & string, Filter>> & Record<string, Filter>;
|
|
18
20
|
interface Query<T = Record<string, unknown>> {
|
|
19
|
-
where?:
|
|
21
|
+
where?: Where<T>;
|
|
20
22
|
select?: (keyof T & string)[] | string[];
|
|
21
23
|
order?: string;
|
|
22
24
|
limit?: number;
|
|
@@ -107,6 +109,11 @@ interface EmittedEvent {
|
|
|
107
109
|
* `page` is optional: adapters that can report a total (PostgREST `count=exact`,
|
|
108
110
|
* an in-memory store) implement it; others fall back to `list` only.
|
|
109
111
|
*
|
|
112
|
+
* `updateIf` is optional too, and for a stricter reason: a compare-and-set
|
|
113
|
+
* has to be one atomic write, so the client cannot emulate it as a read
|
|
114
|
+
* followed by an update — that is exactly the race it exists to close. An
|
|
115
|
+
* adapter without it makes `updateIf()` fail rather than degrade.
|
|
116
|
+
*
|
|
110
117
|
* `emit` and `emitted` are optional for the same reason — an adapter that
|
|
111
118
|
* cannot reach the event bus simply does not implement them, and the entity
|
|
112
119
|
* client says so rather than pretending the event went out.
|
|
@@ -118,6 +125,11 @@ interface Adapter {
|
|
|
118
125
|
create(entity: Entity, data: Row): Promise<Row>;
|
|
119
126
|
update(entity: Entity, id: string | number, patch: Row): Promise<Row>;
|
|
120
127
|
remove(entity: Entity, id: string | number): Promise<void>;
|
|
128
|
+
/**
|
|
129
|
+
* Update the row only if it still matches `where`; `null` when no row
|
|
130
|
+
* matched — gone, invisible, or the condition no longer holds.
|
|
131
|
+
*/
|
|
132
|
+
updateIf?(entity: Entity, id: string | number, where: Where, patch: Row): Promise<Row | null>;
|
|
121
133
|
page?(entity: Entity, query?: Query): Promise<Page>;
|
|
122
134
|
emit?(target: EmitTarget, data: Row, options: EmitOptions): Promise<EmitResult>;
|
|
123
135
|
/** What this adapter recorded instead of publishing (mock only). */
|
|
@@ -329,9 +341,9 @@ declare class HttpError extends Error {
|
|
|
329
341
|
}
|
|
330
342
|
/** Duck-typed `instanceof HttpError` — survives the bundle split (see above). */
|
|
331
343
|
declare function isHttpError(err: unknown): err is HttpError;
|
|
332
|
-
declare const notFound: (message?: string) => HttpError;
|
|
333
|
-
declare const badRequest: (message?: string, details?: unknown) => HttpError;
|
|
334
|
-
declare const forbidden: (message?: string) => HttpError;
|
|
335
|
-
declare const conflict: (message?: string) => HttpError;
|
|
344
|
+
declare const notFound: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
345
|
+
declare const badRequest: (message?: string, details?: unknown, options?: HttpErrorOptions) => HttpError;
|
|
346
|
+
declare const forbidden: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
347
|
+
declare const conflict: (message?: string, options?: HttpErrorOptions) => HttpError;
|
|
336
348
|
|
|
337
|
-
export { type Adapter as A, type ColumnDef as C, DEFAULT_GATEWAY_ENDPOINT as D, type EmitOptions as E, type Filter as F, HttpError as H, type Op as O, type Page as P, type Query as Q, type Row as R, type Scalar as S, type EmitResult as a, type EmittedEvent as b, type EventDescriptor as c, type Entity as d, DEFAULT_SETTINGS_ERROR_TTL_MS as e, DEFAULT_SETTINGS_TIMEOUT_MS as f, DEFAULT_SETTINGS_TTL_MS as g, type EmitTarget as h, type FilterOp as i, type HttpErrorOptions as j, type ReadOptions as k, type ResolvedSettings as l, type SettingsDefaults as m, type SettingsOptions as n, type SettingsReader as o, type SettingsSnapshot as p, type SettingsSource as q, createSettings as r, isHttpError as s, badRequest as t, conflict as u, forbidden as v, notFound as w };
|
|
349
|
+
export { type Adapter as A, type ColumnDef as C, DEFAULT_GATEWAY_ENDPOINT as D, type EmitOptions as E, type Filter as F, HttpError as H, type Op as O, type Page as P, type Query as Q, type Row as R, type Scalar as S, type Where as W, type EmitResult as a, type EmittedEvent as b, type EventDescriptor as c, type Entity as d, DEFAULT_SETTINGS_ERROR_TTL_MS as e, DEFAULT_SETTINGS_TIMEOUT_MS as f, DEFAULT_SETTINGS_TTL_MS as g, type EmitTarget as h, type FilterOp as i, type HttpErrorOptions as j, type ReadOptions as k, type ResolvedSettings as l, type SettingsDefaults as m, type SettingsOptions as n, type SettingsReader as o, type SettingsSnapshot as p, type SettingsSource as q, createSettings as r, isHttpError as s, badRequest as t, conflict as u, forbidden as v, notFound as w };
|