@sdflc/backend-helpers 1.0.122 → 1.0.124
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +208 -45
- package/build/BaseGateway.d.ts +270 -50
- package/build/BaseGateway.js +551 -64
- package/build/Database.d.ts +15 -0
- package/build/Database.js +17 -1
- package/build/esm/BaseGateway.d.ts +270 -50
- package/build/esm/BaseGateway.js +552 -65
- package/build/esm/Database.d.ts +15 -0
- package/build/esm/Database.js +17 -1
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +71 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +0 -1
- package/build/esm/interfaces/GatewayFilterRule.d.ts +109 -0
- package/build/esm/interfaces/GatewayFilterRule.js +1 -0
- package/build/esm/interfaces/index.d.ts +1 -0
- package/build/esm/interfaces/index.js +1 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +71 -0
- package/build/interfaces/BaseGatewayPropsInterface.js +0 -1
- package/build/interfaces/GatewayFilterRule.d.ts +109 -0
- package/build/interfaces/GatewayFilterRule.js +2 -0
- package/build/interfaces/index.d.ts +1 -0
- package/build/interfaces/index.js +1 -0
- package/package.json +1 -1
package/build/esm/BaseGateway.js
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
|
-
// ./src/BaseGateway.ts
|
|
2
1
|
import { v4 } from 'uuid';
|
|
3
2
|
import dayjs from 'dayjs';
|
|
4
3
|
import check from 'check-types';
|
|
5
4
|
import { camelCase, castArray, pullAll } from 'lodash';
|
|
6
|
-
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels, isLogger } from '@sdflc/utils';
|
|
5
|
+
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels, isLogger, camelResponse, } from '@sdflc/utils';
|
|
7
6
|
import { DataCache } from './DataCache';
|
|
8
7
|
import { FIELDS, ID_FIELD } from './constants';
|
|
9
8
|
const DEFAULT_CHUNCK_SIZE = 2500;
|
|
9
|
+
/**
|
|
10
|
+
* Filter types that are valid on the update and remove paths.
|
|
11
|
+
* Search and date-range filters are intentionally excluded — update/remove
|
|
12
|
+
* filters must be precise identifiers, not fuzzy searches or time windows.
|
|
13
|
+
*/
|
|
14
|
+
const UPDATE_REMOVE_SUPPORTED_TYPES = new Set(['array', 'eq', 'bool', 'nullableBool']);
|
|
10
15
|
/**
|
|
11
16
|
* BaseGateway is the foundation for all database-backed gateway classes.
|
|
12
17
|
*
|
|
@@ -27,6 +32,25 @@ const DEFAULT_CHUNCK_SIZE = 2500;
|
|
|
27
32
|
* attach computed properties)
|
|
28
33
|
* - `generateId()` — to use a domain-specific ID strategy
|
|
29
34
|
*
|
|
35
|
+
* ── Declarative filters ──────────────────────────────────────────────────────
|
|
36
|
+
* Simple, repetitive filter logic can be expressed via the listFilters,
|
|
37
|
+
* updateFilters, and removeFilters config arrays (see BaseGatewayPropsInterface).
|
|
38
|
+
* Rules are applied after the standard base logic inside onListFilter /
|
|
39
|
+
* onUpdateFilter / onRemoveFilter — they supplement, never replace, the
|
|
40
|
+
* override chain.
|
|
41
|
+
*
|
|
42
|
+
* ── Protected filter helpers ─────────────────────────────────────────────────
|
|
43
|
+
* Subclasses can call the following helpers directly inside their own
|
|
44
|
+
* onListFilter overrides instead of re-implementing the patterns themselves:
|
|
45
|
+
*
|
|
46
|
+
* applyArrayFilter(query, value, column)
|
|
47
|
+
* applyEqFilter(query, value, column)
|
|
48
|
+
* applyBoolFilter(query, value, column)
|
|
49
|
+
* applyNullableBoolFilter(query, value, column)
|
|
50
|
+
* applyDateRangeFilter(query, from, to, column)
|
|
51
|
+
* applyNullableDateRangeFilter(query, isNull, from, to, column)
|
|
52
|
+
* applySearchFilter(query, search, columns)
|
|
53
|
+
*
|
|
30
54
|
* The loader (DataCache by default) is used for batched per-id loading
|
|
31
55
|
* via DataLoader semantics. It is bypassed when `noCache: true` is set in
|
|
32
56
|
* config, or when `list()` is called with `useCache: false`.
|
|
@@ -79,6 +103,7 @@ class BaseGateway {
|
|
|
79
103
|
// for batched, per-request in-memory caching.
|
|
80
104
|
this.loader = check.function(this.config?.loader) ? this.config.loader : new DataCache(this.config);
|
|
81
105
|
}
|
|
106
|
+
// ─── Config / context accessors ────────────────────────────────────────────
|
|
82
107
|
/**
|
|
83
108
|
* Returns the full gateway config object.
|
|
84
109
|
* Useful for subclasses or external code that needs to inspect configuration
|
|
@@ -124,6 +149,415 @@ class BaseGateway {
|
|
|
124
149
|
this.loader = new DataCache({ ...this.config, ...config });
|
|
125
150
|
return this;
|
|
126
151
|
}
|
|
152
|
+
/**
|
|
153
|
+
* Returns the requestId from the current ApiContext.
|
|
154
|
+
* Useful for correlating log entries or error reports to a specific request.
|
|
155
|
+
*/
|
|
156
|
+
getRequestId() {
|
|
157
|
+
return this.config.context.requestId;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Returns the full ApiContext associated with this gateway instance.
|
|
161
|
+
* The context carries request-scoped values: userId, spaceId, headers,
|
|
162
|
+
* other gateways, cores, db, etc.
|
|
163
|
+
*/
|
|
164
|
+
getContext() {
|
|
165
|
+
return this.config.context;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Returns all gateway instances from the current request context.
|
|
169
|
+
* Allows one gateway to call another (e.g. UserGateway calling RoleGateway)
|
|
170
|
+
* without going through a core, using the same shared context and db connection.
|
|
171
|
+
*
|
|
172
|
+
* Returns an empty object if context is not available.
|
|
173
|
+
*/
|
|
174
|
+
getGateways() {
|
|
175
|
+
return this.config.context?.gateways || {};
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Returns the Database instance from config.
|
|
179
|
+
* All query builders are derived from this instance.
|
|
180
|
+
*/
|
|
181
|
+
getDb() {
|
|
182
|
+
return this.config.db;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* Returns a Knex query builder scoped to this gateway's table.
|
|
186
|
+
* The builder is a fresh instance each time — it does not carry state
|
|
187
|
+
* between calls.
|
|
188
|
+
*/
|
|
189
|
+
getBuilder() {
|
|
190
|
+
return this.getDb()?.getBuilder(this.config.table);
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Returns the primary key field name used for SELECT and loader operations.
|
|
194
|
+
* Defaults to the global ID_FIELD constant if not set in config.
|
|
195
|
+
*
|
|
196
|
+
* Note: this may differ from `getIdFieldUpdateRemove()` — some tables use
|
|
197
|
+
* a different column for update/delete filtering (e.g. a composite key)
|
|
198
|
+
* while listing and loading still uses the primary key.
|
|
199
|
+
*/
|
|
200
|
+
getIdField() {
|
|
201
|
+
return this.config.idField || ID_FIELD;
|
|
202
|
+
}
|
|
203
|
+
/**
|
|
204
|
+
* Returns the field name used to identify records in UPDATE and DELETE
|
|
205
|
+
* WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
|
|
206
|
+
*
|
|
207
|
+
* Separate from `getIdField()` to support tables where the logical primary
|
|
208
|
+
* key used for loading differs from the column used for writes
|
|
209
|
+
* (e.g. a table with a UUID primary key but a separate "slug" as update target).
|
|
210
|
+
*/
|
|
211
|
+
getIdFieldUpdateRemove() {
|
|
212
|
+
return this.config.idFieldUpdateRemove || this.config.idField || ID_FIELD;
|
|
213
|
+
}
|
|
214
|
+
// ─── Protected filter helpers ───────────────────────────────────────────────
|
|
215
|
+
//
|
|
216
|
+
// These helpers encode the common WHERE clause patterns used across gateway
|
|
217
|
+
// subclasses. Call them directly from onListFilter overrides to avoid
|
|
218
|
+
// re-implementing the same patterns in every gateway.
|
|
219
|
+
//
|
|
220
|
+
// All helpers are no-ops when the filter value is absent / null / undefined,
|
|
221
|
+
// so callers never need to guard against undefined before calling.
|
|
222
|
+
/**
|
|
223
|
+
* Applies a whereIn or where-equals filter for scalar or array values.
|
|
224
|
+
*
|
|
225
|
+
* Normalises the value to an array, discarding null / undefined / empty-string
|
|
226
|
+
* entries. Single-element arrays are unwrapped to a plain equality check so
|
|
227
|
+
* the query planner sees a simpler predicate.
|
|
228
|
+
*
|
|
229
|
+
* No-op when the normalised array is empty.
|
|
230
|
+
*
|
|
231
|
+
* @param query Knex query builder
|
|
232
|
+
* @param value Scalar value, array of values, null, or undefined
|
|
233
|
+
* @param column Fully-qualified column name (e.g. 'Party_Guest.Party_ID')
|
|
234
|
+
*/
|
|
235
|
+
applyArrayFilter(query, value, column) {
|
|
236
|
+
const items = normaliseToArray(value);
|
|
237
|
+
if (items.length === 0)
|
|
238
|
+
return;
|
|
239
|
+
if (items.length === 1) {
|
|
240
|
+
query.where(column, items[0]);
|
|
241
|
+
}
|
|
242
|
+
else {
|
|
243
|
+
query.whereIn(column, items);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* Applies a strict equality filter: WHERE column = value.
|
|
248
|
+
*
|
|
249
|
+
* No-op when value is null or undefined. Does NOT expand arrays —
|
|
250
|
+
* if the value might be an array, use applyArrayFilter instead.
|
|
251
|
+
*
|
|
252
|
+
* @param query Knex query builder
|
|
253
|
+
* @param value The exact value to match
|
|
254
|
+
* @param column Fully-qualified column name
|
|
255
|
+
*/
|
|
256
|
+
applyEqFilter(query, value, column) {
|
|
257
|
+
if (value == null)
|
|
258
|
+
return;
|
|
259
|
+
query.where(column, value);
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* Applies a boolean equality filter: WHERE column = true/false.
|
|
263
|
+
*
|
|
264
|
+
* Only fires when value is strictly true or false. null, undefined, and
|
|
265
|
+
* any other type are ignored — the column is left unconstrained.
|
|
266
|
+
*
|
|
267
|
+
* Use for boolean columns where you want to filter on the stored value
|
|
268
|
+
* (e.g. WHERE Is_Starred = true). For nullable columns that encode
|
|
269
|
+
* presence via NULL / NOT NULL, use applyNullableBoolFilter instead.
|
|
270
|
+
*
|
|
271
|
+
* @param query Knex query builder
|
|
272
|
+
* @param value Must be strictly true or false to fire
|
|
273
|
+
* @param column Fully-qualified column name
|
|
274
|
+
*/
|
|
275
|
+
applyBoolFilter(query, value, column) {
|
|
276
|
+
if (value === true || value === false) {
|
|
277
|
+
query.where(column, value);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* Applies a null-presence filter driven by a boolean flag:
|
|
282
|
+
* true → WHERE column IS NOT NULL
|
|
283
|
+
* false → WHERE column IS NULL
|
|
284
|
+
* null / undefined → no-op (column is left unconstrained)
|
|
285
|
+
*
|
|
286
|
+
* Use when a nullable column encodes presence semantically — e.g.
|
|
287
|
+
* wasInvited ↔ Invited_At IS [NOT] NULL.
|
|
288
|
+
*
|
|
289
|
+
* @param query Knex query builder
|
|
290
|
+
* @param value true, false, null, or undefined
|
|
291
|
+
* @param column Fully-qualified column name
|
|
292
|
+
*/
|
|
293
|
+
applyNullableBoolFilter(query, value, column) {
|
|
294
|
+
if (value === true) {
|
|
295
|
+
query.whereNotNull(column);
|
|
296
|
+
}
|
|
297
|
+
else if (value === false) {
|
|
298
|
+
query.whereNull(column);
|
|
299
|
+
}
|
|
300
|
+
// null / undefined: intentional no-op
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Applies an inclusive date-range filter: WHERE column >= from AND column <= to.
|
|
304
|
+
*
|
|
305
|
+
* Each bound is independently optional — omitting one leaves that side open.
|
|
306
|
+
* Both bounds are no-ops when null or undefined.
|
|
307
|
+
*
|
|
308
|
+
* @param query Knex query builder
|
|
309
|
+
* @param from Inclusive lower bound (Date, ISO string, or null/undefined)
|
|
310
|
+
* @param to Inclusive upper bound (Date, ISO string, or null/undefined)
|
|
311
|
+
* @param column Fully-qualified column name
|
|
312
|
+
*/
|
|
313
|
+
applyDateRangeFilter(query, from, to, column) {
|
|
314
|
+
if (from != null) {
|
|
315
|
+
query.where(column, '>=', from);
|
|
316
|
+
}
|
|
317
|
+
if (to != null) {
|
|
318
|
+
query.where(column, '<=', to);
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* Applies a composite nullable date-range filter combining a null-check phase
|
|
323
|
+
* and an optional from/to range, driven by three independent filter values.
|
|
324
|
+
*
|
|
325
|
+
* isNull controls the null-presence check:
|
|
326
|
+
* true → WHERE column IS NULL (from/to are skipped — meaningless on nulls)
|
|
327
|
+
* false → WHERE column IS NOT NULL, then from/to applied if present
|
|
328
|
+
* null / undefined → null-ness unconstrained; from/to applied if present
|
|
329
|
+
*
|
|
330
|
+
* This matches the pattern used across Party_Guest datetime columns (Rsvp_At,
|
|
331
|
+
* Checked_In_At, Checked_Out_At) where the consumer may want to find records
|
|
332
|
+
* with no timestamp, or records within a specific time window, or both.
|
|
333
|
+
*
|
|
334
|
+
* @param query Knex query builder
|
|
335
|
+
* @param isNull Boolean flag or null/undefined
|
|
336
|
+
* @param from Inclusive lower bound or null/undefined
|
|
337
|
+
* @param to Inclusive upper bound or null/undefined
|
|
338
|
+
* @param column Fully-qualified column name
|
|
339
|
+
*/
|
|
340
|
+
applyNullableDateRangeFilter(query, isNull, from, to, column) {
|
|
341
|
+
if (isNull === true) {
|
|
342
|
+
query.whereNull(column);
|
|
343
|
+
// from/to are meaningless when forcing null — skip them
|
|
344
|
+
return;
|
|
345
|
+
}
|
|
346
|
+
if (isNull === false) {
|
|
347
|
+
query.whereNotNull(column);
|
|
348
|
+
}
|
|
349
|
+
this.applyDateRangeFilter(query, from, to, column);
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Applies a case-insensitive LIKE / ILIKE search across one or more columns
|
|
353
|
+
* using OR semantics: WHERE (col1 LIKE %search% OR col2 LIKE %search% …).
|
|
354
|
+
*
|
|
355
|
+
* The operator ('like' vs 'ilike') is resolved from the connected database
|
|
356
|
+
* type via Database.getSqlLikeOperator():
|
|
357
|
+
* - PostgreSQL → 'ilike' (native case-insensitive LIKE)
|
|
358
|
+
* - MSSQL → 'like' (case-insensitive under _CI_ collations)
|
|
359
|
+
* - Others → 'like' (safe default)
|
|
360
|
+
*
|
|
361
|
+
* No-op when:
|
|
362
|
+
* - search is not a non-empty string after trimming
|
|
363
|
+
* - columns array is empty or not provided
|
|
364
|
+
* - the Database instance is unavailable
|
|
365
|
+
*
|
|
366
|
+
* @param query Knex query builder
|
|
367
|
+
* @param search The search string (will be wrapped in %)
|
|
368
|
+
* @param columns One or more fully-qualified column names to search across
|
|
369
|
+
*/
|
|
370
|
+
applySearchFilter(query, search, columns) {
|
|
371
|
+
if (!Array.isArray(columns) || columns.length === 0)
|
|
372
|
+
return;
|
|
373
|
+
const term = typeof search === 'string' ? search.trim() : '';
|
|
374
|
+
if (term.length === 0)
|
|
375
|
+
return;
|
|
376
|
+
const likeOp = this.getDb()?.getSqlLikeOperator() ?? 'like';
|
|
377
|
+
const pattern = `%${term}%`;
|
|
378
|
+
query.where((sub) => {
|
|
379
|
+
columns.forEach((col, idx) => {
|
|
380
|
+
if (idx === 0) {
|
|
381
|
+
sub.where(col, likeOp, pattern);
|
|
382
|
+
}
|
|
383
|
+
else {
|
|
384
|
+
sub.orWhere(col, likeOp, pattern);
|
|
385
|
+
}
|
|
386
|
+
});
|
|
387
|
+
});
|
|
388
|
+
}
|
|
389
|
+
// ─── Declarative filter application ────────────────────────────────────────
|
|
390
|
+
/**
|
|
391
|
+
* Applies a single GatewayFilterRule to a Knex query builder against
|
|
392
|
+
* the provided filter params object.
|
|
393
|
+
*
|
|
394
|
+
* Called by applyDeclarativeListFilters and is also available to subclasses
|
|
395
|
+
* that want to apply individual rules from custom filter methods.
|
|
396
|
+
*
|
|
397
|
+
* Returns true if the rule produced at least one WHERE clause,
|
|
398
|
+
* false if it was a no-op (value absent, unsupported type, etc.).
|
|
399
|
+
*
|
|
400
|
+
* Note: for 'dateRange' and 'nullableDateRange' the return value reflects
|
|
401
|
+
* whether the rule was structurally valid, not whether any bound was
|
|
402
|
+
* actually present (since both bounds are optional).
|
|
403
|
+
*/
|
|
404
|
+
applyFilterRule(query, rule, filterParams) {
|
|
405
|
+
const { field, column, type, columns } = rule;
|
|
406
|
+
const value = filterParams?.[field];
|
|
407
|
+
switch (type) {
|
|
408
|
+
case 'array': {
|
|
409
|
+
const items = normaliseToArray(value);
|
|
410
|
+
if (items.length === 0)
|
|
411
|
+
return false;
|
|
412
|
+
this.applyArrayFilter(query, value, column);
|
|
413
|
+
return true;
|
|
414
|
+
}
|
|
415
|
+
case 'eq': {
|
|
416
|
+
if (value == null)
|
|
417
|
+
return false;
|
|
418
|
+
this.applyEqFilter(query, value, column);
|
|
419
|
+
return true;
|
|
420
|
+
}
|
|
421
|
+
case 'bool': {
|
|
422
|
+
if (value !== true && value !== false)
|
|
423
|
+
return false;
|
|
424
|
+
this.applyBoolFilter(query, value, column);
|
|
425
|
+
return true;
|
|
426
|
+
}
|
|
427
|
+
case 'nullableBool': {
|
|
428
|
+
if (value !== true && value !== false)
|
|
429
|
+
return false;
|
|
430
|
+
this.applyNullableBoolFilter(query, value, column);
|
|
431
|
+
return true;
|
|
432
|
+
}
|
|
433
|
+
case 'dateRange': {
|
|
434
|
+
const from = filterParams?.[`${field}From`];
|
|
435
|
+
const to = filterParams?.[`${field}To`];
|
|
436
|
+
this.applyDateRangeFilter(query, from, to, column);
|
|
437
|
+
// Counts as applied when at least one bound is present
|
|
438
|
+
return from != null || to != null;
|
|
439
|
+
}
|
|
440
|
+
case 'nullableDateRange': {
|
|
441
|
+
const isNull = filterParams?.[`${field}Null`];
|
|
442
|
+
const from = filterParams?.[`${field}From`];
|
|
443
|
+
const to = filterParams?.[`${field}To`];
|
|
444
|
+
this.applyNullableDateRangeFilter(query, isNull, from, to, column);
|
|
445
|
+
return isNull != null || from != null || to != null;
|
|
446
|
+
}
|
|
447
|
+
case 'search': {
|
|
448
|
+
const term = typeof value === 'string' ? value.trim() : '';
|
|
449
|
+
if (term.length === 0 || !Array.isArray(columns) || columns.length === 0)
|
|
450
|
+
return false;
|
|
451
|
+
this.applySearchFilter(query, value, columns);
|
|
452
|
+
return true;
|
|
453
|
+
}
|
|
454
|
+
default: {
|
|
455
|
+
// Exhaustiveness guard — TypeScript narrows 'never' here if all cases
|
|
456
|
+
// are covered, so this branch fires only when an unknown type is passed
|
|
457
|
+
// at runtime (e.g. via a cast or a future type added without updating
|
|
458
|
+
// this switch).
|
|
459
|
+
this.logger.log(`BaseGateway: skipping filter rule with unrecognised type "${rule.type}" for field "${field}"`);
|
|
460
|
+
return false;
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
}
|
|
464
|
+
/**
|
|
465
|
+
* Applies all rules from config.listFilters to the query in declaration order.
|
|
466
|
+
* Called at the end of onListFilter() after the standard base logic.
|
|
467
|
+
*
|
|
468
|
+
* All filter types are supported on the list path.
|
|
469
|
+
*/
|
|
470
|
+
applyDeclarativeListFilters(query, filterParams) {
|
|
471
|
+
const rules = this.config.listFilters;
|
|
472
|
+
if (!Array.isArray(rules) || rules.length === 0)
|
|
473
|
+
return;
|
|
474
|
+
for (const rule of rules) {
|
|
475
|
+
this.applyFilterRule(query, rule, filterParams);
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
/**
|
|
479
|
+
* Applies all rules from config.updateFilters to the query in declaration order.
|
|
480
|
+
* Called at the end of onUpdateFilter() after the standard base logic.
|
|
481
|
+
*
|
|
482
|
+
* Returns the count of rules that actually produced a WHERE clause,
|
|
483
|
+
* which is added to filtersAppliedQty in the caller.
|
|
484
|
+
*
|
|
485
|
+
* 'search', 'dateRange', and 'nullableDateRange' are not valid on the update
|
|
486
|
+
* path — they are skipped with a warning log.
|
|
487
|
+
*/
|
|
488
|
+
applyDeclarativeUpdateFilters(query, filterParams) {
|
|
489
|
+
const rules = this.config.updateFilters;
|
|
490
|
+
if (!Array.isArray(rules) || rules.length === 0)
|
|
491
|
+
return 0;
|
|
492
|
+
let count = 0;
|
|
493
|
+
for (const rule of rules) {
|
|
494
|
+
if (!UPDATE_REMOVE_SUPPORTED_TYPES.has(rule.type)) {
|
|
495
|
+
this.logger.log(`BaseGateway: update filter rule for field "${rule.field}" has unsupported type "${rule.type}" — skipped. ` +
|
|
496
|
+
`Only 'array', 'eq', 'bool', 'nullableBool' are supported on the update path.`);
|
|
497
|
+
continue;
|
|
498
|
+
}
|
|
499
|
+
if (this.applyFilterRule(query, rule, filterParams)) {
|
|
500
|
+
count++;
|
|
501
|
+
}
|
|
502
|
+
}
|
|
503
|
+
return count;
|
|
504
|
+
}
|
|
505
|
+
/**
|
|
506
|
+
* Applies all rules from config.removeFilters to the query in declaration order.
|
|
507
|
+
* Called at the end of onRemoveFilter() after the standard base logic.
|
|
508
|
+
*
|
|
509
|
+
* The remove path operates on castArray(whereParams) — a potentially multi-
|
|
510
|
+
* entry array for bulk removes. For 'array' type rules, values are collected
|
|
511
|
+
* across ALL entries and applied as a single whereIn, consistent with the
|
|
512
|
+
* bulk-remove pattern in PartyGuestGw.onRemoveFilter.
|
|
513
|
+
*
|
|
514
|
+
* For non-array types (eq, bool, nullableBool), only the first entry's value
|
|
515
|
+
* is used, since these filters express single-value constraints that cannot
|
|
516
|
+
* meaningfully be merged across multiple remove targets.
|
|
517
|
+
*
|
|
518
|
+
* Returns the count of rules that actually produced a WHERE clause.
|
|
519
|
+
*
|
|
520
|
+
* 'search', 'dateRange', and 'nullableDateRange' are not valid on the remove
|
|
521
|
+
* path — they are skipped with a warning log.
|
|
522
|
+
*/
|
|
523
|
+
applyDeclarativeRemoveFilters(query, whereParams) {
|
|
524
|
+
const rules = this.config.removeFilters;
|
|
525
|
+
if (!Array.isArray(rules) || rules.length === 0)
|
|
526
|
+
return 0;
|
|
527
|
+
const entries = castArray(whereParams).filter(Boolean);
|
|
528
|
+
let count = 0;
|
|
529
|
+
for (const rule of rules) {
|
|
530
|
+
if (!UPDATE_REMOVE_SUPPORTED_TYPES.has(rule.type)) {
|
|
531
|
+
this.logger.log(`BaseGateway: remove filter rule for field "${rule.field}" has unsupported type "${rule.type}" — skipped. ` +
|
|
532
|
+
`Only 'array', 'eq', 'bool', 'nullableBool' are supported on the remove path.`);
|
|
533
|
+
continue;
|
|
534
|
+
}
|
|
535
|
+
if (rule.type === 'array') {
|
|
536
|
+
// Collect values across all entries for bulk-remove support
|
|
537
|
+
const allValues = [
|
|
538
|
+
...new Set(entries.flatMap((entry) => normaliseToArray(entry?.[rule.field])).filter((v) => v != null && v !== '')),
|
|
539
|
+
];
|
|
540
|
+
if (allValues.length === 0)
|
|
541
|
+
continue;
|
|
542
|
+
if (allValues.length === 1) {
|
|
543
|
+
query.where(rule.column, allValues[0]);
|
|
544
|
+
}
|
|
545
|
+
else {
|
|
546
|
+
query.whereIn(rule.column, allValues);
|
|
547
|
+
}
|
|
548
|
+
count++;
|
|
549
|
+
}
|
|
550
|
+
else {
|
|
551
|
+
// For non-array types use only the first entry's value
|
|
552
|
+
const firstParams = entries[0] ?? {};
|
|
553
|
+
if (this.applyFilterRule(query, rule, firstParams)) {
|
|
554
|
+
count++;
|
|
555
|
+
}
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
return count;
|
|
559
|
+
}
|
|
560
|
+
// ─── ID generation ─────────────────────────────────────────────────────────
|
|
127
561
|
/**
|
|
128
562
|
* Generates a unique ID for a new record.
|
|
129
563
|
*
|
|
@@ -136,13 +570,15 @@ class BaseGateway {
|
|
|
136
570
|
async generateId(_object) {
|
|
137
571
|
return v4();
|
|
138
572
|
}
|
|
573
|
+
// ─── Filter hooks ──────────────────────────────────────────────────────────
|
|
139
574
|
/**
|
|
140
575
|
* Applies WHERE clauses to a list query based on the provided filter params.
|
|
141
576
|
* Called internally by `list()` after the base query is built.
|
|
142
577
|
*
|
|
143
578
|
* Override in subclasses to add resource-specific filters. Always call
|
|
144
579
|
* `super.onListFilter(query, filterParams)` first to preserve the standard
|
|
145
|
-
* filtering behaviour (status, spaceId, lang, keyword, etc.)
|
|
580
|
+
* filtering behaviour (status, spaceId, lang, keyword, etc.) AND to ensure
|
|
581
|
+
* declarative listFilters rules are applied.
|
|
146
582
|
*
|
|
147
583
|
* Built-in filter behaviours (each controlled by a config flag):
|
|
148
584
|
* - `hasStatus` — filters by status; defaults to activeStatuses if
|
|
@@ -152,6 +588,7 @@ class BaseGateway {
|
|
|
152
588
|
* - `hasLang` — filters by language
|
|
153
589
|
* - `fieldForKeyword` — applies a case-insensitive LIKE on the configured field
|
|
154
590
|
* - `filterByUserField` — scopes to the current userId from context
|
|
591
|
+
* - `listFilters` — applies declarative GatewayFilterRule array (new)
|
|
155
592
|
*
|
|
156
593
|
* Nuance: `hasSpace` checks both `filterParams[SPACE_ID]` and
|
|
157
594
|
* `context.spaceId`, preferring the explicit param. If neither is set and
|
|
@@ -185,6 +622,9 @@ class BaseGateway {
|
|
|
185
622
|
if (filterByUserField) {
|
|
186
623
|
query.where({ [filterByUserField]: this.getContext()?.userId });
|
|
187
624
|
}
|
|
625
|
+
// Declarative list filter rules — applied last so subclass super() calls
|
|
626
|
+
// are unaffected and custom overrides always run before declarative rules.
|
|
627
|
+
this.applyDeclarativeListFilters(query, filterParams);
|
|
188
628
|
}
|
|
189
629
|
/**
|
|
190
630
|
* Applies WHERE clauses to an update query based on the provided filter params.
|
|
@@ -201,6 +641,7 @@ class BaseGateway {
|
|
|
201
641
|
* - `hasVersion` — adds an optimistic-lock check on the version field,
|
|
202
642
|
* preventing updates if the version has changed since the record was read
|
|
203
643
|
* - `hasStatus` — excludes already-removed records from being updated
|
|
644
|
+
* - `updateFilters` — applies declarative GatewayFilterRule array (new)
|
|
204
645
|
*/
|
|
205
646
|
async onUpdateFilter(query, filterParams) {
|
|
206
647
|
const { hasStatus, hasVersion } = this.config;
|
|
@@ -225,6 +666,8 @@ class BaseGateway {
|
|
|
225
666
|
query.where(FIELDS.STATUS, '!=', STATUSES.REMOVED);
|
|
226
667
|
}
|
|
227
668
|
}
|
|
669
|
+
// Declarative update filter rules — applied after base logic.
|
|
670
|
+
filtersAppliedQty += this.applyDeclarativeUpdateFilters(query, filterParams);
|
|
228
671
|
return filtersAppliedQty;
|
|
229
672
|
}
|
|
230
673
|
/**
|
|
@@ -243,6 +686,7 @@ class BaseGateway {
|
|
|
243
686
|
* Built-in filter behaviours:
|
|
244
687
|
* - Collects the id field (idFieldUpdateRemove) from each item in filterParams
|
|
245
688
|
* - `hasStatus` — adds a guard to prevent double-removal of already-removed records
|
|
689
|
+
* - `removeFilters` — applies declarative GatewayFilterRule array (new)
|
|
246
690
|
*/
|
|
247
691
|
async onRemoveFilter(query, filterParams) {
|
|
248
692
|
const { hasStatus } = this.config;
|
|
@@ -263,8 +707,27 @@ class BaseGateway {
|
|
|
263
707
|
filtersAppliedQty++;
|
|
264
708
|
query.where(FIELDS.STATUS, '!=', STATUSES.REMOVED);
|
|
265
709
|
}
|
|
710
|
+
// Declarative remove filter rules — applied after base logic.
|
|
711
|
+
filtersAppliedQty += this.applyDeclarativeRemoveFilters(query, filterParams);
|
|
266
712
|
return filtersAppliedQty;
|
|
267
713
|
}
|
|
714
|
+
/**
|
|
715
|
+
* Hook called by count() to apply custom WHERE conditions to the count query.
|
|
716
|
+
*
|
|
717
|
+
* Parallel to onListFilter() — override in subclasses that need filter logic
|
|
718
|
+
* beyond what the declarative countFilters rules can express (OR conditions,
|
|
719
|
+
* subqueries, cross-table joins, etc.).
|
|
720
|
+
*
|
|
721
|
+
* The base implementation is a no-op. Call super.onCountFilter() when
|
|
722
|
+
* overriding so future base-class logic is not silently skipped.
|
|
723
|
+
*
|
|
724
|
+
* @param query Knex query builder for the count query
|
|
725
|
+
* @param filterParams The raw filter object passed to count()
|
|
726
|
+
*/
|
|
727
|
+
onCountFilter(query, filterParams) {
|
|
728
|
+
// no-op — override in subclasses for custom count filter logic
|
|
729
|
+
}
|
|
730
|
+
// ─── Record transforms ─────────────────────────────────────────────────────
|
|
268
731
|
/**
|
|
269
732
|
* Transforms a params object before it is inserted into the database.
|
|
270
733
|
* Called once per object inside the `create()` loop, after the ID is generated.
|
|
@@ -502,68 +965,7 @@ class BaseGateway {
|
|
|
502
965
|
transformOnOut(item) {
|
|
503
966
|
return item;
|
|
504
967
|
}
|
|
505
|
-
|
|
506
|
-
* Returns the requestId from the current ApiContext.
|
|
507
|
-
* Useful for correlating log entries or error reports to a specific request.
|
|
508
|
-
*/
|
|
509
|
-
getRequestId() {
|
|
510
|
-
return this.config.context.requestId;
|
|
511
|
-
}
|
|
512
|
-
/**
|
|
513
|
-
* Returns the full ApiContext associated with this gateway instance.
|
|
514
|
-
* The context carries request-scoped values: userId, spaceId, headers,
|
|
515
|
-
* other gateways, cores, db, etc.
|
|
516
|
-
*/
|
|
517
|
-
getContext() {
|
|
518
|
-
return this.config.context;
|
|
519
|
-
}
|
|
520
|
-
/**
|
|
521
|
-
* Returns all gateway instances from the current request context.
|
|
522
|
-
* Allows one gateway to call another (e.g. UserGateway calling RoleGateway)
|
|
523
|
-
* without going through a core, using the same shared context and db connection.
|
|
524
|
-
*
|
|
525
|
-
* Returns an empty object if context is not available.
|
|
526
|
-
*/
|
|
527
|
-
getGateways() {
|
|
528
|
-
return this.config.context?.gateways || {};
|
|
529
|
-
}
|
|
530
|
-
/**
|
|
531
|
-
* Returns the Database instance from config.
|
|
532
|
-
* All query builders are derived from this instance.
|
|
533
|
-
*/
|
|
534
|
-
getDb() {
|
|
535
|
-
return this.config.db;
|
|
536
|
-
}
|
|
537
|
-
/**
|
|
538
|
-
* Returns a Knex query builder scoped to this gateway's table.
|
|
539
|
-
* The builder is a fresh instance each time — it does not carry state
|
|
540
|
-
* between calls.
|
|
541
|
-
*/
|
|
542
|
-
getBuilder() {
|
|
543
|
-
return this.getDb()?.getBuilder(this.config.table);
|
|
544
|
-
}
|
|
545
|
-
/**
|
|
546
|
-
* Returns the primary key field name used for SELECT and loader operations.
|
|
547
|
-
* Defaults to the global ID_FIELD constant if not set in config.
|
|
548
|
-
*
|
|
549
|
-
* Note: this may differ from `getIdFieldUpdateRemove()` — some tables use
|
|
550
|
-
* a different column for update/delete filtering (e.g. a composite key)
|
|
551
|
-
* while listing and loading still uses the primary key.
|
|
552
|
-
*/
|
|
553
|
-
getIdField() {
|
|
554
|
-
return this.config.idField || ID_FIELD;
|
|
555
|
-
}
|
|
556
|
-
/**
|
|
557
|
-
* Returns the field name used to identify records in UPDATE and DELETE
|
|
558
|
-
* WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
|
|
559
|
-
*
|
|
560
|
-
* Separate from `getIdField()` to support tables where the logical primary
|
|
561
|
-
* key used for loading differs from the column used for writes
|
|
562
|
-
* (e.g. a table with a UUID primary key but a separate "slug" as update target).
|
|
563
|
-
*/
|
|
564
|
-
getIdFieldUpdateRemove() {
|
|
565
|
-
return this.config.idFieldUpdateRemove || this.config.idField || ID_FIELD;
|
|
566
|
-
}
|
|
968
|
+
// ─── Loader operations ─────────────────────────────────────────────────────
|
|
567
969
|
/**
|
|
568
970
|
* Loads a single record by id via the loader (DataCache/DataLoader).
|
|
569
971
|
* Leverages DataLoader batching — multiple `get()` calls within the same
|
|
@@ -586,6 +988,7 @@ class BaseGateway {
|
|
|
586
988
|
async getMany(ids) {
|
|
587
989
|
return this.loader.loadMany(ids);
|
|
588
990
|
}
|
|
991
|
+
// ─── Query building ────────────────────────────────────────────────────────
|
|
589
992
|
/**
|
|
590
993
|
* Builds the base SELECT query for `list()`.
|
|
591
994
|
* Override in subclasses to add JOINs, computed columns, or subqueries
|
|
@@ -606,6 +1009,7 @@ class BaseGateway {
|
|
|
606
1009
|
query.select(fieldsToUse || '*');
|
|
607
1010
|
return { query };
|
|
608
1011
|
}
|
|
1012
|
+
// ─── CRUD operations ───────────────────────────────────────────────────────
|
|
609
1013
|
/**
|
|
610
1014
|
* Fetches a paginated, filtered list of records from the database.
|
|
611
1015
|
*
|
|
@@ -916,5 +1320,88 @@ class BaseGateway {
|
|
|
916
1320
|
}
|
|
917
1321
|
return items.map((item) => this.transformOnOut(item));
|
|
918
1322
|
}
|
|
1323
|
+
/**
|
|
1324
|
+
* Returns the count of non-removed rows matching the given filter.
|
|
1325
|
+
*
|
|
1326
|
+
* Applies the same soft-delete, space, and user scoping that list() uses,
|
|
1327
|
+
* ensuring count() and list() always agree on which rows are "visible" for
|
|
1328
|
+
* an identical filter. Uses COUNT(*) — no column data is read, so this is
|
|
1329
|
+
* as cheap as possible on both PostgreSQL and MS Azure SQL.
|
|
1330
|
+
*
|
|
1331
|
+
* Filter application order (mirrors list()):
|
|
1332
|
+
* 1. Soft-delete guard — WHERE Removed_By IS NULL (when hasRemovedBy)
|
|
1333
|
+
* WHERE Removed_At IS NULL (when hasRemovedAt and
|
|
1334
|
+
* not hasRemovedBy — rare, but handled for safety)
|
|
1335
|
+
* 2. Space scoping — WHERE Space_ID = context.spaceId (if hasSpace)
|
|
1336
|
+
* 3. User scoping — WHERE {filterByUserField} = context.userId (if set)
|
|
1337
|
+
* 4. onCountFilter() hook — subclass custom logic
|
|
1338
|
+
* 5. Declarative rules — countFilters when set, otherwise listFilters
|
|
1339
|
+
*
|
|
1340
|
+
* Subclasses that need count with different scoping than list have two options:
|
|
1341
|
+
* A) Set explicit countFilters in the constructor props.
|
|
1342
|
+
* B) Override onCountFilter() for logic that declarative rules cannot express.
|
|
1343
|
+
*
|
|
1344
|
+
* @param filterParams Filter object (same shape as passed to list())
|
|
1345
|
+
* @returns Row count as a number; 0 when nothing matches or on error
|
|
1346
|
+
*/
|
|
1347
|
+
async count(filterParams) {
|
|
1348
|
+
const query = this.getBuilder().count({ qty: '*' });
|
|
1349
|
+
// ── 1. Soft-delete guard ────────────────────────────────────────────────
|
|
1350
|
+
// In this codebase hasRemovedBy and hasRemovedAt are always set together
|
|
1351
|
+
// on the remove path — Removed_By is the primary sentinel. Guard on
|
|
1352
|
+
// Removed_By IS NULL first; fall back to Removed_At IS NULL for tables
|
|
1353
|
+
// that have a timestamp column but no author column (uncommon but valid).
|
|
1354
|
+
if (this.config.hasRemovedBy) {
|
|
1355
|
+
query.whereNull(`${this.config.table}.${FIELDS.REMOVED_BY}`);
|
|
1356
|
+
}
|
|
1357
|
+
else if (this.config.hasRemovedAt) {
|
|
1358
|
+
query.whereNull(`${this.config.table}.${FIELDS.REMOVED_AT}`);
|
|
1359
|
+
}
|
|
1360
|
+
// ── 2. Space scoping ────────────────────────────────────────────────────
|
|
1361
|
+
if (this.config.hasSpace && this.config.context?.spaceId) {
|
|
1362
|
+
query.where(`${this.config.table}.${FIELDS.SPACE_ID}`, this.config.context.spaceId);
|
|
1363
|
+
}
|
|
1364
|
+
// ── 3. User scoping ─────────────────────────────────────────────────────
|
|
1365
|
+
if (this.config.filterByUserField && this.config.context?.userId) {
|
|
1366
|
+
query.where(`${this.config.table}.${this.config.filterByUserField}`, this.config.context.userId);
|
|
1367
|
+
}
|
|
1368
|
+
// ── 4. Subclass hook ────────────────────────────────────────────────────
|
|
1369
|
+
this.onCountFilter(query, filterParams);
|
|
1370
|
+
// ── 5. Declarative filter rules ─────────────────────────────────────────
|
|
1371
|
+
// Fall back to listFilters when countFilters is not explicitly configured.
|
|
1372
|
+
// This means gateways that already declare listFilters get count() for free
|
|
1373
|
+
// with no changes required.
|
|
1374
|
+
const rulesToApply = this.config.countFilters ?? this.config.listFilters ?? [];
|
|
1375
|
+
for (const rule of rulesToApply) {
|
|
1376
|
+
this.applyFilterRule(query, rule, filterParams);
|
|
1377
|
+
}
|
|
1378
|
+
this.logger.debug(`Executing count on table "${this.config.table}"`);
|
|
1379
|
+
const result = camelResponse(await query);
|
|
1380
|
+
const qty = result?.[0]?.qty;
|
|
1381
|
+
if (qty == null) {
|
|
1382
|
+
this.logger.log(`Count query on "${this.config.table}" returned no result row — defaulting to 0`);
|
|
1383
|
+
return 0;
|
|
1384
|
+
}
|
|
1385
|
+
return Number(qty);
|
|
1386
|
+
}
|
|
919
1387
|
}
|
|
920
1388
|
export { BaseGateway };
|
|
1389
|
+
// ─── Module-level helpers ──────────────────────────────────────────────────────
|
|
1390
|
+
/**
|
|
1391
|
+
* Normalises a scalar or array value into a non-empty any[].
|
|
1392
|
+
*
|
|
1393
|
+
* Rules:
|
|
1394
|
+
* - null / undefined → []
|
|
1395
|
+
* - '' (empty string) → []
|
|
1396
|
+
* - scalar → [scalar]
|
|
1397
|
+
* - array → filtered to remove null / undefined / '' entries
|
|
1398
|
+
*
|
|
1399
|
+
* Kept module-private — callers use the protected gateway methods instead.
|
|
1400
|
+
* Not exported because nothing outside this file needs direct access.
|
|
1401
|
+
*/
|
|
1402
|
+
function normaliseToArray(value) {
|
|
1403
|
+
if (value == null)
|
|
1404
|
+
return [];
|
|
1405
|
+
const arr = Array.isArray(value) ? value : [value];
|
|
1406
|
+
return arr.filter((v) => v != null && v !== '');
|
|
1407
|
+
}
|