fastify-auto-sqlapi 0.5.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/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 +258 -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 +94 -28
- 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 -62
- 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 +33 -21
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +42 -23
- 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/dist/types/search.d.ts
CHANGED
|
@@ -1,16 +1,28 @@
|
|
|
1
1
|
import type { ApiRequest } from './request.js';
|
|
2
2
|
import type { QueryClient } from '../lib/db.js';
|
|
3
|
-
import type {
|
|
3
|
+
import type { TableConfig } from './table.js';
|
|
4
4
|
import type { TenantContext } from './tenant.js';
|
|
5
5
|
import type { JoinFetchRequest, JoinGroupRequest, JoinRefFilter } from './join.js';
|
|
6
|
-
import type {
|
|
6
|
+
import type { RowsByAlias } from './db.js';
|
|
7
|
+
import type { FilterRecord, SearchCondition } from './conditions.js';
|
|
7
8
|
export interface Paginator {
|
|
8
9
|
page: number;
|
|
9
10
|
itemsPerPage: number;
|
|
10
11
|
}
|
|
12
|
+
/** The aggregate functions a search may compute over all matching rows: those of joinGroup. */
|
|
13
|
+
export declare const COMPUTE_FNS: readonly ["min", "max", "sum", "avg", "count", "distinctCount"];
|
|
14
|
+
export type ComputeFn = (typeof COMPUTE_FNS)[number];
|
|
15
|
+
/**
|
|
16
|
+
* Aggregates over ALL rows matching the search, whatever page is returned, by function:
|
|
17
|
+
* `{ sum: ['total'], count: ['id'] }`. Each lands in `result.computed.<fn>.<field>`; no
|
|
18
|
+
* paginator is needed.
|
|
19
|
+
*/
|
|
20
|
+
export type ComputeRequest = Partial<Record<ComputeFn, string[]>>;
|
|
21
|
+
/** `result.computed`: one value per requested function and field. */
|
|
22
|
+
export type ComputedResult = Partial<Record<ComputeFn, Record<string, unknown>>>;
|
|
11
23
|
export interface SearchParams {
|
|
12
24
|
db: QueryClient;
|
|
13
|
-
tableConf:
|
|
25
|
+
tableConf: TableConfig;
|
|
14
26
|
filters?: FilterRecord;
|
|
15
27
|
conditions?: SearchCondition[];
|
|
16
28
|
joinMustExist?: Record<string, JoinRefFilter>;
|
|
@@ -19,15 +31,17 @@ export interface SearchParams {
|
|
|
19
31
|
joinLeft?: Record<string, JoinFetchRequest>;
|
|
20
32
|
orderBy?: string;
|
|
21
33
|
paginator?: Paginator;
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
computeSum?: string;
|
|
25
|
-
computeAvg?: string;
|
|
34
|
+
/** Aggregates over all matching rows; see `ComputeRequest`. */
|
|
35
|
+
compute?: ComputeRequest;
|
|
26
36
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
37
|
+
* Fields to project into `main` rows: schema fields and computed fields alike. Omitted,
|
|
38
|
+
* every readable schema field is returned and no computed field. The primary key, the
|
|
39
|
+
* fields the requested joins correlate on and, with `distinctResults`, the ORDER BY fields
|
|
40
|
+
* are always projected: the response and the side queries need them. An unknown or
|
|
41
|
+
* `readExclude`d name is a 400 at `select.<i>`. `'*'` stands for the default projection, so
|
|
42
|
+
* `['*', 'fullName']` is every readable field plus that computed field.
|
|
29
43
|
*/
|
|
30
|
-
|
|
44
|
+
select?: string[];
|
|
31
45
|
tenant?: TenantContext;
|
|
32
46
|
/**
|
|
33
47
|
* Row cap applied to the main query when no `paginator` is supplied, bounding an otherwise
|
|
@@ -42,14 +56,15 @@ export interface SearchParams {
|
|
|
42
56
|
export interface PaginationResult {
|
|
43
57
|
total: number;
|
|
44
58
|
pages: number;
|
|
45
|
-
computed?: Record<string, Record<string, unknown>>;
|
|
46
59
|
paginator: Paginator;
|
|
47
60
|
}
|
|
48
61
|
export interface SearchResult {
|
|
49
62
|
main: Record<string, unknown>[];
|
|
50
|
-
joinMultiple?:
|
|
51
|
-
joinLeft?:
|
|
63
|
+
joinMultiple?: RowsByAlias;
|
|
64
|
+
joinLeft?: RowsByAlias;
|
|
52
65
|
joinGroup?: Record<string, Record<string, unknown>>;
|
|
66
|
+
/** Present when `compute` was requested: aggregates over every matching row. */
|
|
67
|
+
computed?: ComputedResult;
|
|
53
68
|
pagination?: PaginationResult;
|
|
54
69
|
}
|
|
55
70
|
//# sourceMappingURL=search.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/types/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/types/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+FAA+F;AAC/F,eAAO,MAAM,WAAW,iEAAkE,CAAC;AAC3F,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAElE,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,gFAAgF;IAChF,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B"}
|
package/dist/types/search.js
CHANGED
|
@@ -1 +1,2 @@
|
|
|
1
|
-
|
|
1
|
+
/** The aggregate functions a search may compute over all matching rows: those of joinGroup. */
|
|
2
|
+
export const COMPUTE_FNS = ['min', 'max', 'sum', 'avg', 'count', 'distinctCount'];
|
package/dist/types/table.d.ts
CHANGED
|
@@ -1,54 +1,66 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
import type { TSchema,
|
|
1
|
+
import type { ConditionBuilder } from 'node-condition-builder';
|
|
2
|
+
import type { TSchema, TObject } from 'typebox';
|
|
3
3
|
import type { ApiRequest, ApiReply } from './request.js';
|
|
4
|
-
import type { QueryClient } from '../lib/db.js';
|
|
5
4
|
import type { SchemaDefinition } from './schema.js';
|
|
5
|
+
import type { FilterRecord } from './conditions.js';
|
|
6
6
|
import type { ComputedFieldFn } from './computed.js';
|
|
7
7
|
import type { JoinDefinition } from './join.js';
|
|
8
8
|
import type { TenantScope } from './tenant.js';
|
|
9
9
|
import type { ValidatorFn, BulkValidatorFn } from './validation.js';
|
|
10
|
-
|
|
10
|
+
import type { WriteHookContext, AfterInsertContext, AfterUpdateContext, AfterReadContext, DeleteHookContext, BulkDeleteHookContext } from './hooks.js';
|
|
11
|
+
/** Auto-generated HTTP operations that can be enabled per table via `TableConfig.operations`. */
|
|
11
12
|
export type TableOperation = 'search' | 'get' | 'insert' | 'update' | 'delete' | 'bulkUpsert' | 'bulkDelete';
|
|
12
|
-
|
|
13
|
-
export
|
|
14
|
-
/**
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
* inside a correlated subquery whose FROM is aliased — there the bare table name would
|
|
23
|
-
* resolve against the OUTER query.
|
|
24
|
-
*/
|
|
25
|
-
export type TableFilterFn = (filters: FilterRecord, dialect?: CbDialect, qualifier?: string) => ConditionBuilder;
|
|
26
|
-
/** Which read path produced the rows an `afterRead` hook is handed. */
|
|
27
|
-
export type ReadSource = 'get' | 'search' | 'joinMultiple' | 'joinLeft';
|
|
28
|
-
/** Where the rows an `afterRead` hook receives came from. */
|
|
29
|
-
export interface AfterReadContext {
|
|
30
|
-
source: ReadSource;
|
|
31
|
-
/** The relation's alias, on the two join sources; absent on `get` and `search`. */
|
|
32
|
-
alias?: string;
|
|
13
|
+
/** Every {@link TableOperation}, in route order. */
|
|
14
|
+
export declare const TABLE_OPERATIONS: readonly TableOperation[];
|
|
15
|
+
/** The third argument of `extendedCondition`. */
|
|
16
|
+
export interface ExtendedConditionContext<F extends Record<string, TSchema> = Record<string, TSchema>> {
|
|
17
|
+
/**
|
|
18
|
+
* The column of a schema field, quoted for the dialect and qualified the way the statement the
|
|
19
|
+
* condition lands in needs: the table name in the main search and in a side query, the alias
|
|
20
|
+
* inside a correlated subquery. A name that is not a field of the schema throws.
|
|
21
|
+
*/
|
|
22
|
+
col(field: string & keyof F): string;
|
|
33
23
|
}
|
|
34
|
-
export
|
|
24
|
+
export type ExtendedConditionFn = (condition: ConditionBuilder, filters: FilterRecord, ctx: ExtendedConditionContext) => void;
|
|
25
|
+
export interface TableConfig<F extends Record<string, TSchema> = Record<string, TSchema>> {
|
|
35
26
|
primary: (string & keyof F) | (string & keyof F)[];
|
|
36
|
-
Schema:
|
|
37
|
-
|
|
38
|
-
|
|
27
|
+
/** The table's generated Schema: columns, their types, the table name. */
|
|
28
|
+
schema: SchemaDefinition<F>;
|
|
29
|
+
/**
|
|
30
|
+
* Search filters that are not columns, as a record of fields or a `Type.Object`. They are
|
|
31
|
+
* validated like column filters and reach `extendedCondition`, which alone gives them a
|
|
32
|
+
* meaning: nothing else turns them into SQL.
|
|
33
|
+
*/
|
|
34
|
+
extraFilters?: Record<string, TSchema> | TObject;
|
|
35
|
+
/**
|
|
36
|
+
* Add to the search WHERE: receives the ConditionBuilder already holding the column
|
|
37
|
+
* equality filters, every filter value — columns and `extraFilters` alike — and `{ col }`.
|
|
38
|
+
* Name every column with `col(field)`: the same condition runs in the main search and inside
|
|
39
|
+
* join subqueries, where only `col` knows the qualifier.
|
|
40
|
+
*/
|
|
41
|
+
extendedCondition?: ExtendedConditionFn;
|
|
39
42
|
/**
|
|
40
43
|
* Virtual fields produced by a SQL expression. Usable like schema fields in
|
|
41
44
|
* `filters`, `conditions` (non-dotted), `orderBy` (1-part),
|
|
42
|
-
* `
|
|
45
|
+
* `compute`, and (opt-in, when listed) in `select` for the main
|
|
43
46
|
* response. Each entry MUST declare `type` for Swagger and validation.
|
|
44
47
|
*
|
|
45
48
|
* Naming clashes with `Schema.fields` or `extraFilters` keys throw at
|
|
46
49
|
* `defineTable` time.
|
|
47
50
|
*/
|
|
48
51
|
computedFields?: Record<string, ComputedFieldFn>;
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
+
readJoins?: JoinDefinition[];
|
|
53
|
+
writeJoins?: JoinDefinition[];
|
|
54
|
+
/**
|
|
55
|
+
* Upsert the main row on this key: an insert (`POST /rest`, `sqlApi.insert`) and every bulk
|
|
56
|
+
* upsert item becomes `INSERT … ON CONFLICT (<key>) DO UPDATE`. Fields (camelCase), exactly
|
|
57
|
+
* the schema's primary key or one of its `uniqueKeys`, checked at startup (ADR 0021).
|
|
58
|
+
* Absent, those writes are plain INSERTs.
|
|
59
|
+
*
|
|
60
|
+
* The main row only: the secondaries a write join carries upsert on the `upsertKey` of that
|
|
61
|
+
* relation (`buildRelation(…, { upsertKey })`).
|
|
62
|
+
*/
|
|
63
|
+
upsertKey?: (string & keyof F)[];
|
|
52
64
|
/**
|
|
53
65
|
* Narrow a field's generated type where the DB could only describe it loosely: a column
|
|
54
66
|
* Postgres calls `text` is an email, a UUID, a URL; an `integer` has a range. The generated
|
|
@@ -71,30 +83,36 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
|
|
|
71
83
|
* API is what `afterRead` (out) and `beforeInsert`/`beforeUpdate` (in) are for.
|
|
72
84
|
*/
|
|
73
85
|
schemaOverrides?: Partial<Record<string & keyof F, TSchema>>;
|
|
86
|
+
/** Business validation of an insert/update: `{ db, req, main, upsert, replace }` → errors (any → 400, nothing written). */
|
|
74
87
|
validate?: ValidatorFn<F>;
|
|
88
|
+
/** Bulk upsert validation, called once with every item: `{ db, req, items }`. When set, per-item `validate` is skipped in bulk. */
|
|
75
89
|
validateBulk?: BulkValidatorFn<F>;
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
beforeUpdate?: (
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
90
|
+
/** Before the INSERT, after `insertExclude` stripped the client payload (ADR 0005): mutate `ctx.record` in place. */
|
|
91
|
+
beforeInsert?: (ctx: WriteHookContext<F>) => void | Promise<void>;
|
|
92
|
+
/** Before the UPDATE: mutate `ctx.record` in place. The PK is present but never written. */
|
|
93
|
+
beforeUpdate?: (ctx: WriteHookContext<F>) => void | Promise<void>;
|
|
94
|
+
/**
|
|
95
|
+
* Runs after a successful insert: `{ db, req, record, secondaries, deletions }`, the camelCase
|
|
96
|
+
* input record merged with the generated primary key, the child rows written with it and
|
|
97
|
+
* those a `replace` removed, keyed by alias (absent when there were none).
|
|
98
|
+
*
|
|
99
|
+
* On an insert it runs inside the transaction of the INSERT and its child rows, so throwing
|
|
100
|
+
* rolls them back. On a bulk upsert it runs once per item, outside any transaction (ADR 0003)
|
|
101
|
+
* — except for an item with a `replace`, whose child rows and hook share one (ADR 0029).
|
|
102
|
+
*/
|
|
103
|
+
afterInsert?: (ctx: AfterInsertContext<F>) => void | Promise<void>;
|
|
104
|
+
/**
|
|
105
|
+
* Runs after a successful update, inside the same transaction as the UPDATE and its child
|
|
106
|
+
* rows: throwing here rolls back the whole operation. `{ db, req, record, secondaries,
|
|
107
|
+
* deletions }`: the camelCase input record (including the PK) plus the child rows written and
|
|
108
|
+
* deleted, by alias.
|
|
109
|
+
*/
|
|
110
|
+
afterUpdate?: (ctx: AfterUpdateContext<F>) => void | Promise<void>;
|
|
111
|
+
/**
|
|
112
|
+
* Runs on the rows a read returned, once per result set, before they become the response:
|
|
113
|
+
* `{ db, req, rows, source, alias }`. The read-side counterpart of `beforeInsert`/
|
|
114
|
+
* `beforeUpdate`: the place to turn a stored representation back into the API one
|
|
115
|
+
* (decrypting a column, unpacking a blob).
|
|
98
116
|
*
|
|
99
117
|
* `rows` are camelCase records and are mutated **in place** — the return value is ignored.
|
|
100
118
|
* Rows cannot be added or removed: the pagination `COUNT` has already run, so a hook that
|
|
@@ -104,53 +122,39 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
|
|
|
104
122
|
*
|
|
105
123
|
* Declared on the table that OWNS the column, and it follows a join: the hook runs whenever
|
|
106
124
|
* that table's rows surface, including through a `joinMultiple` or `joinLeft` declared on
|
|
107
|
-
* another table (`
|
|
108
|
-
*
|
|
125
|
+
* another table (`source` and `alias` say which). It does not run on `joinGroup`, whose rows
|
|
126
|
+
* are aggregates rather than table rows.
|
|
109
127
|
*
|
|
110
128
|
* Not called when the read returned no rows. Whatever the hook writes is serialized against
|
|
111
129
|
* the response schema, so a transform that changes a field's JSON type needs a matching
|
|
112
130
|
* `schemaOverrides` entry — without it `fast-json-stringify` coerces the value silently.
|
|
113
|
-
*
|
|
114
|
-
* `req` is the request that triggered the read. Same caveat as `beforeDelete`:
|
|
115
|
-
* present through the auto-generated HTTP routes, `undefined` when a programmatic caller
|
|
116
|
-
* invokes `sqlApi.search()`/`sqlApi.get()` without passing one.
|
|
117
131
|
*/
|
|
118
|
-
afterRead?: (
|
|
132
|
+
afterRead?: (ctx: AfterReadContext) => void | Promise<void>;
|
|
119
133
|
/**
|
|
120
|
-
* Runs before a single record is deleted (DELETE /rest/:id)
|
|
121
|
-
* deletion (the thrown error's `statusCode`/`message` are surfaced to the client).
|
|
134
|
+
* Runs before a single record is deleted (DELETE /rest/:id): `{ db, req, id }`. Throw to
|
|
135
|
+
* abort the deletion (the thrown error's `statusCode`/`message` are surfaced to the client).
|
|
122
136
|
* Use it to enforce referential or business rules the DB cascade would otherwise hide.
|
|
123
137
|
*
|
|
124
138
|
* For tenant-scoped tables the hook only runs once ownership has been verified, so it
|
|
125
139
|
* never fires for rows the caller cannot access.
|
|
126
|
-
*
|
|
127
|
-
* `req` is the request that triggered the operation. It is always present when
|
|
128
|
-
* the delete comes through the auto-generated HTTP route. It is `undefined` only if you
|
|
129
|
-
* call `sqlApi.delete(table, id)` programmatically without passing a request — in that
|
|
130
|
-
* case any hook that reads request context (e.g. `req.user`) must guard for it.
|
|
131
|
-
*/
|
|
132
|
-
beforeDelete?: (db: QueryClient, req: ApiRequest, id: string | number) => void | Promise<void>;
|
|
133
|
-
/**
|
|
134
|
-
* Runs after a single record has been deleted (DELETE /rest/:id). Not called when the
|
|
135
|
-
* record was not found (404). Same `req` caveat as `beforeDelete`.
|
|
136
140
|
*/
|
|
137
|
-
|
|
141
|
+
beforeDelete?: (ctx: DeleteHookContext) => void | Promise<void>;
|
|
142
|
+
/** Runs after a single record has been deleted: `{ db, req, id }`. Not called when the record was not found (404). */
|
|
143
|
+
afterDelete?: (ctx: DeleteHookContext) => void | Promise<void>;
|
|
138
144
|
/**
|
|
139
145
|
* Bulk counterpart of `beforeDelete`, invoked ONCE with all ids before a bulk delete
|
|
140
|
-
* (POST /bulk/:table/delete)
|
|
141
|
-
*
|
|
142
|
-
*
|
|
143
|
-
*
|
|
144
|
-
* Same `req` caveat as `beforeDelete`: present via the HTTP route, `undefined` only when
|
|
145
|
-
* `sqlApi.bulkDelete(table, ids)` is called programmatically without a request.
|
|
146
|
+
* (POST /bulk/:table/delete): `{ db, req, ids }`, the ids as the request sent them — values,
|
|
147
|
+
* or `{ <field>: value }` objects on a composite primary key. Called once — not per id — to preserve the
|
|
148
|
+
* single-query optimization. Throw to abort the whole batch. `beforeDelete` is NOT called
|
|
149
|
+
* for bulk deletes; configure this hook if you need a guard there.
|
|
146
150
|
*/
|
|
147
|
-
beforeBulkDelete?: (
|
|
151
|
+
beforeBulkDelete?: (ctx: BulkDeleteHookContext) => void | Promise<void>;
|
|
148
152
|
/**
|
|
149
|
-
* Bulk counterpart of `afterDelete`, invoked ONCE after a bulk delete with the ids that
|
|
150
|
-
*
|
|
151
|
-
*
|
|
153
|
+
* Bulk counterpart of `afterDelete`, invoked ONCE after a bulk delete with the ids that were
|
|
154
|
+
* ACTUALLY deleted (a subset of the requested ones when some rows did not exist):
|
|
155
|
+
* `{ db, req, ids }`. Not called when nothing was deleted.
|
|
152
156
|
*/
|
|
153
|
-
afterBulkDelete?: (
|
|
157
|
+
afterBulkDelete?: (ctx: BulkDeleteHookContext) => void | Promise<void>;
|
|
154
158
|
/**
|
|
155
159
|
* Whitelist of auto-generated HTTP routes for this table. When omitted, ALL operations
|
|
156
160
|
* are exposed (search, get, insert, update, delete, bulkUpsert, bulkDelete) — the
|
|
@@ -163,11 +167,11 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
|
|
|
163
167
|
operations?: TableOperation[];
|
|
164
168
|
/**
|
|
165
169
|
* Fields hidden from every read: they are not projected by search/get, not included
|
|
166
|
-
* in the read response schemas, and omitted from this table's default join
|
|
170
|
+
* in the read response schemas, and omitted from this table's default join projection
|
|
167
171
|
* when it is the target of a join.
|
|
168
172
|
*
|
|
169
173
|
* Referencing an excluded field from filters, conditions, orderBy, aggregations or an
|
|
170
|
-
* explicit join
|
|
174
|
+
* explicit join `select` is rejected with 400 — hiding a field from the output while
|
|
171
175
|
* letting it be filtered would still leak its value by bisection.
|
|
172
176
|
*
|
|
173
177
|
* Write paths are NOT affected: a field can be writable but never readable (e.g. a
|
|
@@ -187,24 +191,35 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
|
|
|
187
191
|
*
|
|
188
192
|
* Not a per-caller permission: it is static and applies to everyone, admins included.
|
|
189
193
|
* Field-level rules that depend on who is asking belong in `beforeUpdate` (silent strip) or
|
|
190
|
-
* `validate` (loud 400). Not `
|
|
191
|
-
*
|
|
194
|
+
* `validate` (loud 400). Not `insertExclude` either — that one whitelists client input on
|
|
195
|
+
* insert only, and deliberately lets a hook assign the field afterwards.
|
|
192
196
|
*
|
|
193
197
|
* The primary key cannot be excluded: the update body identifies the row with it.
|
|
194
198
|
*/
|
|
195
199
|
writeExclude?: (string & keyof F)[];
|
|
200
|
+
/**
|
|
201
|
+
* Fields a client may not send on insert: their value is dropped from the client payload,
|
|
202
|
+
* and they are Optional in the insert body. The server still may set them — `beforeInsert`
|
|
203
|
+
* runs after the drop, and the FK of a secondary is auto-filled after it too (ADR 0005).
|
|
204
|
+
* The generator lists auto-increment and identity primary keys here.
|
|
205
|
+
*
|
|
206
|
+
* Insert only, and client input only: every field stays updatable (ADR 0004), and it applies
|
|
207
|
+
* to the rows this table receives as secondaries of another table as well. For a column no
|
|
208
|
+
* write may carry, whoever sets it, use `writeExclude`.
|
|
209
|
+
*/
|
|
210
|
+
insertExclude?: (string & keyof F)[];
|
|
196
211
|
defaultOrder?: string;
|
|
197
|
-
excludeFromCreation?: (string & keyof F)[];
|
|
198
212
|
distinctResults?: boolean;
|
|
199
213
|
onRequests?: ((request: ApiRequest, reply: ApiReply) => Promise<void | ApiReply>)[];
|
|
200
214
|
tenantScope?: TenantScope;
|
|
201
215
|
}
|
|
202
|
-
export type DbTables = Record<string,
|
|
216
|
+
export type DbTables = Record<string, TableConfig<any>>;
|
|
203
217
|
export declare function primaryAsString(pk: string | string[]): string;
|
|
204
218
|
/**
|
|
205
219
|
* True when the primary key spans more than one column. Operations that address a
|
|
206
|
-
* record by a single PK value (get, delete
|
|
207
|
-
* matching on the first column alone would hit every row sharing that value.
|
|
220
|
+
* record by a single PK value in the path (get, delete) cannot work on such tables:
|
|
221
|
+
* matching on the first column alone would hit every row sharing that value. Bulk delete
|
|
222
|
+
* takes one object per key instead.
|
|
208
223
|
*/
|
|
209
224
|
export declare function isCompositePrimary(pk: string | string[]): boolean;
|
|
210
225
|
export declare function primaryAsCols(pk: string | string[], colFn: (f: string) => string): string | string[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/types/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/types/table.ts"],"names":[],"mappings":"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"}
|
package/dist/types/table.js
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
|
+
/** Every {@link TableOperation}, in route order. */
|
|
2
|
+
export const TABLE_OPERATIONS = [
|
|
3
|
+
'search', 'get', 'insert', 'update', 'delete', 'bulkUpsert', 'bulkDelete',
|
|
4
|
+
];
|
|
1
5
|
// Primary key helpers
|
|
2
6
|
export function primaryAsString(pk) {
|
|
3
7
|
return Array.isArray(pk) ? pk[0] : pk;
|
|
4
8
|
}
|
|
5
9
|
/**
|
|
6
10
|
* True when the primary key spans more than one column. Operations that address a
|
|
7
|
-
* record by a single PK value (get, delete
|
|
8
|
-
* matching on the first column alone would hit every row sharing that value.
|
|
11
|
+
* record by a single PK value in the path (get, delete) cannot work on such tables:
|
|
12
|
+
* matching on the first column alone would hit every row sharing that value. Bulk delete
|
|
13
|
+
* takes one object per key instead.
|
|
9
14
|
*/
|
|
10
15
|
export function isCompositePrimary(pk) {
|
|
11
16
|
return Array.isArray(pk) && pk.length > 1;
|
package/dist/types/tenant.d.ts
CHANGED
|
@@ -1,13 +1,39 @@
|
|
|
1
1
|
import type { SchemaDefinition } from './schema.js';
|
|
2
|
+
import type { ApiRequest } from './request.js';
|
|
2
3
|
export type TenantId = string | number;
|
|
4
|
+
/**
|
|
5
|
+
* The value `getTenantId` returns for a caller allowed to see every tenant's rows. Admin is
|
|
6
|
+
* declared, never inferred: an absent tenant (`null`/`undefined`) is a 401 on any scoped
|
|
7
|
+
* table, so an auth hook that failed to run cannot open the data. A registry symbol, so two
|
|
8
|
+
* copies of the package agree on it and no real tenant id can collide with it.
|
|
9
|
+
*/
|
|
10
|
+
export declare const TENANT_ADMIN: unique symbol;
|
|
11
|
+
export type TenantAdmin = typeof TENANT_ADMIN;
|
|
12
|
+
/**
|
|
13
|
+
* What `getTenantId` resolves a request to: one tenant id, several (a caller who belongs to
|
|
14
|
+
* more than one tenant), `TENANT_ADMIN` for no filtering, or nothing — which is refused with
|
|
15
|
+
* 401 as soon as a scoped table is in reach. `[]` is a caller with no tenant at all: 403.
|
|
16
|
+
*/
|
|
17
|
+
export type TenantResolution = TenantId | TenantId[] | TenantAdmin | null | undefined;
|
|
18
|
+
export type GetTenantId = (request: ApiRequest) => TenantResolution | Promise<TenantResolution>;
|
|
19
|
+
/**
|
|
20
|
+
* The names of a scope are schema fields, like every other key of a table config, each resolved
|
|
21
|
+
* to its column through the schema of the table it lives on. The column of a field is accepted as
|
|
22
|
+
* written; any other name is refused by `defineTable` (ADR 0032).
|
|
23
|
+
*/
|
|
3
24
|
export interface TenantScopeDirect {
|
|
25
|
+
/** The tenant field of this table. */
|
|
4
26
|
column: string;
|
|
5
27
|
}
|
|
6
28
|
export interface TenantScopeIndirect {
|
|
29
|
+
/** The tenant field of the parent table, `through.schema`. */
|
|
7
30
|
column: string;
|
|
8
31
|
through: {
|
|
32
|
+
/** The parent table's schema. */
|
|
9
33
|
schema: SchemaDefinition;
|
|
34
|
+
/** The FK field of this table that names the parent row. */
|
|
10
35
|
localField: string;
|
|
36
|
+
/** The field of the parent table the FK points at. */
|
|
11
37
|
foreignField: string;
|
|
12
38
|
};
|
|
13
39
|
}
|
|
@@ -18,7 +44,7 @@ export interface TenantScopeIndirect {
|
|
|
18
44
|
*
|
|
19
45
|
* Writes cannot auto-inject a tenant the way a single-column scope does — the plugin has no way
|
|
20
46
|
* to know which party the caller is meant to be — so the payload must anchor the row itself:
|
|
21
|
-
* see `assertTenantAnchor`.
|
|
47
|
+
* see `assertTenantAnchor`. The entries are fields of this table, like `TenantScopeDirect.column`.
|
|
22
48
|
*
|
|
23
49
|
* Not combinable with `column`/`through`: an entry reached through a parent FK would need its
|
|
24
50
|
* own join per entry, and is rejected at `defineTable` time rather than half-supported.
|
|
@@ -34,7 +60,7 @@ export type TenantScope = TenantScopeDirect | TenantScopeIndirect | TenantScopeA
|
|
|
34
60
|
* the request touches. `scope` is table-level and therefore **optional**: the addressed table may
|
|
35
61
|
* declare no scope of its own while a table it reaches through a relation does. Absent `scope`
|
|
36
62
|
* means "no filtering on this table", never "no tenant" — `tenantForTable` re-targets the same
|
|
37
|
-
* ids onto a related table's own scope.
|
|
63
|
+
* ids onto a related table's own scope. Its names are already resolved to columns.
|
|
38
64
|
*/
|
|
39
65
|
export interface TenantContext {
|
|
40
66
|
ids: TenantId[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuD,CAAC;AAC1F,MAAM,MAAM,WAAW,GAAG,OAAO,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,EAAE,GAAG,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;AACtF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,iCAAiC;QACjC,MAAM,EAAE,gBAAgB,CAAC;QACzB,4DAA4D;QAC5D,UAAU,EAAE,MAAM,CAAC;QACnB,sDAAsD;QACtD,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}
|
package/dist/types/tenant.js
CHANGED
|
@@ -1 +1,7 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The value `getTenantId` returns for a caller allowed to see every tenant's rows. Admin is
|
|
3
|
+
* declared, never inferred: an absent tenant (`null`/`undefined`) is a 401 on any scoped
|
|
4
|
+
* table, so an auth hook that failed to run cannot open the data. A registry symbol, so two
|
|
5
|
+
* copies of the package agree on it and no real tenant id can collide with it.
|
|
6
|
+
*/
|
|
7
|
+
export const TENANT_ADMIN = Symbol.for('fastify-auto-sqlapi.tenant.admin');
|
|
@@ -1,21 +1,77 @@
|
|
|
1
|
-
import type { TSchema, Static } from '
|
|
2
|
-
import type {
|
|
3
|
-
import type {
|
|
1
|
+
import type { TSchema, Static } from 'typebox';
|
|
2
|
+
import type { RowsByAlias } from './db.js';
|
|
3
|
+
import type { HookContext } from './hooks.js';
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* -
|
|
5
|
+
* One entry of the `fields` array every 400 response carries, whether the error came from
|
|
6
|
+
* the request schema, from a table's `validate`/`validateBulk`, or from the engine.
|
|
7
|
+
*
|
|
8
|
+
* - `path`: dot path of the offending value inside the request — body keys from the root
|
|
9
|
+
* (`main.name`, `upsert.orders.0.total`, `filters.status`, `conditions.2.params`,
|
|
10
|
+
* `joinMultiple.orders.select.1`), querystring and path parameters by name (`orderBy`,
|
|
11
|
+
* `itemsPerPage`, `id`). The empty string when the error is not attributable to one input.
|
|
12
|
+
* - `code`: machine-readable and stable — an Ajv keyword (`required`, `type`, `maximum`…),
|
|
13
|
+
* the code a `validate` hook returned, or one of the engine's codes (`unknown_field`,
|
|
14
|
+
* `not_readable`, `unknown_alias`, `invalid_params`…, see AGENTS_FRONTEND.md).
|
|
15
|
+
* - `message`: Ajv's, the engine's or an `httpError`'s description, for a developer. Absent
|
|
16
|
+
* when there is nothing to say beyond the code: on an entry `validate`/`validateBulk`
|
|
17
|
+
* returned (a hook writes no prose) and on a `dbErrors` answer.
|
|
9
18
|
*/
|
|
10
|
-
export
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
19
|
+
export interface ValidationField {
|
|
20
|
+
path: string;
|
|
21
|
+
code: string;
|
|
22
|
+
message?: string;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The main row a child row is written with, as the child table's `validate`/`validateBulk` sees
|
|
26
|
+
* it when its rows arrive through another table's write join (ADR 0030): the alias they were
|
|
27
|
+
* sent under and that table's main row, camelCase, as the request sent it.
|
|
28
|
+
*/
|
|
29
|
+
export interface ValidateParent {
|
|
30
|
+
alias: string;
|
|
31
|
+
main: Record<string, unknown>;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* `validate`: the camelCase main record of an insert or update, and the child rows it writes,
|
|
35
|
+
* by alias, under the request's own section names — so an error's `path` is the request's.
|
|
36
|
+
*
|
|
37
|
+
* When the table's rows arrive as another table's child rows, `main` is one of them — with the
|
|
38
|
+
* FK to that table's main row when the request names its key — and `parent` names that table's
|
|
39
|
+
* main row; on the table's own routes `parent` is absent (ADR 0030).
|
|
40
|
+
*/
|
|
41
|
+
export interface ValidateContext<F extends Record<string, TSchema> = Record<string, TSchema>> extends HookContext {
|
|
42
|
+
main: {
|
|
43
|
+
[K in keyof F]?: Static<F[K]>;
|
|
44
|
+
};
|
|
45
|
+
upsert?: RowsByAlias;
|
|
46
|
+
replace?: RowsByAlias;
|
|
47
|
+
parent?: ValidateParent;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* What a `validate`/`validateBulk` hook returns: one `{ path, code }` per problem, rendered as
|
|
51
|
+
* a field of the 400 — `path` in the grammar of `ValidationField.path` (`main.name`,
|
|
52
|
+
* `upsert.orders.0.total`; in `validateBulk`, `items.3.main.code`), `code` the stable
|
|
53
|
+
* code the client translates (`required`, `overlap`, `unique`). An empty array lets the write
|
|
54
|
+
* through.
|
|
55
|
+
*/
|
|
56
|
+
export type ValidatorResult = Pick<ValidationField, 'path' | 'code'>[];
|
|
57
|
+
export type ValidatorFn<F extends Record<string, TSchema> = Record<string, TSchema>> = (ctx: ValidateContext<F>) => Promise<ValidatorResult> | ValidatorResult;
|
|
58
|
+
/** One item of a bulk upsert, as the request sent it. */
|
|
14
59
|
export interface BulkValidatorItem<F extends Record<string, TSchema> = Record<string, TSchema>> {
|
|
15
60
|
main: {
|
|
16
61
|
[K in keyof F]?: Static<F[K]>;
|
|
17
62
|
};
|
|
18
|
-
|
|
63
|
+
upsert?: RowsByAlias;
|
|
64
|
+
delete?: RowsByAlias;
|
|
65
|
+
replace?: RowsByAlias;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* `validateBulk`: every item of a bulk upsert, once — or, when the table's rows arrive as
|
|
69
|
+
* another table's child rows, the rows of one alias as `{ main }` items, with `parent`
|
|
70
|
+
* (ADR 0030).
|
|
71
|
+
*/
|
|
72
|
+
export interface BulkValidateContext<F extends Record<string, TSchema> = Record<string, TSchema>> extends HookContext {
|
|
73
|
+
items: BulkValidatorItem<F>[];
|
|
74
|
+
parent?: ValidateParent;
|
|
19
75
|
}
|
|
20
|
-
export type BulkValidatorFn<F extends Record<string, TSchema> = Record<string, TSchema>> = (
|
|
76
|
+
export type BulkValidatorFn<F extends Record<string, TSchema> = Record<string, TSchema>> = (ctx: BulkValidateContext<F>) => Promise<ValidatorResult> | ValidatorResult;
|
|
21
77
|
//# sourceMappingURL=validation.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,
|
|
1
|
+
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW;IAC/G,IAAI,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAEvE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACrF,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,KACpB,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,yDAAyD;AACzD,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5F,IAAI,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW;IACnH,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACzF,GAAG,EAAE,mBAAmB,CAAC,CAAC,CAAC,KACxB,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC"}
|