@sdflc/backend-helpers 1.0.128 → 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.
@@ -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;
@@ -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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.128",
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": {