@sdflc/backend-helpers 1.0.112 → 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.
- package/README.md +1422 -146
- package/build/BaseController.d.ts +20 -0
- package/build/BaseController.js +64 -0
- package/build/BaseCore.d.ts +470 -33
- package/build/BaseCore.js +608 -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/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +12 -27
- 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 +470 -33
- package/build/esm/BaseCore.js +599 -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/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 +12 -27
- 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 +5 -2
- package/build/esm/index.js +5 -2
- package/build/esm/interfaces/ApiContext.d.ts +7 -3
- 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 +87 -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 +20 -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 +5 -2
- package/build/index.js +5 -2
- package/build/interfaces/ApiContext.d.ts +7 -3
- 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 +87 -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 +20 -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/Database.d.ts
CHANGED
|
@@ -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
|
-
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 };
|
package/build/esm/Database.js
CHANGED
|
@@ -1,13 +1,42 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
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,
|
|
8
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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,
|
|
98
|
+
return [true, 'Such item already exists'];
|
|
99
|
+
default:
|
|
100
|
+
return [false, ''];
|
|
53
101
|
}
|
|
54
102
|
}
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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
|
|
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
|
|
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 (
|
|
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
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
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 =
|
|
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];
|