@sdflc/backend-helpers 1.0.127 → 1.0.129

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.
@@ -134,6 +134,16 @@ declare class BaseGateway {
134
134
  * while listing and loading still uses the primary key.
135
135
  */
136
136
  getIdField(): string;
137
+ /**
138
+ * Returns the column name used for the status field.
139
+ * Defaults to FIELDS.STATUS ('Status') for standard tables.
140
+ * Override via config.statusField for legacy tables that use a different
141
+ * column name (e.g. 'Status_ID').
142
+ *
143
+ * All status-related WHERE clauses and update patches use this value,
144
+ * so setting it once in the gateway constructor propagates everywhere.
145
+ */
146
+ getStatusField(): string;
137
147
  /**
138
148
  * Returns the field name used to identify records in UPDATE and DELETE
139
149
  * WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
@@ -462,14 +472,9 @@ declare class BaseGateway {
462
472
  * Builds the patch object applied to a record when it is soft-deleted.
463
473
  * Called by `remove()` when `hardRemove` is false and `hasRemovedAt` is true.
464
474
  *
465
- * Returns a new object (merged from `args`) with removal fields populated.
475
+ * Returns a new object with removal fields populated.
466
476
  * Override in subclasses to add custom soft-delete fields.
467
- * Always call `super.transformOnRemove(args)` first.
468
- *
469
- * The `args` parameter is the original `where` filter passed to `remove()`.
470
- * It is available so subclasses can derive removal values from the filter
471
- * (e.g. storing which id was removed). In the base implementation it is
472
- * spread into the patch object as-is.
477
+ * Always call `super.transformOnRemove()` first.
473
478
  *
474
479
  * Built-in transformations:
475
480
  * - `hasRemovedAt` — sets removedAt to the current time (dayjs, not
@@ -488,7 +493,7 @@ declare class BaseGateway {
488
493
  * (construction time). This is intentional — removal timestamps should be
489
494
  * as accurate as possible and are not batch-grouped like create/update times.
490
495
  */
491
- transformOnRemove(args?: any): Promise<any>;
496
+ transformOnRemove(): Promise<any>;
492
497
  /**
493
498
  * Transforms a record after it is read from the database, before it is
494
499
  * returned to the caller.
@@ -206,6 +206,18 @@ class BaseGateway {
206
206
  getIdField() {
207
207
  return this.config.idField || constants_1.ID_FIELD;
208
208
  }
209
+ /**
210
+ * Returns the column name used for the status field.
211
+ * Defaults to FIELDS.STATUS ('Status') for standard tables.
212
+ * Override via config.statusField for legacy tables that use a different
213
+ * column name (e.g. 'Status_ID').
214
+ *
215
+ * All status-related WHERE clauses and update patches use this value,
216
+ * so setting it once in the gateway constructor propagates everywhere.
217
+ */
218
+ getStatusField() {
219
+ return this.config.statusField ?? constants_1.FIELDS.STATUS;
220
+ }
209
221
  /**
210
222
  * Returns the field name used to identify records in UPDATE and DELETE
211
223
  * WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
@@ -603,7 +615,8 @@ class BaseGateway {
603
615
  async onListFilter(query, filterParams) {
604
616
  const { table, hasStatus, hasRemovedAt, hasSpace, activeStatuses, hasLang, fieldForKeyword, filterByUserField } = this.config || {};
605
617
  if (hasStatus) {
606
- query.whereIn(`${table}.${constants_1.FIELDS.STATUS}`, filterParams?.[constants_1.FIELDS.STATUS] != null ? (0, lodash_1.castArray)(filterParams?.[constants_1.FIELDS.STATUS]) : (0, lodash_1.castArray)(activeStatuses));
618
+ const statusField = this.getStatusField();
619
+ query.whereIn(`${table}.${statusField}`, filterParams?.[statusField] != null ? (0, lodash_1.castArray)(filterParams?.[statusField]) : (0, lodash_1.castArray)(activeStatuses));
607
620
  }
608
621
  if (hasRemovedAt) {
609
622
  query.whereNull(`${table}.${constants_1.FIELDS.REMOVED_AT}`);
@@ -664,12 +677,13 @@ class BaseGateway {
664
677
  }
665
678
  }
666
679
  if (hasStatus) {
680
+ const statusField = this.getStatusField();
667
681
  filtersAppliedQty++;
668
- if (Array.isArray(filterParams?.[constants_1.FIELDS.STATUS])) {
669
- query.whereIn(constants_1.FIELDS.STATUS, filterParams?.[constants_1.FIELDS.STATUS]);
682
+ if (Array.isArray(filterParams?.[statusField])) {
683
+ query.whereIn(statusField, filterParams?.[statusField]);
670
684
  }
671
685
  else {
672
- query.where(constants_1.FIELDS.STATUS, '!=', utils_1.STATUSES.REMOVED);
686
+ query.where(statusField, '!=', utils_1.STATUSES.REMOVED);
673
687
  }
674
688
  }
675
689
  // Declarative update filter rules — applied after base logic.
@@ -711,7 +725,7 @@ class BaseGateway {
711
725
  }
712
726
  if (hasStatus === true) {
713
727
  filtersAppliedQty++;
714
- query.where(constants_1.FIELDS.STATUS, '!=', utils_1.STATUSES.REMOVED);
728
+ query.where(this.getStatusField(), '!=', utils_1.STATUSES.REMOVED);
715
729
  }
716
730
  // Declarative remove filter rules — applied after base logic.
717
731
  filtersAppliedQty += this.applyDeclarativeRemoveFilters(query, filterParams);
@@ -900,14 +914,9 @@ class BaseGateway {
900
914
  * Builds the patch object applied to a record when it is soft-deleted.
901
915
  * Called by `remove()` when `hardRemove` is false and `hasRemovedAt` is true.
902
916
  *
903
- * Returns a new object (merged from `args`) with removal fields populated.
917
+ * Returns a new object with removal fields populated.
904
918
  * Override in subclasses to add custom soft-delete fields.
905
- * Always call `super.transformOnRemove(args)` first.
906
- *
907
- * The `args` parameter is the original `where` filter passed to `remove()`.
908
- * It is available so subclasses can derive removal values from the filter
909
- * (e.g. storing which id was removed). In the base implementation it is
910
- * spread into the patch object as-is.
919
+ * Always call `super.transformOnRemove()` first.
911
920
  *
912
921
  * Built-in transformations:
913
922
  * - `hasRemovedAt` — sets removedAt to the current time (dayjs, not
@@ -926,11 +935,11 @@ class BaseGateway {
926
935
  * (construction time). This is intentional — removal timestamps should be
927
936
  * as accurate as possible and are not batch-grouped like create/update times.
928
937
  */
929
- async transformOnRemove(args) {
938
+ async transformOnRemove() {
930
939
  const { hasRemovedAt, hasRemovedAtStr, hasStatus, hasRemovedBy, hasLang, localizationForField } = this.config;
931
940
  const removalTime = (0, dayjs_1.default)();
932
941
  const removalTimeStr = removalTime.format('YYYYMMDDTHHmmssZ');
933
- const obj = { ...(args || {}) };
942
+ const obj = {};
934
943
  if (hasRemovedAt) {
935
944
  obj[constants_1.FIELDS.REMOVED_AT] = removalTime.toDate();
936
945
  }
@@ -938,7 +947,7 @@ class BaseGateway {
938
947
  obj[constants_1.FIELDS.REMOVED_AT_STR] = removalTimeStr;
939
948
  }
940
949
  if (hasStatus) {
941
- obj[constants_1.FIELDS.STATUS] = utils_1.STATUSES.REMOVED;
950
+ obj[this.getStatusField()] = utils_1.STATUSES.REMOVED;
942
951
  }
943
952
  if (hasRemovedBy) {
944
953
  if (obj[constants_1.FIELDS.REMOVED_BY] === undefined) {
@@ -1307,7 +1316,7 @@ class BaseGateway {
1307
1316
  query.delete(this.config.returnFields);
1308
1317
  }
1309
1318
  else {
1310
- const object = await this.transformOnRemove(where);
1319
+ const object = await this.transformOnRemove();
1311
1320
  query.update(object).returning(this.config.returnFields);
1312
1321
  }
1313
1322
  const filtersAppliedQty = await this.onRemoveFilter(query, where);
@@ -13,24 +13,80 @@ declare class BaseRestApiCrudController extends BaseController {
13
13
  protected disableRemove: boolean;
14
14
  protected disableRemoveMany: boolean;
15
15
  constructor(props: BaseRestApiCrudControllerPropsInterface);
16
+ /**
17
+ * Builds the `where` object for update and remove operations.
18
+ *
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.
22
+ *
23
+ * @param req - the Express request
24
+ * @param ids - ids parsed from req.params.id (always an array)
25
+ */
26
+ protected buildWhere(req: any, ids: string[]): Record<string, any>;
27
+ /**
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).
33
+ *
34
+ * @param req - the Express request
35
+ */
36
+ protected buildFilter(req: any): Record<string, any>;
37
+ /**
38
+ * Builds the `params` object for list operations (pagination / sorting).
39
+ *
40
+ * Base implementation picks only the known PAGINATION_KEYS from the query
41
+ * string. Override to support additional pagination conventions.
42
+ *
43
+ * @param req - the Express request
44
+ */
45
+ protected buildParams(req: any): Record<string, any>;
16
46
  protected resolveCore(req: any): Promise<any>;
17
47
  init(props: {
18
48
  app: any;
19
49
  root: string;
20
50
  }): void;
51
+ /**
52
+ * GET /
53
+ * Splits the query string into filter and pagination params, consistent
54
+ * with the GraphQL list resolver argument shape.
55
+ */
21
56
  protected list(req: any): Promise<any>;
22
57
  /**
23
- * Handles GET /:id — routes to core.get() for a single id,
24
- * or core.getMany() when the :id param contains commas.
58
+ * 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.
25
61
  */
26
62
  protected getOrGetMany(req: any): Promise<any>;
63
+ /**
64
+ * POST /
65
+ * Body must be { params: {...} } — consistent with GraphQL mutation args.
66
+ */
27
67
  protected create(req: any): Promise<any>;
68
+ /**
69
+ * POST /many
70
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
71
+ */
28
72
  protected createMany(req: any): Promise<any>;
73
+ /**
74
+ * 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.
78
+ */
29
79
  protected update(req: any): Promise<any>;
80
+ /**
81
+ * PUT /many
82
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
83
+ */
30
84
  protected updateMany(req: any): Promise<any>;
31
85
  /**
32
- * Handles DELETE /:id — routes to core.remove() for a single id,
33
- * or core.removeMany() when the :id param contains commas.
86
+ * 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.
34
90
  */
35
91
  protected removeOrRemoveMany(req: any): Promise<any>;
36
92
  }
@@ -4,6 +4,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
4
4
  exports.BaseRestApiCrudController = void 0;
5
5
  const BaseController_1 = require("./BaseController");
6
6
  const parseIds_1 = require("./parseIds");
7
+ /**
8
+ * Pagination / sorting keys that are always routed to `params` in list().
9
+ * Everything else in the query string is treated as a filter field.
10
+ */
11
+ const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
7
12
  class BaseRestApiCrudController extends BaseController_1.BaseController {
8
13
  coreToUse;
9
14
  getContext;
@@ -34,6 +39,56 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
34
39
  this.disableRemove = props.disableRemove ?? false;
35
40
  this.disableRemoveMany = props.disableRemoveMany ?? false;
36
41
  }
42
+ // ─── Extension points ───────────────────────────────────────────────────────
43
+ /**
44
+ * Builds the `where` object for update and remove operations.
45
+ *
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.
49
+ *
50
+ * @param req - the Express request
51
+ * @param ids - ids parsed from req.params.id (always an array)
52
+ */
53
+ buildWhere(req, ids) {
54
+ return { id: ids };
55
+ }
56
+ /**
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).
62
+ *
63
+ * @param req - the Express request
64
+ */
65
+ buildFilter(req) {
66
+ const filter = {};
67
+ for (const [key, value] of Object.entries(req.query ?? {})) {
68
+ if (!PAGINATION_KEYS.has(key)) {
69
+ filter[key] = value;
70
+ }
71
+ }
72
+ return filter;
73
+ }
74
+ /**
75
+ * Builds the `params` object for list operations (pagination / sorting).
76
+ *
77
+ * Base implementation picks only the known PAGINATION_KEYS from the query
78
+ * string. Override to support additional pagination conventions.
79
+ *
80
+ * @param req - the Express request
81
+ */
82
+ buildParams(req) {
83
+ const params = {};
84
+ for (const [key, value] of Object.entries(req.query ?? {})) {
85
+ if (PAGINATION_KEYS.has(key)) {
86
+ params[key] = value;
87
+ }
88
+ }
89
+ return params;
90
+ }
91
+ // ─── Core resolution ────────────────────────────────────────────────────────
37
92
  async resolveCore(req) {
38
93
  const context = await this.getContext(req);
39
94
  const core = context?.cores?.[this.coreToUse];
@@ -42,6 +97,7 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
42
97
  }
43
98
  return core;
44
99
  }
100
+ // ─── Route registration ─────────────────────────────────────────────────────
45
101
  init(props) {
46
102
  const { app, root } = props || {};
47
103
  if (!app || !root) {
@@ -71,14 +127,23 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
71
127
  app.delete(`${root}/:id`, this.json(this.removeOrRemoveMany.bind(this)));
72
128
  }
73
129
  }
74
- // ─── Route handlers ────────────────────────────────────────────────────────
130
+ // ─── Route handlers ─────────────────────────────────────────────────────────
131
+ /**
132
+ * GET /
133
+ * Splits the query string into filter and pagination params, consistent
134
+ * with the GraphQL list resolver argument shape.
135
+ */
75
136
  async list(req) {
76
137
  const core = await this.resolveCore(req);
77
- return core.list({ params: req.query });
138
+ return core.list({
139
+ filter: this.buildFilter(req),
140
+ params: this.buildParams(req),
141
+ });
78
142
  }
79
143
  /**
80
- * Handles GET /:id — routes to core.get() for a single id,
81
- * or core.getMany() when the :id param contains commas.
144
+ * 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.
82
147
  */
83
148
  async getOrGetMany(req) {
84
149
  const core = await this.resolveCore(req);
@@ -87,34 +152,58 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
87
152
  if (this.disableGet) {
88
153
  throw new Error(`GET by single id is disabled on this resource`);
89
154
  }
90
- return core.get({ params: { ...req.query, id: ids[0] } });
155
+ return core.get({ id: ids[0] });
91
156
  }
92
157
  if (this.disableGetMany) {
93
158
  throw new Error(`GET by multiple ids is disabled on this resource`);
94
159
  }
95
- return core.getMany({ params: { ...req.query, ids } });
160
+ return core.getMany({ ids });
96
161
  }
162
+ /**
163
+ * POST /
164
+ * Body must be { params: {...} } — consistent with GraphQL mutation args.
165
+ */
97
166
  async create(req) {
98
167
  const core = await this.resolveCore(req);
99
- return core.create({ params: req.body });
168
+ return core.create({ params: req.body.params });
100
169
  }
170
+ /**
171
+ * POST /many
172
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
173
+ */
101
174
  async createMany(req) {
102
175
  const core = await this.resolveCore(req);
103
- const items = Array.isArray(req.body) ? req.body : [req.body];
176
+ const items = Array.isArray(req.body.params) ? req.body.params : [req.body.params];
104
177
  return core.createMany({ params: items });
105
178
  }
179
+ /**
180
+ * 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.
184
+ */
106
185
  async update(req) {
107
186
  const core = await this.resolveCore(req);
108
- return core.update({ params: { ...req.body, id: req.params.id } });
187
+ const [, ids] = (0, parseIds_1.parseIds)(req.params.id);
188
+ return core.update({
189
+ where: this.buildWhere(req, ids),
190
+ params: req.body.params,
191
+ });
109
192
  }
193
+ /**
194
+ * PUT /many
195
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
196
+ */
110
197
  async updateMany(req) {
111
198
  const core = await this.resolveCore(req);
112
- const items = Array.isArray(req.body) ? req.body : [req.body];
199
+ const items = Array.isArray(req.body.params) ? req.body.params : [req.body.params];
113
200
  return core.updateMany({ params: items });
114
201
  }
115
202
  /**
116
- * Handles DELETE /:id — routes to core.remove() for a single id,
117
- * or core.removeMany() when the :id param contains commas.
203
+ * 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.
118
207
  */
119
208
  async removeOrRemoveMany(req) {
120
209
  const core = await this.resolveCore(req);
@@ -123,12 +212,12 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
123
212
  if (this.disableRemove) {
124
213
  throw new Error(`DELETE by single id is disabled on this resource`);
125
214
  }
126
- return core.remove({ params: { id: ids[0] } });
215
+ return core.remove({ where: this.buildWhere(req, ids) });
127
216
  }
128
217
  if (this.disableRemoveMany) {
129
218
  throw new Error(`DELETE by multiple ids is disabled on this resource`);
130
219
  }
131
- return core.removeMany({ params: { ids } });
220
+ return core.removeMany({ where: this.buildWhere(req, ids) });
132
221
  }
133
222
  }
134
223
  exports.BaseRestApiCrudController = BaseRestApiCrudController;
@@ -134,6 +134,16 @@ declare class BaseGateway {
134
134
  * while listing and loading still uses the primary key.
135
135
  */
136
136
  getIdField(): string;
137
+ /**
138
+ * Returns the column name used for the status field.
139
+ * Defaults to FIELDS.STATUS ('Status') for standard tables.
140
+ * Override via config.statusField for legacy tables that use a different
141
+ * column name (e.g. 'Status_ID').
142
+ *
143
+ * All status-related WHERE clauses and update patches use this value,
144
+ * so setting it once in the gateway constructor propagates everywhere.
145
+ */
146
+ getStatusField(): string;
137
147
  /**
138
148
  * Returns the field name used to identify records in UPDATE and DELETE
139
149
  * WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
@@ -462,14 +472,9 @@ declare class BaseGateway {
462
472
  * Builds the patch object applied to a record when it is soft-deleted.
463
473
  * Called by `remove()` when `hardRemove` is false and `hasRemovedAt` is true.
464
474
  *
465
- * Returns a new object (merged from `args`) with removal fields populated.
475
+ * Returns a new object with removal fields populated.
466
476
  * Override in subclasses to add custom soft-delete fields.
467
- * Always call `super.transformOnRemove(args)` first.
468
- *
469
- * The `args` parameter is the original `where` filter passed to `remove()`.
470
- * It is available so subclasses can derive removal values from the filter
471
- * (e.g. storing which id was removed). In the base implementation it is
472
- * spread into the patch object as-is.
477
+ * Always call `super.transformOnRemove()` first.
473
478
  *
474
479
  * Built-in transformations:
475
480
  * - `hasRemovedAt` — sets removedAt to the current time (dayjs, not
@@ -488,7 +493,7 @@ declare class BaseGateway {
488
493
  * (construction time). This is intentional — removal timestamps should be
489
494
  * as accurate as possible and are not batch-grouped like create/update times.
490
495
  */
491
- transformOnRemove(args?: any): Promise<any>;
496
+ transformOnRemove(): Promise<any>;
492
497
  /**
493
498
  * Transforms a record after it is read from the database, before it is
494
499
  * returned to the caller.
@@ -200,6 +200,18 @@ class BaseGateway {
200
200
  getIdField() {
201
201
  return this.config.idField || ID_FIELD;
202
202
  }
203
+ /**
204
+ * Returns the column name used for the status field.
205
+ * Defaults to FIELDS.STATUS ('Status') for standard tables.
206
+ * Override via config.statusField for legacy tables that use a different
207
+ * column name (e.g. 'Status_ID').
208
+ *
209
+ * All status-related WHERE clauses and update patches use this value,
210
+ * so setting it once in the gateway constructor propagates everywhere.
211
+ */
212
+ getStatusField() {
213
+ return this.config.statusField ?? FIELDS.STATUS;
214
+ }
203
215
  /**
204
216
  * Returns the field name used to identify records in UPDATE and DELETE
205
217
  * WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
@@ -597,7 +609,8 @@ class BaseGateway {
597
609
  async onListFilter(query, filterParams) {
598
610
  const { table, hasStatus, hasRemovedAt, hasSpace, activeStatuses, hasLang, fieldForKeyword, filterByUserField } = this.config || {};
599
611
  if (hasStatus) {
600
- query.whereIn(`${table}.${FIELDS.STATUS}`, filterParams?.[FIELDS.STATUS] != null ? castArray(filterParams?.[FIELDS.STATUS]) : castArray(activeStatuses));
612
+ const statusField = this.getStatusField();
613
+ query.whereIn(`${table}.${statusField}`, filterParams?.[statusField] != null ? castArray(filterParams?.[statusField]) : castArray(activeStatuses));
601
614
  }
602
615
  if (hasRemovedAt) {
603
616
  query.whereNull(`${table}.${FIELDS.REMOVED_AT}`);
@@ -658,12 +671,13 @@ class BaseGateway {
658
671
  }
659
672
  }
660
673
  if (hasStatus) {
674
+ const statusField = this.getStatusField();
661
675
  filtersAppliedQty++;
662
- if (Array.isArray(filterParams?.[FIELDS.STATUS])) {
663
- query.whereIn(FIELDS.STATUS, filterParams?.[FIELDS.STATUS]);
676
+ if (Array.isArray(filterParams?.[statusField])) {
677
+ query.whereIn(statusField, filterParams?.[statusField]);
664
678
  }
665
679
  else {
666
- query.where(FIELDS.STATUS, '!=', STATUSES.REMOVED);
680
+ query.where(statusField, '!=', STATUSES.REMOVED);
667
681
  }
668
682
  }
669
683
  // Declarative update filter rules — applied after base logic.
@@ -705,7 +719,7 @@ class BaseGateway {
705
719
  }
706
720
  if (hasStatus === true) {
707
721
  filtersAppliedQty++;
708
- query.where(FIELDS.STATUS, '!=', STATUSES.REMOVED);
722
+ query.where(this.getStatusField(), '!=', STATUSES.REMOVED);
709
723
  }
710
724
  // Declarative remove filter rules — applied after base logic.
711
725
  filtersAppliedQty += this.applyDeclarativeRemoveFilters(query, filterParams);
@@ -894,14 +908,9 @@ class BaseGateway {
894
908
  * Builds the patch object applied to a record when it is soft-deleted.
895
909
  * Called by `remove()` when `hardRemove` is false and `hasRemovedAt` is true.
896
910
  *
897
- * Returns a new object (merged from `args`) with removal fields populated.
911
+ * Returns a new object with removal fields populated.
898
912
  * Override in subclasses to add custom soft-delete fields.
899
- * Always call `super.transformOnRemove(args)` first.
900
- *
901
- * The `args` parameter is the original `where` filter passed to `remove()`.
902
- * It is available so subclasses can derive removal values from the filter
903
- * (e.g. storing which id was removed). In the base implementation it is
904
- * spread into the patch object as-is.
913
+ * Always call `super.transformOnRemove()` first.
905
914
  *
906
915
  * Built-in transformations:
907
916
  * - `hasRemovedAt` — sets removedAt to the current time (dayjs, not
@@ -920,11 +929,11 @@ class BaseGateway {
920
929
  * (construction time). This is intentional — removal timestamps should be
921
930
  * as accurate as possible and are not batch-grouped like create/update times.
922
931
  */
923
- async transformOnRemove(args) {
932
+ async transformOnRemove() {
924
933
  const { hasRemovedAt, hasRemovedAtStr, hasStatus, hasRemovedBy, hasLang, localizationForField } = this.config;
925
934
  const removalTime = dayjs();
926
935
  const removalTimeStr = removalTime.format('YYYYMMDDTHHmmssZ');
927
- const obj = { ...(args || {}) };
936
+ const obj = {};
928
937
  if (hasRemovedAt) {
929
938
  obj[FIELDS.REMOVED_AT] = removalTime.toDate();
930
939
  }
@@ -932,7 +941,7 @@ class BaseGateway {
932
941
  obj[FIELDS.REMOVED_AT_STR] = removalTimeStr;
933
942
  }
934
943
  if (hasStatus) {
935
- obj[FIELDS.STATUS] = STATUSES.REMOVED;
944
+ obj[this.getStatusField()] = STATUSES.REMOVED;
936
945
  }
937
946
  if (hasRemovedBy) {
938
947
  if (obj[FIELDS.REMOVED_BY] === undefined) {
@@ -1301,7 +1310,7 @@ class BaseGateway {
1301
1310
  query.delete(this.config.returnFields);
1302
1311
  }
1303
1312
  else {
1304
- const object = await this.transformOnRemove(where);
1313
+ const object = await this.transformOnRemove();
1305
1314
  query.update(object).returning(this.config.returnFields);
1306
1315
  }
1307
1316
  const filtersAppliedQty = await this.onRemoveFilter(query, where);
@@ -13,24 +13,80 @@ declare class BaseRestApiCrudController extends BaseController {
13
13
  protected disableRemove: boolean;
14
14
  protected disableRemoveMany: boolean;
15
15
  constructor(props: BaseRestApiCrudControllerPropsInterface);
16
+ /**
17
+ * Builds the `where` object for update and remove operations.
18
+ *
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.
22
+ *
23
+ * @param req - the Express request
24
+ * @param ids - ids parsed from req.params.id (always an array)
25
+ */
26
+ protected buildWhere(req: any, ids: string[]): Record<string, any>;
27
+ /**
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).
33
+ *
34
+ * @param req - the Express request
35
+ */
36
+ protected buildFilter(req: any): Record<string, any>;
37
+ /**
38
+ * Builds the `params` object for list operations (pagination / sorting).
39
+ *
40
+ * Base implementation picks only the known PAGINATION_KEYS from the query
41
+ * string. Override to support additional pagination conventions.
42
+ *
43
+ * @param req - the Express request
44
+ */
45
+ protected buildParams(req: any): Record<string, any>;
16
46
  protected resolveCore(req: any): Promise<any>;
17
47
  init(props: {
18
48
  app: any;
19
49
  root: string;
20
50
  }): void;
51
+ /**
52
+ * GET /
53
+ * Splits the query string into filter and pagination params, consistent
54
+ * with the GraphQL list resolver argument shape.
55
+ */
21
56
  protected list(req: any): Promise<any>;
22
57
  /**
23
- * Handles GET /:id — routes to core.get() for a single id,
24
- * or core.getMany() when the :id param contains commas.
58
+ * 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.
25
61
  */
26
62
  protected getOrGetMany(req: any): Promise<any>;
63
+ /**
64
+ * POST /
65
+ * Body must be { params: {...} } — consistent with GraphQL mutation args.
66
+ */
27
67
  protected create(req: any): Promise<any>;
68
+ /**
69
+ * POST /many
70
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
71
+ */
28
72
  protected createMany(req: any): Promise<any>;
73
+ /**
74
+ * 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.
78
+ */
29
79
  protected update(req: any): Promise<any>;
80
+ /**
81
+ * PUT /many
82
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
83
+ */
30
84
  protected updateMany(req: any): Promise<any>;
31
85
  /**
32
- * Handles DELETE /:id — routes to core.remove() for a single id,
33
- * or core.removeMany() when the :id param contains commas.
86
+ * 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.
34
90
  */
35
91
  protected removeOrRemoveMany(req: any): Promise<any>;
36
92
  }
@@ -1,6 +1,11 @@
1
1
  // ./src/baseRestApiCrudController.ts
2
2
  import { BaseController } from './BaseController';
3
3
  import { parseIds } from './parseIds';
4
+ /**
5
+ * Pagination / sorting keys that are always routed to `params` in list().
6
+ * Everything else in the query string is treated as a filter field.
7
+ */
8
+ const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
4
9
  class BaseRestApiCrudController extends BaseController {
5
10
  coreToUse;
6
11
  getContext;
@@ -31,6 +36,56 @@ class BaseRestApiCrudController extends BaseController {
31
36
  this.disableRemove = props.disableRemove ?? false;
32
37
  this.disableRemoveMany = props.disableRemoveMany ?? false;
33
38
  }
39
+ // ─── Extension points ───────────────────────────────────────────────────────
40
+ /**
41
+ * Builds the `where` object for update and remove operations.
42
+ *
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.
46
+ *
47
+ * @param req - the Express request
48
+ * @param ids - ids parsed from req.params.id (always an array)
49
+ */
50
+ buildWhere(req, ids) {
51
+ return { id: ids };
52
+ }
53
+ /**
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).
59
+ *
60
+ * @param req - the Express request
61
+ */
62
+ buildFilter(req) {
63
+ const filter = {};
64
+ for (const [key, value] of Object.entries(req.query ?? {})) {
65
+ if (!PAGINATION_KEYS.has(key)) {
66
+ filter[key] = value;
67
+ }
68
+ }
69
+ return filter;
70
+ }
71
+ /**
72
+ * Builds the `params` object for list operations (pagination / sorting).
73
+ *
74
+ * Base implementation picks only the known PAGINATION_KEYS from the query
75
+ * string. Override to support additional pagination conventions.
76
+ *
77
+ * @param req - the Express request
78
+ */
79
+ buildParams(req) {
80
+ const params = {};
81
+ for (const [key, value] of Object.entries(req.query ?? {})) {
82
+ if (PAGINATION_KEYS.has(key)) {
83
+ params[key] = value;
84
+ }
85
+ }
86
+ return params;
87
+ }
88
+ // ─── Core resolution ────────────────────────────────────────────────────────
34
89
  async resolveCore(req) {
35
90
  const context = await this.getContext(req);
36
91
  const core = context?.cores?.[this.coreToUse];
@@ -39,6 +94,7 @@ class BaseRestApiCrudController extends BaseController {
39
94
  }
40
95
  return core;
41
96
  }
97
+ // ─── Route registration ─────────────────────────────────────────────────────
42
98
  init(props) {
43
99
  const { app, root } = props || {};
44
100
  if (!app || !root) {
@@ -68,14 +124,23 @@ class BaseRestApiCrudController extends BaseController {
68
124
  app.delete(`${root}/:id`, this.json(this.removeOrRemoveMany.bind(this)));
69
125
  }
70
126
  }
71
- // ─── Route handlers ────────────────────────────────────────────────────────
127
+ // ─── Route handlers ─────────────────────────────────────────────────────────
128
+ /**
129
+ * GET /
130
+ * Splits the query string into filter and pagination params, consistent
131
+ * with the GraphQL list resolver argument shape.
132
+ */
72
133
  async list(req) {
73
134
  const core = await this.resolveCore(req);
74
- return core.list({ params: req.query });
135
+ return core.list({
136
+ filter: this.buildFilter(req),
137
+ params: this.buildParams(req),
138
+ });
75
139
  }
76
140
  /**
77
- * Handles GET /:id — routes to core.get() for a single id,
78
- * or core.getMany() when the :id param contains commas.
141
+ * 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.
79
144
  */
80
145
  async getOrGetMany(req) {
81
146
  const core = await this.resolveCore(req);
@@ -84,34 +149,58 @@ class BaseRestApiCrudController extends BaseController {
84
149
  if (this.disableGet) {
85
150
  throw new Error(`GET by single id is disabled on this resource`);
86
151
  }
87
- return core.get({ params: { ...req.query, id: ids[0] } });
152
+ return core.get({ id: ids[0] });
88
153
  }
89
154
  if (this.disableGetMany) {
90
155
  throw new Error(`GET by multiple ids is disabled on this resource`);
91
156
  }
92
- return core.getMany({ params: { ...req.query, ids } });
157
+ return core.getMany({ ids });
93
158
  }
159
+ /**
160
+ * POST /
161
+ * Body must be { params: {...} } — consistent with GraphQL mutation args.
162
+ */
94
163
  async create(req) {
95
164
  const core = await this.resolveCore(req);
96
- return core.create({ params: req.body });
165
+ return core.create({ params: req.body.params });
97
166
  }
167
+ /**
168
+ * POST /many
169
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
170
+ */
98
171
  async createMany(req) {
99
172
  const core = await this.resolveCore(req);
100
- const items = Array.isArray(req.body) ? req.body : [req.body];
173
+ const items = Array.isArray(req.body.params) ? req.body.params : [req.body.params];
101
174
  return core.createMany({ params: items });
102
175
  }
176
+ /**
177
+ * 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.
181
+ */
103
182
  async update(req) {
104
183
  const core = await this.resolveCore(req);
105
- return core.update({ params: { ...req.body, id: req.params.id } });
184
+ const [, ids] = parseIds(req.params.id);
185
+ return core.update({
186
+ where: this.buildWhere(req, ids),
187
+ params: req.body.params,
188
+ });
106
189
  }
190
+ /**
191
+ * PUT /many
192
+ * Body must be { params: [{...}, ...] } or { params: {...} } for a single item.
193
+ */
107
194
  async updateMany(req) {
108
195
  const core = await this.resolveCore(req);
109
- const items = Array.isArray(req.body) ? req.body : [req.body];
196
+ const items = Array.isArray(req.body.params) ? req.body.params : [req.body.params];
110
197
  return core.updateMany({ params: items });
111
198
  }
112
199
  /**
113
- * Handles DELETE /:id — routes to core.remove() for a single id,
114
- * or core.removeMany() when the :id param contains commas.
200
+ * 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.
115
204
  */
116
205
  async removeOrRemoveMany(req) {
117
206
  const core = await this.resolveCore(req);
@@ -120,12 +209,12 @@ class BaseRestApiCrudController extends BaseController {
120
209
  if (this.disableRemove) {
121
210
  throw new Error(`DELETE by single id is disabled on this resource`);
122
211
  }
123
- return core.remove({ params: { id: ids[0] } });
212
+ return core.remove({ where: this.buildWhere(req, ids) });
124
213
  }
125
214
  if (this.disableRemoveMany) {
126
215
  throw new Error(`DELETE by multiple ids is disabled on this resource`);
127
216
  }
128
- return core.removeMany({ params: { ids } });
217
+ return core.removeMany({ where: this.buildWhere(req, ids) });
129
218
  }
130
219
  }
131
220
  export { BaseRestApiCrudController };
@@ -16,6 +16,14 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
16
16
  * Defaults to the global ID_FIELD constant.
17
17
  */
18
18
  idField?: string;
19
+ /**
20
+ * Column name for the status field. Defaults to FIELDS.STATUS ('Status').
21
+ * Set to the actual column name on legacy tables that use a different name
22
+ * (e.g. statusField: 'Status_ID').
23
+ *
24
+ * All status-related WHERE clauses and soft-delete patches respect this value.
25
+ */
26
+ statusField?: string;
19
27
  /**
20
28
  * Field name used in UPDATE/DELETE WHERE clauses.
21
29
  * Separate from idField for tables where the write target differs
@@ -16,6 +16,14 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
16
16
  * Defaults to the global ID_FIELD constant.
17
17
  */
18
18
  idField?: string;
19
+ /**
20
+ * Column name for the status field. Defaults to FIELDS.STATUS ('Status').
21
+ * Set to the actual column name on legacy tables that use a different name
22
+ * (e.g. statusField: 'Status_ID').
23
+ *
24
+ * All status-related WHERE clauses and soft-delete patches respect this value.
25
+ */
26
+ statusField?: string;
19
27
  /**
20
28
  * Field name used in UPDATE/DELETE WHERE clauses.
21
29
  * Separate from idField for tables where the write target differs
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.127",
3
+ "version": "1.0.129",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {