@sdflc/backend-helpers 1.0.111 → 1.0.113

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 (206) 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 +470 -33
  5. package/build/BaseCore.js +613 -126
  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/RedisDataLoader.d.ts +144 -21
  19. package/build/RedisDataLoader.js +178 -49
  20. package/build/apiContext.d.ts +0 -8
  21. package/build/apiContext.js +12 -27
  22. package/build/checkItHelpers.d.ts +32 -0
  23. package/build/checkItHelpers.js +73 -7
  24. package/build/commonValidators.d.ts +107 -16
  25. package/build/commonValidators.js +211 -106
  26. package/build/configBuilder.d.ts +23 -0
  27. package/build/configBuilder.js +73 -0
  28. package/build/constants.d.ts +134 -17
  29. package/build/constants.js +95 -15
  30. package/build/dbHelpers.d.ts +89 -29
  31. package/build/dbHelpers.js +175 -86
  32. package/build/dbSeeder.d.ts +10 -1
  33. package/build/dbSeeder.js +80 -15
  34. package/build/dbTableHelpers.d.ts +122 -5
  35. package/build/dbTableHelpers.js +151 -13
  36. package/build/downloadHelpers.d.ts +24 -1
  37. package/build/downloadHelpers.js +51 -21
  38. package/build/esm/BaseController.d.ts +20 -0
  39. package/build/esm/BaseController.js +58 -0
  40. package/build/esm/BaseCore.d.ts +470 -33
  41. package/build/esm/BaseCore.js +615 -128
  42. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  43. package/build/esm/BaseExternalApiGateway.js +48 -0
  44. package/build/esm/BaseGateway.d.ts +455 -17
  45. package/build/esm/BaseGateway.js +503 -57
  46. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  47. package/build/esm/BaseRestApiCrudController.js +131 -0
  48. package/build/esm/DataCache.d.ts +116 -5
  49. package/build/esm/DataCache.js +142 -20
  50. package/build/esm/Database.d.ts +165 -4
  51. package/build/esm/Database.js +224 -51
  52. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  53. package/build/esm/DbMigratorAndSeeder.js +184 -71
  54. package/build/esm/RedisDataLoader.d.ts +144 -21
  55. package/build/esm/RedisDataLoader.js +179 -50
  56. package/build/esm/apiContext.d.ts +0 -8
  57. package/build/esm/apiContext.js +12 -27
  58. package/build/esm/checkItHelpers.d.ts +32 -0
  59. package/build/esm/checkItHelpers.js +73 -7
  60. package/build/esm/commonValidators.d.ts +107 -16
  61. package/build/esm/commonValidators.js +209 -105
  62. package/build/esm/configBuilder.d.ts +23 -0
  63. package/build/esm/configBuilder.js +69 -0
  64. package/build/esm/constants.d.ts +134 -17
  65. package/build/esm/constants.js +94 -14
  66. package/build/esm/dbHelpers.d.ts +89 -29
  67. package/build/esm/dbHelpers.js +171 -81
  68. package/build/esm/dbSeeder.d.ts +10 -1
  69. package/build/esm/dbSeeder.js +81 -16
  70. package/build/esm/dbTableHelpers.d.ts +122 -5
  71. package/build/esm/dbTableHelpers.js +152 -14
  72. package/build/esm/downloadHelpers.d.ts +24 -1
  73. package/build/esm/downloadHelpers.js +51 -21
  74. package/build/esm/index.d.ts +5 -2
  75. package/build/esm/index.js +5 -2
  76. package/build/esm/interfaces/ApiContext.d.ts +7 -3
  77. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  78. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  79. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  80. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  81. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  82. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +87 -9
  83. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  84. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  85. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  86. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  87. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  88. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  89. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  90. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  91. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  92. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  93. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  94. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  95. package/build/esm/interfaces/CacheInterface.js +1 -0
  96. package/build/esm/interfaces/CoreActionInterface.d.ts +20 -0
  97. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  98. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  99. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  100. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  101. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  102. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  103. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  104. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  105. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  106. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  107. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  108. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  109. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  110. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  111. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  112. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  113. package/build/esm/interfaces/LoaderInterface.js +1 -0
  114. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  115. package/build/esm/interfaces/UserTokenParams.js +1 -0
  116. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  117. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  118. package/build/esm/interfaces/index.d.ts +4 -0
  119. package/build/esm/interfaces/index.js +4 -0
  120. package/build/esm/knexConfigBuilder.d.ts +25 -0
  121. package/build/esm/knexConfigBuilder.js +100 -36
  122. package/build/esm/parseIds.d.ts +6 -0
  123. package/build/esm/parseIds.js +13 -0
  124. package/build/esm/passwordHelpers.d.ts +22 -0
  125. package/build/esm/passwordHelpers.js +40 -8
  126. package/build/esm/redisClient.d.ts +57 -4
  127. package/build/esm/redisClient.js +40 -54
  128. package/build/esm/resolveClientIp.d.ts +15 -0
  129. package/build/esm/resolveClientIp.js +34 -0
  130. package/build/esm/resolversHelpers.d.ts +21 -1
  131. package/build/esm/resolversHelpers.js +48 -26
  132. package/build/esm/userToken.d.ts +50 -1
  133. package/build/esm/userToken.js +85 -20
  134. package/build/esm/utils.d.ts +20 -0
  135. package/build/esm/utils.js +23 -1
  136. package/build/index.d.ts +5 -2
  137. package/build/index.js +5 -2
  138. package/build/interfaces/ApiContext.d.ts +7 -3
  139. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  140. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  141. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  142. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  143. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  144. package/build/interfaces/BaseCorePropsInterface.d.ts +87 -9
  145. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  146. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  147. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  148. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  149. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  150. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  151. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  152. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  153. package/build/interfaces/BuildConfigOptions.js +1 -0
  154. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  155. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  156. package/build/interfaces/CacheInterface.d.ts +18 -1
  157. package/build/interfaces/CacheInterface.js +1 -0
  158. package/build/interfaces/CoreActionInterface.d.ts +20 -0
  159. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  160. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  161. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  162. package/build/interfaces/DataCachePropsInterface.js +3 -0
  163. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  164. package/build/interfaces/DatabaseOptions.js +1 -0
  165. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  166. package/build/interfaces/DatabaseReadInterface.js +1 -0
  167. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  168. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  169. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  170. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  171. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  172. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  173. package/build/interfaces/ListArgsInterface.js +1 -0
  174. package/build/interfaces/LoaderInterface.d.ts +36 -1
  175. package/build/interfaces/LoaderInterface.js +1 -0
  176. package/build/interfaces/UserTokenParams.d.ts +23 -5
  177. package/build/interfaces/UserTokenParams.js +1 -0
  178. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  179. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  180. package/build/interfaces/index.d.ts +4 -0
  181. package/build/interfaces/index.js +4 -0
  182. package/build/knexConfigBuilder.d.ts +25 -0
  183. package/build/knexConfigBuilder.js +99 -35
  184. package/build/parseIds.d.ts +6 -0
  185. package/build/parseIds.js +17 -0
  186. package/build/passwordHelpers.d.ts +22 -0
  187. package/build/passwordHelpers.js +40 -8
  188. package/build/redisClient.d.ts +57 -4
  189. package/build/redisClient.js +40 -54
  190. package/build/resolveClientIp.d.ts +15 -0
  191. package/build/resolveClientIp.js +38 -0
  192. package/build/resolversHelpers.d.ts +21 -1
  193. package/build/resolversHelpers.js +48 -26
  194. package/build/userToken.d.ts +50 -1
  195. package/build/userToken.js +85 -20
  196. package/build/utils.d.ts +20 -0
  197. package/build/utils.js +23 -1
  198. package/package.json +19 -18
  199. package/build/baseController.d.ts +0 -17
  200. package/build/baseController.js +0 -63
  201. package/build/configBulder.d.ts +0 -2
  202. package/build/configBulder.js +0 -36
  203. package/build/esm/baseController.d.ts +0 -17
  204. package/build/esm/baseController.js +0 -57
  205. package/build/esm/configBulder.d.ts +0 -2
  206. package/build/esm/configBulder.js +0 -32
@@ -1,4 +1,20 @@
1
1
  import { DatabaseOptions, DatabaseReadInterface } from './interfaces';
2
+ /**
3
+ * Database is a thin wrapper around a Knex connection that adds:
4
+ * - Connection pool deduplication (one Knex instance per unique connection config)
5
+ * - Transaction lifecycle management (start, commit, rollback)
6
+ * - Schema-scoped query builder
7
+ * - Common DB error classification (isDbError)
8
+ * - Utility methods for pagination, sorting, calculated fields, and raw reads
9
+ *
10
+ * One Database instance is created per request in createContextDefault() and
11
+ * shared across all gateways via ApiContext. This ensures all gateways in a
12
+ * single request share the same transaction when one is active.
13
+ *
14
+ * Connection pools are shared across requests via the module-level knexHandles
15
+ * cache — creating a new Database instance does not open a new connection pool
16
+ * if one already exists for the same host/port/user/database/schema combination.
17
+ */
2
18
  declare class Database {
3
19
  private trx;
4
20
  private dbType;
@@ -6,31 +22,176 @@ declare class Database {
6
22
  private dbSchema;
7
23
  private logger;
8
24
  constructor(props: DatabaseOptions);
25
+ /**
26
+ * Destroys the Knex connection pool for this instance.
27
+ * Call on application shutdown to cleanly close all DB connections.
28
+ * Note: affects all instances sharing this pool — use with care.
29
+ */
9
30
  destroy(): void;
10
- isDbError(ex: any): any[];
11
- createTransaction(trx: any): Promise<unknown>;
31
+ /**
32
+ * Classifies a caught database error by its PostgreSQL error code.
33
+ * Returns `[true, humanMessage]` for known DB errors that are safe to
34
+ * surface to the client, or `[false, '']` for unknown errors.
35
+ *
36
+ * Known codes:
37
+ * 23503 — foreign key violation (referenced record does not exist)
38
+ * 23505 — unique constraint violation (record already exists)
39
+ *
40
+ * Used by BaseCore.exceptionFailure() to decide whether to return the
41
+ * DB error message directly or log it and return a generic message.
42
+ */
43
+ isDbError(ex: any): [boolean, string];
44
+ /**
45
+ * Creates a new Knex transaction.
46
+ * If `trx` is provided, creates a nested transaction on the existing one.
47
+ * Prefer `startTransaction()` for standard usage — this method is lower-level.
48
+ */
49
+ createTransaction(trx: any): Promise<any>;
50
+ /**
51
+ * Returns the database type string (e.g. 'pg', 'mysql2', 'sqlite3').
52
+ * Used by gateways to build type-specific query fragments.
53
+ */
12
54
  getDbType(): string;
55
+ /**
56
+ * Returns the configured schema name, or empty string if not set.
57
+ */
13
58
  getSchema(): string;
59
+ /**
60
+ * Returns a Knex query builder for the given table, scoped to the
61
+ * configured schema if one is set. Uses the active transaction if present.
62
+ *
63
+ * Fix: withSchema() is only called when dbSchema is non-empty — passing
64
+ * an empty string to withSchema() causes unexpected behaviour in some drivers.
65
+ *
66
+ * @param arg Table name or Knex raw expression
67
+ */
14
68
  getBuilder(arg: any): any;
69
+ /**
70
+ * Returns a Knex raw expression. Useful for CONCAT, uuid_generate_v4(),
71
+ * and other DB-level expressions used in gateway transforms.
72
+ *
73
+ * @param query Raw SQL string with optional `?` placeholders
74
+ * @param bindings Values to bind to `?` placeholders
75
+ */
15
76
  raw(query: string, bindings?: any): any;
77
+ /**
78
+ * Executes a raw SQL query against the database.
79
+ * Uses the active transaction if present.
80
+ *
81
+ * @param query Raw SQL string with optional `?` placeholders
82
+ * @param bindings Values to bind to `?` placeholders
83
+ */
16
84
  runRawQuery(query: string, bindings: any): Promise<any>;
17
- startTransaction(): Promise<unknown>;
85
+ /**
86
+ * Starts a new database transaction and stores it on this instance.
87
+ * All subsequent `getBuilder()` calls will use the transaction until
88
+ * `commitTransaction()` or `rollbackTransaction()` is called.
89
+ *
90
+ * Guard: if a transaction is already active, logs a warning and returns
91
+ * the existing transaction rather than creating a nested one. Most databases
92
+ * do not support true nested transactions — the sameRequest flag in
93
+ * BaseCore.runAction() is the primary guard, but this adds a safety net.
94
+ *
95
+ * @returns The Knex transaction object
96
+ */
97
+ startTransaction(): Promise<any>;
98
+ /**
99
+ * Replaces the active transaction with the provided one.
100
+ * Use when a transaction was created externally (e.g. passed in from a
101
+ * test harness or a parent transaction manager).
102
+ */
18
103
  setTransaction(trx: any): void;
104
+ /**
105
+ * Returns the active transaction, or null if none is active.
106
+ */
19
107
  getTransaction(): any;
108
+ /**
109
+ * Commits the active transaction and clears it from this instance.
110
+ * Does nothing if no transaction is active.
111
+ */
20
112
  commitTransaction(): Promise<void>;
113
+ /**
114
+ * Rolls back the active transaction and clears it from this instance.
115
+ * Does nothing if no transaction is active.
116
+ *
117
+ * Rollback errors are caught and logged rather than re-thrown — a failed
118
+ * rollback is logged for observability but should not mask the original
119
+ * exception that triggered the rollback.
120
+ */
21
121
  rollbackTransaction(): Promise<void>;
122
+ /**
123
+ * Applies calculated field values to a single result row.
124
+ * Each entry in `calculatedFields` specifies a field name and either a
125
+ * static value or a function that receives the row and returns a value.
126
+ *
127
+ * Entries with no `name` are silently skipped with a warning.
128
+ *
129
+ * @param item The result row to mutate
130
+ * @param calculatedFields Array of { name, value } descriptors
131
+ */
22
132
  doCalculated(item: any, calculatedFields: any[]): void;
23
- read(args: DatabaseReadInterface): Promise<any>;
133
+ /**
134
+ * Executes a SELECT query with optional WHERE, whereIn, and query extension,
135
+ * then optionally maps results into a keyed object and/or applies
136
+ * calculated fields to each row.
137
+ *
138
+ * When `mapBy` is set, returns a `Record<string, row>` keyed by the
139
+ * camelCase value of `mapBy` field on each row, processed through
140
+ * `buildKey` (defaults to the `buildKey` from @sdflc/utils).
141
+ * When `mapBy` is not set, returns a plain array.
142
+ *
143
+ * @param args DatabaseReadInterface describing the query
144
+ */
145
+ read(args: DatabaseReadInterface): Promise<any[] | Record<string, any>>;
146
+ /**
147
+ * Converts a sortBy array from the API params format into the Knex
148
+ * `orderBy` format `[{ column, order }]`.
149
+ *
150
+ * Falls back to `defaultSortBy` if `sortBy` is null/undefined.
151
+ * Returns null if neither is provided — callers should skip `orderBy()`
152
+ * when this returns null.
153
+ *
154
+ * @param sortBy Array of `{ name, order }` from request params
155
+ * @param defaultSortBy Fallback sort config from gateway config
156
+ */
24
157
  createSortBy(sortBy: any[], defaultSortBy?: any): any[] | null;
158
+ /**
159
+ * Calculates `limit` and `offset` values from page/pageSize pagination params.
160
+ *
161
+ * Page is 1-indexed — page 1 with pageSize 10 gives offset 0.
162
+ * If `pageSize` is absent or NaN, `limit` is undefined (no limit applied).
163
+ * If `page` is absent, NaN, or < 1, it defaults to 1.
164
+ *
165
+ * @param page 1-based page number
166
+ * @param pageSize Number of records per page
167
+ */
25
168
  createLimitOffset(page: number, pageSize: number): {
26
169
  limit: number | undefined;
27
170
  offset: number;
28
171
  };
172
+ /**
173
+ * Combines `createLimitOffset()` and `createSortBy()` into a single call,
174
+ * reading pagination and sorting from the standard request params shape:
175
+ * `{ pagination: { page, pageSize }, sortBy: [{ name, order }] }`.
176
+ *
177
+ * Returns `{ limit, offset, sortBy }` ready to be applied to a Knex query.
178
+ * `sortBy` may be null if no sort is configured — callers should skip
179
+ * `query.orderBy()` in that case.
180
+ *
181
+ * @param params Request params object (may be null/undefined)
182
+ * @param defaultSortBy Fallback sort config from gateway config
183
+ */
29
184
  createLimitOffsetSortBy(params: any, defaultSortBy: any): {
30
185
  limit: number | undefined;
31
186
  offset: number;
32
187
  sortBy: any[] | null;
33
188
  };
189
+ /**
190
+ * Destroys the shared Knex connection pool for the given config.
191
+ * Use on application shutdown or in tests that need to reset the pool.
192
+ *
193
+ * Static because the pool is module-level — no instance needed.
194
+ */
34
195
  static destroyHandle(props: DatabaseOptions): void;
35
196
  }
36
197
  export { Database };
@@ -1,13 +1,42 @@
1
- import { camelCase } from 'lodash';
1
+ // ./src/Database.ts (capitalised to match class name convention)
2
+ import camelCase from 'lodash/camelCase';
2
3
  import knex from 'knex';
3
- import { buildKey as defaultBuildKey, Logger, LoggerLevels } from '@sdflc/utils';
4
+ import { buildKey as defaultBuildKey, Logger, LoggerLevels, isLogger } from '@sdflc/utils';
5
+ /**
6
+ * Module-level Knex handle cache keyed by connection config.
7
+ * Shared across all Database instances in the same process to avoid
8
+ * creating redundant connection pools for the same database.
9
+ *
10
+ * Key format: "host|port|user|database|schema"
11
+ * Note: password is intentionally excluded from the key to avoid
12
+ * storing credentials in memory beyond what the Knex driver requires.
13
+ */
4
14
  const knexHandles = {};
5
- const buildKey = (args) => {
15
+ /**
16
+ * Builds a deduplication key for the Knex handle cache from connection config.
17
+ * Excludes password to avoid unnecessary credential retention in memory.
18
+ */
19
+ const buildKnexCacheKey = (args) => {
6
20
  const { connection, dbSchema } = args || {};
7
- const { host, port, user, password, database } = connection || {};
8
- const parts = [host, port, user, password, database, dbSchema];
9
- return parts.join('|');
21
+ const { host, port, user, database } = connection || {};
22
+ return [host, port, user, database, dbSchema].join('|');
10
23
  };
24
+ /**
25
+ * Database is a thin wrapper around a Knex connection that adds:
26
+ * - Connection pool deduplication (one Knex instance per unique connection config)
27
+ * - Transaction lifecycle management (start, commit, rollback)
28
+ * - Schema-scoped query builder
29
+ * - Common DB error classification (isDbError)
30
+ * - Utility methods for pagination, sorting, calculated fields, and raw reads
31
+ *
32
+ * One Database instance is created per request in createContextDefault() and
33
+ * shared across all gateways via ApiContext. This ensures all gateways in a
34
+ * single request share the same transaction when one is active.
35
+ *
36
+ * Connection pools are shared across requests via the module-level knexHandles
37
+ * cache — creating a new Database instance does not open a new connection pool
38
+ * if one already exists for the same host/port/user/database/schema combination.
39
+ */
11
40
  class Database {
12
41
  trx = null;
13
42
  dbType = '';
@@ -18,10 +47,14 @@ class Database {
18
47
  if (!props.knexConfig) {
19
48
  throw new Error('The Database class expects to have `knexConfig` in its constructor props');
20
49
  }
21
- if (props.logger instanceof Logger) {
50
+ // Duck-type check to avoid instanceof failures across package versions
51
+ if (props.logger && isLogger(props.logger)) {
22
52
  this.logger = props.logger;
23
53
  }
24
- const cfgKey = buildKey({ connection: props.knexConfig.connection, dbSchema: props.dbSchema });
54
+ const cfgKey = buildKnexCacheKey({
55
+ connection: props.knexConfig.connection,
56
+ dbSchema: props.dbSchema,
57
+ });
25
58
  if (!knexHandles[cfgKey]) {
26
59
  this.logger.debug(`Create a new KnexJs configuration`);
27
60
  knexHandles[cfgKey] = knex(props.knexConfig);
@@ -32,85 +65,193 @@ class Database {
32
65
  this.knexHandle = knexHandles[cfgKey];
33
66
  this.dbType = props.dbType || props.knexConfig?.client || '';
34
67
  this.dbSchema = props.dbSchema || '';
35
- this.trx = props.trx;
68
+ this.trx = props.trx || null;
36
69
  }
70
+ /**
71
+ * Destroys the Knex connection pool for this instance.
72
+ * Call on application shutdown to cleanly close all DB connections.
73
+ * Note: affects all instances sharing this pool — use with care.
74
+ */
37
75
  destroy() {
38
76
  if (this.knexHandle) {
39
77
  this.knexHandle.destroy();
40
78
  }
41
79
  }
80
+ /**
81
+ * Classifies a caught database error by its PostgreSQL error code.
82
+ * Returns `[true, humanMessage]` for known DB errors that are safe to
83
+ * surface to the client, or `[false, '']` for unknown errors.
84
+ *
85
+ * Known codes:
86
+ * 23503 — foreign key violation (referenced record does not exist)
87
+ * 23505 — unique constraint violation (record already exists)
88
+ *
89
+ * Used by BaseCore.exceptionFailure() to decide whether to return the
90
+ * DB error message directly or log it and return a generic message.
91
+ */
42
92
  isDbError(ex) {
43
93
  const { code } = ex || {};
44
94
  switch (code) {
45
- default:
46
- return [false, ''];
47
95
  case '23503':
48
- // ex.detail: 'Key (message_id)=(78403d9e-4e95-4091-8136-ae99ddbfa3ca) is not present in table "message".',
49
- // ex.constraint: 'message_recipient_status_message_id_foreign',
50
- return [true, `Reference does not exist`];
96
+ return [true, 'Reference does not exist'];
51
97
  case '23505':
52
- return [true, `Such item already exists`];
98
+ return [true, 'Such item already exists'];
99
+ default:
100
+ return [false, ''];
53
101
  }
54
102
  }
55
- createTransaction(trx) {
56
- return new Promise((resolve) => {
57
- return (trx ? trx : this.knexHandle).transaction(resolve);
58
- });
103
+ /**
104
+ * Creates a new Knex transaction.
105
+ * If `trx` is provided, creates a nested transaction on the existing one.
106
+ * Prefer `startTransaction()` for standard usage — this method is lower-level.
107
+ */
108
+ async createTransaction(trx) {
109
+ return (trx ? trx : this.knexHandle).transaction();
59
110
  }
111
+ /**
112
+ * Returns the database type string (e.g. 'pg', 'mysql2', 'sqlite3').
113
+ * Used by gateways to build type-specific query fragments.
114
+ */
60
115
  getDbType() {
61
116
  return this.dbType;
62
117
  }
118
+ /**
119
+ * Returns the configured schema name, or empty string if not set.
120
+ */
63
121
  getSchema() {
64
122
  return this.dbSchema;
65
123
  }
124
+ /**
125
+ * Returns a Knex query builder for the given table, scoped to the
126
+ * configured schema if one is set. Uses the active transaction if present.
127
+ *
128
+ * Fix: withSchema() is only called when dbSchema is non-empty — passing
129
+ * an empty string to withSchema() causes unexpected behaviour in some drivers.
130
+ *
131
+ * @param arg Table name or Knex raw expression
132
+ */
66
133
  getBuilder(arg) {
67
- return this.trx ? this.trx(arg).withSchema(this.getSchema()) : this.knexHandle(arg).withSchema(this.getSchema());
134
+ const builder = this.trx ? this.trx(arg) : this.knexHandle(arg);
135
+ return this.dbSchema ? builder.withSchema(this.dbSchema) : builder;
68
136
  }
137
+ /**
138
+ * Returns a Knex raw expression. Useful for CONCAT, uuid_generate_v4(),
139
+ * and other DB-level expressions used in gateway transforms.
140
+ *
141
+ * @param query Raw SQL string with optional `?` placeholders
142
+ * @param bindings Values to bind to `?` placeholders
143
+ */
69
144
  raw(query, bindings) {
70
145
  return this.knexHandle.raw(query, bindings);
71
146
  }
147
+ /**
148
+ * Executes a raw SQL query against the database.
149
+ * Uses the active transaction if present.
150
+ *
151
+ * @param query Raw SQL string with optional `?` placeholders
152
+ * @param bindings Values to bind to `?` placeholders
153
+ */
72
154
  async runRawQuery(query, bindings) {
73
- const rows = await (this.trx ? this.trx : this.knexHandle).raw(query, bindings);
74
- return rows;
155
+ return (this.trx ? this.trx : this.knexHandle).raw(query, bindings);
75
156
  }
157
+ /**
158
+ * Starts a new database transaction and stores it on this instance.
159
+ * All subsequent `getBuilder()` calls will use the transaction until
160
+ * `commitTransaction()` or `rollbackTransaction()` is called.
161
+ *
162
+ * Guard: if a transaction is already active, logs a warning and returns
163
+ * the existing transaction rather than creating a nested one. Most databases
164
+ * do not support true nested transactions — the sameRequest flag in
165
+ * BaseCore.runAction() is the primary guard, but this adds a safety net.
166
+ *
167
+ * @returns The Knex transaction object
168
+ */
76
169
  async startTransaction() {
77
- const trx = await this.createTransaction(this.trx);
170
+ if (this.trx) {
171
+ this.logger.warn(`startTransaction called while a transaction is already active — reusing existing transaction`);
172
+ return this.trx;
173
+ }
174
+ const trx = await this.createTransaction(null);
78
175
  this.trx = trx;
79
176
  return trx;
80
177
  }
178
+ /**
179
+ * Replaces the active transaction with the provided one.
180
+ * Use when a transaction was created externally (e.g. passed in from a
181
+ * test harness or a parent transaction manager).
182
+ */
81
183
  setTransaction(trx) {
82
184
  this.trx = trx;
83
185
  }
186
+ /**
187
+ * Returns the active transaction, or null if none is active.
188
+ */
84
189
  getTransaction() {
85
190
  return this.trx;
86
191
  }
192
+ /**
193
+ * Commits the active transaction and clears it from this instance.
194
+ * Does nothing if no transaction is active.
195
+ */
87
196
  async commitTransaction() {
88
197
  if (this.trx) {
89
198
  await this.trx.commit();
90
- this.trx = undefined;
199
+ this.trx = null;
91
200
  }
92
201
  }
202
+ /**
203
+ * Rolls back the active transaction and clears it from this instance.
204
+ * Does nothing if no transaction is active.
205
+ *
206
+ * Rollback errors are caught and logged rather than re-thrown — a failed
207
+ * rollback is logged for observability but should not mask the original
208
+ * exception that triggered the rollback.
209
+ */
93
210
  async rollbackTransaction() {
94
211
  if (this.trx) {
95
212
  try {
96
213
  await this.trx.rollback();
97
214
  }
98
215
  catch (ex) {
99
- // Do nothing here
100
- this.logger.error(`Failed to rollback a transaction:`, ex.message);
216
+ this.logger.error(`Failed to rollback a transaction:`, ex?.message ?? String(ex));
101
217
  }
102
218
  }
103
- this.trx = undefined;
219
+ this.trx = null;
104
220
  }
221
+ /**
222
+ * Applies calculated field values to a single result row.
223
+ * Each entry in `calculatedFields` specifies a field name and either a
224
+ * static value or a function that receives the row and returns a value.
225
+ *
226
+ * Entries with no `name` are silently skipped with a warning.
227
+ *
228
+ * @param item The result row to mutate
229
+ * @param calculatedFields Array of { name, value } descriptors
230
+ */
105
231
  doCalculated(item, calculatedFields) {
106
232
  calculatedFields.forEach((calcField) => {
107
- if (calcField.name) {
108
- item[calcField.name] = typeof calcField.value === 'function' ? calcField.value(item) : calcField.value;
233
+ if (!calcField.name) {
234
+ this.logger.warn(`doCalculated: skipping entry with missing 'name' field`, calcField);
235
+ return;
109
236
  }
237
+ item[calcField.name] = typeof calcField.value === 'function' ? calcField.value(item) : calcField.value;
110
238
  });
111
239
  }
240
+ /**
241
+ * Executes a SELECT query with optional WHERE, whereIn, and query extension,
242
+ * then optionally maps results into a keyed object and/or applies
243
+ * calculated fields to each row.
244
+ *
245
+ * When `mapBy` is set, returns a `Record<string, row>` keyed by the
246
+ * camelCase value of `mapBy` field on each row, processed through
247
+ * `buildKey` (defaults to the `buildKey` from @sdflc/utils).
248
+ * When `mapBy` is not set, returns a plain array.
249
+ *
250
+ * @param args DatabaseReadInterface describing the query
251
+ */
112
252
  async read(args) {
113
- const { where, whereIn, extendQuery, table, selectFields, mapBy, calculated, buildKey } = args || {};
253
+ const { where, whereIn, extendQuery, table, selectFields, mapBy, calculated, buildKey: callerBuildKey, // renamed to avoid shadowing module-level buildKnexCacheKey
254
+ } = args || {};
114
255
  const query = this.getBuilder(table).select(Array.isArray(selectFields) && selectFields.length > 0 ? selectFields : '*');
115
256
  if (where) {
116
257
  query.where(where);
@@ -122,43 +263,58 @@ class Database {
122
263
  await extendQuery(query);
123
264
  }
124
265
  let dbResults = await query;
266
+ const hasCalculated = Array.isArray(calculated) && calculated.length > 0;
125
267
  if (mapBy) {
126
- const fnBuildKey = typeof buildKey === 'function' ? buildKey : defaultBuildKey;
268
+ const fnBuildKey = typeof callerBuildKey === 'function' ? callerBuildKey : defaultBuildKey;
127
269
  dbResults = dbResults.reduce((acc, item) => {
128
270
  const key = fnBuildKey(item[camelCase(mapBy)]);
129
- if (Array.isArray(calculated) && calculated.length > 0) {
271
+ if (hasCalculated) {
130
272
  this.doCalculated(item, calculated);
131
273
  }
132
274
  acc[key] = item;
133
275
  return acc;
134
276
  }, {});
135
277
  }
136
- else {
137
- if (Array.isArray(calculated) && calculated.length > 0) {
138
- dbResults.forEach((row) => {
139
- this.doCalculated(row, calculated);
140
- });
141
- }
278
+ else if (hasCalculated) {
279
+ dbResults.forEach((row) => {
280
+ this.doCalculated(row, calculated);
281
+ });
142
282
  }
143
283
  return dbResults;
144
284
  }
285
+ /**
286
+ * Converts a sortBy array from the API params format into the Knex
287
+ * `orderBy` format `[{ column, order }]`.
288
+ *
289
+ * Falls back to `defaultSortBy` if `sortBy` is null/undefined.
290
+ * Returns null if neither is provided — callers should skip `orderBy()`
291
+ * when this returns null.
292
+ *
293
+ * @param sortBy Array of `{ name, order }` from request params
294
+ * @param defaultSortBy Fallback sort config from gateway config
295
+ */
145
296
  createSortBy(sortBy, defaultSortBy) {
146
297
  if (!sortBy) {
147
298
  if (Array.isArray(defaultSortBy)) {
148
299
  return this.createSortBy(defaultSortBy);
149
300
  }
150
- else {
151
- return null;
152
- }
301
+ return null;
153
302
  }
154
303
  return sortBy.reduce((acc, item) => {
155
- acc.push({
156
- column: item.name,
157
- order: item.order,
158
- });
304
+ acc.push({ column: item.name, order: item.order });
159
305
  return acc;
160
306
  }, []);
161
307
  }
308
+ /**
309
+ * Calculates `limit` and `offset` values from page/pageSize pagination params.
310
+ *
311
+ * Page is 1-indexed — page 1 with pageSize 10 gives offset 0.
312
+ * If `pageSize` is absent or NaN, `limit` is undefined (no limit applied).
313
+ * If `page` is absent, NaN, or < 1, it defaults to 1.
314
+ *
315
+ * @param page 1-based page number
316
+ * @param pageSize Number of records per page
317
+ */
162
318
  createLimitOffset(page, pageSize) {
163
319
  const limit = isNaN(pageSize) || pageSize == null ? undefined : Number(pageSize);
164
320
  const pageToUse = isNaN(page) || page < 1 ? 1 : Number(page);
@@ -167,19 +323,36 @@ class Database {
167
323
  offset: limit ? (pageToUse - 1) * limit : 0,
168
324
  };
169
325
  }
326
+ /**
327
+ * Combines `createLimitOffset()` and `createSortBy()` into a single call,
328
+ * reading pagination and sorting from the standard request params shape:
329
+ * `{ pagination: { page, pageSize }, sortBy: [{ name, order }] }`.
330
+ *
331
+ * Returns `{ limit, offset, sortBy }` ready to be applied to a Knex query.
332
+ * `sortBy` may be null if no sort is configured — callers should skip
333
+ * `query.orderBy()` in that case.
334
+ *
335
+ * @param params Request params object (may be null/undefined)
336
+ * @param defaultSortBy Fallback sort config from gateway config
337
+ */
170
338
  createLimitOffsetSortBy(params, defaultSortBy) {
171
339
  const { pagination, sortBy } = params || {};
172
340
  const { page, pageSize } = pagination || {};
173
341
  const { limit, offset } = this.createLimitOffset(page, pageSize);
174
342
  const sortByToUse = this.createSortBy(sortBy, defaultSortBy);
175
- return {
176
- limit,
177
- offset,
178
- sortBy: sortByToUse,
179
- };
343
+ return { limit, offset, sortBy: sortByToUse };
180
344
  }
345
+ /**
346
+ * Destroys the shared Knex connection pool for the given config.
347
+ * Use on application shutdown or in tests that need to reset the pool.
348
+ *
349
+ * Static because the pool is module-level — no instance needed.
350
+ */
181
351
  static destroyHandle(props) {
182
- const cfgKey = buildKey({ connection: props.knexConfig.connection, dbSchema: props.dbSchema });
352
+ const cfgKey = buildKnexCacheKey({
353
+ connection: props.knexConfig.connection,
354
+ dbSchema: props.dbSchema,
355
+ });
183
356
  if (knexHandles[cfgKey]) {
184
357
  knexHandles[cfgKey].destroy();
185
358
  delete knexHandles[cfgKey];