@sdflc/backend-helpers 1.0.130 → 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.
@@ -9,16 +9,33 @@ import { BaseRestApiCrudControllerPropsInterface } from './interfaces';
9
9
  * changes.
10
10
  *
11
11
  * ── Argument shapes ───────────────────────────────────────────────────────────
12
- * list → core.list({ filter, params })
12
+ * list → core.list({ filter, params }) params: PaginationAndSorting
13
13
  * get → core.get({ id })
14
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: [{...}] }
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
19
  * remove → core.remove({ where })
20
20
  * removeMany → core.removeMany({ where })
21
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
+ *
22
39
  * ── Extension points ──────────────────────────────────────────────────────────
23
40
  * buildWhere(req, ids) — override to add extra where conditions beyond id
24
41
  * buildFilter(req) — override to customise filter extraction from QS
@@ -67,15 +84,27 @@ declare class BaseRestApiCrudController extends BaseController {
67
84
  * Builds the `filter` object passed to core.list().
68
85
  *
69
86
  * Base implementation treats every query string key that is NOT a known
70
- * pagination key as a filter field. Override to apply custom parsing
71
- * (e.g. typed booleans, array values, renamed fields).
87
+ * pagination key (pagination, sortBy) as a filter field. Override to
88
+ * apply custom parsing (e.g. typed booleans, array values, renamed fields).
72
89
  */
73
90
  protected buildFilter(req: any): Record<string, any>;
74
91
  /**
75
- * Builds the `params` object passed to core.list() (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.
102
+ *
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.
76
106
  *
77
- * Base implementation picks only the known PAGINATION_KEYS from the query
78
- * string. Override to support additional or renamed pagination conventions.
107
+ * Override to support additional or renamed pagination conventions.
79
108
  */
80
109
  protected buildParams(req: any): Record<string, any>;
81
110
  protected resolveCore(req: any): Promise<any>;
@@ -97,8 +126,8 @@ declare class BaseRestApiCrudController extends BaseController {
97
126
  * GET /
98
127
  *
99
128
  * Splits the query string into filter (non-pagination keys) and params
100
- * (pagination keys) via buildFilter() and buildParams(). Shape matches
101
- * the GraphQL list resolver: core.list({ filter, params }).
129
+ * (PaginationAndSorting shape) via buildFilter() and buildParams().
130
+ * Shape matches the GraphQL list resolver: core.list({ filter, params }).
102
131
  */
103
132
  protected list(req: any): Promise<any>;
104
133
  /**
@@ -5,10 +5,15 @@ 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' }] }
10
15
  */
11
- const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
16
+ const PAGINATION_KEYS = new Set(['pagination', 'sortBy']);
12
17
  /**
13
18
  * BaseRestApiCrudController
14
19
  *
@@ -18,16 +23,33 @@ const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir',
18
23
  * changes.
19
24
  *
20
25
  * ── Argument shapes ───────────────────────────────────────────────────────────
21
- * list → core.list({ filter, params })
26
+ * list → core.list({ filter, params }) params: PaginationAndSorting
22
27
  * get → core.get({ id })
23
28
  * getMany → core.getMany({ ids })
24
- * create → core.create({ params }) body: { params: {...} }
25
- * createMany → core.createMany({ params }) body: { params: [{...}] }
26
- * update → core.update({ where, params }) body: { params: {...} }
27
- * updateMany → core.updateMany({ params }) body: { params: [{...}] }
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: [{...}] }
28
33
  * remove → core.remove({ where })
29
34
  * removeMany → core.removeMany({ where })
30
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
+ *
31
53
  * ── Extension points ──────────────────────────────────────────────────────────
32
54
  * buildWhere(req, ids) — override to add extra where conditions beyond id
33
55
  * buildFilter(req) — override to customise filter extraction from QS
@@ -97,8 +119,8 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
97
119
  * Builds the `filter` object passed to core.list().
98
120
  *
99
121
  * Base implementation treats every query string key that is NOT a known
100
- * pagination key as a filter field. Override to apply custom parsing
101
- * (e.g. typed booleans, array values, renamed fields).
122
+ * pagination key (pagination, sortBy) as a filter field. Override to
123
+ * apply custom parsing (e.g. typed booleans, array values, renamed fields).
102
124
  */
103
125
  buildFilter(req) {
104
126
  const filter = {};
@@ -110,16 +132,48 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
110
132
  return filter;
111
133
  }
112
134
  /**
113
- * Builds the `params` object passed to core.list() (pagination / sorting).
135
+ * Builds the `params` object passed to core.list().
136
+ *
137
+ * Assembles the PaginationAndSorting shape expected by cores:
138
+ * {
139
+ * pagination: { page: string, pageSize: string },
140
+ * sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
141
+ * }
142
+ *
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.
114
149
  *
115
- * Base implementation picks only the known PAGINATION_KEYS from the query
116
- * string. Override to support additional or renamed pagination conventions.
150
+ * Override to support additional or renamed pagination conventions.
117
151
  */
118
152
  buildParams(req) {
153
+ const query = req.query ?? {};
119
154
  const params = {};
120
- for (const [key, value] of Object.entries(req.query ?? {})) {
121
- if (PAGINATION_KEYS.has(key)) {
122
- 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;
123
177
  }
124
178
  }
125
179
  return params;
@@ -180,8 +234,8 @@ class BaseRestApiCrudController extends BaseController_1.BaseController {
180
234
  * GET /
181
235
  *
182
236
  * Splits the query string into filter (non-pagination keys) and params
183
- * (pagination keys) via buildFilter() and buildParams(). Shape matches
184
- * the GraphQL list resolver: core.list({ filter, params }).
237
+ * (PaginationAndSorting shape) via buildFilter() and buildParams().
238
+ * Shape matches the GraphQL list resolver: core.list({ filter, params }).
185
239
  */
186
240
  async list(req) {
187
241
  const core = await this.resolveCore(req);
@@ -9,16 +9,33 @@ import { BaseRestApiCrudControllerPropsInterface } from './interfaces';
9
9
  * changes.
10
10
  *
11
11
  * ── Argument shapes ───────────────────────────────────────────────────────────
12
- * list → core.list({ filter, params })
12
+ * list → core.list({ filter, params }) params: PaginationAndSorting
13
13
  * get → core.get({ id })
14
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: [{...}] }
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
19
  * remove → core.remove({ where })
20
20
  * removeMany → core.removeMany({ where })
21
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
+ *
22
39
  * ── Extension points ──────────────────────────────────────────────────────────
23
40
  * buildWhere(req, ids) — override to add extra where conditions beyond id
24
41
  * buildFilter(req) — override to customise filter extraction from QS
@@ -67,15 +84,27 @@ declare class BaseRestApiCrudController extends BaseController {
67
84
  * Builds the `filter` object passed to core.list().
68
85
  *
69
86
  * Base implementation treats every query string key that is NOT a known
70
- * pagination key as a filter field. Override to apply custom parsing
71
- * (e.g. typed booleans, array values, renamed fields).
87
+ * pagination key (pagination, sortBy) as a filter field. Override to
88
+ * apply custom parsing (e.g. typed booleans, array values, renamed fields).
72
89
  */
73
90
  protected buildFilter(req: any): Record<string, any>;
74
91
  /**
75
- * Builds the `params` object passed to core.list() (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.
102
+ *
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.
76
106
  *
77
- * Base implementation picks only the known PAGINATION_KEYS from the query
78
- * string. Override to support additional or renamed pagination conventions.
107
+ * Override to support additional or renamed pagination conventions.
79
108
  */
80
109
  protected buildParams(req: any): Record<string, any>;
81
110
  protected resolveCore(req: any): Promise<any>;
@@ -97,8 +126,8 @@ declare class BaseRestApiCrudController extends BaseController {
97
126
  * GET /
98
127
  *
99
128
  * Splits the query string into filter (non-pagination keys) and params
100
- * (pagination keys) via buildFilter() and buildParams(). Shape matches
101
- * the GraphQL list resolver: core.list({ filter, params }).
129
+ * (PaginationAndSorting shape) via buildFilter() and buildParams().
130
+ * Shape matches the GraphQL list resolver: core.list({ filter, params }).
102
131
  */
103
132
  protected list(req: any): Promise<any>;
104
133
  /**
@@ -2,10 +2,15 @@
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' }] }
7
12
  */
8
- const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir', 'orderBy']);
13
+ const PAGINATION_KEYS = new Set(['pagination', 'sortBy']);
9
14
  /**
10
15
  * BaseRestApiCrudController
11
16
  *
@@ -15,16 +20,33 @@ const PAGINATION_KEYS = new Set(['page', 'limit', 'offset', 'sortBy', 'sortDir',
15
20
  * changes.
16
21
  *
17
22
  * ── Argument shapes ───────────────────────────────────────────────────────────
18
- * list → core.list({ filter, params })
23
+ * list → core.list({ filter, params }) params: PaginationAndSorting
19
24
  * get → core.get({ id })
20
25
  * getMany → core.getMany({ ids })
21
- * create → core.create({ params }) body: { params: {...} }
22
- * createMany → core.createMany({ params }) body: { params: [{...}] }
23
- * update → core.update({ where, params }) body: { params: {...} }
24
- * updateMany → core.updateMany({ params }) body: { params: [{...}] }
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: [{...}] }
25
30
  * remove → core.remove({ where })
26
31
  * removeMany → core.removeMany({ where })
27
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
+ *
28
50
  * ── Extension points ──────────────────────────────────────────────────────────
29
51
  * buildWhere(req, ids) — override to add extra where conditions beyond id
30
52
  * buildFilter(req) — override to customise filter extraction from QS
@@ -94,8 +116,8 @@ class BaseRestApiCrudController extends BaseController {
94
116
  * Builds the `filter` object passed to core.list().
95
117
  *
96
118
  * Base implementation treats every query string key that is NOT a known
97
- * pagination key as a filter field. Override to apply custom parsing
98
- * (e.g. typed booleans, array values, renamed fields).
119
+ * pagination key (pagination, sortBy) as a filter field. Override to
120
+ * apply custom parsing (e.g. typed booleans, array values, renamed fields).
99
121
  */
100
122
  buildFilter(req) {
101
123
  const filter = {};
@@ -107,16 +129,48 @@ class BaseRestApiCrudController extends BaseController {
107
129
  return filter;
108
130
  }
109
131
  /**
110
- * Builds the `params` object passed to core.list() (pagination / sorting).
132
+ * Builds the `params` object passed to core.list().
133
+ *
134
+ * Assembles the PaginationAndSorting shape expected by cores:
135
+ * {
136
+ * pagination: { page: string, pageSize: string },
137
+ * sortBy: [{ name: string, order: 'ASC' | 'DESC' }]
138
+ * }
139
+ *
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.
111
146
  *
112
- * Base implementation picks only the known PAGINATION_KEYS from the query
113
- * string. Override to support additional or renamed pagination conventions.
147
+ * Override to support additional or renamed pagination conventions.
114
148
  */
115
149
  buildParams(req) {
150
+ const query = req.query ?? {};
116
151
  const params = {};
117
- for (const [key, value] of Object.entries(req.query ?? {})) {
118
- if (PAGINATION_KEYS.has(key)) {
119
- 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;
120
174
  }
121
175
  }
122
176
  return params;
@@ -177,8 +231,8 @@ class BaseRestApiCrudController extends BaseController {
177
231
  * GET /
178
232
  *
179
233
  * Splits the query string into filter (non-pagination keys) and params
180
- * (pagination keys) via buildFilter() and buildParams(). Shape matches
181
- * the GraphQL list resolver: core.list({ filter, params }).
234
+ * (PaginationAndSorting shape) via buildFilter() and buildParams().
235
+ * Shape matches the GraphQL list resolver: core.list({ filter, params }).
182
236
  */
183
237
  async list(req) {
184
238
  const core = await this.resolveCore(req);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.130",
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": {