@sdflc/backend-helpers 1.0.112 → 1.0.114
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 +1422 -146
- package/build/BaseController.d.ts +20 -0
- package/build/BaseController.js +64 -0
- package/build/BaseCore.d.ts +586 -33
- package/build/BaseCore.js +821 -127
- package/build/BaseExternalApiGateway.d.ts +16 -0
- package/build/BaseExternalApiGateway.js +54 -0
- package/build/BaseGateway.d.ts +455 -17
- package/build/BaseGateway.js +502 -56
- package/build/BaseRestApiCrudController.d.ts +37 -0
- package/build/BaseRestApiCrudController.js +134 -0
- package/build/DataCache.d.ts +116 -5
- package/build/DataCache.js +144 -22
- package/build/Database.d.ts +165 -4
- package/build/Database.js +224 -51
- package/build/DbMigratorAndSeeder.d.ts +127 -26
- package/build/DbMigratorAndSeeder.js +180 -69
- package/build/IpRateLimiter.d.ts +105 -0
- package/build/IpRateLimiter.js +104 -0
- package/build/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +30 -32
- package/build/checkItHelpers.d.ts +32 -0
- package/build/checkItHelpers.js +73 -7
- package/build/commonValidators.d.ts +107 -16
- package/build/commonValidators.js +211 -106
- package/build/configBuilder.d.ts +23 -0
- package/build/configBuilder.js +73 -0
- package/build/constants.d.ts +134 -17
- package/build/constants.js +95 -15
- package/build/dbHelpers.d.ts +89 -29
- package/build/dbHelpers.js +175 -86
- package/build/dbSeeder.d.ts +10 -1
- package/build/dbSeeder.js +80 -15
- package/build/dbTableHelpers.d.ts +122 -5
- package/build/dbTableHelpers.js +151 -13
- package/build/downloadHelpers.d.ts +24 -1
- package/build/downloadHelpers.js +51 -21
- package/build/esm/BaseController.d.ts +20 -0
- package/build/esm/BaseController.js +58 -0
- package/build/esm/BaseCore.d.ts +586 -33
- package/build/esm/BaseCore.js +812 -118
- package/build/esm/BaseExternalApiGateway.d.ts +16 -0
- package/build/esm/BaseExternalApiGateway.js +48 -0
- package/build/esm/BaseGateway.d.ts +455 -17
- package/build/esm/BaseGateway.js +503 -57
- package/build/esm/BaseRestApiCrudController.d.ts +37 -0
- package/build/esm/BaseRestApiCrudController.js +131 -0
- package/build/esm/DataCache.d.ts +116 -5
- package/build/esm/DataCache.js +142 -20
- package/build/esm/Database.d.ts +165 -4
- package/build/esm/Database.js +224 -51
- package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
- package/build/esm/DbMigratorAndSeeder.js +184 -71
- package/build/esm/IpRateLimiter.d.ts +105 -0
- package/build/esm/IpRateLimiter.js +100 -0
- package/build/esm/RedisDataLoader.d.ts +144 -21
- package/build/esm/RedisDataLoader.js +179 -50
- package/build/esm/apiContext.d.ts +0 -8
- package/build/esm/apiContext.js +30 -32
- package/build/esm/checkItHelpers.d.ts +32 -0
- package/build/esm/checkItHelpers.js +73 -7
- package/build/esm/commonValidators.d.ts +107 -16
- package/build/esm/commonValidators.js +209 -105
- package/build/esm/configBuilder.d.ts +23 -0
- package/build/esm/configBuilder.js +69 -0
- package/build/esm/constants.d.ts +134 -17
- package/build/esm/constants.js +94 -14
- package/build/esm/dbHelpers.d.ts +89 -29
- package/build/esm/dbHelpers.js +171 -81
- package/build/esm/dbSeeder.d.ts +10 -1
- package/build/esm/dbSeeder.js +81 -16
- package/build/esm/dbTableHelpers.d.ts +122 -5
- package/build/esm/dbTableHelpers.js +152 -14
- package/build/esm/downloadHelpers.d.ts +24 -1
- package/build/esm/downloadHelpers.js +51 -21
- package/build/esm/index.d.ts +6 -2
- package/build/esm/index.js +6 -2
- package/build/esm/interfaces/ApiContext.d.ts +33 -3
- package/build/esm/interfaces/ApiContext.js +1 -0
- package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
- package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/esm/interfaces/BuildConfigOptions.js +1 -0
- package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/esm/interfaces/CacheInterface.d.ts +18 -1
- package/build/esm/interfaces/CacheInterface.js +1 -0
- package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/esm/interfaces/CoreActionInterface.js +1 -0
- package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
- package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/esm/interfaces/DatabaseOptions.js +1 -0
- package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
- package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/esm/interfaces/ListArgsInterface.js +1 -0
- package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
- package/build/esm/interfaces/LoaderInterface.js +1 -0
- package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
- package/build/esm/interfaces/UserTokenParams.js +1 -0
- package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/esm/interfaces/index.d.ts +4 -0
- package/build/esm/interfaces/index.js +4 -0
- package/build/esm/knexConfigBuilder.d.ts +25 -0
- package/build/esm/knexConfigBuilder.js +100 -36
- package/build/esm/parseIds.d.ts +6 -0
- package/build/esm/parseIds.js +13 -0
- package/build/esm/passwordHelpers.d.ts +22 -0
- package/build/esm/passwordHelpers.js +40 -8
- package/build/esm/redisClient.d.ts +57 -4
- package/build/esm/redisClient.js +40 -54
- package/build/esm/resolveClientIp.d.ts +15 -0
- package/build/esm/resolveClientIp.js +34 -0
- package/build/esm/resolversHelpers.d.ts +21 -1
- package/build/esm/resolversHelpers.js +48 -26
- package/build/esm/userToken.d.ts +50 -1
- package/build/esm/userToken.js +85 -20
- package/build/esm/utils.d.ts +20 -2
- package/build/esm/utils.js +23 -13
- package/build/index.d.ts +6 -2
- package/build/index.js +6 -2
- package/build/interfaces/ApiContext.d.ts +33 -3
- package/build/interfaces/ApiContext.js +1 -0
- package/build/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/interfaces/BaseControllerPropsInterface.js +2 -0
- package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
- package/build/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/interfaces/BuildConfigOptions.js +1 -0
- package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/interfaces/CacheInterface.d.ts +18 -1
- package/build/interfaces/CacheInterface.js +1 -0
- package/build/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/interfaces/CoreActionInterface.js +1 -0
- package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/interfaces/DataCachePropsInterface.js +3 -0
- package/build/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/interfaces/DatabaseOptions.js +1 -0
- package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/interfaces/DatabaseReadInterface.js +1 -0
- package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/interfaces/ListArgsInterface.js +1 -0
- package/build/interfaces/LoaderInterface.d.ts +36 -1
- package/build/interfaces/LoaderInterface.js +1 -0
- package/build/interfaces/UserTokenParams.d.ts +23 -5
- package/build/interfaces/UserTokenParams.js +1 -0
- package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/interfaces/index.d.ts +4 -0
- package/build/interfaces/index.js +4 -0
- package/build/knexConfigBuilder.d.ts +25 -0
- package/build/knexConfigBuilder.js +99 -35
- package/build/parseIds.d.ts +6 -0
- package/build/parseIds.js +17 -0
- package/build/passwordHelpers.d.ts +22 -0
- package/build/passwordHelpers.js +40 -8
- package/build/redisClient.d.ts +57 -4
- package/build/redisClient.js +40 -54
- package/build/resolveClientIp.d.ts +15 -0
- package/build/resolveClientIp.js +38 -0
- package/build/resolversHelpers.d.ts +21 -1
- package/build/resolversHelpers.js +48 -26
- package/build/userToken.d.ts +50 -1
- package/build/userToken.js +85 -20
- package/build/utils.d.ts +20 -2
- package/build/utils.js +24 -16
- package/package.json +19 -18
- package/build/baseController.d.ts +0 -17
- package/build/baseController.js +0 -64
- package/build/configBulder.d.ts +0 -2
- package/build/configBulder.js +0 -36
- package/build/esm/baseController.d.ts +0 -17
- package/build/esm/baseController.js +0 -58
- package/build/esm/configBulder.d.ts +0 -2
- package/build/esm/configBulder.js +0 -32
package/build/esm/BaseGateway.js
CHANGED
|
@@ -1,90 +1,208 @@
|
|
|
1
|
+
// ./src/BaseGateway.ts
|
|
1
2
|
import { v4 } from 'uuid';
|
|
2
3
|
import dayjs from 'dayjs';
|
|
3
4
|
import check from 'check-types';
|
|
4
5
|
import { camelCase, castArray, pullAll } from 'lodash';
|
|
5
|
-
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels } from '@sdflc/utils';
|
|
6
|
+
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels, isLogger } from '@sdflc/utils';
|
|
6
7
|
import { DataCache } from './DataCache';
|
|
7
8
|
import { FIELDS, ID_FIELD } from './constants';
|
|
8
9
|
const DEFAULT_CHUNCK_SIZE = 2500;
|
|
10
|
+
/**
|
|
11
|
+
* BaseGateway is the foundation for all database-backed gateway classes.
|
|
12
|
+
*
|
|
13
|
+
* A gateway is a low-level data-access object responsible for a single
|
|
14
|
+
* database table. It handles CRUD operations, cache management, soft-delete
|
|
15
|
+
* patterns, field transforms, and query filtering.
|
|
16
|
+
*
|
|
17
|
+
* Gateways are instantiated per-request — they receive a full ApiContext
|
|
18
|
+
* (including db, spaceId, userId etc.) at construction time and must not
|
|
19
|
+
* be reused across requests. This is critical because `dateTimeNow` and all
|
|
20
|
+
* context-derived values (userId, spaceId) are snapshotted at construction.
|
|
21
|
+
*
|
|
22
|
+
* Subclasses typically override:
|
|
23
|
+
* - `onListFilter()` — to add resource-specific WHERE clauses
|
|
24
|
+
* - `onUpdateFilter()` — to add resource-specific update conditions
|
|
25
|
+
* - `onRemoveFilter()` — to add resource-specific remove conditions
|
|
26
|
+
* - `transformOnOut()` — to shape outbound records (e.g. rename fields,
|
|
27
|
+
* attach computed properties)
|
|
28
|
+
* - `generateId()` — to use a domain-specific ID strategy
|
|
29
|
+
*
|
|
30
|
+
* The loader (DataCache by default) is used for batched per-id loading
|
|
31
|
+
* via DataLoader semantics. It is bypassed when `noCache: true` is set in
|
|
32
|
+
* config, or when `list()` is called with `useCache: false`.
|
|
33
|
+
*/
|
|
9
34
|
class BaseGateway {
|
|
10
35
|
config;
|
|
11
36
|
logger;
|
|
12
37
|
loader;
|
|
13
38
|
dateTime = new DateTimeHelpers();
|
|
39
|
+
/**
|
|
40
|
+
* Timestamp captured at construction time. Used as the value for
|
|
41
|
+
* createdAt / updatedAt / removedAt fields so that all writes within
|
|
42
|
+
* a single request share the same timestamp.
|
|
43
|
+
*
|
|
44
|
+
* IMPORTANT: This is set once at instantiation — gateways must be
|
|
45
|
+
* created per-request. Reusing a gateway instance across requests will
|
|
46
|
+
* result in stale timestamps being written to the database.
|
|
47
|
+
*/
|
|
14
48
|
dateTimeNow = new Date();
|
|
15
49
|
constructor(props) {
|
|
16
50
|
this.config = props;
|
|
51
|
+
// Normalise returnFields — default to ['*'] if not provided or empty.
|
|
52
|
+
// returnFields controls which columns are included in INSERT/UPDATE RETURNING clauses.
|
|
17
53
|
this.config.returnFields =
|
|
18
54
|
Array.isArray(this.config.returnFields) && this.config.returnFields.length > 0 ? this.config.returnFields : ['*'];
|
|
55
|
+
// Normalise activeStatuses — used by onListFilter when no explicit status
|
|
56
|
+
// filter is provided in the query params.
|
|
19
57
|
this.config.activeStatuses = Array.isArray(this.config.activeStatuses)
|
|
20
58
|
? this.config.activeStatuses
|
|
21
59
|
: [STATUSES.ACTIVE];
|
|
60
|
+
// keyPrefix is used to namespace DataLoader cache keys. It falls back through
|
|
61
|
+
// context.keyPrefix → config.keyPrefix → table name, in that order.
|
|
22
62
|
this.config.keyPrefix = this.config.context?.keyPrefix || this.config.keyPrefix || this.config.table;
|
|
63
|
+
// Enforce uniqueness of keyPrefix within a single request context.
|
|
64
|
+
// Two gateways with the same keyPrefix would share a DataLoader cache,
|
|
65
|
+
// causing one gateway's cached records to be returned for another's queries.
|
|
23
66
|
if (this.config.keyPrefix && this.config.context?.usedKeyPrefixes) {
|
|
24
67
|
if (this.config.context.usedKeyPrefixes[this.config.keyPrefix]) {
|
|
25
|
-
throw new Error(`The "${this.config.keyPrefix}" is already used as the "keyPrefix" in the application.
|
|
68
|
+
throw new Error(`The "${this.config.keyPrefix}" is already used as the "keyPrefix" in the application. ` +
|
|
69
|
+
`Please use another one that is not: ${Object.keys(this.config.context.usedKeyPrefixes).join(', ')}`);
|
|
26
70
|
}
|
|
27
71
|
this.config.context.usedKeyPrefixes[this.config.keyPrefix] = true;
|
|
28
72
|
}
|
|
29
|
-
|
|
73
|
+
// Duck-type check instead of instanceof to avoid false negatives when
|
|
74
|
+
// the consuming app has a different installed version of @sdflc/utils,
|
|
75
|
+
// which would produce a different Logger class reference.
|
|
76
|
+
this.logger = props?.logger && isLogger(props?.logger) ? props.logger : new Logger({ level: LoggerLevels.WARNING });
|
|
77
|
+
// If a custom loader function is provided in config, use it directly.
|
|
78
|
+
// Otherwise fall back to the default DataCache, which wraps DataLoader
|
|
79
|
+
// for batched, per-request in-memory caching.
|
|
30
80
|
this.loader = check.function(this.config?.loader) ? this.config.loader : new DataCache(this.config);
|
|
31
81
|
}
|
|
82
|
+
/**
|
|
83
|
+
* Returns the full gateway config object.
|
|
84
|
+
* Useful for subclasses or external code that needs to inspect configuration
|
|
85
|
+
* without accessing protected fields directly.
|
|
86
|
+
*/
|
|
32
87
|
getConfig() {
|
|
33
88
|
return this.config;
|
|
34
89
|
}
|
|
90
|
+
/**
|
|
91
|
+
* Merges the provided props into the existing config.
|
|
92
|
+
* Allows runtime config changes (e.g. swapping the table, adjusting chunk size)
|
|
93
|
+
* without recreating the gateway.
|
|
94
|
+
*
|
|
95
|
+
* Returns `this` for chaining.
|
|
96
|
+
*/
|
|
35
97
|
setConfigPart(props) {
|
|
36
98
|
Object.assign(this.config, props);
|
|
37
99
|
return this;
|
|
38
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* Replaces the loader used for `get()` and `getMany()` calls.
|
|
103
|
+
* The loader must implement the `LoaderInterface` (i.e. `load` and `loadMany`).
|
|
104
|
+
*
|
|
105
|
+
* Use this to inject a custom DataLoader, a mock in tests, or a loader
|
|
106
|
+
* backed by a different cache layer (Redis, etc.).
|
|
107
|
+
*
|
|
108
|
+
* Returns `this` for chaining.
|
|
109
|
+
*/
|
|
39
110
|
setLoader(loader) {
|
|
40
111
|
this.loader = loader;
|
|
41
112
|
return this;
|
|
42
113
|
}
|
|
114
|
+
/**
|
|
115
|
+
* Replaces the loader with a new DataCache instance built from the
|
|
116
|
+
* provided cache config merged with the existing gateway config.
|
|
117
|
+
*
|
|
118
|
+
* Use this when you want to adjust caching behaviour (TTL, batch size, etc.)
|
|
119
|
+
* without providing a fully custom loader.
|
|
120
|
+
*
|
|
121
|
+
* Returns `this` for chaining.
|
|
122
|
+
*/
|
|
43
123
|
setLoaderConfig(config) {
|
|
44
124
|
this.loader = new DataCache({ ...this.config, ...config });
|
|
45
125
|
return this;
|
|
46
126
|
}
|
|
47
127
|
/**
|
|
48
|
-
* Generates
|
|
49
|
-
*
|
|
50
|
-
*
|
|
128
|
+
* Generates a unique ID for a new record.
|
|
129
|
+
*
|
|
130
|
+
* Defaults to UUID v4. Override in a subclass to use a different ID
|
|
131
|
+
* strategy (e.g. nanoid, sequential IDs, composite keys).
|
|
132
|
+
*
|
|
133
|
+
* The `object` parameter is the record about to be inserted — it is
|
|
134
|
+
* available in case the ID needs to be derived from the object's data.
|
|
51
135
|
*/
|
|
52
|
-
async generateId(
|
|
136
|
+
async generateId(_object) {
|
|
53
137
|
return v4();
|
|
54
138
|
}
|
|
139
|
+
/**
|
|
140
|
+
* Applies WHERE clauses to a list query based on the provided filter params.
|
|
141
|
+
* Called internally by `list()` after the base query is built.
|
|
142
|
+
*
|
|
143
|
+
* Override in subclasses to add resource-specific filters. Always call
|
|
144
|
+
* `super.onListFilter(query, filterParams)` first to preserve the standard
|
|
145
|
+
* filtering behaviour (status, spaceId, lang, keyword, etc.).
|
|
146
|
+
*
|
|
147
|
+
* Built-in filter behaviours (each controlled by a config flag):
|
|
148
|
+
* - `hasStatus` — filters by status; defaults to activeStatuses if
|
|
149
|
+
* no status param is provided
|
|
150
|
+
* - `hasRemovedAt` — excludes soft-deleted records (removedAt IS NULL)
|
|
151
|
+
* - `hasSpace` — scopes to the current spaceId from context or params
|
|
152
|
+
* - `hasLang` — filters by language
|
|
153
|
+
* - `fieldForKeyword` — applies a case-insensitive LIKE on the configured field
|
|
154
|
+
* - `filterByUserField` — scopes to the current userId from context
|
|
155
|
+
*
|
|
156
|
+
* Nuance: `hasSpace` checks both `filterParams[SPACE_ID]` and
|
|
157
|
+
* `context.spaceId`, preferring the explicit param. If neither is set and
|
|
158
|
+
* `hasSpace` is true, the filter is skipped entirely — no space scoping.
|
|
159
|
+
*/
|
|
55
160
|
async onListFilter(query, filterParams) {
|
|
56
161
|
const { table, hasStatus, hasRemovedAt, hasSpace, activeStatuses, hasLang, fieldForKeyword, filterByUserField } = this.config || {};
|
|
57
|
-
// This function should be overriden
|
|
58
162
|
if (hasStatus) {
|
|
59
163
|
query.whereIn(`${table}.${FIELDS.STATUS}`, filterParams?.[FIELDS.STATUS] != null ? castArray(filterParams?.[FIELDS.STATUS]) : castArray(activeStatuses));
|
|
60
164
|
}
|
|
61
165
|
if (hasRemovedAt) {
|
|
62
166
|
query.whereNull(`${table}.${FIELDS.REMOVED_AT}`);
|
|
63
167
|
}
|
|
64
|
-
if (hasSpace && (filterParams?.[FIELDS.SPACE_ID] != undefined || this.config.context
|
|
168
|
+
if (hasSpace && (filterParams?.[FIELDS.SPACE_ID] != undefined || this.config.context?.spaceId)) {
|
|
65
169
|
query.where({
|
|
66
|
-
[`${table}.${FIELDS.SPACE_ID}`]: filterParams?.[FIELDS.SPACE_ID] != undefined ? filterParams?.[FIELDS.SPACE_ID] : this.config.context
|
|
170
|
+
[`${table}.${FIELDS.SPACE_ID}`]: filterParams?.[FIELDS.SPACE_ID] != undefined ? filterParams?.[FIELDS.SPACE_ID] : this.config.context?.spaceId,
|
|
67
171
|
});
|
|
68
172
|
}
|
|
69
173
|
if (hasLang && filterParams?.[FIELDS.LANG] != undefined) {
|
|
70
174
|
query.whereIn(`${table}.${FIELDS.LANG}`, castArray(filterParams?.[FIELDS.LANG]));
|
|
71
175
|
}
|
|
176
|
+
// Allow filtering by the id field directly in filterParams.
|
|
177
|
+
// Supports both simple column names and qualified names (table.column).
|
|
72
178
|
const idField = this.getIdField();
|
|
73
179
|
if (filterParams?.[idField]) {
|
|
74
|
-
query.whereIn(idField.includes('.') ?
|
|
180
|
+
query.whereIn(idField.includes('.') ? idField : `${table}.${idField}`, castArray(filterParams?.[idField]));
|
|
75
181
|
}
|
|
76
182
|
if (fieldForKeyword && filterParams.keyword) {
|
|
77
|
-
// const opLike = this.getDb().getDbType() === 'pg' ? 'ILIKE' : 'LIKE';
|
|
78
|
-
// query.whereRaw(`?? ${opLike} ?`, [fieldForKeyword, `%${filterParams.keyword}%`]);
|
|
79
183
|
query.whereILike(fieldForKeyword, `%${filterParams.keyword}%`);
|
|
80
184
|
}
|
|
81
185
|
if (filterByUserField) {
|
|
82
|
-
query.where({ [filterByUserField]: this.getContext()
|
|
186
|
+
query.where({ [filterByUserField]: this.getContext()?.userId });
|
|
83
187
|
}
|
|
84
|
-
// TODO: prse filterParams and buils where clause automatically here
|
|
85
188
|
}
|
|
189
|
+
/**
|
|
190
|
+
* Applies WHERE clauses to an update query based on the provided filter params.
|
|
191
|
+
* Called internally by `update()` after the UPDATE statement is prepared.
|
|
192
|
+
*
|
|
193
|
+
* Returns the number of filter conditions applied. If this is 0, `update()`
|
|
194
|
+
* will throw to prevent an unfiltered UPDATE from affecting all rows.
|
|
195
|
+
*
|
|
196
|
+
* Override in subclasses to add resource-specific update conditions.
|
|
197
|
+
* Always call `super.onUpdateFilter()` first.
|
|
198
|
+
*
|
|
199
|
+
* Built-in filter behaviours:
|
|
200
|
+
* - Always filters by the id field (idFieldUpdateRemove) when present
|
|
201
|
+
* - `hasVersion` — adds an optimistic-lock check on the version field,
|
|
202
|
+
* preventing updates if the version has changed since the record was read
|
|
203
|
+
* - `hasStatus` — excludes already-removed records from being updated
|
|
204
|
+
*/
|
|
86
205
|
async onUpdateFilter(query, filterParams) {
|
|
87
|
-
// This function should be overriden
|
|
88
206
|
const { hasStatus, hasVersion } = this.config;
|
|
89
207
|
const idName = this.getIdFieldUpdateRemove();
|
|
90
208
|
let filtersAppliedQty = 0;
|
|
@@ -109,14 +227,30 @@ class BaseGateway {
|
|
|
109
227
|
}
|
|
110
228
|
return filtersAppliedQty;
|
|
111
229
|
}
|
|
230
|
+
/**
|
|
231
|
+
* Applies WHERE clauses to a remove query based on the provided filter params.
|
|
232
|
+
* Called internally by `remove()` after the DELETE/UPDATE statement is prepared.
|
|
233
|
+
*
|
|
234
|
+
* Returns the number of filter conditions applied. If this is 0, `remove()`
|
|
235
|
+
* will throw to prevent an unfiltered DELETE or soft-delete UPDATE.
|
|
236
|
+
*
|
|
237
|
+
* `filterParams` can be a single object or an array of objects. The method
|
|
238
|
+
* collects the id field value from each entry and applies a single whereIn.
|
|
239
|
+
*
|
|
240
|
+
* Override in subclasses to add resource-specific remove conditions.
|
|
241
|
+
* Always call `super.onRemoveFilter()` first.
|
|
242
|
+
*
|
|
243
|
+
* Built-in filter behaviours:
|
|
244
|
+
* - Collects the id field (idFieldUpdateRemove) from each item in filterParams
|
|
245
|
+
* - `hasStatus` — adds a guard to prevent double-removal of already-removed records
|
|
246
|
+
*/
|
|
112
247
|
async onRemoveFilter(query, filterParams) {
|
|
113
|
-
// This function should be overriden
|
|
114
248
|
const { hasStatus } = this.config;
|
|
115
249
|
const arr = filterParams ? castArray(filterParams) : [];
|
|
116
250
|
let filtersAppliedQty = 0;
|
|
117
251
|
const idName = this.getIdFieldUpdateRemove();
|
|
118
252
|
const ids = [];
|
|
119
|
-
for (
|
|
253
|
+
for (const filter of arr) {
|
|
120
254
|
if (filter[idName]) {
|
|
121
255
|
ids.push(filter[idName]);
|
|
122
256
|
}
|
|
@@ -131,6 +265,27 @@ class BaseGateway {
|
|
|
131
265
|
}
|
|
132
266
|
return filtersAppliedQty;
|
|
133
267
|
}
|
|
268
|
+
/**
|
|
269
|
+
* Transforms a params object before it is inserted into the database.
|
|
270
|
+
* Called once per object inside the `create()` loop, after the ID is generated.
|
|
271
|
+
*
|
|
272
|
+
* Mutates and returns the params object. Override in subclasses to add
|
|
273
|
+
* computed fields, enforce defaults, or validate data before insert.
|
|
274
|
+
* Always call `super.transformOnCreate(params)` first.
|
|
275
|
+
*
|
|
276
|
+
* Built-in transformations (each controlled by a config flag):
|
|
277
|
+
* - `hasCreatedAt` — sets createdAt to the gateway's construction timestamp
|
|
278
|
+
* - `hasCreatedBy` — sets createdBy to context.userId if not already set
|
|
279
|
+
* - `hasUserId` — sets userId to context.userId if not already set
|
|
280
|
+
* - `hasSpace` — sets spaceId from context (always overwritten)
|
|
281
|
+
* - `hasVersion` — initialises version to 0
|
|
282
|
+
* - `hasLang` + `localizationForField` — builds a composite id from the
|
|
283
|
+
* localisation field value and the lang field (e.g. "slug_en")
|
|
284
|
+
*
|
|
285
|
+
* Nuance: createdBy and userId are only set if not already present in params,
|
|
286
|
+
* allowing the caller to supply an explicit value (e.g. when migrating data).
|
|
287
|
+
* spaceId, by contrast, is always overwritten from context to prevent spoofing.
|
|
288
|
+
*/
|
|
134
289
|
async transformOnCreate(params) {
|
|
135
290
|
const { hasCreatedAt, hasCreatedBy, hasSpace, hasVersion, hasLang, localizationForField, hasUserId } = this.config;
|
|
136
291
|
if (hasCreatedAt) {
|
|
@@ -139,17 +294,17 @@ class BaseGateway {
|
|
|
139
294
|
if (hasCreatedBy) {
|
|
140
295
|
const createdBy = camelCase(FIELDS.CREATED_BY);
|
|
141
296
|
if (params[createdBy] === undefined) {
|
|
142
|
-
params[createdBy] = this.getContext()
|
|
297
|
+
params[createdBy] = this.getContext()?.userId;
|
|
143
298
|
}
|
|
144
299
|
}
|
|
145
300
|
if (hasUserId) {
|
|
146
301
|
const userId = camelCase(FIELDS.USER_ID);
|
|
147
302
|
if (params[userId] === undefined) {
|
|
148
|
-
params[userId] = this.getContext()
|
|
303
|
+
params[userId] = this.getContext()?.userId;
|
|
149
304
|
}
|
|
150
305
|
}
|
|
151
306
|
if (hasSpace) {
|
|
152
|
-
params[camelCase(FIELDS.SPACE_ID)] = this.getContext()
|
|
307
|
+
params[camelCase(FIELDS.SPACE_ID)] = this.getContext()?.spaceId;
|
|
153
308
|
}
|
|
154
309
|
if (hasVersion) {
|
|
155
310
|
params[camelCase(FIELDS.VERSION)] = 0;
|
|
@@ -159,6 +314,29 @@ class BaseGateway {
|
|
|
159
314
|
}
|
|
160
315
|
return params;
|
|
161
316
|
}
|
|
317
|
+
/**
|
|
318
|
+
* Transforms a params object before it is applied as an UPDATE in the database.
|
|
319
|
+
* Called by `update()`, `increment()`, and `decrement()` before the query runs.
|
|
320
|
+
*
|
|
321
|
+
* Mutates and returns the params object. Override in subclasses to add
|
|
322
|
+
* computed fields or enforce constraints before update.
|
|
323
|
+
* Always call `super.transformOnUpdate(params, where)` first.
|
|
324
|
+
*
|
|
325
|
+
* The `where` parameter carries the filter criteria (including the id) and is
|
|
326
|
+
* available for subclasses that need to derive update values from the filter.
|
|
327
|
+
*
|
|
328
|
+
* Built-in transformations:
|
|
329
|
+
* - `hasUpdatedAt` — sets updatedAt to the gateway's construction timestamp
|
|
330
|
+
* - `hasUpdatedBy` — sets updatedBy to context.userId if not already set
|
|
331
|
+
* - `hasVersion` — increments version by 1 (only if version is present
|
|
332
|
+
* and numeric in params; no-op otherwise)
|
|
333
|
+
* - `hasLang` + `localizationForField` — rebuilds the composite id from the
|
|
334
|
+
* localisation field value and lang (same logic as transformOnCreate)
|
|
335
|
+
*
|
|
336
|
+
* Nuance: version increment only fires if the version is already present in
|
|
337
|
+
* params. This allows callers to explicitly omit version management when needed
|
|
338
|
+
* (e.g. admin operations that should not bump the version).
|
|
339
|
+
*/
|
|
162
340
|
async transformOnUpdate(params, where) {
|
|
163
341
|
const { hasUpdatedAt, hasUpdatedBy, hasVersion, hasLang, localizationForField } = this.config;
|
|
164
342
|
if (hasUpdatedAt) {
|
|
@@ -167,7 +345,7 @@ class BaseGateway {
|
|
|
167
345
|
if (hasUpdatedBy) {
|
|
168
346
|
const updatedBy = camelCase(FIELDS.UPDATED_BY);
|
|
169
347
|
if (params[updatedBy] === undefined) {
|
|
170
|
-
params[updatedBy] = this.getContext()
|
|
348
|
+
params[updatedBy] = this.getContext()?.userId;
|
|
171
349
|
}
|
|
172
350
|
}
|
|
173
351
|
if (hasVersion) {
|
|
@@ -181,6 +359,31 @@ class BaseGateway {
|
|
|
181
359
|
}
|
|
182
360
|
return params;
|
|
183
361
|
}
|
|
362
|
+
/**
|
|
363
|
+
* Transforms a params object before it is applied as an upsert (INSERT ... ON CONFLICT MERGE).
|
|
364
|
+
* Called by `set()` for each object before the batch is inserted.
|
|
365
|
+
*
|
|
366
|
+
* This is a superset of both `transformOnCreate` and `transformOnUpdate`:
|
|
367
|
+
* it applies creation fields (createdAt, createdBy, spaceId) AND update fields
|
|
368
|
+
* (updatedAt, updatedBy) in a single pass, making it suitable for upserts where
|
|
369
|
+
* you don't know in advance whether the record already exists.
|
|
370
|
+
*
|
|
371
|
+
* Mutates and returns the params object. Override in subclasses as needed.
|
|
372
|
+
* Always call `super.transformOnSet(params)` first.
|
|
373
|
+
*
|
|
374
|
+
* Built-in transformations:
|
|
375
|
+
* - `hasCreatedAt` — sets createdAt (will be skipped in the ON CONFLICT
|
|
376
|
+
* MERGE clause via skipFields — existing records keep
|
|
377
|
+
* their original createdAt)
|
|
378
|
+
* - `hasCreatedBy` — sets createdBy if not already set (also skipped on merge)
|
|
379
|
+
* - `hasUserId` — sets userId if not already set
|
|
380
|
+
* - `hasSpace` — sets spaceId (also skipped on merge)
|
|
381
|
+
* - `hasUpdatedAt` — sets updatedAt (always merged on conflict)
|
|
382
|
+
* - `hasUpdatedBy` — sets updatedBy if not already set
|
|
383
|
+
* - `hasVersion` — increments version if present and numeric,
|
|
384
|
+
* otherwise initialises to 0 (create path)
|
|
385
|
+
* - `hasLang` + `localizationForField` — builds composite id from localisation field + lang
|
|
386
|
+
*/
|
|
184
387
|
async transformOnSet(params) {
|
|
185
388
|
const { hasCreatedAt, hasCreatedBy, hasSpace, hasUpdatedAt, hasUpdatedBy, hasVersion, hasLang, localizationForField, hasUserId, } = this.config;
|
|
186
389
|
if (hasCreatedAt) {
|
|
@@ -189,17 +392,17 @@ class BaseGateway {
|
|
|
189
392
|
if (hasCreatedBy) {
|
|
190
393
|
const createdBy = camelCase(FIELDS.CREATED_BY);
|
|
191
394
|
if (params[createdBy] === undefined) {
|
|
192
|
-
params[createdBy] = this.getContext()
|
|
395
|
+
params[createdBy] = this.getContext()?.userId;
|
|
193
396
|
}
|
|
194
397
|
}
|
|
195
398
|
if (hasUserId) {
|
|
196
399
|
const userId = camelCase(FIELDS.USER_ID);
|
|
197
400
|
if (params[userId] === undefined) {
|
|
198
|
-
params[userId] = this.getContext()
|
|
401
|
+
params[userId] = this.getContext()?.userId;
|
|
199
402
|
}
|
|
200
403
|
}
|
|
201
404
|
if (hasSpace) {
|
|
202
|
-
params[camelCase(FIELDS.SPACE_ID)] = this.getContext()
|
|
405
|
+
params[camelCase(FIELDS.SPACE_ID)] = this.getContext()?.spaceId;
|
|
203
406
|
}
|
|
204
407
|
if (hasUpdatedAt) {
|
|
205
408
|
params[camelCase(FIELDS.UPDATED_AT)] = this.dateTime.dbFormat(this.dateTimeNow);
|
|
@@ -207,7 +410,7 @@ class BaseGateway {
|
|
|
207
410
|
if (hasUpdatedBy) {
|
|
208
411
|
const updatedBy = camelCase(FIELDS.UPDATED_BY);
|
|
209
412
|
if (params[updatedBy] === undefined) {
|
|
210
|
-
params[updatedBy] = this.getContext()
|
|
413
|
+
params[updatedBy] = this.getContext()?.userId;
|
|
211
414
|
}
|
|
212
415
|
}
|
|
213
416
|
if (hasVersion) {
|
|
@@ -224,13 +427,41 @@ class BaseGateway {
|
|
|
224
427
|
}
|
|
225
428
|
return params;
|
|
226
429
|
}
|
|
430
|
+
/**
|
|
431
|
+
* Builds the patch object applied to a record when it is soft-deleted.
|
|
432
|
+
* Called by `remove()` when `hardRemove` is false and `hasRemovedAt` is true.
|
|
433
|
+
*
|
|
434
|
+
* Returns a new object (merged from `args`) with removal fields populated.
|
|
435
|
+
* Override in subclasses to add custom soft-delete fields.
|
|
436
|
+
* Always call `super.transformOnRemove(args)` first.
|
|
437
|
+
*
|
|
438
|
+
* The `args` parameter is the original `where` filter passed to `remove()`.
|
|
439
|
+
* It is available so subclasses can derive removal values from the filter
|
|
440
|
+
* (e.g. storing which id was removed). In the base implementation it is
|
|
441
|
+
* spread into the patch object as-is.
|
|
442
|
+
*
|
|
443
|
+
* Built-in transformations:
|
|
444
|
+
* - `hasRemovedAt` — sets removedAt to the current time (dayjs, not
|
|
445
|
+
* dateTimeNow — removal time is always real-time,
|
|
446
|
+
* not the gateway construction timestamp)
|
|
447
|
+
* - `hasRemovedAtStr` — sets removedAtStr to a formatted string timestamp
|
|
448
|
+
* (YYYYMMDDTHHmmssZ), useful for building composite
|
|
449
|
+
* keys that need to encode the removal time
|
|
450
|
+
* - `hasStatus` — sets status to STATUSES.REMOVED
|
|
451
|
+
* - `hasRemovedBy` — sets removedBy to context.userId if not already set
|
|
452
|
+
* - `hasLang` + `localizationForField` — appends the removal timestamp to
|
|
453
|
+
* the id field using a raw CONCAT expression, so
|
|
454
|
+
* the old localisation key is freed up for re-use
|
|
455
|
+
*
|
|
456
|
+
* Nuance: removedAt uses `dayjs()` (current time) rather than `dateTimeNow`
|
|
457
|
+
* (construction time). This is intentional — removal timestamps should be
|
|
458
|
+
* as accurate as possible and are not batch-grouped like create/update times.
|
|
459
|
+
*/
|
|
227
460
|
async transformOnRemove(args) {
|
|
228
461
|
const { hasRemovedAt, hasRemovedAtStr, hasStatus, hasRemovedBy, hasLang, localizationForField } = this.config;
|
|
229
462
|
const removalTime = dayjs();
|
|
230
463
|
const removalTimeStr = removalTime.format('YYYYMMDDTHHmmssZ');
|
|
231
|
-
const obj = {
|
|
232
|
-
...(args || {}),
|
|
233
|
-
};
|
|
464
|
+
const obj = { ...(args || {}) };
|
|
234
465
|
if (hasRemovedAt) {
|
|
235
466
|
obj[FIELDS.REMOVED_AT] = removalTime.toDate();
|
|
236
467
|
}
|
|
@@ -242,50 +473,159 @@ class BaseGateway {
|
|
|
242
473
|
}
|
|
243
474
|
if (hasRemovedBy) {
|
|
244
475
|
if (obj[FIELDS.REMOVED_BY] === undefined) {
|
|
245
|
-
obj[FIELDS.REMOVED_BY] = this.getContext()
|
|
476
|
+
obj[FIELDS.REMOVED_BY] = this.getContext()?.userId;
|
|
246
477
|
}
|
|
247
478
|
}
|
|
248
479
|
if (hasLang && localizationForField) {
|
|
480
|
+
// Append removal timestamp to the id to free the original localisation key
|
|
481
|
+
// for future re-use (e.g. if a new record with the same lang + slug is created).
|
|
249
482
|
obj[this.getIdField()] = this.getDb().raw(`CONCAT(id, '-${removalTimeStr}')`);
|
|
250
483
|
}
|
|
251
484
|
return obj;
|
|
252
485
|
}
|
|
486
|
+
/**
|
|
487
|
+
* Transforms a record after it is read from the database, before it is
|
|
488
|
+
* returned to the caller.
|
|
489
|
+
*
|
|
490
|
+
* The base implementation is a no-op — it returns the item unchanged.
|
|
491
|
+
* Override in subclasses to rename fields, attach computed properties,
|
|
492
|
+
* strip sensitive columns, or convert types (e.g. parse JSON strings).
|
|
493
|
+
*
|
|
494
|
+
* Called by: `list()`, `create()`, `update()`, `updateMany()`,
|
|
495
|
+
* `increment()`, `decrement()`, `set()`, `remove()`.
|
|
496
|
+
*
|
|
497
|
+
* Note: `get()` and `getMany()` go through the loader (DataCache/DataLoader)
|
|
498
|
+
* and do NOT call `transformOnOut()` — transformations on cached records
|
|
499
|
+
* must be handled in the loader's priming logic or in the calling code.
|
|
500
|
+
*/
|
|
253
501
|
transformOnOut(item) {
|
|
254
502
|
return item;
|
|
255
503
|
}
|
|
504
|
+
/**
|
|
505
|
+
* Returns the requestId from the current ApiContext.
|
|
506
|
+
* Useful for correlating log entries or error reports to a specific request.
|
|
507
|
+
*/
|
|
256
508
|
getRequestId() {
|
|
257
509
|
return this.config.context.requestId;
|
|
258
510
|
}
|
|
511
|
+
/**
|
|
512
|
+
* Returns the full ApiContext associated with this gateway instance.
|
|
513
|
+
* The context carries request-scoped values: userId, spaceId, headers,
|
|
514
|
+
* other gateways, cores, db, etc.
|
|
515
|
+
*/
|
|
259
516
|
getContext() {
|
|
260
517
|
return this.config.context;
|
|
261
518
|
}
|
|
519
|
+
/**
|
|
520
|
+
* Returns all gateway instances from the current request context.
|
|
521
|
+
* Allows one gateway to call another (e.g. UserGateway calling RoleGateway)
|
|
522
|
+
* without going through a core, using the same shared context and db connection.
|
|
523
|
+
*
|
|
524
|
+
* Returns an empty object if context is not available.
|
|
525
|
+
*/
|
|
262
526
|
getGateways() {
|
|
263
|
-
return this.config.context
|
|
527
|
+
return this.config.context?.gateways || {};
|
|
264
528
|
}
|
|
529
|
+
/**
|
|
530
|
+
* Returns the Database instance from config.
|
|
531
|
+
* All query builders are derived from this instance.
|
|
532
|
+
*/
|
|
265
533
|
getDb() {
|
|
266
534
|
return this.config.db;
|
|
267
535
|
}
|
|
536
|
+
/**
|
|
537
|
+
* Returns a Knex query builder scoped to this gateway's table.
|
|
538
|
+
* The builder is a fresh instance each time — it does not carry state
|
|
539
|
+
* between calls.
|
|
540
|
+
*/
|
|
268
541
|
getBuilder() {
|
|
269
542
|
return this.getDb()?.getBuilder(this.config.table);
|
|
270
543
|
}
|
|
544
|
+
/**
|
|
545
|
+
* Returns the primary key field name used for SELECT and loader operations.
|
|
546
|
+
* Defaults to the global ID_FIELD constant if not set in config.
|
|
547
|
+
*
|
|
548
|
+
* Note: this may differ from `getIdFieldUpdateRemove()` — some tables use
|
|
549
|
+
* a different column for update/delete filtering (e.g. a composite key)
|
|
550
|
+
* while listing and loading still uses the primary key.
|
|
551
|
+
*/
|
|
271
552
|
getIdField() {
|
|
272
553
|
return this.config.idField || ID_FIELD;
|
|
273
554
|
}
|
|
555
|
+
/**
|
|
556
|
+
* Returns the field name used to identify records in UPDATE and DELETE
|
|
557
|
+
* WHERE clauses. Falls back through idFieldUpdateRemove → idField → ID_FIELD.
|
|
558
|
+
*
|
|
559
|
+
* Separate from `getIdField()` to support tables where the logical primary
|
|
560
|
+
* key used for loading differs from the column used for writes
|
|
561
|
+
* (e.g. a table with a UUID primary key but a separate "slug" as update target).
|
|
562
|
+
*/
|
|
274
563
|
getIdFieldUpdateRemove() {
|
|
275
564
|
return this.config.idFieldUpdateRemove || this.config.idField || ID_FIELD;
|
|
276
565
|
}
|
|
566
|
+
/**
|
|
567
|
+
* Loads a single record by id via the loader (DataCache/DataLoader).
|
|
568
|
+
* Leverages DataLoader batching — multiple `get()` calls within the same
|
|
569
|
+
* tick are coalesced into a single database query.
|
|
570
|
+
*
|
|
571
|
+
* Results are cached for the duration of the request. To bypass the cache,
|
|
572
|
+
* call `list()` with `useCache: false` instead.
|
|
573
|
+
*/
|
|
277
574
|
async get(id) {
|
|
278
575
|
return this.loader.load(id);
|
|
279
576
|
}
|
|
577
|
+
/**
|
|
578
|
+
* Loads multiple records by their ids via the loader (DataCache/DataLoader).
|
|
579
|
+
* Returns results in the same order as the input ids array, with `null`
|
|
580
|
+
* entries for any ids that were not found (DataLoader semantics).
|
|
581
|
+
*
|
|
582
|
+
* Leverages DataLoader batching — all ids are fetched in a single query.
|
|
583
|
+
* Results are cached for the duration of the request.
|
|
584
|
+
*/
|
|
280
585
|
async getMany(ids) {
|
|
281
586
|
return this.loader.loadMany(ids);
|
|
282
587
|
}
|
|
588
|
+
/**
|
|
589
|
+
* Builds the base SELECT query for `list()`.
|
|
590
|
+
* Override in subclasses to add JOINs, computed columns, or subqueries
|
|
591
|
+
* that should always be present in list results.
|
|
592
|
+
*
|
|
593
|
+
* The `fieldsToUse` argument determines which columns are selected:
|
|
594
|
+
* - When `useCache` is true (default), only the id field is selected —
|
|
595
|
+
* the full records are then fetched via the loader/cache.
|
|
596
|
+
* - When `useCache` is false, `selectFields` from config are used, falling
|
|
597
|
+
* back to '*' if not configured.
|
|
598
|
+
*
|
|
599
|
+
* Returns an object `{ query }` so subclasses can destructure it and
|
|
600
|
+
* attach additional query segments before returning.
|
|
601
|
+
*/
|
|
283
602
|
async buildListQuery(args) {
|
|
284
603
|
const { fieldsToUse } = args || {};
|
|
285
604
|
const query = this.getBuilder();
|
|
286
605
|
query.select(fieldsToUse || '*');
|
|
287
606
|
return { query };
|
|
288
607
|
}
|
|
608
|
+
/**
|
|
609
|
+
* Fetches a paginated, filtered list of records from the database.
|
|
610
|
+
*
|
|
611
|
+
* Flow:
|
|
612
|
+
* 1. Builds the base query via `buildListQuery()`
|
|
613
|
+
* 2. Applies filter conditions via `onListFilter()`
|
|
614
|
+
* 3. Applies pagination (limit/offset) and sorting
|
|
615
|
+
* 4. If `useCache` is true, fetches only ids then loads full records
|
|
616
|
+
* via the loader (DataLoader batching + in-memory cache)
|
|
617
|
+
* 5. Transforms each result via `transformOnOut()`
|
|
618
|
+
*
|
|
619
|
+
* Cache behaviour:
|
|
620
|
+
* - `useCache` defaults to `!config.noCache`
|
|
621
|
+
* - When true, the list query selects only id fields, and full records
|
|
622
|
+
* are hydrated through the DataLoader. This means list results benefit
|
|
623
|
+
* from the same cache as `get()` / `getMany()` calls in the same request.
|
|
624
|
+
* - When false, `selectFields` are fetched directly without going through
|
|
625
|
+
* the loader. Use this for aggregations, reports, or large exports.
|
|
626
|
+
*
|
|
627
|
+
* Returns an empty array immediately if `config.table` is not set.
|
|
628
|
+
*/
|
|
289
629
|
async list(args) {
|
|
290
630
|
const { filter, params, useCache } = args || {};
|
|
291
631
|
const { limit, offset, sortBy } = this.getDb().createLimitOffsetSortBy(params, this.config.defaultSorting || []);
|
|
@@ -306,6 +646,23 @@ class BaseGateway {
|
|
|
306
646
|
const result = shouldUseCache ? await this.getMany(items.map((row) => row.id)) : items;
|
|
307
647
|
return result.map((item) => this.transformOnOut(item));
|
|
308
648
|
}
|
|
649
|
+
/**
|
|
650
|
+
* Inserts one or more records into the database.
|
|
651
|
+
*
|
|
652
|
+
* Accepts a single object or an array of objects (via castArray).
|
|
653
|
+
* For each object:
|
|
654
|
+
* 1. Generates a new id via `generateId()`
|
|
655
|
+
* 2. Applies `transformOnCreate()` to set audit fields, spaceId, version, etc.
|
|
656
|
+
*
|
|
657
|
+
* Inserts are batched into chunks of `config.insertChunkSize` (default 2500)
|
|
658
|
+
* to avoid hitting database parameter limits on large arrays.
|
|
659
|
+
*
|
|
660
|
+
* Returns all inserted records (via RETURNING), each passed through
|
|
661
|
+
* `transformOnOut()`.
|
|
662
|
+
*
|
|
663
|
+
* Note: does NOT prime the loader cache with the newly created records.
|
|
664
|
+
* Subsequent `get()` calls for these ids will hit the database.
|
|
665
|
+
*/
|
|
309
666
|
async create(args) {
|
|
310
667
|
const objects = castArray(args);
|
|
311
668
|
if (!args || objects.length === 0) {
|
|
@@ -315,7 +672,6 @@ class BaseGateway {
|
|
|
315
672
|
const object = objects[idx];
|
|
316
673
|
const id = await this.generateId(object);
|
|
317
674
|
objects[idx] = await this.transformOnCreate({ id, ...object });
|
|
318
|
-
//objects.push(obj);
|
|
319
675
|
}
|
|
320
676
|
const result = [];
|
|
321
677
|
const chunks = arrToChunks(objects, this.config?.insertChunkSize || DEFAULT_CHUNCK_SIZE);
|
|
@@ -325,12 +681,33 @@ class BaseGateway {
|
|
|
325
681
|
}
|
|
326
682
|
return result.map((item) => this.transformOnOut(item));
|
|
327
683
|
}
|
|
684
|
+
/**
|
|
685
|
+
* Updates one or more records matching the `where` filter.
|
|
686
|
+
*
|
|
687
|
+
* Flow:
|
|
688
|
+
* 1. Applies `transformOnUpdate()` to set audit fields and increment version
|
|
689
|
+
* 2. Builds the UPDATE query with RETURNING
|
|
690
|
+
* 3. Applies WHERE conditions via `onUpdateFilter()`
|
|
691
|
+
* 4. Throws if no filter conditions were applied (safety guard against
|
|
692
|
+
* unfiltered updates that would affect all rows)
|
|
693
|
+
* 5. Clears affected records from the loader cache
|
|
694
|
+
* 6. Returns updated records through `transformOnOut()`
|
|
695
|
+
*
|
|
696
|
+
* The `where` object should contain the id field and optionally version
|
|
697
|
+
* (for optimistic locking). Additional filter logic can be added by
|
|
698
|
+
* overriding `onUpdateFilter()`.
|
|
699
|
+
*
|
|
700
|
+
* Nuance: if `hasVersion` is configured and `where` does not include a
|
|
701
|
+
* version, the version check is skipped. This allows unconditional updates
|
|
702
|
+
* (e.g. admin operations) by simply omitting the version from the filter.
|
|
703
|
+
*/
|
|
328
704
|
async update(where, params) {
|
|
329
705
|
const object = await this.transformOnUpdate(params, where);
|
|
330
706
|
const query = this.getBuilder().update(object).returning(this.config.returnFields);
|
|
331
707
|
const filtersAppliedQty = await this.onUpdateFilter(query, where);
|
|
332
708
|
if (filtersAppliedQty == null || filtersAppliedQty <= 0) {
|
|
333
|
-
throw new Error(`Failed to update
|
|
709
|
+
throw new Error(`Failed to update table '${this.config.table}': no filters applied. ` +
|
|
710
|
+
`Expected id field: '${this.getIdFieldUpdateRemove()}'. Received: ${JSON.stringify(where, null, 2)}`);
|
|
334
711
|
}
|
|
335
712
|
const items = await query;
|
|
336
713
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
@@ -343,6 +720,20 @@ class BaseGateway {
|
|
|
343
720
|
}
|
|
344
721
|
return items.map((item) => this.transformOnOut(item));
|
|
345
722
|
}
|
|
723
|
+
/**
|
|
724
|
+
* Updates multiple records, each with its own where filter and params.
|
|
725
|
+
*
|
|
726
|
+
* Accepts an array of `{ where, params }` pairs (or a single pair, which
|
|
727
|
+
* is normalised to an array). Each pair is processed sequentially via
|
|
728
|
+
* `update()`, so each item gets its own filter validation, audit field
|
|
729
|
+
* transform, and cache invalidation.
|
|
730
|
+
*
|
|
731
|
+
* Returns all updated records across all pairs, flattened into a single
|
|
732
|
+
* array, each passed through `transformOnOut()`.
|
|
733
|
+
*
|
|
734
|
+
* Note: cache clearing is handled inside each `update()` call — there is
|
|
735
|
+
* no second pass over the results here.
|
|
736
|
+
*/
|
|
346
737
|
async updateMany(params) {
|
|
347
738
|
if (!Array.isArray(params)) {
|
|
348
739
|
params = [params];
|
|
@@ -353,22 +744,27 @@ class BaseGateway {
|
|
|
353
744
|
const items = await this.update(item.where, item.params);
|
|
354
745
|
results.push(...items);
|
|
355
746
|
}
|
|
356
|
-
if (results.length > 0 && this.config.noCache !== true) {
|
|
357
|
-
const idName = this.getIdFieldUpdateRemove();
|
|
358
|
-
results.forEach((item) => {
|
|
359
|
-
if (item[idName]) {
|
|
360
|
-
this.loader.clear(item[idName]);
|
|
361
|
-
}
|
|
362
|
-
});
|
|
363
|
-
}
|
|
364
747
|
return results.map((item) => this.transformOnOut(item));
|
|
365
748
|
}
|
|
749
|
+
/**
|
|
750
|
+
* Increments numeric field(s) on records matching the `where` filter.
|
|
751
|
+
* Uses the database's native INCREMENT operation rather than a read-modify-write,
|
|
752
|
+
* making it safe for concurrent requests.
|
|
753
|
+
*
|
|
754
|
+
* `params` should be an object mapping field names to the increment amounts
|
|
755
|
+
* (e.g. `{ viewCount: 1 }`). `transformOnUpdate()` is still called, so
|
|
756
|
+
* audit fields (updatedAt, updatedBy) and version are updated as normal.
|
|
757
|
+
*
|
|
758
|
+
* Throws if no filter conditions are applied (same safety guard as `update()`).
|
|
759
|
+
* Clears affected records from the loader cache after the operation.
|
|
760
|
+
*/
|
|
366
761
|
async increment(where, params) {
|
|
367
762
|
const object = await this.transformOnUpdate(params, where);
|
|
368
763
|
const query = this.getBuilder().increment(object).returning(this.config.returnFields);
|
|
369
764
|
const filtersAppliedQty = await this.onUpdateFilter(query, where);
|
|
370
765
|
if (filtersAppliedQty == null || filtersAppliedQty <= 0) {
|
|
371
|
-
throw new Error(`Failed to
|
|
766
|
+
throw new Error(`Failed to increment in table '${this.config.table}': no filters applied. ` +
|
|
767
|
+
`Expected id field: '${this.getIdFieldUpdateRemove()}'. Received: ${JSON.stringify(where, null, 2)}`);
|
|
372
768
|
}
|
|
373
769
|
const items = await query;
|
|
374
770
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
@@ -381,12 +777,19 @@ class BaseGateway {
|
|
|
381
777
|
}
|
|
382
778
|
return items.map((item) => this.transformOnOut(item));
|
|
383
779
|
}
|
|
780
|
+
/**
|
|
781
|
+
* Decrements numeric field(s) on records matching the `where` filter.
|
|
782
|
+
* Mirror of `increment()` using the database's native DECREMENT operation.
|
|
783
|
+
*
|
|
784
|
+
* Same behaviour, safety guards, and cache invalidation as `increment()`.
|
|
785
|
+
*/
|
|
384
786
|
async decrement(where, params) {
|
|
385
787
|
const object = await this.transformOnUpdate(params, where);
|
|
386
788
|
const query = this.getBuilder().decrement(object).returning(this.config.returnFields);
|
|
387
789
|
const filtersAppliedQty = await this.onUpdateFilter(query, where);
|
|
388
790
|
if (filtersAppliedQty == null || filtersAppliedQty <= 0) {
|
|
389
|
-
throw new Error(`Failed to
|
|
791
|
+
throw new Error(`Failed to decrement in table '${this.config.table}': no filters applied. ` +
|
|
792
|
+
`Expected id field: '${this.getIdFieldUpdateRemove()}'. Received: ${JSON.stringify(where, null, 2)}`);
|
|
390
793
|
}
|
|
391
794
|
const items = await query;
|
|
392
795
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
@@ -400,11 +803,29 @@ class BaseGateway {
|
|
|
400
803
|
return items.map((item) => this.transformOnOut(item));
|
|
401
804
|
}
|
|
402
805
|
/**
|
|
403
|
-
*
|
|
404
|
-
*
|
|
405
|
-
*
|
|
406
|
-
*
|
|
407
|
-
*
|
|
806
|
+
* Upserts one or more records using INSERT ... ON CONFLICT ... MERGE.
|
|
807
|
+
*
|
|
808
|
+
* For each object:
|
|
809
|
+
* 1. Applies `transformOnSet()` (combined create + update transforms)
|
|
810
|
+
* 2. Generates an id if none is present
|
|
811
|
+
*
|
|
812
|
+
* The merge behaviour:
|
|
813
|
+
* - Conflict target: `config.setFields` if set, otherwise the id field
|
|
814
|
+
* - Fields merged on conflict: all keys found across all objects, minus
|
|
815
|
+
* `skipFields` (createdAt, createdBy, spaceId when their flags are set)
|
|
816
|
+
* - skipFields ensures that on conflict (update path), creation-time
|
|
817
|
+
* fields are not overwritten — existing records keep their original
|
|
818
|
+
* createdAt, createdBy, and spaceId values
|
|
819
|
+
* - If `config.mergeFields` is set, it takes precedence over the
|
|
820
|
+
* auto-derived field list entirely
|
|
821
|
+
*
|
|
822
|
+
* Inserts are batched into chunks of `config.insertChunkSize` (default 2500).
|
|
823
|
+
*
|
|
824
|
+
* Returns all upserted records (via RETURNING), each passed through
|
|
825
|
+
* `transformOnOut()`.
|
|
826
|
+
*
|
|
827
|
+
* Nuance: fields are collected from all objects (not just the first) to
|
|
828
|
+
* avoid silently dropping fields that only appear on some items in the batch.
|
|
408
829
|
*/
|
|
409
830
|
async set(params) {
|
|
410
831
|
const { hasCreatedAt, hasCreatedBy, hasSpace, mergeFields } = this.config || {};
|
|
@@ -413,15 +834,12 @@ class BaseGateway {
|
|
|
413
834
|
return [];
|
|
414
835
|
}
|
|
415
836
|
const skipFields = [];
|
|
416
|
-
if (hasCreatedAt)
|
|
837
|
+
if (hasCreatedAt)
|
|
417
838
|
skipFields.push(FIELDS.CREATED_AT);
|
|
418
|
-
|
|
419
|
-
if (hasCreatedBy) {
|
|
839
|
+
if (hasCreatedBy)
|
|
420
840
|
skipFields.push(FIELDS.CREATED_BY);
|
|
421
|
-
|
|
422
|
-
if (hasSpace) {
|
|
841
|
+
if (hasSpace)
|
|
423
842
|
skipFields.push(FIELDS.SPACE_ID);
|
|
424
|
-
}
|
|
425
843
|
const idField = this.getIdFieldUpdateRemove();
|
|
426
844
|
for (let idx = 0, len = objects.length; idx < len; ++idx) {
|
|
427
845
|
const object = objects[idx];
|
|
@@ -430,7 +848,12 @@ class BaseGateway {
|
|
|
430
848
|
objects[idx][idField] = await this.generateId(object);
|
|
431
849
|
}
|
|
432
850
|
}
|
|
433
|
-
|
|
851
|
+
// Collect all unique keys across all objects to build the merge field list.
|
|
852
|
+
// Using only objects[0] would silently drop fields present on later items
|
|
853
|
+
// if the batch has inconsistent shapes.
|
|
854
|
+
const fields = Array.isArray(mergeFields)
|
|
855
|
+
? mergeFields
|
|
856
|
+
: [...new Set(objects.flatMap((o) => Object.keys(o)))];
|
|
434
857
|
const result = [];
|
|
435
858
|
const chunks = arrToChunks(objects, this.config?.insertChunkSize || DEFAULT_CHUNCK_SIZE);
|
|
436
859
|
for (let idx = 0, len = chunks.length; idx < len; ++idx) {
|
|
@@ -443,6 +866,28 @@ class BaseGateway {
|
|
|
443
866
|
}
|
|
444
867
|
return result.map((item) => this.transformOnOut(item));
|
|
445
868
|
}
|
|
869
|
+
/**
|
|
870
|
+
* Removes records matching the `where` filter, either hard or soft.
|
|
871
|
+
*
|
|
872
|
+
* Hard vs soft delete:
|
|
873
|
+
* - Hard delete (`hardRemove: true` OR `hasRemovedAt: false`):
|
|
874
|
+
* Issues a DELETE query. Records are permanently removed.
|
|
875
|
+
* - Soft delete (default when `hasRemovedAt: true`):
|
|
876
|
+
* Issues an UPDATE with the removal patch from `transformOnRemove()`.
|
|
877
|
+
* Records are retained in the database with removedAt, status = REMOVED,
|
|
878
|
+
* and optionally removedBy set.
|
|
879
|
+
*
|
|
880
|
+
* The `where` parameter is passed to both `onRemoveFilter()` (for the WHERE
|
|
881
|
+
* clause) and `transformOnRemove()` (so the removal patch can reference
|
|
882
|
+
* the filter, e.g. for lang/localisation key rotation).
|
|
883
|
+
*
|
|
884
|
+
* Throws if no filter conditions are applied — a safety guard to prevent
|
|
885
|
+
* an unfiltered DELETE or soft-delete UPDATE from affecting all rows.
|
|
886
|
+
*
|
|
887
|
+
* Clears affected records from the loader cache after the operation.
|
|
888
|
+
* Returns all affected records (via RETURNING), each passed through
|
|
889
|
+
* `transformOnOut()`.
|
|
890
|
+
*/
|
|
446
891
|
async remove(where) {
|
|
447
892
|
const { hardRemove, hasRemovedAt } = this.config || {};
|
|
448
893
|
const query = this.getBuilder();
|
|
@@ -450,12 +895,13 @@ class BaseGateway {
|
|
|
450
895
|
query.delete(this.config.returnFields);
|
|
451
896
|
}
|
|
452
897
|
else {
|
|
453
|
-
const object = await this.transformOnRemove();
|
|
898
|
+
const object = await this.transformOnRemove(where);
|
|
454
899
|
query.update(object).returning(this.config.returnFields);
|
|
455
900
|
}
|
|
456
901
|
const filtersAppliedQty = await this.onRemoveFilter(query, where);
|
|
457
902
|
if (filtersAppliedQty == null || filtersAppliedQty <= 0) {
|
|
458
|
-
throw new Error(`Failed to remove records in
|
|
903
|
+
throw new Error(`Failed to remove records in table '${this.config.table}': no filters applied. ` +
|
|
904
|
+
`Expected id field: '${this.getIdFieldUpdateRemove()}'. Received: ${JSON.stringify(where, null, 2)}`);
|
|
459
905
|
}
|
|
460
906
|
const items = await query;
|
|
461
907
|
if (items.length > 0 && this.config.noCache !== true) {
|