fastify-auto-sqlapi 0.5.1 → 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/AGENTS.md +5 -5
- package/AGENTS_BACKEND.md +166 -130
- package/AGENTS_FRONTEND.md +60 -38
- package/BREAKING_CHANGES.md +9 -893
- package/CHANGELOG.md +246 -15
- package/README.md +71 -45
- package/dist/bin/generate-schema.js +12 -12
- package/dist/bin/generate-tables.js +1 -2
- package/dist/bin/utils.d.ts +2 -6
- package/dist/bin/utils.d.ts.map +1 -1
- package/dist/bin/utils.js +13 -33
- package/dist/index.d.ts +13 -33
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -37
- package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
- package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
- package/dist/lib/adapters/pg-adapter.d.ts +5 -2
- package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
- package/dist/lib/agent/manifest.d.ts +27 -10
- package/dist/lib/agent/manifest.d.ts.map +1 -1
- package/dist/lib/agent/manifest.js +43 -26
- package/dist/lib/agent/tool-schemas.d.ts +5 -4
- package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
- package/dist/lib/agent/tool-schemas.js +5 -5
- package/dist/lib/cli/config.d.ts +37 -2
- package/dist/lib/cli/config.d.ts.map +1 -1
- package/dist/lib/cli/config.js +106 -16
- package/dist/lib/cli/mysql-introspect.d.ts +6 -1
- package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
- package/dist/lib/cli/mysql-introspect.js +15 -15
- package/dist/lib/cli/pg-introspect.d.ts +0 -1
- package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
- package/dist/lib/cli/pg-introspect.js +2 -13
- package/dist/lib/cli/tables-codegen.d.ts +0 -4
- package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
- package/dist/lib/cli/tables-codegen.js +24 -87
- package/dist/lib/db.d.ts +42 -17
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +114 -40
- package/dist/lib/dialect.d.ts +5 -0
- package/dist/lib/dialect.d.ts.map +1 -1
- package/dist/lib/dialect.js +3 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-delete.js +66 -30
- package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
- package/dist/lib/engine/read-hooks.d.ts +3 -3
- package/dist/lib/engine/read-hooks.d.ts.map +1 -1
- package/dist/lib/engine/read-hooks.js +3 -3
- package/dist/lib/engine/rest/delete.d.ts.map +1 -1
- package/dist/lib/engine/rest/delete.js +12 -18
- package/dist/lib/engine/rest/get.js +8 -8
- package/dist/lib/engine/rest/insert.d.ts.map +1 -1
- package/dist/lib/engine/rest/insert.js +31 -18
- package/dist/lib/engine/rest/update.d.ts.map +1 -1
- package/dist/lib/engine/rest/update.js +34 -17
- package/dist/lib/engine/search/aggregations.d.ts +3 -3
- package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
- package/dist/lib/engine/search/aggregations.js +20 -16
- package/dist/lib/engine/search/conditions.d.ts +9 -5
- package/dist/lib/engine/search/conditions.d.ts.map +1 -1
- package/dist/lib/engine/search/conditions.js +31 -20
- package/dist/lib/engine/search/fields.d.ts +44 -11
- package/dist/lib/engine/search/fields.d.ts.map +1 -1
- package/dist/lib/engine/search/fields.js +93 -27
- package/dist/lib/engine/search/join-families.d.ts +7 -7
- package/dist/lib/engine/search/join-families.d.ts.map +1 -1
- package/dist/lib/engine/search/join-families.js +84 -75
- package/dist/lib/engine/search/joins.d.ts +15 -7
- package/dist/lib/engine/search/joins.d.ts.map +1 -1
- package/dist/lib/engine/search/joins.js +23 -13
- package/dist/lib/engine/search/order-by.d.ts +11 -12
- package/dist/lib/engine/search/order-by.d.ts.map +1 -1
- package/dist/lib/engine/search/order-by.js +24 -28
- package/dist/lib/engine/search/search.d.ts.map +1 -1
- package/dist/lib/engine/search/search.js +111 -64
- package/dist/lib/engine/validate.d.ts +21 -3
- package/dist/lib/engine/validate.d.ts.map +1 -1
- package/dist/lib/engine/validate.js +106 -16
- package/dist/lib/engine/write-helpers.d.ts +69 -16
- package/dist/lib/engine/write-helpers.d.ts.map +1 -1
- package/dist/lib/engine/write-helpers.js +257 -105
- package/dist/lib/errors.d.ts +42 -10
- package/dist/lib/errors.d.ts.map +1 -1
- package/dist/lib/errors.js +69 -15
- package/dist/lib/nullable.d.ts +3 -2
- package/dist/lib/nullable.d.ts.map +1 -1
- package/dist/lib/nullable.js +14 -5
- package/dist/lib/read-access.d.ts +25 -16
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +33 -17
- package/dist/lib/schema/bulk-delete.d.ts +13 -7
- package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
- package/dist/lib/schema/bulk-delete.js +18 -8
- package/dist/lib/schema/bulk-upsert.d.ts +3 -3
- package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/schema/bulk-upsert.js +9 -14
- package/dist/lib/schema/get.d.ts +1 -1
- package/dist/lib/schema/get.d.ts.map +1 -1
- package/dist/lib/schema/get.js +2 -2
- package/dist/lib/schema/helpers.d.ts +41 -23
- package/dist/lib/schema/helpers.d.ts.map +1 -1
- package/dist/lib/schema/helpers.js +80 -33
- package/dist/lib/schema/insert.d.ts +1 -1
- package/dist/lib/schema/insert.d.ts.map +1 -1
- package/dist/lib/schema/insert.js +12 -20
- package/dist/lib/schema/search.d.ts +2 -13
- package/dist/lib/schema/search.d.ts.map +1 -1
- package/dist/lib/schema/search.js +64 -61
- package/dist/lib/schema/update.d.ts +1 -1
- package/dist/lib/schema/update.d.ts.map +1 -1
- package/dist/lib/schema/update.js +6 -13
- package/dist/lib/sql-api.d.ts +47 -25
- package/dist/lib/sql-api.d.ts.map +1 -1
- package/dist/lib/sql-api.js +70 -27
- package/dist/lib/table-helpers.d.ts +92 -14
- package/dist/lib/table-helpers.d.ts.map +1 -1
- package/dist/lib/table-helpers.js +367 -128
- package/dist/lib/tenant.d.ts +16 -22
- package/dist/lib/tenant.d.ts.map +1 -1
- package/dist/lib/tenant.js +38 -54
- package/dist/lib/write-access.d.ts +15 -9
- package/dist/lib/write-access.d.ts.map +1 -1
- package/dist/lib/write-access.js +12 -4
- package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
- package/dist/routes/auto/agent-manifest.routes.js +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-delete.routes.js +1 -7
- package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-upsert.routes.js +2 -2
- package/dist/routes/auto/delete.routes.d.ts +2 -2
- package/dist/routes/auto/delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/delete.routes.js +8 -10
- package/dist/routes/auto/get.routes.d.ts +2 -2
- package/dist/routes/auto/get.routes.d.ts.map +1 -1
- package/dist/routes/auto/get.routes.js +5 -5
- package/dist/routes/auto/insert.routes.d.ts +2 -2
- package/dist/routes/auto/insert.routes.d.ts.map +1 -1
- package/dist/routes/auto/insert.routes.js +1 -7
- package/dist/routes/auto/plugin.d.ts +6 -0
- package/dist/routes/auto/plugin.d.ts.map +1 -1
- package/dist/routes/auto/plugin.js +60 -36
- package/dist/routes/auto/route-helpers.d.ts +26 -12
- package/dist/routes/auto/route-helpers.d.ts.map +1 -1
- package/dist/routes/auto/route-helpers.js +50 -19
- package/dist/routes/auto/search.routes.d.ts +2 -2
- package/dist/routes/auto/search.routes.d.ts.map +1 -1
- package/dist/routes/auto/search.routes.js +36 -24
- package/dist/routes/auto/update.routes.d.ts +2 -2
- package/dist/routes/auto/update.routes.d.ts.map +1 -1
- package/dist/routes/auto/update.routes.js +1 -8
- package/dist/routes/sql-api-decorator.d.ts +30 -12
- package/dist/routes/sql-api-decorator.d.ts.map +1 -1
- package/dist/routes/sql-api-decorator.js +44 -27
- package/dist/types/cli.d.ts +17 -6
- package/dist/types/cli.d.ts.map +1 -1
- package/dist/types/computed.d.ts +1 -1
- package/dist/types/computed.d.ts.map +1 -1
- package/dist/types/conditions.d.ts +3 -1
- package/dist/types/conditions.d.ts.map +1 -1
- package/dist/types/db.d.ts +44 -4
- package/dist/types/db.d.ts.map +1 -1
- package/dist/types/dml.d.ts +26 -17
- package/dist/types/dml.d.ts.map +1 -1
- package/dist/types/hooks.d.ts +62 -0
- package/dist/types/hooks.d.ts.map +1 -0
- package/dist/types/hooks.js +1 -0
- package/dist/types/join.d.ts +25 -8
- package/dist/types/join.d.ts.map +1 -1
- package/dist/types/plugin.d.ts +58 -19
- package/dist/types/plugin.d.ts.map +1 -1
- package/dist/types/plugin.js +2 -0
- package/dist/types/request.d.ts +2 -2
- package/dist/types/schema.d.ts +3 -3
- package/dist/types/schema.d.ts.map +1 -1
- package/dist/types/search.d.ts +28 -13
- package/dist/types/search.d.ts.map +1 -1
- package/dist/types/search.js +2 -1
- package/dist/types/table.d.ts +109 -94
- package/dist/types/table.d.ts.map +1 -1
- package/dist/types/table.js +7 -2
- package/dist/types/tenant.d.ts +28 -2
- package/dist/types/tenant.d.ts.map +1 -1
- package/dist/types/tenant.js +7 -1
- package/dist/types/validation.d.ts +69 -13
- package/dist/types/validation.d.ts.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/docs/GLOSSARY.md +11 -5
- package/docs/adr/0003-bulk-not-transactional.md +2 -1
- package/docs/adr/0006-raw-db-errors.md +2 -1
- package/docs/adr/0013-sanitized-db-errors.md +2 -1
- package/docs/adr/0014-what-follows-a-write-join.md +1 -1
- package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
- package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
- package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
- package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
- package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
- package/docs/adr/0027-the-1-0-contract.md +74 -0
- package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
- package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
- package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
- package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
- package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
- package/docs/adr/README.md +12 -1
- package/docs/upgrading/0.x.md +906 -0
- package/docs/upgrading/1.0.md +628 -0
- package/package.json +4 -5
package/AGENTS_FRONTEND.md
CHANGED
|
@@ -6,27 +6,31 @@ This is the request GRAMMAR. The vocabulary (this deployment's tables, fields, j
|
|
|
6
6
|
- `{p}` = deployment prefix (e.g. `/api`). `{table}` = the table's key in the manifest, which may differ from the DB table name (one table can be exposed under several keys, each with its own rules).
|
|
7
7
|
- Join keys are backend-declared ALIASES (default: the joined table name).
|
|
8
8
|
- Write responses return PKs only. Send only real schema fields in write bodies: unknown ones are dropped or rejected (400), depending on the server.
|
|
9
|
-
- Composite-PK tables have no get/delete
|
|
9
|
+
- Composite-PK tables have no get/delete-by-`:id` routes (404): read with search, write with update, delete with bulk delete, one object per key.
|
|
10
10
|
|
|
11
11
|
## Endpoints
|
|
12
12
|
|
|
13
13
|
```
|
|
14
14
|
POST {p}/search/{table} body=search request → {table, main:[...], ...}
|
|
15
15
|
GET {p}/rest/{table}/:id → {main:{...}} | 404
|
|
16
|
-
POST {p}/rest/{table} body={main,
|
|
17
|
-
PUT {p}/rest/{table} body={main(+PK),
|
|
16
|
+
POST {p}/rest/{table} body={main, upsert?, replace?} → 201 {main:{id}, action, secondaries?, deletions?} // action: "inserted" | "updated" (upsert tables); deletions: only from a replace
|
|
17
|
+
PUT {p}/rest/{table} body={main(+PK), upsert?, delete?, replace?} → {main:{id}, secondaries?, deletions?}
|
|
18
18
|
DELETE {p}/rest/{table}/:id → {main:{id}} | 404
|
|
19
|
-
PUT {p}/bulk/{table} body=[{main,
|
|
20
|
-
POST {p}/bulk/{table}/delete body=
|
|
19
|
+
PUT {p}/bulk/{table} body=[{main, upsert?, delete?, replace?}, ...] → [{main:{id}, action, secondaries?, deletions?}, ...]
|
|
20
|
+
POST {p}/bulk/{table}/delete body={ids:[1, 2]} → [{main:{id:1}}, ...] // only the rows actually deleted; main key = the table's PK field
|
|
21
|
+
// composite PK: one object per key, every key field: body={ids:[{postId:1, tagId:2}]} → [{main:{postId:1, tagId:2}}, ...]
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
## Search
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
Everything travels in the body, and only there; all keys are optional and combinable, `{}` returns the first N rows. `orderBy`, `page`, `itemsPerPage` or `computeMin|Max|Sum|Avg` in the querystring → 400 `retired_key` at that key.
|
|
26
27
|
|
|
27
28
|
```jsonc
|
|
28
|
-
// POST {p}/search/customer
|
|
29
|
+
// POST {p}/search/customer
|
|
29
30
|
{
|
|
31
|
+
"orderBy": "orders.sum.total DESC, creator.name ASC, id", // see orderBy below
|
|
32
|
+
"paginator": { "page": 1, "itemsPerPage": 20 }, // see Pagination
|
|
33
|
+
"compute": { "sum": ["total"], "count": ["id"] }, // min|max|sum|avg|count|distinctCount over ALL matching rows, not the page → computed; paginator not needed
|
|
30
34
|
"filters": { "status": "active", "deletedById": null }, // equality, AND; null → IS NULL; also computed fields and backend extra filters (see manifest). Unknown key → 400
|
|
31
35
|
"conditions": [ // AND; the same field may repeat
|
|
32
36
|
{ "field": "total", "method": "isBetween", "params": [100, 500] },
|
|
@@ -34,21 +38,22 @@ Querystring, all optional: `orderBy`, `page`, `itemsPerPage`, `computeMin|Max|Su
|
|
|
34
38
|
{ "field": "status", "method": "isIn", "params": [["active", "pending"]] },
|
|
35
39
|
{ "field": "orders.count.id", "method": "isGreaterOrEqual", "params": [4] } // alias.fn.field, HAVING-style: needs the matching joinGroup below
|
|
36
40
|
],
|
|
37
|
-
"
|
|
38
|
-
"joinMustExist": { // EXISTS on
|
|
41
|
+
"select": ["id", "name", "displayName"], // main fields to return, computed ones included; default: every readable field and no computed one. "*" = that default: ["*", "fullName"] adds a computed field without listing the rest (main select only). The PK and the keys of the requested joins are always included. Unknown or hidden name → 400
|
|
42
|
+
"joinMustExist": { // EXISTS on child rows: decides WHICH main rows return; fetches nothing
|
|
39
43
|
"labels": { "filters": { "labelId": 1 }, "conditions": [] }
|
|
40
44
|
},
|
|
41
45
|
"joinMultiple": { // side query: child rows of the returned main rows
|
|
42
|
-
"orders": { "filters": { "status": "pending" }, "conditions": [], "
|
|
46
|
+
"orders": { "filters": { "status": "pending" }, "conditions": [], "select": ["customerId", "id", "total", "status"] } // default set by the backend; a select returns only what it lists — include the FK (customerId) to tell which main row a child belongs to
|
|
43
47
|
},
|
|
44
48
|
"joinGroup": { // aggregates child rows of the returned main rows
|
|
45
49
|
"orders": {
|
|
46
|
-
"
|
|
47
|
-
"
|
|
50
|
+
"by": "customerId", // optional GROUP BY (field or computed); absent or the FK when alias.fn.field is in orderBy or conditions
|
|
51
|
+
"sum": ["total"], "min": ["total"], "max": ["total"], "avg": ["total"], "count": ["id"], "distinctCount": ["status"], // at least one
|
|
52
|
+
"filters": { "status": "active" }, "conditions": [] // narrow the child rows before aggregating
|
|
48
53
|
}
|
|
49
54
|
},
|
|
50
55
|
"joinLeft": { // N:1 parent (alias declared unique by the backend)
|
|
51
|
-
"creator": { "
|
|
56
|
+
"creator": { "select": ["id", "name"], "filters": {}, "conditions": [] } // filters here EXCLUDE mains whose parent does not match; no extra filters here
|
|
52
57
|
}
|
|
53
58
|
}
|
|
54
59
|
```
|
|
@@ -60,22 +65,21 @@ Response; each section is present only if requested:
|
|
|
60
65
|
"table": "customer",
|
|
61
66
|
"main": [{ "id": 1, "name": "Mario", "creatorId": 7, "displayName": "..." }],
|
|
62
67
|
"joinMultiple": { "orders": [{ "id": 10, "customerId": 1, "total": 50 }] }, // flat list for all mains: group client-side by FK
|
|
63
|
-
"joinGroup": { "orders": {
|
|
64
|
-
"sum": { "total":
|
|
65
|
-
|
|
66
|
-
}},
|
|
68
|
+
"joinGroup": { "orders": { "rows": [ // always rows, [] when no main matched
|
|
69
|
+
{ "by": 1, "sum": { "total": "100.00" }, "count": { "id": "2" } } // with "by": one row per group; by = FK field gives per-main values. Aggregates come as the database returns them: often strings, exact — parse them
|
|
70
|
+
]}}, // without "by": ONE row, no "by", over the child rows of ALL returned mains
|
|
67
71
|
"joinLeft": { "creator": [{ "id": 7, "name": "Alice" }] }, // deduplicated: match main.creatorId === creator.id
|
|
68
|
-
"
|
|
72
|
+
"computed": { "sum": { "total": "999.00" }, "count": { "id": "25" } }, // only when compute is sent: one entry per function and field; values as in joinGroup
|
|
73
|
+
"pagination": { // only when paginator is sent, even {}
|
|
69
74
|
"total": 25, "pages": 3,
|
|
70
|
-
"computed": { "sum": { "total": 999 } }, // computeMin/Max/Sum/Avg over all matching rows; require pagination
|
|
71
75
|
"paginator": { "page": 1, "itemsPerPage": 20 }
|
|
72
76
|
}
|
|
73
77
|
}
|
|
74
78
|
```
|
|
75
79
|
|
|
76
80
|
Pagination:
|
|
77
|
-
- Without `
|
|
78
|
-
- With `page` only, `itemsPerPage` defaults to 500 (or the server maximum if lower).
|
|
81
|
+
- Without `paginator`, the server caps rows at its maximum (default 1000) and returns no `pagination` block.
|
|
82
|
+
- With `page` only, `itemsPerPage` defaults to 500 (or the server maximum if lower); with `itemsPerPage` only, `page` defaults to 1.
|
|
79
83
|
- Both are integers ≥ 1. `itemsPerPage` above the server maximum → 400.
|
|
80
84
|
|
|
81
85
|
`orderBy` is a comma-separated list, each part one of:
|
|
@@ -85,7 +89,7 @@ Pagination:
|
|
|
85
89
|
|
|
86
90
|
For `alias.fn.field`, in both `orderBy` and conditions, the joinGroup `by` must be absent or equal to the FK (else 400). In `orderBy` it is also a 400 on tables with distinct results.
|
|
87
91
|
|
|
88
|
-
A main without
|
|
92
|
+
A main without child rows (or none left after the joinGroup filters) has `count`, `distinctCount` and `sum` = 0, but `min`, `max` and `avg` = null. Null sorts where the database puts it (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC) and fails every comparison: `max < 5` excludes such mains; `isNull` selects them.
|
|
89
93
|
|
|
90
94
|
Condition methods and `params` arity:
|
|
91
95
|
- `[v]`: `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual`
|
|
@@ -101,36 +105,54 @@ An unknown field or method, or `params` that is not an array or is too short →
|
|
|
101
105
|
```jsonc
|
|
102
106
|
// POST {p}/rest/customer — insert; omit auto-generated PKs
|
|
103
107
|
{ "main": { "name": "Mario", "email": "m@t.it" },
|
|
104
|
-
"
|
|
105
|
-
// → 201 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 10 }] } }
|
|
108
|
+
"upsert": { "orders": [{ "total": 50, "status": "pending" }] } } // child FK auto-filled from the new main PK
|
|
109
|
+
// → 201 { "main": { "id": 1 }, "action": "inserted", "secondaries": { "orders": [{ "id": 10 }] } }
|
|
106
110
|
|
|
107
111
|
// PUT {p}/rest/customer — update; main MUST include the PK; send only the fields to change; null sets NULL
|
|
108
112
|
{ "main": { "id": 1, "email": "new@t.it" },
|
|
109
|
-
"
|
|
110
|
-
"
|
|
111
|
-
// → 200 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 20 }] }, "deletions": { "orders": [{ "id": 10 }] } }
|
|
113
|
+
"upsert": { "orders": [{ "total": 75 }] }, // insert (or upsert) child rows, FK auto-filled; the others stay
|
|
114
|
+
"delete": { "orders": [{ "id": 10 }] } } // delete child rows by PK, only those of this main
|
|
115
|
+
// → 200 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 20 }] }, "deletions": { "orders": [{ "id": 10, "customerId": 1 }] } }
|
|
112
116
|
|
|
113
117
|
// PUT {p}/bulk/customer — bulk upsert; items need not share keys: an omitted field keeps the stored value (update) or takes the column default (insert)
|
|
114
|
-
[ { "main": { "name": "Mario" }, "
|
|
118
|
+
[ { "main": { "id": 1, "name": "Mario" }, "upsert": { "orders": [{ "total": 50 }] } }, // customer has upsertKey [id] in the manifest
|
|
115
119
|
{ "main": { "name": "Luigi" } } ]
|
|
116
|
-
// → 200 [ { "main": { "id": 1 }, "secondaries": {...} }, { "main": { "id": 2 } } ]
|
|
120
|
+
// → 200 [ { "main": { "id": 1 }, "action": "updated", "secondaries": {...} }, { "main": { "id": 2 }, "action": "inserted" } ]
|
|
121
|
+
// action: what the statement did to the main row. "updated" when an upsert rule matched an existing row (also with nothing left to change), "inserted" otherwise; tables without a rule always say "inserted".
|
|
122
|
+
// The request says what to do with child rows (upsert, delete, replace); the response says what happened: secondaries = rows written (PKs only), deletions = rows removed.
|
|
117
123
|
```
|
|
118
124
|
|
|
119
|
-
|
|
125
|
+
Child rows go in one section per action, by write alias (manifest):
|
|
126
|
+
- `upsert`: write these rows; the other child rows stay.
|
|
127
|
+
- `delete` (update and bulk): delete these rows, named by their key; only child rows of this main.
|
|
128
|
+
- `replace`: these are all the child rows — the rows sent are upserted, every other child row of the main row is deleted. `[]` deletes them all. Only for a write alias with an `upsertKey` in the manifest.
|
|
129
|
+
|
|
130
|
+
```jsonc
|
|
131
|
+
// post 1 has tags 1 and 2
|
|
132
|
+
PUT {p}/rest/post { "main": { "id": 1 }, "replace": { "tags": [{ "tagId": 2 }, { "tagId": 3 }] } }
|
|
133
|
+
// → 200 { "main": { "id": 1 }, "secondaries": { "tags": [...] }, "deletions": { "tags": [{ "postId": 1, "tagId": 1 }] } }
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
400, and nothing is written: an alias the table does not write (including one only readable), or `replace` on an alias without `upsertKey` → `unknown_field` at `<section>.<alias>` (`<i>.<section>.<alias>` in a bulk); one alias in `replace` and in `upsert` or `delete` too → `conflicting_alias` at `replace.<alias>`; the pre-1.0 `secondaries` / `deletions` keys → `retired_key`.
|
|
137
|
+
|
|
138
|
+
Upsert tables (`upsertKey` on the table in the manifest; on a write alias, it is the child rows' key):
|
|
120
139
|
- Every row, main or child, carries its conflict key: missing, null, or shared by two rows of one request → 400.
|
|
121
|
-
- When the key is the id, rows without an id are inserted.
|
|
140
|
+
- When the key is the id, rows without an id are inserted. If the server generates ids (`serverGenerated` in the manifest), an id must name an existing row: none → 400 `not_found` at its path, nothing written.
|
|
122
141
|
- Bulk arrays are capped (default 1000): chunk client-side.
|
|
123
142
|
|
|
124
143
|
## Errors
|
|
125
144
|
|
|
126
|
-
|
|
145
|
+
Every error the plugin's routes raise has one shape (a route the backend did not register, e.g. get/delete on a composite-PK table, is the framework's plain 404, without `requestId`). `error` is the HTTP reason phrase; `requestId` is the server log's `reqId`, quote it when reporting a problem.
|
|
127
146
|
|
|
128
147
|
```json
|
|
129
|
-
{ "statusCode": 400, "error": "Bad Request", "message": "Validation failed",
|
|
130
|
-
"fields": [ { "path": "
|
|
148
|
+
{ "statusCode": 400, "error": "Bad Request", "message": "Validation failed", "requestId": "req-1",
|
|
149
|
+
"fields": [ { "path": "main.name", "code": "required", "message": "must have required property 'name'" } ] }
|
|
131
150
|
```
|
|
132
151
|
|
|
133
|
-
-
|
|
134
|
-
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
152
|
+
- 400 always carries `fields`, whether the request failed the schema, the backend's business validation or the engine. Map `fields[].path` to form fields; when `fields` is empty, show `message`.
|
|
153
|
+
- `path` is the dot path of the offending value in the request: body keys from the root (`main.name`, `upsert.orders.0.total`, `filters.status`, `conditions.2.params`, `joinGroup.orders.by`, `joinMultiple.orders.select.1`), path parameters and retired querystring keys by name (`id`, `orderBy`). `""` when the error is not attributable to one input.
|
|
154
|
+
- `code` is stable: an Ajv keyword (`required`, `type`, `maximum`, `additionalProperties`, `enum`…), a code the backend chose in its own validation, or an engine code: `unknown_field`, `not_readable`, `unknown_alias`, `wrong_join_family`, `invalid_method`, `invalid_params`, `invalid_order_by`, `invalid_paginator`, `invalid_aggregation`, `undeclared_aggregation`, `bound_values_not_allowed`, `extra_filter_not_allowed`, `limit_exceeded`, `retired_key` (a key the API no longer reads, e.g. `selectComputed`, a join's `selection`, the search querystring, `secondaries`/`deletions` in a write), `conflicting_alias`, `missing_key`, `duplicate_key`, `not_found`, `ambiguous_tenant`. The engine's `message` repeats the field's.
|
|
155
|
+
- `message`, when present, is a low-level description for the developer (Ajv's or the engine's, in English). A backend validation and a mapped DB error carry none: the code is the whole answer. Show the user a translation of `code`, never `message`.
|
|
156
|
+
- 401: on a table with tenant scope, the request carries no tenant (the backend's auth resolved none). 403: tenant violation. 404: row not found, or outside your tenant. No `fields`, except a mapped DB error (below).
|
|
157
|
+
- 500: DB errors (e.g. constraint violations): `message` is fixed, the detail is in the server log under `requestId`. The backend may answer some of them with another status instead (typically 409 on a duplicate): same envelope, plus `fields: [{ path: "", code }]` with a backend-chosen code to translate.
|
|
158
|
+
- Per search, max 100 `conditions` per section (top level and each join): over it → 400 `maxItems` at that `conditions`. `orderBy` takes max 20 `orderBy` parts (→ 400 `limit_exceeded`) in ≤ 1024 chars (→ 400 `maxLength`). Collapse many equality conditions into one `isIn`.
|