@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.
Files changed (214) hide show
  1. package/README.md +1422 -146
  2. package/build/BaseController.d.ts +20 -0
  3. package/build/BaseController.js +64 -0
  4. package/build/BaseCore.d.ts +586 -33
  5. package/build/BaseCore.js +821 -127
  6. package/build/BaseExternalApiGateway.d.ts +16 -0
  7. package/build/BaseExternalApiGateway.js +54 -0
  8. package/build/BaseGateway.d.ts +455 -17
  9. package/build/BaseGateway.js +502 -56
  10. package/build/BaseRestApiCrudController.d.ts +37 -0
  11. package/build/BaseRestApiCrudController.js +134 -0
  12. package/build/DataCache.d.ts +116 -5
  13. package/build/DataCache.js +144 -22
  14. package/build/Database.d.ts +165 -4
  15. package/build/Database.js +224 -51
  16. package/build/DbMigratorAndSeeder.d.ts +127 -26
  17. package/build/DbMigratorAndSeeder.js +180 -69
  18. package/build/IpRateLimiter.d.ts +105 -0
  19. package/build/IpRateLimiter.js +104 -0
  20. package/build/RedisDataLoader.d.ts +144 -21
  21. package/build/RedisDataLoader.js +178 -49
  22. package/build/apiContext.d.ts +0 -8
  23. package/build/apiContext.js +30 -32
  24. package/build/checkItHelpers.d.ts +32 -0
  25. package/build/checkItHelpers.js +73 -7
  26. package/build/commonValidators.d.ts +107 -16
  27. package/build/commonValidators.js +211 -106
  28. package/build/configBuilder.d.ts +23 -0
  29. package/build/configBuilder.js +73 -0
  30. package/build/constants.d.ts +134 -17
  31. package/build/constants.js +95 -15
  32. package/build/dbHelpers.d.ts +89 -29
  33. package/build/dbHelpers.js +175 -86
  34. package/build/dbSeeder.d.ts +10 -1
  35. package/build/dbSeeder.js +80 -15
  36. package/build/dbTableHelpers.d.ts +122 -5
  37. package/build/dbTableHelpers.js +151 -13
  38. package/build/downloadHelpers.d.ts +24 -1
  39. package/build/downloadHelpers.js +51 -21
  40. package/build/esm/BaseController.d.ts +20 -0
  41. package/build/esm/BaseController.js +58 -0
  42. package/build/esm/BaseCore.d.ts +586 -33
  43. package/build/esm/BaseCore.js +812 -118
  44. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  45. package/build/esm/BaseExternalApiGateway.js +48 -0
  46. package/build/esm/BaseGateway.d.ts +455 -17
  47. package/build/esm/BaseGateway.js +503 -57
  48. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  49. package/build/esm/BaseRestApiCrudController.js +131 -0
  50. package/build/esm/DataCache.d.ts +116 -5
  51. package/build/esm/DataCache.js +142 -20
  52. package/build/esm/Database.d.ts +165 -4
  53. package/build/esm/Database.js +224 -51
  54. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  55. package/build/esm/DbMigratorAndSeeder.js +184 -71
  56. package/build/esm/IpRateLimiter.d.ts +105 -0
  57. package/build/esm/IpRateLimiter.js +100 -0
  58. package/build/esm/RedisDataLoader.d.ts +144 -21
  59. package/build/esm/RedisDataLoader.js +179 -50
  60. package/build/esm/apiContext.d.ts +0 -8
  61. package/build/esm/apiContext.js +30 -32
  62. package/build/esm/checkItHelpers.d.ts +32 -0
  63. package/build/esm/checkItHelpers.js +73 -7
  64. package/build/esm/commonValidators.d.ts +107 -16
  65. package/build/esm/commonValidators.js +209 -105
  66. package/build/esm/configBuilder.d.ts +23 -0
  67. package/build/esm/configBuilder.js +69 -0
  68. package/build/esm/constants.d.ts +134 -17
  69. package/build/esm/constants.js +94 -14
  70. package/build/esm/dbHelpers.d.ts +89 -29
  71. package/build/esm/dbHelpers.js +171 -81
  72. package/build/esm/dbSeeder.d.ts +10 -1
  73. package/build/esm/dbSeeder.js +81 -16
  74. package/build/esm/dbTableHelpers.d.ts +122 -5
  75. package/build/esm/dbTableHelpers.js +152 -14
  76. package/build/esm/downloadHelpers.d.ts +24 -1
  77. package/build/esm/downloadHelpers.js +51 -21
  78. package/build/esm/index.d.ts +6 -2
  79. package/build/esm/index.js +6 -2
  80. package/build/esm/interfaces/ApiContext.d.ts +33 -3
  81. package/build/esm/interfaces/ApiContext.js +1 -0
  82. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  83. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  84. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  85. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  86. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  87. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
  88. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  89. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  90. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  91. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  92. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  93. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  94. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  95. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  96. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  97. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  98. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  99. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  100. package/build/esm/interfaces/CacheInterface.js +1 -0
  101. package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
  102. package/build/esm/interfaces/CoreActionInterface.js +1 -0
  103. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  104. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  105. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  106. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  107. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  108. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  109. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  110. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  111. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  112. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  113. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  114. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  115. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  116. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  117. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  118. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  119. package/build/esm/interfaces/LoaderInterface.js +1 -0
  120. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  121. package/build/esm/interfaces/UserTokenParams.js +1 -0
  122. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  123. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  124. package/build/esm/interfaces/index.d.ts +4 -0
  125. package/build/esm/interfaces/index.js +4 -0
  126. package/build/esm/knexConfigBuilder.d.ts +25 -0
  127. package/build/esm/knexConfigBuilder.js +100 -36
  128. package/build/esm/parseIds.d.ts +6 -0
  129. package/build/esm/parseIds.js +13 -0
  130. package/build/esm/passwordHelpers.d.ts +22 -0
  131. package/build/esm/passwordHelpers.js +40 -8
  132. package/build/esm/redisClient.d.ts +57 -4
  133. package/build/esm/redisClient.js +40 -54
  134. package/build/esm/resolveClientIp.d.ts +15 -0
  135. package/build/esm/resolveClientIp.js +34 -0
  136. package/build/esm/resolversHelpers.d.ts +21 -1
  137. package/build/esm/resolversHelpers.js +48 -26
  138. package/build/esm/userToken.d.ts +50 -1
  139. package/build/esm/userToken.js +85 -20
  140. package/build/esm/utils.d.ts +20 -2
  141. package/build/esm/utils.js +23 -13
  142. package/build/index.d.ts +6 -2
  143. package/build/index.js +6 -2
  144. package/build/interfaces/ApiContext.d.ts +33 -3
  145. package/build/interfaces/ApiContext.js +1 -0
  146. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  147. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  148. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  149. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  150. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  151. package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
  152. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  153. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  154. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  155. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  156. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  157. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  158. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  159. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  160. package/build/interfaces/BuildConfigOptions.js +1 -0
  161. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  162. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  163. package/build/interfaces/CacheInterface.d.ts +18 -1
  164. package/build/interfaces/CacheInterface.js +1 -0
  165. package/build/interfaces/CoreActionInterface.d.ts +60 -0
  166. package/build/interfaces/CoreActionInterface.js +1 -0
  167. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  168. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  169. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  170. package/build/interfaces/DataCachePropsInterface.js +3 -0
  171. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  172. package/build/interfaces/DatabaseOptions.js +1 -0
  173. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  174. package/build/interfaces/DatabaseReadInterface.js +1 -0
  175. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  176. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  177. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  178. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  179. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  180. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  181. package/build/interfaces/ListArgsInterface.js +1 -0
  182. package/build/interfaces/LoaderInterface.d.ts +36 -1
  183. package/build/interfaces/LoaderInterface.js +1 -0
  184. package/build/interfaces/UserTokenParams.d.ts +23 -5
  185. package/build/interfaces/UserTokenParams.js +1 -0
  186. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  187. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  188. package/build/interfaces/index.d.ts +4 -0
  189. package/build/interfaces/index.js +4 -0
  190. package/build/knexConfigBuilder.d.ts +25 -0
  191. package/build/knexConfigBuilder.js +99 -35
  192. package/build/parseIds.d.ts +6 -0
  193. package/build/parseIds.js +17 -0
  194. package/build/passwordHelpers.d.ts +22 -0
  195. package/build/passwordHelpers.js +40 -8
  196. package/build/redisClient.d.ts +57 -4
  197. package/build/redisClient.js +40 -54
  198. package/build/resolveClientIp.d.ts +15 -0
  199. package/build/resolveClientIp.js +38 -0
  200. package/build/resolversHelpers.d.ts +21 -1
  201. package/build/resolversHelpers.js +48 -26
  202. package/build/userToken.d.ts +50 -1
  203. package/build/userToken.js +85 -20
  204. package/build/utils.d.ts +20 -2
  205. package/build/utils.js +24 -16
  206. package/package.json +19 -18
  207. package/build/baseController.d.ts +0 -17
  208. package/build/baseController.js +0 -64
  209. package/build/configBulder.d.ts +0 -2
  210. package/build/configBulder.js +0 -36
  211. package/build/esm/baseController.d.ts +0 -17
  212. package/build/esm/baseController.js +0 -58
  213. package/build/esm/configBulder.d.ts +0 -2
  214. package/build/esm/configBulder.js +0 -32
@@ -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. Please use another one that is not as: ${Object.keys(this.config.context.usedKeyPrefixes).join(', ')}`);
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
- this.logger = props?.logger instanceof Logger ? props.logger : new Logger({ level: LoggerLevels.WARNING });
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 object's ID
49
- * @param object use them when overriding the generate method and you may need data from an object
50
- * @returns unique ID, by default it is UUID v4
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(object) {
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.spaceId)) {
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.spaceId,
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('.') ? `${idField}` : `${table}.${idField}`, castArray(filterParams?.[idField]));
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().userId });
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 (let filter of arr) {
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().userId;
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().userId;
303
+ params[userId] = this.getContext()?.userId;
149
304
  }
150
305
  }
151
306
  if (hasSpace) {
152
- params[camelCase(FIELDS.SPACE_ID)] = this.getContext().spaceId;
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().userId;
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().userId;
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().userId;
401
+ params[userId] = this.getContext()?.userId;
199
402
  }
200
403
  }
201
404
  if (hasSpace) {
202
- params[camelCase(FIELDS.SPACE_ID)] = this.getContext().spaceId;
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().userId;
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().userId;
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.gateways || {};
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 the table '${this.config.table}' as none of filters applied: ${JSON.stringify(where, null, 2)}`);
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 update the table '${this.config.table}' as none of filters applied: ${JSON.stringify(where, null, 2)}`);
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 update the table '${this.config.table}' as none of filters applied: ${JSON.stringify(where, null, 2)}`);
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
- * Inserts or updates data in the database.
404
- * If the element of given array has not empty id field then the record is updated
405
- * oterwise inserted
406
- * @param params Array of objects to update or create
407
- * @returns Array of updated or inserted objects
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
- const fields = Array.isArray(mergeFields) ? mergeFields : Object.keys(objects[0]);
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 the table '${this.config.table}' as none of filters applied: ${JSON.stringify(where, null, 2)}`);
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) {