@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.
@@ -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: BaseRestApiCrudControllerPropsInterface);
68
+ constructor(props?: BaseRestApiCrudControllerPropsInterface);
16
69
  /**
17
70
  * Builds the `where` object for update and remove operations.
18
71
  *
19
- * Base implementation uses the ids parsed from the `:id` route param.
20
- * Override in a subclass to add extra conditions from the request body
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
- * @param req - the Express request
24
- * @param ids - ids parsed from req.params.id (always an array)
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 for list operations.
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
- * @param req - the Express request
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 for list operations (pagination / sorting).
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
- * Base implementation picks only the known PAGINATION_KEYS from the query
41
- * string. Override to support additional pagination conventions.
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
- * @param req - the Express request
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
- * Splits the query string into filter and pagination params, consistent
54
- * with the GraphQL list resolver argument shape.
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
- * Routes to core.get() for a single id, or core.getMany() when the :id
60
- * param contains commas. Argument shape matches GraphQL resolver args.
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
- * Body must be { params: {...} } — consistent with GraphQL mutation args.
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
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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
- * Body must be { params: {...} }. The :id route param is parsed and merged
76
- * into the where object via buildWhere() — override buildWhere() to add
77
- * extra conditions while keeping the URL pattern.
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
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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
- * Routes to core.remove() for a single id, or core.removeMany() when the
88
- * :id param contains commas. where is built via buildWhere() — override
89
- * to add extra conditions while keeping the URL pattern.
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
- * Pagination / sorting keys that are always routed to `params` in list().
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
- if (!getContext) {
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
- this.getContext = getContext;
32
- this.disableList = props.disableList ?? false;
33
- this.disableGet = props.disableGet ?? false;
34
- this.disableGetMany = props.disableGetMany ?? false;
35
- this.disableCreate = props.disableCreate ?? false;
36
- this.disableCreateMany = props.disableCreateMany ?? false;
37
- this.disableUpdate = props.disableUpdate ?? false;
38
- this.disableUpdateMany = props.disableUpdateMany ?? false;
39
- this.disableRemove = props.disableRemove ?? false;
40
- this.disableRemoveMany = props.disableRemoveMany ?? false;
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 uses the ids parsed from the `:id` route param.
47
- * Override in a subclass to add extra conditions from the request body
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
- * @param req - the Express request
51
- * @param ids - ids parsed from req.params.id (always an array)
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 for list operations.
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
- * @param req - the Express request
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 for list operations (pagination / sorting).
135
+ * Builds the `params` object passed to core.list().
76
136
  *
77
- * Base implementation picks only the known PAGINATION_KEYS from the query
78
- * string. Override to support additional pagination conventions.
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
- * @param req - the Express request
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
- for (const [key, value] of Object.entries(req.query ?? {})) {
85
- if (PAGINATION_KEYS.has(key)) {
86
- params[key] = value;
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
- // GET /:id — branches to get() or getMany() based on comma presence
110
- if (!this.disableGet || !this.disableGetMany) {
111
- app.get(`${root}/:id`, this.json(this.getOrGetMany.bind(this)));
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
- if (!this.disableCreateMany) {
117
- app.post(`${root}/many`, this.json(this.createMany.bind(this)));
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
- * Splits the query string into filter and pagination params, consistent
134
- * with the GraphQL list resolver argument shape.
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
- * Routes to core.get() for a single id, or core.getMany() when the :id
146
- * param contains commas. Argument shape matches GraphQL resolver args.
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
- * Body must be { params: {...} } — consistent with GraphQL mutation args.
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.params });
275
+ return core.create({ params: req.body?.params });
169
276
  }
170
277
  /**
171
278
  * POST /many
172
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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.params) ? req.body.params : [req.body.params];
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
- * Body must be { params: {...} }. The :id route param is parsed and merged
182
- * into the where object via buildWhere() — override buildWhere() to add
183
- * extra conditions while keeping the URL pattern.
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.params,
302
+ params: req.body?.params,
191
303
  });
192
304
  }
193
305
  /**
194
306
  * PUT /many
195
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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.params) ? req.body.params : [req.body.params];
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
- * Routes to core.remove() for a single id, or core.removeMany() when the
205
- * :id param contains commas. where is built via buildWhere() — override
206
- * to add extra conditions while keeping the URL pattern.
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: BaseRestApiCrudControllerPropsInterface);
68
+ constructor(props?: BaseRestApiCrudControllerPropsInterface);
16
69
  /**
17
70
  * Builds the `where` object for update and remove operations.
18
71
  *
19
- * Base implementation uses the ids parsed from the `:id` route param.
20
- * Override in a subclass to add extra conditions from the request body
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
- * @param req - the Express request
24
- * @param ids - ids parsed from req.params.id (always an array)
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 for list operations.
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
- * @param req - the Express request
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 for list operations (pagination / sorting).
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
- * Base implementation picks only the known PAGINATION_KEYS from the query
41
- * string. Override to support additional pagination conventions.
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
- * @param req - the Express request
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
- * Splits the query string into filter and pagination params, consistent
54
- * with the GraphQL list resolver argument shape.
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
- * Routes to core.get() for a single id, or core.getMany() when the :id
60
- * param contains commas. Argument shape matches GraphQL resolver args.
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
- * Body must be { params: {...} } — consistent with GraphQL mutation args.
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
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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
- * Body must be { params: {...} }. The :id route param is parsed and merged
76
- * into the where object via buildWhere() — override buildWhere() to add
77
- * extra conditions while keeping the URL pattern.
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
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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
- * Routes to core.remove() for a single id, or core.removeMany() when the
88
- * :id param contains commas. where is built via buildWhere() — override
89
- * to add extra conditions while keeping the URL pattern.
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
- * Pagination / sorting keys that are always routed to `params` in list().
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
- if (!getContext) {
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
- this.getContext = getContext;
29
- this.disableList = props.disableList ?? false;
30
- this.disableGet = props.disableGet ?? false;
31
- this.disableGetMany = props.disableGetMany ?? false;
32
- this.disableCreate = props.disableCreate ?? false;
33
- this.disableCreateMany = props.disableCreateMany ?? false;
34
- this.disableUpdate = props.disableUpdate ?? false;
35
- this.disableUpdateMany = props.disableUpdateMany ?? false;
36
- this.disableRemove = props.disableRemove ?? false;
37
- this.disableRemoveMany = props.disableRemoveMany ?? false;
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 uses the ids parsed from the `:id` route param.
44
- * Override in a subclass to add extra conditions from the request body
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
- * @param req - the Express request
48
- * @param ids - ids parsed from req.params.id (always an array)
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 for list operations.
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
- * @param req - the Express request
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 for list operations (pagination / sorting).
132
+ * Builds the `params` object passed to core.list().
73
133
  *
74
- * Base implementation picks only the known PAGINATION_KEYS from the query
75
- * string. Override to support additional pagination conventions.
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
- * @param req - the Express request
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
- for (const [key, value] of Object.entries(req.query ?? {})) {
82
- if (PAGINATION_KEYS.has(key)) {
83
- params[key] = value;
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
- // GET /:id — branches to get() or getMany() based on comma presence
107
- if (!this.disableGet || !this.disableGetMany) {
108
- app.get(`${root}/:id`, this.json(this.getOrGetMany.bind(this)));
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
- if (!this.disableCreateMany) {
114
- app.post(`${root}/many`, this.json(this.createMany.bind(this)));
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
- * Splits the query string into filter and pagination params, consistent
131
- * with the GraphQL list resolver argument shape.
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
- * Routes to core.get() for a single id, or core.getMany() when the :id
143
- * param contains commas. Argument shape matches GraphQL resolver args.
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
- * Body must be { params: {...} } — consistent with GraphQL mutation args.
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.params });
272
+ return core.create({ params: req.body?.params });
166
273
  }
167
274
  /**
168
275
  * POST /many
169
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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.params) ? req.body.params : [req.body.params];
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
- * Body must be { params: {...} }. The :id route param is parsed and merged
179
- * into the where object via buildWhere() — override buildWhere() to add
180
- * extra conditions while keeping the URL pattern.
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.params,
299
+ params: req.body?.params,
188
300
  });
189
301
  }
190
302
  /**
191
303
  * PUT /many
192
- * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
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.params) ? req.body.params : [req.body.params];
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
- * Routes to core.remove() for a single id, or core.removeMany() when the
202
- * :id param contains commas. where is built via buildWhere() — override
203
- * to add extra conditions while keeping the URL pattern.
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
- * Required — controllers need context to reach cores.
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: (req: any) => Promise<any> | any;
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
- * Required — controllers need context to reach cores.
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: (req: any) => Promise<any> | any;
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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.129",
3
+ "version": "1.0.131",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {