@sdflc/backend-helpers 1.0.129 → 1.0.131
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/build/BaseRestApiCrudController.d.ts +116 -29
- package/build/BaseRestApiCrudController.js +175 -60
- package/build/esm/BaseRestApiCrudController.d.ts +116 -29
- package/build/esm/BaseRestApiCrudController.js +175 -60
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +9 -2
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +9 -2
- package/package.json +1 -1
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
import { BaseController } from './BaseController';
|
|
2
2
|
import { BaseRestApiCrudControllerPropsInterface } from './interfaces';
|
|
3
|
+
/**
|
|
4
|
+
* BaseRestApiCrudController
|
|
5
|
+
*
|
|
6
|
+
* Provides a standard REST CRUD surface that maps HTTP requests to core
|
|
7
|
+
* method calls using the same argument shapes as GraphQL resolvers. This
|
|
8
|
+
* means a core written for GraphQL works identically over REST with no
|
|
9
|
+
* changes.
|
|
10
|
+
*
|
|
11
|
+
* ── Argument shapes ───────────────────────────────────────────────────────────
|
|
12
|
+
* list → core.list({ filter, params }) params: PaginationAndSorting
|
|
13
|
+
* get → core.get({ id })
|
|
14
|
+
* getMany → core.getMany({ ids })
|
|
15
|
+
* create → core.create({ params }) body: { params: {...} }
|
|
16
|
+
* createMany → core.createMany({ params }) body: { params: [{...}] }
|
|
17
|
+
* update → core.update({ where, params }) body: { params: {...} }
|
|
18
|
+
* updateMany → core.updateMany({ params }) body: { params: [{...}] }
|
|
19
|
+
* remove → core.remove({ where })
|
|
20
|
+
* removeMany → core.removeMany({ where })
|
|
21
|
+
*
|
|
22
|
+
* ── URL conventions ───────────────────────────────────────────────────────────
|
|
23
|
+
* Filter fields go flat in the query string:
|
|
24
|
+
* ?partyId=abc-123&isEnabled=true
|
|
25
|
+
*
|
|
26
|
+
* Pagination and sorting use bracket notation (parsed by qs automatically):
|
|
27
|
+
* ?pagination[page]=1&pagination[pageSize]=20
|
|
28
|
+
* ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
29
|
+
*
|
|
30
|
+
* Combined example:
|
|
31
|
+
* GET /api/v1/party-ticket-types
|
|
32
|
+
* ?partyId=abc-123
|
|
33
|
+
* &isEnabled=true
|
|
34
|
+
* &pagination[page]=1
|
|
35
|
+
* &pagination[pageSize]=20
|
|
36
|
+
* &sortBy[0][name]=orderNo
|
|
37
|
+
* &sortBy[0][order]=ASC
|
|
38
|
+
*
|
|
39
|
+
* ── Extension points ──────────────────────────────────────────────────────────
|
|
40
|
+
* buildWhere(req, ids) — override to add extra where conditions beyond id
|
|
41
|
+
* buildFilter(req) — override to customise filter extraction from QS
|
|
42
|
+
* buildParams(req) — override to customise pagination extraction from QS
|
|
43
|
+
*
|
|
44
|
+
* ── Route registration ────────────────────────────────────────────────────────
|
|
45
|
+
* Each subclass declares its own `root` path (e.g. '/api/v1/party-ticket-types').
|
|
46
|
+
* app.ts calls controller.init({ app, root: controller.root }) so no
|
|
47
|
+
* root needs to be passed at instantiation time.
|
|
48
|
+
*
|
|
49
|
+
* ── Context resolution ────────────────────────────────────────────────────────
|
|
50
|
+
* `getContext` defaults to (req) => req.context, which is set by the
|
|
51
|
+
* createContext middleware in app.ts before any REST handler runs.
|
|
52
|
+
* Override via props only when a controller needs a different context source.
|
|
53
|
+
*/
|
|
3
54
|
declare class BaseRestApiCrudController extends BaseController {
|
|
55
|
+
/** Mount path for this controller, e.g. '/api/v1/party-ticket-types' */
|
|
56
|
+
root: string;
|
|
4
57
|
protected coreToUse: string;
|
|
5
58
|
protected getContext: (req: any) => Promise<any> | any;
|
|
6
59
|
protected disableList: boolean;
|
|
@@ -12,81 +65,115 @@ declare class BaseRestApiCrudController extends BaseController {
|
|
|
12
65
|
protected disableUpdateMany: boolean;
|
|
13
66
|
protected disableRemove: boolean;
|
|
14
67
|
protected disableRemoveMany: boolean;
|
|
15
|
-
constructor(props
|
|
68
|
+
constructor(props?: BaseRestApiCrudControllerPropsInterface);
|
|
16
69
|
/**
|
|
17
70
|
* Builds the `where` object for update and remove operations.
|
|
18
71
|
*
|
|
19
|
-
* Base implementation
|
|
20
|
-
*
|
|
21
|
-
* or query string while keeping the URL pattern intact.
|
|
72
|
+
* Base implementation returns { id: ids } where ids is the array parsed
|
|
73
|
+
* from the `:id` route param (single or comma-separated).
|
|
22
74
|
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
75
|
+
* Override in a subclass to add extra conditions from req.body or
|
|
76
|
+
* req.query while keeping the /:id URL pattern intact. Example:
|
|
77
|
+
*
|
|
78
|
+
* protected buildWhere(req: any, ids: string[]): Record<string, any> {
|
|
79
|
+
* return { id: ids, statusId: req.body?.where?.statusId };
|
|
80
|
+
* }
|
|
25
81
|
*/
|
|
26
82
|
protected buildWhere(req: any, ids: string[]): Record<string, any>;
|
|
27
83
|
/**
|
|
28
|
-
* Builds the `filter` object
|
|
29
|
-
*
|
|
30
|
-
* Base implementation treats every query string key that is NOT in
|
|
31
|
-
* PAGINATION_KEYS as a filter field. Override to apply custom filtering
|
|
32
|
-
* logic or to parse typed values (e.g. booleans, arrays).
|
|
84
|
+
* Builds the `filter` object passed to core.list().
|
|
33
85
|
*
|
|
34
|
-
*
|
|
86
|
+
* Base implementation treats every query string key that is NOT a known
|
|
87
|
+
* pagination key (pagination, sortBy) as a filter field. Override to
|
|
88
|
+
* apply custom parsing (e.g. typed booleans, array values, renamed fields).
|
|
35
89
|
*/
|
|
36
90
|
protected buildFilter(req: any): Record<string, any>;
|
|
37
91
|
/**
|
|
38
|
-
* Builds the `params` object
|
|
92
|
+
* Builds the `params` object passed to core.list().
|
|
93
|
+
*
|
|
94
|
+
* Assembles the PaginationAndSorting shape expected by cores:
|
|
95
|
+
* {
|
|
96
|
+
* pagination: { page: string, pageSize: string },
|
|
97
|
+
* sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
|
|
98
|
+
* }
|
|
99
|
+
*
|
|
100
|
+
* pagination values are passed through as-is (strings from qs) —
|
|
101
|
+
* type coercion is left to the core/gateway layer.
|
|
39
102
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
103
|
+
* sortBy entries with a missing or empty name are silently dropped.
|
|
104
|
+
* order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
105
|
+
* unrecognised value — this is structural normalisation, not type coercion.
|
|
42
106
|
*
|
|
43
|
-
*
|
|
107
|
+
* Override to support additional or renamed pagination conventions.
|
|
44
108
|
*/
|
|
45
109
|
protected buildParams(req: any): Record<string, any>;
|
|
46
110
|
protected resolveCore(req: any): Promise<any>;
|
|
111
|
+
/**
|
|
112
|
+
* Registers all enabled routes on the Express app under `root`.
|
|
113
|
+
* Called once at startup by app.ts:
|
|
114
|
+
*
|
|
115
|
+
* controller.init({ app, root: controller.root })
|
|
116
|
+
*
|
|
117
|
+
* Routes are only registered for operations that are not disabled.
|
|
118
|
+
* /many routes are registered before /:id to avoid Express matching
|
|
119
|
+
* "many" as an id param.
|
|
120
|
+
*/
|
|
47
121
|
init(props: {
|
|
48
122
|
app: any;
|
|
49
123
|
root: string;
|
|
50
124
|
}): void;
|
|
51
125
|
/**
|
|
52
126
|
* GET /
|
|
53
|
-
*
|
|
54
|
-
*
|
|
127
|
+
*
|
|
128
|
+
* Splits the query string into filter (non-pagination keys) and params
|
|
129
|
+
* (PaginationAndSorting shape) via buildFilter() and buildParams().
|
|
130
|
+
* Shape matches the GraphQL list resolver: core.list({ filter, params }).
|
|
55
131
|
*/
|
|
56
132
|
protected list(req: any): Promise<any>;
|
|
57
133
|
/**
|
|
58
134
|
* GET /:id
|
|
59
|
-
*
|
|
60
|
-
*
|
|
135
|
+
*
|
|
136
|
+
* Routes to core.get({ id }) for a single id, or core.getMany({ ids })
|
|
137
|
+
* when the :id param contains comma-separated values.
|
|
61
138
|
*/
|
|
62
139
|
protected getOrGetMany(req: any): Promise<any>;
|
|
63
140
|
/**
|
|
64
141
|
* POST /
|
|
65
|
-
*
|
|
142
|
+
*
|
|
143
|
+
* Body must be { params: {...} }.
|
|
144
|
+
* Consistent with GraphQL mutation: partyTicketTypeCreate(params: Input).
|
|
66
145
|
*/
|
|
67
146
|
protected create(req: any): Promise<any>;
|
|
68
147
|
/**
|
|
69
148
|
* POST /many
|
|
70
|
-
*
|
|
149
|
+
*
|
|
150
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
151
|
+
* item which is auto-wrapped in an array.
|
|
71
152
|
*/
|
|
72
153
|
protected createMany(req: any): Promise<any>;
|
|
73
154
|
/**
|
|
74
155
|
* PUT /:id
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
156
|
+
*
|
|
157
|
+
* Body must be { params: {...} }. The :id route param is parsed into an
|
|
158
|
+
* array and passed to buildWhere() — override buildWhere() to add extra
|
|
159
|
+
* conditions beyond id while keeping the /:id URL pattern.
|
|
160
|
+
*
|
|
161
|
+
* Shape: core.update({ where: { id: [id] }, params: {...} })
|
|
78
162
|
*/
|
|
79
163
|
protected update(req: any): Promise<any>;
|
|
80
164
|
/**
|
|
81
165
|
* PUT /many
|
|
82
|
-
*
|
|
166
|
+
*
|
|
167
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
168
|
+
* item which is auto-wrapped in an array.
|
|
83
169
|
*/
|
|
84
170
|
protected updateMany(req: any): Promise<any>;
|
|
85
171
|
/**
|
|
86
172
|
* DELETE /:id
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
173
|
+
*
|
|
174
|
+
* Routes to core.remove({ where }) for a single id, or
|
|
175
|
+
* core.removeMany({ where }) for comma-separated ids. where is built via
|
|
176
|
+
* buildWhere() — override to add extra conditions.
|
|
90
177
|
*/
|
|
91
178
|
protected removeOrRemoveMany(req: any): Promise<any>;
|
|
92
179
|
}
|
|
@@ -5,11 +5,69 @@ exports.BaseRestApiCrudController = void 0;
|
|
|
5
5
|
const BaseController_1 = require("./BaseController");
|
|
6
6
|
const parseIds_1 = require("./parseIds");
|
|
7
7
|
/**
|
|
8
|
-
*
|
|
8
|
+
* Query string keys that belong to `params` (PaginationAndSorting shape).
|
|
9
9
|
* Everything else in the query string is treated as a filter field.
|
|
10
|
+
*
|
|
11
|
+
* qs (used by Express) parses bracket notation automatically, so:
|
|
12
|
+
* ?pagination[page]=1&pagination[pageSize]=20&sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
13
|
+
* arrives in req.query as:
|
|
14
|
+
* { pagination: { page: '1', pageSize: '20' }, sortBy: [{ name: 'orderNo', order: 'ASC' }] }
|
|
15
|
+
*/
|
|
16
|
+
const PAGINATION_KEYS = new Set(['pagination', 'sortBy']);
|
|
17
|
+
/**
|
|
18
|
+
* BaseRestApiCrudController
|
|
19
|
+
*
|
|
20
|
+
* Provides a standard REST CRUD surface that maps HTTP requests to core
|
|
21
|
+
* method calls using the same argument shapes as GraphQL resolvers. This
|
|
22
|
+
* means a core written for GraphQL works identically over REST with no
|
|
23
|
+
* changes.
|
|
24
|
+
*
|
|
25
|
+
* ── Argument shapes ───────────────────────────────────────────────────────────
|
|
26
|
+
* list → core.list({ filter, params }) params: PaginationAndSorting
|
|
27
|
+
* get → core.get({ id })
|
|
28
|
+
* getMany → core.getMany({ ids })
|
|
29
|
+
* create → core.create({ params }) body: { params: {...} }
|
|
30
|
+
* createMany → core.createMany({ params }) body: { params: [{...}] }
|
|
31
|
+
* update → core.update({ where, params }) body: { params: {...} }
|
|
32
|
+
* updateMany → core.updateMany({ params }) body: { params: [{...}] }
|
|
33
|
+
* remove → core.remove({ where })
|
|
34
|
+
* removeMany → core.removeMany({ where })
|
|
35
|
+
*
|
|
36
|
+
* ── URL conventions ───────────────────────────────────────────────────────────
|
|
37
|
+
* Filter fields go flat in the query string:
|
|
38
|
+
* ?partyId=abc-123&isEnabled=true
|
|
39
|
+
*
|
|
40
|
+
* Pagination and sorting use bracket notation (parsed by qs automatically):
|
|
41
|
+
* ?pagination[page]=1&pagination[pageSize]=20
|
|
42
|
+
* ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
43
|
+
*
|
|
44
|
+
* Combined example:
|
|
45
|
+
* GET /api/v1/party-ticket-types
|
|
46
|
+
* ?partyId=abc-123
|
|
47
|
+
* &isEnabled=true
|
|
48
|
+
* &pagination[page]=1
|
|
49
|
+
* &pagination[pageSize]=20
|
|
50
|
+
* &sortBy[0][name]=orderNo
|
|
51
|
+
* &sortBy[0][order]=ASC
|
|
52
|
+
*
|
|
53
|
+
* ── Extension points ──────────────────────────────────────────────────────────
|
|
54
|
+
* buildWhere(req, ids) — override to add extra where conditions beyond id
|
|
55
|
+
* buildFilter(req) — override to customise filter extraction from QS
|
|
56
|
+
* buildParams(req) — override to customise pagination extraction from QS
|
|
57
|
+
*
|
|
58
|
+
* ── Route registration ────────────────────────────────────────────────────────
|
|
59
|
+
* Each subclass declares its own `root` path (e.g. '/api/v1/party-ticket-types').
|
|
60
|
+
* app.ts calls controller.init({ app, root: controller.root }) so no
|
|
61
|
+
* root needs to be passed at instantiation time.
|
|
62
|
+
*
|
|
63
|
+
* ── Context resolution ────────────────────────────────────────────────────────
|
|
64
|
+
* `getContext` defaults to (req) => req.context, which is set by the
|
|
65
|
+
* createContext middleware in app.ts before any REST handler runs.
|
|
66
|
+
* Override via props only when a controller needs a different context source.
|
|
10
67
|
*/
|
|
11
|
-
const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
|
|
12
68
|
class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
69
|
+
/** Mount path for this controller, e.g. '/api/v1/party-ticket-types' */
|
|
70
|
+
root;
|
|
13
71
|
coreToUse;
|
|
14
72
|
getContext;
|
|
15
73
|
disableList;
|
|
@@ -22,45 +80,47 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
22
80
|
disableRemove;
|
|
23
81
|
disableRemoveMany;
|
|
24
82
|
constructor(props) {
|
|
25
|
-
super(props);
|
|
26
|
-
const { prefix, core, getContext } = props || {};
|
|
27
|
-
|
|
28
|
-
throw new Error('BaseRestApiCrudController: `getContext` is required');
|
|
29
|
-
}
|
|
83
|
+
super(props ?? {});
|
|
84
|
+
const { prefix, core, getContext, root } = props || {};
|
|
85
|
+
this.root = root ?? '';
|
|
30
86
|
this.coreToUse = core || `${prefix}Core`;
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
this.
|
|
35
|
-
this.
|
|
36
|
-
this.
|
|
37
|
-
this.
|
|
38
|
-
this.
|
|
39
|
-
this.
|
|
40
|
-
this.
|
|
87
|
+
// Default: read the context that createContext middleware attached to req.
|
|
88
|
+
// Pass an explicit getContext in props only when a controller needs to
|
|
89
|
+
// resolve the context differently.
|
|
90
|
+
this.getContext = getContext ?? ((req) => req.context);
|
|
91
|
+
this.disableList = props?.disableList ?? false;
|
|
92
|
+
this.disableGet = props?.disableGet ?? false;
|
|
93
|
+
this.disableGetMany = props?.disableGetMany ?? false;
|
|
94
|
+
this.disableCreate = props?.disableCreate ?? false;
|
|
95
|
+
this.disableCreateMany = props?.disableCreateMany ?? false;
|
|
96
|
+
this.disableUpdate = props?.disableUpdate ?? false;
|
|
97
|
+
this.disableUpdateMany = props?.disableUpdateMany ?? false;
|
|
98
|
+
this.disableRemove = props?.disableRemove ?? false;
|
|
99
|
+
this.disableRemoveMany = props?.disableRemoveMany ?? false;
|
|
41
100
|
}
|
|
42
101
|
// ─── Extension points ───────────────────────────────────────────────────────
|
|
43
102
|
/**
|
|
44
103
|
* Builds the `where` object for update and remove operations.
|
|
45
104
|
*
|
|
46
|
-
* Base implementation
|
|
47
|
-
*
|
|
48
|
-
* or query string while keeping the URL pattern intact.
|
|
105
|
+
* Base implementation returns { id: ids } where ids is the array parsed
|
|
106
|
+
* from the `:id` route param (single or comma-separated).
|
|
49
107
|
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
108
|
+
* Override in a subclass to add extra conditions from req.body or
|
|
109
|
+
* req.query while keeping the /:id URL pattern intact. Example:
|
|
110
|
+
*
|
|
111
|
+
* protected buildWhere(req: any, ids: string[]): Record<string, any> {
|
|
112
|
+
* return { id: ids, statusId: req.body?.where?.statusId };
|
|
113
|
+
* }
|
|
52
114
|
*/
|
|
53
115
|
buildWhere(req, ids) {
|
|
54
116
|
return { id: ids };
|
|
55
117
|
}
|
|
56
118
|
/**
|
|
57
|
-
* Builds the `filter` object
|
|
58
|
-
*
|
|
59
|
-
* Base implementation treats every query string key that is NOT in
|
|
60
|
-
* PAGINATION_KEYS as a filter field. Override to apply custom filtering
|
|
61
|
-
* logic or to parse typed values (e.g. booleans, arrays).
|
|
119
|
+
* Builds the `filter` object passed to core.list().
|
|
62
120
|
*
|
|
63
|
-
*
|
|
121
|
+
* Base implementation treats every query string key that is NOT a known
|
|
122
|
+
* pagination key (pagination, sortBy) as a filter field. Override to
|
|
123
|
+
* apply custom parsing (e.g. typed booleans, array values, renamed fields).
|
|
64
124
|
*/
|
|
65
125
|
buildFilter(req) {
|
|
66
126
|
const filter = {};
|
|
@@ -72,18 +132,48 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
72
132
|
return filter;
|
|
73
133
|
}
|
|
74
134
|
/**
|
|
75
|
-
* Builds the `params` object
|
|
135
|
+
* Builds the `params` object passed to core.list().
|
|
76
136
|
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
137
|
+
* Assembles the PaginationAndSorting shape expected by cores:
|
|
138
|
+
* {
|
|
139
|
+
* pagination: { page: string, pageSize: string },
|
|
140
|
+
* sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
|
|
141
|
+
* }
|
|
79
142
|
*
|
|
80
|
-
*
|
|
143
|
+
* pagination values are passed through as-is (strings from qs) —
|
|
144
|
+
* type coercion is left to the core/gateway layer.
|
|
145
|
+
*
|
|
146
|
+
* sortBy entries with a missing or empty name are silently dropped.
|
|
147
|
+
* order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
148
|
+
* unrecognised value — this is structural normalisation, not type coercion.
|
|
149
|
+
*
|
|
150
|
+
* Override to support additional or renamed pagination conventions.
|
|
81
151
|
*/
|
|
82
152
|
buildParams(req) {
|
|
153
|
+
const query = req.query ?? {};
|
|
83
154
|
const params = {};
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
155
|
+
// ── pagination ────────────────────────────────────────────────────────────
|
|
156
|
+
// qs parses ?pagination[page]=1&pagination[pageSize]=20 into:
|
|
157
|
+
// req.query.pagination = { page: '1', pageSize: '20' }
|
|
158
|
+
// Values are passed through as-is — coercion is left to the core/gateway.
|
|
159
|
+
if (query.pagination && typeof query.pagination === 'object') {
|
|
160
|
+
params.pagination = query.pagination;
|
|
161
|
+
}
|
|
162
|
+
// ── sortBy ────────────────────────────────────────────────────────────────
|
|
163
|
+
// qs parses ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC into:
|
|
164
|
+
// req.query.sortBy = [{ name: 'orderNo', order: 'ASC' }]
|
|
165
|
+
// Entries with a missing or empty name are silently dropped.
|
|
166
|
+
// order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
167
|
+
// unrecognised value — this is structural normalisation, not type coercion.
|
|
168
|
+
if (Array.isArray(query.sortBy)) {
|
|
169
|
+
const sortBy = query.sortBy
|
|
170
|
+
.filter((item) => item && typeof item === 'object' && item.name)
|
|
171
|
+
.map((item) => ({
|
|
172
|
+
name: String(item.name),
|
|
173
|
+
order: String(item.order ?? 'ASC').toUpperCase() === 'DESC' ? 'DESC' : 'ASC',
|
|
174
|
+
}));
|
|
175
|
+
if (sortBy.length > 0) {
|
|
176
|
+
params.sortBy = sortBy;
|
|
87
177
|
}
|
|
88
178
|
}
|
|
89
179
|
return params;
|
|
@@ -98,6 +188,16 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
98
188
|
return core;
|
|
99
189
|
}
|
|
100
190
|
// ─── Route registration ─────────────────────────────────────────────────────
|
|
191
|
+
/**
|
|
192
|
+
* Registers all enabled routes on the Express app under `root`.
|
|
193
|
+
* Called once at startup by app.ts:
|
|
194
|
+
*
|
|
195
|
+
* controller.init({ app, root: controller.root })
|
|
196
|
+
*
|
|
197
|
+
* Routes are only registered for operations that are not disabled.
|
|
198
|
+
* /many routes are registered before /:id to avoid Express matching
|
|
199
|
+
* "many" as an id param.
|
|
200
|
+
*/
|
|
101
201
|
init(props) {
|
|
102
202
|
const { app, root } = props || {};
|
|
103
203
|
if (!app || !root) {
|
|
@@ -106,22 +206,24 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
106
206
|
if (!this.disableList) {
|
|
107
207
|
app.get(root, this.json(this.list.bind(this)));
|
|
108
208
|
}
|
|
109
|
-
//
|
|
110
|
-
|
|
111
|
-
|
|
209
|
+
// /many must be registered before /:id so Express does not treat the
|
|
210
|
+
// literal string "many" as an id param value.
|
|
211
|
+
if (!this.disableCreateMany) {
|
|
212
|
+
app.post(`${root}/many`, this.json(this.createMany.bind(this)));
|
|
213
|
+
}
|
|
214
|
+
if (!this.disableUpdateMany) {
|
|
215
|
+
app.put(`${root}/many`, this.json(this.updateMany.bind(this)));
|
|
112
216
|
}
|
|
113
217
|
if (!this.disableCreate) {
|
|
114
218
|
app.post(root, this.json(this.create.bind(this)));
|
|
115
219
|
}
|
|
116
|
-
|
|
117
|
-
|
|
220
|
+
// GET /:id — branches to get() or getMany() based on comma presence
|
|
221
|
+
if (!this.disableGet || !this.disableGetMany) {
|
|
222
|
+
app.get(`${root}/:id`, this.json(this.getOrGetMany.bind(this)));
|
|
118
223
|
}
|
|
119
224
|
if (!this.disableUpdate) {
|
|
120
225
|
app.put(`${root}/:id`, this.json(this.update.bind(this)));
|
|
121
226
|
}
|
|
122
|
-
if (!this.disableUpdateMany) {
|
|
123
|
-
app.put(`${root}/many`, this.json(this.updateMany.bind(this)));
|
|
124
|
-
}
|
|
125
227
|
// DELETE /:id — branches to remove() or removeMany() based on comma presence
|
|
126
228
|
if (!this.disableRemove || !this.disableRemoveMany) {
|
|
127
229
|
app.delete(`${root}/:id`, this.json(this.removeOrRemoveMany.bind(this)));
|
|
@@ -130,8 +232,10 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
130
232
|
// ─── Route handlers ─────────────────────────────────────────────────────────
|
|
131
233
|
/**
|
|
132
234
|
* GET /
|
|
133
|
-
*
|
|
134
|
-
*
|
|
235
|
+
*
|
|
236
|
+
* Splits the query string into filter (non-pagination keys) and params
|
|
237
|
+
* (PaginationAndSorting shape) via buildFilter() and buildParams().
|
|
238
|
+
* Shape matches the GraphQL list resolver: core.list({ filter, params }).
|
|
135
239
|
*/
|
|
136
240
|
async list(req) {
|
|
137
241
|
const core = await this.resolveCore(req);
|
|
@@ -142,8 +246,9 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
142
246
|
}
|
|
143
247
|
/**
|
|
144
248
|
* GET /:id
|
|
145
|
-
*
|
|
146
|
-
*
|
|
249
|
+
*
|
|
250
|
+
* Routes to core.get({ id }) for a single id, or core.getMany({ ids })
|
|
251
|
+
* when the :id param contains comma-separated values.
|
|
147
252
|
*/
|
|
148
253
|
async getOrGetMany(req) {
|
|
149
254
|
const core = await this.resolveCore(req);
|
|
@@ -161,49 +266,59 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
|
|
|
161
266
|
}
|
|
162
267
|
/**
|
|
163
268
|
* POST /
|
|
164
|
-
*
|
|
269
|
+
*
|
|
270
|
+
* Body must be { params: {...} }.
|
|
271
|
+
* Consistent with GraphQL mutation: partyTicketTypeCreate(params: Input).
|
|
165
272
|
*/
|
|
166
273
|
async create(req) {
|
|
167
274
|
const core = await this.resolveCore(req);
|
|
168
|
-
return core.create({ params: req.body
|
|
275
|
+
return core.create({ params: req.body?.params });
|
|
169
276
|
}
|
|
170
277
|
/**
|
|
171
278
|
* POST /many
|
|
172
|
-
*
|
|
279
|
+
*
|
|
280
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
281
|
+
* item which is auto-wrapped in an array.
|
|
173
282
|
*/
|
|
174
283
|
async createMany(req) {
|
|
175
284
|
const core = await this.resolveCore(req);
|
|
176
|
-
const items = Array.isArray(req.body
|
|
285
|
+
const items = Array.isArray(req.body?.params) ? req.body.params : [req.body?.params];
|
|
177
286
|
return core.createMany({ params: items });
|
|
178
287
|
}
|
|
179
288
|
/**
|
|
180
289
|
* PUT /:id
|
|
181
|
-
*
|
|
182
|
-
*
|
|
183
|
-
*
|
|
290
|
+
*
|
|
291
|
+
* Body must be { params: {...} }. The :id route param is parsed into an
|
|
292
|
+
* array and passed to buildWhere() — override buildWhere() to add extra
|
|
293
|
+
* conditions beyond id while keeping the /:id URL pattern.
|
|
294
|
+
*
|
|
295
|
+
* Shape: core.update({ where: { id: [id] }, params: {...} })
|
|
184
296
|
*/
|
|
185
297
|
async update(req) {
|
|
186
298
|
const core = await this.resolveCore(req);
|
|
187
299
|
const [, ids] = (0, parseIds_1.parseIds)(req.params.id);
|
|
188
300
|
return core.update({
|
|
189
301
|
where: this.buildWhere(req, ids),
|
|
190
|
-
params: req.body
|
|
302
|
+
params: req.body?.params,
|
|
191
303
|
});
|
|
192
304
|
}
|
|
193
305
|
/**
|
|
194
306
|
* PUT /many
|
|
195
|
-
*
|
|
307
|
+
*
|
|
308
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
309
|
+
* item which is auto-wrapped in an array.
|
|
196
310
|
*/
|
|
197
311
|
async updateMany(req) {
|
|
198
312
|
const core = await this.resolveCore(req);
|
|
199
|
-
const items = Array.isArray(req.body
|
|
313
|
+
const items = Array.isArray(req.body?.params) ? req.body.params : [req.body?.params];
|
|
200
314
|
return core.updateMany({ params: items });
|
|
201
315
|
}
|
|
202
316
|
/**
|
|
203
317
|
* DELETE /:id
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
318
|
+
*
|
|
319
|
+
* Routes to core.remove({ where }) for a single id, or
|
|
320
|
+
* core.removeMany({ where }) for comma-separated ids. where is built via
|
|
321
|
+
* buildWhere() — override to add extra conditions.
|
|
207
322
|
*/
|
|
208
323
|
async removeOrRemoveMany(req) {
|
|
209
324
|
const core = await this.resolveCore(req);
|
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
import { BaseController } from './BaseController';
|
|
2
2
|
import { BaseRestApiCrudControllerPropsInterface } from './interfaces';
|
|
3
|
+
/**
|
|
4
|
+
* BaseRestApiCrudController
|
|
5
|
+
*
|
|
6
|
+
* Provides a standard REST CRUD surface that maps HTTP requests to core
|
|
7
|
+
* method calls using the same argument shapes as GraphQL resolvers. This
|
|
8
|
+
* means a core written for GraphQL works identically over REST with no
|
|
9
|
+
* changes.
|
|
10
|
+
*
|
|
11
|
+
* ── Argument shapes ───────────────────────────────────────────────────────────
|
|
12
|
+
* list → core.list({ filter, params }) params: PaginationAndSorting
|
|
13
|
+
* get → core.get({ id })
|
|
14
|
+
* getMany → core.getMany({ ids })
|
|
15
|
+
* create → core.create({ params }) body: { params: {...} }
|
|
16
|
+
* createMany → core.createMany({ params }) body: { params: [{...}] }
|
|
17
|
+
* update → core.update({ where, params }) body: { params: {...} }
|
|
18
|
+
* updateMany → core.updateMany({ params }) body: { params: [{...}] }
|
|
19
|
+
* remove → core.remove({ where })
|
|
20
|
+
* removeMany → core.removeMany({ where })
|
|
21
|
+
*
|
|
22
|
+
* ── URL conventions ───────────────────────────────────────────────────────────
|
|
23
|
+
* Filter fields go flat in the query string:
|
|
24
|
+
* ?partyId=abc-123&isEnabled=true
|
|
25
|
+
*
|
|
26
|
+
* Pagination and sorting use bracket notation (parsed by qs automatically):
|
|
27
|
+
* ?pagination[page]=1&pagination[pageSize]=20
|
|
28
|
+
* ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
29
|
+
*
|
|
30
|
+
* Combined example:
|
|
31
|
+
* GET /api/v1/party-ticket-types
|
|
32
|
+
* ?partyId=abc-123
|
|
33
|
+
* &isEnabled=true
|
|
34
|
+
* &pagination[page]=1
|
|
35
|
+
* &pagination[pageSize]=20
|
|
36
|
+
* &sortBy[0][name]=orderNo
|
|
37
|
+
* &sortBy[0][order]=ASC
|
|
38
|
+
*
|
|
39
|
+
* ── Extension points ──────────────────────────────────────────────────────────
|
|
40
|
+
* buildWhere(req, ids) — override to add extra where conditions beyond id
|
|
41
|
+
* buildFilter(req) — override to customise filter extraction from QS
|
|
42
|
+
* buildParams(req) — override to customise pagination extraction from QS
|
|
43
|
+
*
|
|
44
|
+
* ── Route registration ────────────────────────────────────────────────────────
|
|
45
|
+
* Each subclass declares its own `root` path (e.g. '/api/v1/party-ticket-types').
|
|
46
|
+
* app.ts calls controller.init({ app, root: controller.root }) so no
|
|
47
|
+
* root needs to be passed at instantiation time.
|
|
48
|
+
*
|
|
49
|
+
* ── Context resolution ────────────────────────────────────────────────────────
|
|
50
|
+
* `getContext` defaults to (req) => req.context, which is set by the
|
|
51
|
+
* createContext middleware in app.ts before any REST handler runs.
|
|
52
|
+
* Override via props only when a controller needs a different context source.
|
|
53
|
+
*/
|
|
3
54
|
declare class BaseRestApiCrudController extends BaseController {
|
|
55
|
+
/** Mount path for this controller, e.g. '/api/v1/party-ticket-types' */
|
|
56
|
+
root: string;
|
|
4
57
|
protected coreToUse: string;
|
|
5
58
|
protected getContext: (req: any) => Promise<any> | any;
|
|
6
59
|
protected disableList: boolean;
|
|
@@ -12,81 +65,115 @@ declare class BaseRestApiCrudController extends BaseController {
|
|
|
12
65
|
protected disableUpdateMany: boolean;
|
|
13
66
|
protected disableRemove: boolean;
|
|
14
67
|
protected disableRemoveMany: boolean;
|
|
15
|
-
constructor(props
|
|
68
|
+
constructor(props?: BaseRestApiCrudControllerPropsInterface);
|
|
16
69
|
/**
|
|
17
70
|
* Builds the `where` object for update and remove operations.
|
|
18
71
|
*
|
|
19
|
-
* Base implementation
|
|
20
|
-
*
|
|
21
|
-
* or query string while keeping the URL pattern intact.
|
|
72
|
+
* Base implementation returns { id: ids } where ids is the array parsed
|
|
73
|
+
* from the `:id` route param (single or comma-separated).
|
|
22
74
|
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
75
|
+
* Override in a subclass to add extra conditions from req.body or
|
|
76
|
+
* req.query while keeping the /:id URL pattern intact. Example:
|
|
77
|
+
*
|
|
78
|
+
* protected buildWhere(req: any, ids: string[]): Record<string, any> {
|
|
79
|
+
* return { id: ids, statusId: req.body?.where?.statusId };
|
|
80
|
+
* }
|
|
25
81
|
*/
|
|
26
82
|
protected buildWhere(req: any, ids: string[]): Record<string, any>;
|
|
27
83
|
/**
|
|
28
|
-
* Builds the `filter` object
|
|
29
|
-
*
|
|
30
|
-
* Base implementation treats every query string key that is NOT in
|
|
31
|
-
* PAGINATION_KEYS as a filter field. Override to apply custom filtering
|
|
32
|
-
* logic or to parse typed values (e.g. booleans, arrays).
|
|
84
|
+
* Builds the `filter` object passed to core.list().
|
|
33
85
|
*
|
|
34
|
-
*
|
|
86
|
+
* Base implementation treats every query string key that is NOT a known
|
|
87
|
+
* pagination key (pagination, sortBy) as a filter field. Override to
|
|
88
|
+
* apply custom parsing (e.g. typed booleans, array values, renamed fields).
|
|
35
89
|
*/
|
|
36
90
|
protected buildFilter(req: any): Record<string, any>;
|
|
37
91
|
/**
|
|
38
|
-
* Builds the `params` object
|
|
92
|
+
* Builds the `params` object passed to core.list().
|
|
93
|
+
*
|
|
94
|
+
* Assembles the PaginationAndSorting shape expected by cores:
|
|
95
|
+
* {
|
|
96
|
+
* pagination: { page: string, pageSize: string },
|
|
97
|
+
* sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
|
|
98
|
+
* }
|
|
99
|
+
*
|
|
100
|
+
* pagination values are passed through as-is (strings from qs) —
|
|
101
|
+
* type coercion is left to the core/gateway layer.
|
|
39
102
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
103
|
+
* sortBy entries with a missing or empty name are silently dropped.
|
|
104
|
+
* order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
105
|
+
* unrecognised value — this is structural normalisation, not type coercion.
|
|
42
106
|
*
|
|
43
|
-
*
|
|
107
|
+
* Override to support additional or renamed pagination conventions.
|
|
44
108
|
*/
|
|
45
109
|
protected buildParams(req: any): Record<string, any>;
|
|
46
110
|
protected resolveCore(req: any): Promise<any>;
|
|
111
|
+
/**
|
|
112
|
+
* Registers all enabled routes on the Express app under `root`.
|
|
113
|
+
* Called once at startup by app.ts:
|
|
114
|
+
*
|
|
115
|
+
* controller.init({ app, root: controller.root })
|
|
116
|
+
*
|
|
117
|
+
* Routes are only registered for operations that are not disabled.
|
|
118
|
+
* /many routes are registered before /:id to avoid Express matching
|
|
119
|
+
* "many" as an id param.
|
|
120
|
+
*/
|
|
47
121
|
init(props: {
|
|
48
122
|
app: any;
|
|
49
123
|
root: string;
|
|
50
124
|
}): void;
|
|
51
125
|
/**
|
|
52
126
|
* GET /
|
|
53
|
-
*
|
|
54
|
-
*
|
|
127
|
+
*
|
|
128
|
+
* Splits the query string into filter (non-pagination keys) and params
|
|
129
|
+
* (PaginationAndSorting shape) via buildFilter() and buildParams().
|
|
130
|
+
* Shape matches the GraphQL list resolver: core.list({ filter, params }).
|
|
55
131
|
*/
|
|
56
132
|
protected list(req: any): Promise<any>;
|
|
57
133
|
/**
|
|
58
134
|
* GET /:id
|
|
59
|
-
*
|
|
60
|
-
*
|
|
135
|
+
*
|
|
136
|
+
* Routes to core.get({ id }) for a single id, or core.getMany({ ids })
|
|
137
|
+
* when the :id param contains comma-separated values.
|
|
61
138
|
*/
|
|
62
139
|
protected getOrGetMany(req: any): Promise<any>;
|
|
63
140
|
/**
|
|
64
141
|
* POST /
|
|
65
|
-
*
|
|
142
|
+
*
|
|
143
|
+
* Body must be { params: {...} }.
|
|
144
|
+
* Consistent with GraphQL mutation: partyTicketTypeCreate(params: Input).
|
|
66
145
|
*/
|
|
67
146
|
protected create(req: any): Promise<any>;
|
|
68
147
|
/**
|
|
69
148
|
* POST /many
|
|
70
|
-
*
|
|
149
|
+
*
|
|
150
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
151
|
+
* item which is auto-wrapped in an array.
|
|
71
152
|
*/
|
|
72
153
|
protected createMany(req: any): Promise<any>;
|
|
73
154
|
/**
|
|
74
155
|
* PUT /:id
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
156
|
+
*
|
|
157
|
+
* Body must be { params: {...} }. The :id route param is parsed into an
|
|
158
|
+
* array and passed to buildWhere() — override buildWhere() to add extra
|
|
159
|
+
* conditions beyond id while keeping the /:id URL pattern.
|
|
160
|
+
*
|
|
161
|
+
* Shape: core.update({ where: { id: [id] }, params: {...} })
|
|
78
162
|
*/
|
|
79
163
|
protected update(req: any): Promise<any>;
|
|
80
164
|
/**
|
|
81
165
|
* PUT /many
|
|
82
|
-
*
|
|
166
|
+
*
|
|
167
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
168
|
+
* item which is auto-wrapped in an array.
|
|
83
169
|
*/
|
|
84
170
|
protected updateMany(req: any): Promise<any>;
|
|
85
171
|
/**
|
|
86
172
|
* DELETE /:id
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
173
|
+
*
|
|
174
|
+
* Routes to core.remove({ where }) for a single id, or
|
|
175
|
+
* core.removeMany({ where }) for comma-separated ids. where is built via
|
|
176
|
+
* buildWhere() — override to add extra conditions.
|
|
90
177
|
*/
|
|
91
178
|
protected removeOrRemoveMany(req: any): Promise<any>;
|
|
92
179
|
}
|
|
@@ -2,11 +2,69 @@
|
|
|
2
2
|
import { BaseController } from './BaseController';
|
|
3
3
|
import { parseIds } from './parseIds';
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
5
|
+
* Query string keys that belong to `params` (PaginationAndSorting shape).
|
|
6
6
|
* Everything else in the query string is treated as a filter field.
|
|
7
|
+
*
|
|
8
|
+
* qs (used by Express) parses bracket notation automatically, so:
|
|
9
|
+
* ?pagination[page]=1&pagination[pageSize]=20&sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
10
|
+
* arrives in req.query as:
|
|
11
|
+
* { pagination: { page: '1', pageSize: '20' }, sortBy: [{ name: 'orderNo', order: 'ASC' }] }
|
|
12
|
+
*/
|
|
13
|
+
const PAGINATION_KEYS = new Set(['pagination', 'sortBy']);
|
|
14
|
+
/**
|
|
15
|
+
* BaseRestApiCrudController
|
|
16
|
+
*
|
|
17
|
+
* Provides a standard REST CRUD surface that maps HTTP requests to core
|
|
18
|
+
* method calls using the same argument shapes as GraphQL resolvers. This
|
|
19
|
+
* means a core written for GraphQL works identically over REST with no
|
|
20
|
+
* changes.
|
|
21
|
+
*
|
|
22
|
+
* ── Argument shapes ───────────────────────────────────────────────────────────
|
|
23
|
+
* list → core.list({ filter, params }) params: PaginationAndSorting
|
|
24
|
+
* get → core.get({ id })
|
|
25
|
+
* getMany → core.getMany({ ids })
|
|
26
|
+
* create → core.create({ params }) body: { params: {...} }
|
|
27
|
+
* createMany → core.createMany({ params }) body: { params: [{...}] }
|
|
28
|
+
* update → core.update({ where, params }) body: { params: {...} }
|
|
29
|
+
* updateMany → core.updateMany({ params }) body: { params: [{...}] }
|
|
30
|
+
* remove → core.remove({ where })
|
|
31
|
+
* removeMany → core.removeMany({ where })
|
|
32
|
+
*
|
|
33
|
+
* ── URL conventions ───────────────────────────────────────────────────────────
|
|
34
|
+
* Filter fields go flat in the query string:
|
|
35
|
+
* ?partyId=abc-123&isEnabled=true
|
|
36
|
+
*
|
|
37
|
+
* Pagination and sorting use bracket notation (parsed by qs automatically):
|
|
38
|
+
* ?pagination[page]=1&pagination[pageSize]=20
|
|
39
|
+
* ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC
|
|
40
|
+
*
|
|
41
|
+
* Combined example:
|
|
42
|
+
* GET /api/v1/party-ticket-types
|
|
43
|
+
* ?partyId=abc-123
|
|
44
|
+
* &isEnabled=true
|
|
45
|
+
* &pagination[page]=1
|
|
46
|
+
* &pagination[pageSize]=20
|
|
47
|
+
* &sortBy[0][name]=orderNo
|
|
48
|
+
* &sortBy[0][order]=ASC
|
|
49
|
+
*
|
|
50
|
+
* ── Extension points ──────────────────────────────────────────────────────────
|
|
51
|
+
* buildWhere(req, ids) — override to add extra where conditions beyond id
|
|
52
|
+
* buildFilter(req) — override to customise filter extraction from QS
|
|
53
|
+
* buildParams(req) — override to customise pagination extraction from QS
|
|
54
|
+
*
|
|
55
|
+
* ── Route registration ────────────────────────────────────────────────────────
|
|
56
|
+
* Each subclass declares its own `root` path (e.g. '/api/v1/party-ticket-types').
|
|
57
|
+
* app.ts calls controller.init({ app, root: controller.root }) so no
|
|
58
|
+
* root needs to be passed at instantiation time.
|
|
59
|
+
*
|
|
60
|
+
* ── Context resolution ────────────────────────────────────────────────────────
|
|
61
|
+
* `getContext` defaults to (req) => req.context, which is set by the
|
|
62
|
+
* createContext middleware in app.ts before any REST handler runs.
|
|
63
|
+
* Override via props only when a controller needs a different context source.
|
|
7
64
|
*/
|
|
8
|
-
const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
|
|
9
65
|
class BaseRestApiCrudController extends BaseController {
|
|
66
|
+
/** Mount path for this controller, e.g. '/api/v1/party-ticket-types' */
|
|
67
|
+
root;
|
|
10
68
|
coreToUse;
|
|
11
69
|
getContext;
|
|
12
70
|
disableList;
|
|
@@ -19,45 +77,47 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
19
77
|
disableRemove;
|
|
20
78
|
disableRemoveMany;
|
|
21
79
|
constructor(props) {
|
|
22
|
-
super(props);
|
|
23
|
-
const { prefix, core, getContext } = props || {};
|
|
24
|
-
|
|
25
|
-
throw new Error('BaseRestApiCrudController: `getContext` is required');
|
|
26
|
-
}
|
|
80
|
+
super(props ?? {});
|
|
81
|
+
const { prefix, core, getContext, root } = props || {};
|
|
82
|
+
this.root = root ?? '';
|
|
27
83
|
this.coreToUse = core || `${prefix}Core`;
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
this.
|
|
32
|
-
this.
|
|
33
|
-
this.
|
|
34
|
-
this.
|
|
35
|
-
this.
|
|
36
|
-
this.
|
|
37
|
-
this.
|
|
84
|
+
// Default: read the context that createContext middleware attached to req.
|
|
85
|
+
// Pass an explicit getContext in props only when a controller needs to
|
|
86
|
+
// resolve the context differently.
|
|
87
|
+
this.getContext = getContext ?? ((req) => req.context);
|
|
88
|
+
this.disableList = props?.disableList ?? false;
|
|
89
|
+
this.disableGet = props?.disableGet ?? false;
|
|
90
|
+
this.disableGetMany = props?.disableGetMany ?? false;
|
|
91
|
+
this.disableCreate = props?.disableCreate ?? false;
|
|
92
|
+
this.disableCreateMany = props?.disableCreateMany ?? false;
|
|
93
|
+
this.disableUpdate = props?.disableUpdate ?? false;
|
|
94
|
+
this.disableUpdateMany = props?.disableUpdateMany ?? false;
|
|
95
|
+
this.disableRemove = props?.disableRemove ?? false;
|
|
96
|
+
this.disableRemoveMany = props?.disableRemoveMany ?? false;
|
|
38
97
|
}
|
|
39
98
|
// ─── Extension points ───────────────────────────────────────────────────────
|
|
40
99
|
/**
|
|
41
100
|
* Builds the `where` object for update and remove operations.
|
|
42
101
|
*
|
|
43
|
-
* Base implementation
|
|
44
|
-
*
|
|
45
|
-
* or query string while keeping the URL pattern intact.
|
|
102
|
+
* Base implementation returns { id: ids } where ids is the array parsed
|
|
103
|
+
* from the `:id` route param (single or comma-separated).
|
|
46
104
|
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
105
|
+
* Override in a subclass to add extra conditions from req.body or
|
|
106
|
+
* req.query while keeping the /:id URL pattern intact. Example:
|
|
107
|
+
*
|
|
108
|
+
* protected buildWhere(req: any, ids: string[]): Record<string, any> {
|
|
109
|
+
* return { id: ids, statusId: req.body?.where?.statusId };
|
|
110
|
+
* }
|
|
49
111
|
*/
|
|
50
112
|
buildWhere(req, ids) {
|
|
51
113
|
return { id: ids };
|
|
52
114
|
}
|
|
53
115
|
/**
|
|
54
|
-
* Builds the `filter` object
|
|
55
|
-
*
|
|
56
|
-
* Base implementation treats every query string key that is NOT in
|
|
57
|
-
* PAGINATION_KEYS as a filter field. Override to apply custom filtering
|
|
58
|
-
* logic or to parse typed values (e.g. booleans, arrays).
|
|
116
|
+
* Builds the `filter` object passed to core.list().
|
|
59
117
|
*
|
|
60
|
-
*
|
|
118
|
+
* Base implementation treats every query string key that is NOT a known
|
|
119
|
+
* pagination key (pagination, sortBy) as a filter field. Override to
|
|
120
|
+
* apply custom parsing (e.g. typed booleans, array values, renamed fields).
|
|
61
121
|
*/
|
|
62
122
|
buildFilter(req) {
|
|
63
123
|
const filter = {};
|
|
@@ -69,18 +129,48 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
69
129
|
return filter;
|
|
70
130
|
}
|
|
71
131
|
/**
|
|
72
|
-
* Builds the `params` object
|
|
132
|
+
* Builds the `params` object passed to core.list().
|
|
73
133
|
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
134
|
+
* Assembles the PaginationAndSorting shape expected by cores:
|
|
135
|
+
* {
|
|
136
|
+
* pagination: { page: string, pageSize: string },
|
|
137
|
+
* sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
|
|
138
|
+
* }
|
|
76
139
|
*
|
|
77
|
-
*
|
|
140
|
+
* pagination values are passed through as-is (strings from qs) —
|
|
141
|
+
* type coercion is left to the core/gateway layer.
|
|
142
|
+
*
|
|
143
|
+
* sortBy entries with a missing or empty name are silently dropped.
|
|
144
|
+
* order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
145
|
+
* unrecognised value — this is structural normalisation, not type coercion.
|
|
146
|
+
*
|
|
147
|
+
* Override to support additional or renamed pagination conventions.
|
|
78
148
|
*/
|
|
79
149
|
buildParams(req) {
|
|
150
|
+
const query = req.query ?? {};
|
|
80
151
|
const params = {};
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
152
|
+
// ── pagination ────────────────────────────────────────────────────────────
|
|
153
|
+
// qs parses ?pagination[page]=1&pagination[pageSize]=20 into:
|
|
154
|
+
// req.query.pagination = { page: '1', pageSize: '20' }
|
|
155
|
+
// Values are passed through as-is — coercion is left to the core/gateway.
|
|
156
|
+
if (query.pagination && typeof query.pagination === 'object') {
|
|
157
|
+
params.pagination = query.pagination;
|
|
158
|
+
}
|
|
159
|
+
// ── sortBy ────────────────────────────────────────────────────────────────
|
|
160
|
+
// qs parses ?sortBy[0][name]=orderNo&sortBy[0][order]=ASC into:
|
|
161
|
+
// req.query.sortBy = [{ name: 'orderNo', order: 'ASC' }]
|
|
162
|
+
// Entries with a missing or empty name are silently dropped.
|
|
163
|
+
// order is normalised to 'ASC' or 'DESC', defaulting to 'ASC' for any
|
|
164
|
+
// unrecognised value — this is structural normalisation, not type coercion.
|
|
165
|
+
if (Array.isArray(query.sortBy)) {
|
|
166
|
+
const sortBy = query.sortBy
|
|
167
|
+
.filter((item) => item && typeof item === 'object' && item.name)
|
|
168
|
+
.map((item) => ({
|
|
169
|
+
name: String(item.name),
|
|
170
|
+
order: String(item.order ?? 'ASC').toUpperCase() === 'DESC' ? 'DESC' : 'ASC',
|
|
171
|
+
}));
|
|
172
|
+
if (sortBy.length > 0) {
|
|
173
|
+
params.sortBy = sortBy;
|
|
84
174
|
}
|
|
85
175
|
}
|
|
86
176
|
return params;
|
|
@@ -95,6 +185,16 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
95
185
|
return core;
|
|
96
186
|
}
|
|
97
187
|
// ─── Route registration ─────────────────────────────────────────────────────
|
|
188
|
+
/**
|
|
189
|
+
* Registers all enabled routes on the Express app under `root`.
|
|
190
|
+
* Called once at startup by app.ts:
|
|
191
|
+
*
|
|
192
|
+
* controller.init({ app, root: controller.root })
|
|
193
|
+
*
|
|
194
|
+
* Routes are only registered for operations that are not disabled.
|
|
195
|
+
* /many routes are registered before /:id to avoid Express matching
|
|
196
|
+
* "many" as an id param.
|
|
197
|
+
*/
|
|
98
198
|
init(props) {
|
|
99
199
|
const { app, root } = props || {};
|
|
100
200
|
if (!app || !root) {
|
|
@@ -103,22 +203,24 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
103
203
|
if (!this.disableList) {
|
|
104
204
|
app.get(root, this.json(this.list.bind(this)));
|
|
105
205
|
}
|
|
106
|
-
//
|
|
107
|
-
|
|
108
|
-
|
|
206
|
+
// /many must be registered before /:id so Express does not treat the
|
|
207
|
+
// literal string "many" as an id param value.
|
|
208
|
+
if (!this.disableCreateMany) {
|
|
209
|
+
app.post(`${root}/many`, this.json(this.createMany.bind(this)));
|
|
210
|
+
}
|
|
211
|
+
if (!this.disableUpdateMany) {
|
|
212
|
+
app.put(`${root}/many`, this.json(this.updateMany.bind(this)));
|
|
109
213
|
}
|
|
110
214
|
if (!this.disableCreate) {
|
|
111
215
|
app.post(root, this.json(this.create.bind(this)));
|
|
112
216
|
}
|
|
113
|
-
|
|
114
|
-
|
|
217
|
+
// GET /:id — branches to get() or getMany() based on comma presence
|
|
218
|
+
if (!this.disableGet || !this.disableGetMany) {
|
|
219
|
+
app.get(`${root}/:id`, this.json(this.getOrGetMany.bind(this)));
|
|
115
220
|
}
|
|
116
221
|
if (!this.disableUpdate) {
|
|
117
222
|
app.put(`${root}/:id`, this.json(this.update.bind(this)));
|
|
118
223
|
}
|
|
119
|
-
if (!this.disableUpdateMany) {
|
|
120
|
-
app.put(`${root}/many`, this.json(this.updateMany.bind(this)));
|
|
121
|
-
}
|
|
122
224
|
// DELETE /:id — branches to remove() or removeMany() based on comma presence
|
|
123
225
|
if (!this.disableRemove || !this.disableRemoveMany) {
|
|
124
226
|
app.delete(`${root}/:id`, this.json(this.removeOrRemoveMany.bind(this)));
|
|
@@ -127,8 +229,10 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
127
229
|
// ─── Route handlers ─────────────────────────────────────────────────────────
|
|
128
230
|
/**
|
|
129
231
|
* GET /
|
|
130
|
-
*
|
|
131
|
-
*
|
|
232
|
+
*
|
|
233
|
+
* Splits the query string into filter (non-pagination keys) and params
|
|
234
|
+
* (PaginationAndSorting shape) via buildFilter() and buildParams().
|
|
235
|
+
* Shape matches the GraphQL list resolver: core.list({ filter, params }).
|
|
132
236
|
*/
|
|
133
237
|
async list(req) {
|
|
134
238
|
const core = await this.resolveCore(req);
|
|
@@ -139,8 +243,9 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
139
243
|
}
|
|
140
244
|
/**
|
|
141
245
|
* GET /:id
|
|
142
|
-
*
|
|
143
|
-
*
|
|
246
|
+
*
|
|
247
|
+
* Routes to core.get({ id }) for a single id, or core.getMany({ ids })
|
|
248
|
+
* when the :id param contains comma-separated values.
|
|
144
249
|
*/
|
|
145
250
|
async getOrGetMany(req) {
|
|
146
251
|
const core = await this.resolveCore(req);
|
|
@@ -158,49 +263,59 @@ class BaseRestApiCrudController extends BaseController {
|
|
|
158
263
|
}
|
|
159
264
|
/**
|
|
160
265
|
* POST /
|
|
161
|
-
*
|
|
266
|
+
*
|
|
267
|
+
* Body must be { params: {...} }.
|
|
268
|
+
* Consistent with GraphQL mutation: partyTicketTypeCreate(params: Input).
|
|
162
269
|
*/
|
|
163
270
|
async create(req) {
|
|
164
271
|
const core = await this.resolveCore(req);
|
|
165
|
-
return core.create({ params: req.body
|
|
272
|
+
return core.create({ params: req.body?.params });
|
|
166
273
|
}
|
|
167
274
|
/**
|
|
168
275
|
* POST /many
|
|
169
|
-
*
|
|
276
|
+
*
|
|
277
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
278
|
+
* item which is auto-wrapped in an array.
|
|
170
279
|
*/
|
|
171
280
|
async createMany(req) {
|
|
172
281
|
const core = await this.resolveCore(req);
|
|
173
|
-
const items = Array.isArray(req.body
|
|
282
|
+
const items = Array.isArray(req.body?.params) ? req.body.params : [req.body?.params];
|
|
174
283
|
return core.createMany({ params: items });
|
|
175
284
|
}
|
|
176
285
|
/**
|
|
177
286
|
* PUT /:id
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
287
|
+
*
|
|
288
|
+
* Body must be { params: {...} }. The :id route param is parsed into an
|
|
289
|
+
* array and passed to buildWhere() — override buildWhere() to add extra
|
|
290
|
+
* conditions beyond id while keeping the /:id URL pattern.
|
|
291
|
+
*
|
|
292
|
+
* Shape: core.update({ where: { id: [id] }, params: {...} })
|
|
181
293
|
*/
|
|
182
294
|
async update(req) {
|
|
183
295
|
const core = await this.resolveCore(req);
|
|
184
296
|
const [, ids] = parseIds(req.params.id);
|
|
185
297
|
return core.update({
|
|
186
298
|
where: this.buildWhere(req, ids),
|
|
187
|
-
params: req.body
|
|
299
|
+
params: req.body?.params,
|
|
188
300
|
});
|
|
189
301
|
}
|
|
190
302
|
/**
|
|
191
303
|
* PUT /many
|
|
192
|
-
*
|
|
304
|
+
*
|
|
305
|
+
* Body must be { params: [{...}, ...] } or { params: {...} } for a single
|
|
306
|
+
* item which is auto-wrapped in an array.
|
|
193
307
|
*/
|
|
194
308
|
async updateMany(req) {
|
|
195
309
|
const core = await this.resolveCore(req);
|
|
196
|
-
const items = Array.isArray(req.body
|
|
310
|
+
const items = Array.isArray(req.body?.params) ? req.body.params : [req.body?.params];
|
|
197
311
|
return core.updateMany({ params: items });
|
|
198
312
|
}
|
|
199
313
|
/**
|
|
200
314
|
* DELETE /:id
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
315
|
+
*
|
|
316
|
+
* Routes to core.remove({ where }) for a single id, or
|
|
317
|
+
* core.removeMany({ where }) for comma-separated ids. where is built via
|
|
318
|
+
* buildWhere() — override to add extra conditions.
|
|
204
319
|
*/
|
|
205
320
|
async removeOrRemoveMany(req) {
|
|
206
321
|
const core = await this.resolveCore(req);
|
|
@@ -1,4 +1,9 @@
|
|
|
1
1
|
export interface BaseRestApiCrudControllerPropsInterface {
|
|
2
|
+
/**
|
|
3
|
+
* Mount path for this controller, e.g. '/api/v1/party-ticket-types'.
|
|
4
|
+
* Registered via controller.init({ app, root: controller.root }) in app.ts.
|
|
5
|
+
*/
|
|
6
|
+
root?: string;
|
|
2
7
|
/**
|
|
3
8
|
* The prefix used to derive the core name, e.g. "user" → "userCore".
|
|
4
9
|
* Ignored if `core` is provided explicitly.
|
|
@@ -11,9 +16,11 @@ export interface BaseRestApiCrudControllerPropsInterface {
|
|
|
11
16
|
core?: string;
|
|
12
17
|
/**
|
|
13
18
|
* Factory that produces the ApiContext for a given request.
|
|
14
|
-
*
|
|
19
|
+
* Defaults to (req) => req.context — which is set by the createContext
|
|
20
|
+
* middleware before any REST handler runs. Override only when a controller
|
|
21
|
+
* needs a different context source.
|
|
15
22
|
*/
|
|
16
|
-
getContext
|
|
23
|
+
getContext?: (req: any) => Promise<any> | any;
|
|
17
24
|
onResponse?: (req: any, res: any, next: any) => Promise<void> | void;
|
|
18
25
|
logger?: any;
|
|
19
26
|
disableList?: boolean;
|
|
@@ -1,4 +1,9 @@
|
|
|
1
1
|
export interface BaseRestApiCrudControllerPropsInterface {
|
|
2
|
+
/**
|
|
3
|
+
* Mount path for this controller, e.g. '/api/v1/party-ticket-types'.
|
|
4
|
+
* Registered via controller.init({ app, root: controller.root }) in app.ts.
|
|
5
|
+
*/
|
|
6
|
+
root?: string;
|
|
2
7
|
/**
|
|
3
8
|
* The prefix used to derive the core name, e.g. "user" → "userCore".
|
|
4
9
|
* Ignored if `core` is provided explicitly.
|
|
@@ -11,9 +16,11 @@ export interface BaseRestApiCrudControllerPropsInterface {
|
|
|
11
16
|
core?: string;
|
|
12
17
|
/**
|
|
13
18
|
* Factory that produces the ApiContext for a given request.
|
|
14
|
-
*
|
|
19
|
+
* Defaults to (req) => req.context — which is set by the createContext
|
|
20
|
+
* middleware before any REST handler runs. Override only when a controller
|
|
21
|
+
* needs a different context source.
|
|
15
22
|
*/
|
|
16
|
-
getContext
|
|
23
|
+
getContext?: (req: any) => Promise<any> | any;
|
|
17
24
|
onResponse?: (req: any, res: any, next: any) => Promise<void> | void;
|
|
18
25
|
logger?: any;
|
|
19
26
|
disableList?: boolean;
|