@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
|
@@ -1,49 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DbMigratorAndSeeder provides database lifecycle management for development,
|
|
3
|
+
* testing, and CI environments.
|
|
4
|
+
*
|
|
5
|
+
* Responsibilities:
|
|
6
|
+
* - Running Knex migrations
|
|
7
|
+
* - Seeding the database from structured seed files
|
|
8
|
+
* - Wiping (dropping all tables) and resetting (wipe + migrate + seed)
|
|
9
|
+
* - Cleaning (truncating) specific tables between test runs
|
|
10
|
+
*
|
|
11
|
+
* NOT intended for production runtime use.
|
|
12
|
+
*
|
|
13
|
+
* @param knexHandle A configured Knex instance (not a Database wrapper)
|
|
14
|
+
* @param config Configuration object with dbType, dbSchema, and optional flags
|
|
15
|
+
*/
|
|
1
16
|
declare class DbMigratorAndSeeder {
|
|
2
17
|
private knexHandle;
|
|
3
18
|
private config;
|
|
4
19
|
private logger;
|
|
5
20
|
constructor(knexHandle: any, config?: any);
|
|
21
|
+
/**
|
|
22
|
+
* Runs all pending Knex migrations and optionally seeds the database.
|
|
23
|
+
*
|
|
24
|
+
* Seeds are only run when `config.runDbSeed` is true AND at least one
|
|
25
|
+
* migration was applied — prevents re-seeding an already-seeded database.
|
|
26
|
+
*
|
|
27
|
+
* Fix: `currentVersion()` returns a Promise — was logged without await,
|
|
28
|
+
* producing `[object Promise]` in the output.
|
|
29
|
+
*/
|
|
6
30
|
runMigrations(): Promise<void>;
|
|
7
31
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
32
|
+
* Converts an array of seed result objects into a single flat object.
|
|
33
|
+
*
|
|
34
|
+
* Converts: `[{ table1: [...], table2: [...] }, { table3: [...] }]`
|
|
35
|
+
* Into: `{ table1: [...], table2: [...], table3: [...] }`
|
|
36
|
+
*
|
|
37
|
+
* Fix: replaced `for...in` (which includes inherited properties) with
|
|
38
|
+
* `Object.assign()` which only copies own enumerable properties.
|
|
39
|
+
*
|
|
40
|
+
* @param generatedSeedArrays Array of seed result objects to merge
|
|
12
41
|
*/
|
|
13
|
-
transformSeedsToObject(generatedSeedArrays: any[]): any
|
|
42
|
+
transformSeedsToObject(generatedSeedArrays: any[]): Record<string, any[]>;
|
|
14
43
|
/**
|
|
15
|
-
*
|
|
44
|
+
* Drops all tables then runs all pending migrations.
|
|
45
|
+
* Intended for full environment resets between test suites.
|
|
46
|
+
*
|
|
47
|
+
* Fix: now re-throws after logging so callers know the reset failed
|
|
48
|
+
* rather than silently continuing with a broken database state.
|
|
16
49
|
*/
|
|
17
50
|
resetDb(): Promise<void>;
|
|
18
51
|
/**
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
52
|
+
* Drops all tables in the configured schema (or entire database if no schema).
|
|
53
|
+
*
|
|
54
|
+
* WARNING: Destructive — permanently removes all tables and data.
|
|
55
|
+
* Does not handle foreign key constraints — tables with dependencies may
|
|
56
|
+
* fail. See TODO.
|
|
57
|
+
*
|
|
58
|
+
* TODO: Remove all constraints before dropping tables.
|
|
59
|
+
*
|
|
60
|
+
* Fix: `BPromise.each()` was called without `await` — DROP TABLE commands
|
|
61
|
+
* were fire-and-forget, meaning wipeDb() resolved before any tables were
|
|
62
|
+
* actually dropped. Subsequent runMigrations() would run on un-wiped tables.
|
|
22
63
|
*/
|
|
23
64
|
wipeDb(): Promise<void>;
|
|
24
65
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
66
|
+
* Deletes all records from the provided list of tables, one at a time.
|
|
67
|
+
* Order matters if foreign key constraints exist — pass tables in
|
|
68
|
+
* dependency order (dependents before parents).
|
|
69
|
+
*
|
|
70
|
+
* Fix: removed redundant `new BPromise(resolve => resolve(...))` wrapper —
|
|
71
|
+
* the function is already async so returning directly is equivalent.
|
|
72
|
+
*
|
|
73
|
+
* @param tablesToClean Array of table names to truncate
|
|
30
74
|
*/
|
|
31
|
-
cleanDb(tablesToClean:
|
|
75
|
+
cleanDb(tablesToClean: string[]): Promise<string[]>;
|
|
32
76
|
/**
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
77
|
+
* Deletes all records from a single table, with optional WHERE filters.
|
|
78
|
+
*
|
|
79
|
+
* If `config.cleanTableFilters[table]` is configured, applies additional
|
|
80
|
+
* WHERE conditions before deleting — useful for preserving system/seed
|
|
81
|
+
* records while clearing user-generated test data.
|
|
82
|
+
*
|
|
83
|
+
* Only filter entries with a `fieldName` property are applied —
|
|
84
|
+
* entries missing `fieldName` are silently skipped.
|
|
85
|
+
*
|
|
86
|
+
* @param table Name of the table to clean
|
|
37
87
|
*/
|
|
38
88
|
cleanDbTable(table: string): Promise<void>;
|
|
39
89
|
/**
|
|
40
|
-
* Returns
|
|
41
|
-
*
|
|
90
|
+
* Returns the list of table names in the configured schema.
|
|
91
|
+
* Tables listed in `config.skipTables` are excluded from the result.
|
|
92
|
+
*
|
|
93
|
+
* Uses schema-scoped query when `config.dbSchema` is set,
|
|
94
|
+
* otherwise queries all tables in the database.
|
|
95
|
+
*
|
|
96
|
+
* Note: result extraction uses `tables.rows` which is pg-specific.
|
|
97
|
+
* Other drivers may return the array directly — handled with fallback.
|
|
98
|
+
*
|
|
99
|
+
* @returns Array of table names in the configured schema
|
|
100
|
+
*/
|
|
101
|
+
listDbTables(): Promise<string[]>;
|
|
102
|
+
/**
|
|
103
|
+
* Loads and executes seed generator functions from the provided file list,
|
|
104
|
+
* building a dependency-ordered array of seed groups.
|
|
105
|
+
*
|
|
106
|
+
* `seedFiles` is an array of groups (arrays of filenames). Within each group,
|
|
107
|
+
* seeds are generated sequentially and the results of earlier seeds are
|
|
108
|
+
* available to later seeds in the same group via the `seeds` accumulator.
|
|
109
|
+
* This allows seeds to reference the ids of previously generated records.
|
|
110
|
+
*
|
|
111
|
+
* Files are loaded from `dirname/objects/<filename>` without extension —
|
|
112
|
+
* the module resolver handles `.js`/`.ts` extension based on the runtime.
|
|
113
|
+
*
|
|
114
|
+
* Fix: removed hardcoded `.js` extension from dynamic imports — was breaking
|
|
115
|
+
* in TypeScript and ESM environments.
|
|
116
|
+
*
|
|
117
|
+
* @param dirname Absolute directory path containing the `objects/` folder
|
|
118
|
+
* @param seedFiles Array of filename groups, e.g. `[['users'], ['posts', 'comments']]`
|
|
119
|
+
* @returns Array of seed group objects ready for `insertRecords()`
|
|
120
|
+
*/
|
|
121
|
+
generateSeeds(dirname: string, seedFiles: string[][]): Promise<any[]>;
|
|
122
|
+
/**
|
|
123
|
+
* Deletes all records for the tables referenced by `seedFiles`, in reverse
|
|
124
|
+
* order to respect foreign key dependencies (children before parents).
|
|
125
|
+
*
|
|
126
|
+
* @param seedFiles Array of filename groups — table order is derived from
|
|
127
|
+
* the flattened + reversed list of filenames
|
|
128
|
+
*/
|
|
129
|
+
removeSeedsFromDb(seedFiles: string[][]): Promise<string[]>;
|
|
130
|
+
/**
|
|
131
|
+
* Inserts seed records group by group, in order.
|
|
132
|
+
* Groups are processed sequentially (each group waits for the previous)
|
|
133
|
+
* but records within a group are inserted in parallel via `Promise.all`.
|
|
134
|
+
*
|
|
135
|
+
* Sequential group processing preserves seed dependency order —
|
|
136
|
+
* a group that references records from a previous group can rely on
|
|
137
|
+
* those records being present before it runs.
|
|
138
|
+
*
|
|
139
|
+
* @param seedGroups Array of seed group objects from `generateSeeds()`
|
|
140
|
+
*/
|
|
141
|
+
insertRecords(seedGroups: any[]): Promise<void>;
|
|
142
|
+
/**
|
|
143
|
+
* Full seed pipeline: generate seeds, remove existing records, then insert.
|
|
144
|
+
*
|
|
145
|
+
* @param dirname Absolute directory path containing the `objects/` folder
|
|
146
|
+
* @param seedFiles Array of filename groups
|
|
42
147
|
*/
|
|
43
|
-
|
|
44
|
-
generateSeeds(dirname: string, seedFiles: any): Promise<any>;
|
|
45
|
-
removeSeedsFromDb(seedFiles: any): Promise<unknown>;
|
|
46
|
-
insertRecords(seedGroups: any): Promise<any>;
|
|
47
|
-
runSeeds(dirname: string, seedFiles: any): Promise<any>;
|
|
148
|
+
runSeeds(dirname: string, seedFiles: string[][]): Promise<void>;
|
|
48
149
|
}
|
|
49
150
|
export { DbMigratorAndSeeder };
|
|
@@ -1,29 +1,53 @@
|
|
|
1
|
+
// ./src/DbMigratorAndSeeder.ts
|
|
1
2
|
import path from 'path';
|
|
2
|
-
import
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
3
|
+
import { camelCase, flatten } from 'lodash';
|
|
4
|
+
import { Logger, LoggerLevels, isLogger } from '@sdflc/utils';
|
|
5
|
+
import { assertSupportedDbType, sanitiseIdentifier } from './dbHelpers';
|
|
6
|
+
/**
|
|
7
|
+
* Database SQL templates — pg only.
|
|
8
|
+
* Schema identifiers are sanitised via sanitiseIdentifier() before interpolation
|
|
9
|
+
* to prevent SQL injection.
|
|
10
|
+
*
|
|
11
|
+
* Fix: removed stray `'` before `;` in dropTables which produced invalid SQL.
|
|
12
|
+
*/
|
|
5
13
|
const SQLS = {
|
|
6
14
|
pg: {
|
|
7
|
-
listTablesSchema: (
|
|
15
|
+
listTablesSchema: (config) => `
|
|
8
16
|
SELECT TABLE_NAME as table_name
|
|
9
17
|
FROM INFORMATION_SCHEMA.TABLES
|
|
10
|
-
WHERE TABLE_SCHEMA = '${
|
|
18
|
+
WHERE TABLE_SCHEMA = '${sanitiseIdentifier(config?.dbSchema)}';
|
|
11
19
|
`,
|
|
12
20
|
listTables: () => `
|
|
13
21
|
SELECT TABLE_NAME as table_name
|
|
14
|
-
FROM INFORMATION_SCHEMA.TABLES
|
|
22
|
+
FROM INFORMATION_SCHEMA.TABLES;
|
|
15
23
|
`,
|
|
16
|
-
dropTablesSchema: (
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
24
|
+
dropTablesSchema: (config) => `
|
|
25
|
+
SELECT 'DROP TABLE IF EXISTS ${sanitiseIdentifier(config?.dbSchema)}.' || TABLE_NAME || ';' as cmd
|
|
26
|
+
FROM INFORMATION_SCHEMA.TABLES
|
|
27
|
+
WHERE TABLE_SCHEMA = '${sanitiseIdentifier(config?.dbSchema)}';
|
|
20
28
|
`,
|
|
21
29
|
dropTables: () => `
|
|
22
30
|
SELECT 'DROP TABLE IF EXISTS ' || TABLE_NAME || ';' as cmd
|
|
23
|
-
FROM INFORMATION_SCHEMA.TABLES
|
|
31
|
+
FROM INFORMATION_SCHEMA.TABLES;
|
|
24
32
|
`,
|
|
25
33
|
},
|
|
26
34
|
};
|
|
35
|
+
// ─── Class ────────────────────────────────────────────────────────────────────
|
|
36
|
+
/**
|
|
37
|
+
* DbMigratorAndSeeder provides database lifecycle management for development,
|
|
38
|
+
* testing, and CI environments.
|
|
39
|
+
*
|
|
40
|
+
* Responsibilities:
|
|
41
|
+
* - Running Knex migrations
|
|
42
|
+
* - Seeding the database from structured seed files
|
|
43
|
+
* - Wiping (dropping all tables) and resetting (wipe + migrate + seed)
|
|
44
|
+
* - Cleaning (truncating) specific tables between test runs
|
|
45
|
+
*
|
|
46
|
+
* NOT intended for production runtime use.
|
|
47
|
+
*
|
|
48
|
+
* @param knexHandle A configured Knex instance (not a Database wrapper)
|
|
49
|
+
* @param config Configuration object with dbType, dbSchema, and optional flags
|
|
50
|
+
*/
|
|
27
51
|
class DbMigratorAndSeeder {
|
|
28
52
|
knexHandle;
|
|
29
53
|
config;
|
|
@@ -31,33 +55,48 @@ class DbMigratorAndSeeder {
|
|
|
31
55
|
constructor(knexHandle, config) {
|
|
32
56
|
this.knexHandle = knexHandle;
|
|
33
57
|
this.config = config;
|
|
34
|
-
|
|
58
|
+
// Duck-type check to avoid instanceof failures across package versions
|
|
59
|
+
this.logger = isLogger(config?.logger) ? config.logger : new Logger({ level: LoggerLevels.LOG });
|
|
35
60
|
}
|
|
61
|
+
/**
|
|
62
|
+
* Runs all pending Knex migrations and optionally seeds the database.
|
|
63
|
+
*
|
|
64
|
+
* Seeds are only run when `config.runDbSeed` is true AND at least one
|
|
65
|
+
* migration was applied — prevents re-seeding an already-seeded database.
|
|
66
|
+
*
|
|
67
|
+
* Fix: `currentVersion()` returns a Promise — was logged without await,
|
|
68
|
+
* producing `[object Promise]` in the output.
|
|
69
|
+
*/
|
|
36
70
|
async runMigrations() {
|
|
37
71
|
const result = await this.knexHandle.migrate.latest();
|
|
38
|
-
if (this.config
|
|
72
|
+
if (this.config?.runDbSeed && result[1].length > 0) {
|
|
39
73
|
await this.knexHandle.seed.run();
|
|
40
74
|
}
|
|
41
75
|
this.logger.log(`Ran ${result[1].length} migration(s)`);
|
|
42
|
-
|
|
76
|
+
// Fix: await the Promise — was previously logging '[object Promise]'
|
|
77
|
+
const version = await this.knexHandle.migrate.currentVersion();
|
|
43
78
|
this.logger.log(`Current version of database: ${version}`);
|
|
44
79
|
}
|
|
45
80
|
/**
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
81
|
+
* Converts an array of seed result objects into a single flat object.
|
|
82
|
+
*
|
|
83
|
+
* Converts: `[{ table1: [...], table2: [...] }, { table3: [...] }]`
|
|
84
|
+
* Into: `{ table1: [...], table2: [...], table3: [...] }`
|
|
85
|
+
*
|
|
86
|
+
* Fix: replaced `for...in` (which includes inherited properties) with
|
|
87
|
+
* `Object.assign()` which only copies own enumerable properties.
|
|
88
|
+
*
|
|
89
|
+
* @param generatedSeedArrays Array of seed result objects to merge
|
|
50
90
|
*/
|
|
51
91
|
transformSeedsToObject(generatedSeedArrays) {
|
|
52
|
-
return reduce(
|
|
53
|
-
for (const key in cur) {
|
|
54
|
-
acc[key] = cur[key];
|
|
55
|
-
}
|
|
56
|
-
return acc;
|
|
57
|
-
}, {});
|
|
92
|
+
return generatedSeedArrays.reduce((acc, cur) => Object.assign(acc, cur), {});
|
|
58
93
|
}
|
|
59
94
|
/**
|
|
60
|
-
*
|
|
95
|
+
* Drops all tables then runs all pending migrations.
|
|
96
|
+
* Intended for full environment resets between test suites.
|
|
97
|
+
*
|
|
98
|
+
* Fix: now re-throws after logging so callers know the reset failed
|
|
99
|
+
* rather than silently continuing with a broken database state.
|
|
61
100
|
*/
|
|
62
101
|
async resetDb() {
|
|
63
102
|
try {
|
|
@@ -65,81 +104,132 @@ class DbMigratorAndSeeder {
|
|
|
65
104
|
await this.runMigrations();
|
|
66
105
|
}
|
|
67
106
|
catch (ex) {
|
|
68
|
-
this.logger.error('An exception has occurred on resetting database:
|
|
107
|
+
this.logger.error('An exception has occurred on resetting database:', ex);
|
|
108
|
+
throw ex;
|
|
69
109
|
}
|
|
70
110
|
}
|
|
71
111
|
/**
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
112
|
+
* Drops all tables in the configured schema (or entire database if no schema).
|
|
113
|
+
*
|
|
114
|
+
* WARNING: Destructive — permanently removes all tables and data.
|
|
115
|
+
* Does not handle foreign key constraints — tables with dependencies may
|
|
116
|
+
* fail. See TODO.
|
|
117
|
+
*
|
|
118
|
+
* TODO: Remove all constraints before dropping tables.
|
|
119
|
+
*
|
|
120
|
+
* Fix: `BPromise.each()` was called without `await` — DROP TABLE commands
|
|
121
|
+
* were fire-and-forget, meaning wipeDb() resolved before any tables were
|
|
122
|
+
* actually dropped. Subsequent runMigrations() would run on un-wiped tables.
|
|
75
123
|
*/
|
|
76
124
|
async wipeDb() {
|
|
125
|
+
assertSupportedDbType(this.config.dbType);
|
|
77
126
|
const query = this.config.dbSchema
|
|
78
127
|
? SQLS[this.config.dbType].dropTablesSchema(this.config)
|
|
79
128
|
: SQLS[this.config.dbType].dropTables(this.config);
|
|
80
129
|
const result = await this.knexHandle.raw(query);
|
|
81
130
|
const commands = result.rows.map((r) => r.cmd);
|
|
82
|
-
BPromise.each(
|
|
131
|
+
// Fix: replaced BPromise.each() (unawaited) with for...of + await
|
|
132
|
+
// to ensure all DROP TABLE commands complete before wipeDb() resolves
|
|
133
|
+
for (const cmd of commands) {
|
|
134
|
+
await this.knexHandle.raw(cmd);
|
|
135
|
+
}
|
|
83
136
|
}
|
|
84
137
|
/**
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
138
|
+
* Deletes all records from the provided list of tables, one at a time.
|
|
139
|
+
* Order matters if foreign key constraints exist — pass tables in
|
|
140
|
+
* dependency order (dependents before parents).
|
|
141
|
+
*
|
|
142
|
+
* Fix: removed redundant `new BPromise(resolve => resolve(...))` wrapper —
|
|
143
|
+
* the function is already async so returning directly is equivalent.
|
|
144
|
+
*
|
|
145
|
+
* @param tablesToClean Array of table names to truncate
|
|
90
146
|
*/
|
|
91
147
|
async cleanDb(tablesToClean) {
|
|
92
|
-
for (
|
|
93
|
-
await this.cleanDbTable(
|
|
148
|
+
for (const table of tablesToClean) {
|
|
149
|
+
await this.cleanDbTable(table);
|
|
94
150
|
}
|
|
95
|
-
return
|
|
96
|
-
resolve(tablesToClean);
|
|
97
|
-
});
|
|
151
|
+
return tablesToClean;
|
|
98
152
|
}
|
|
99
153
|
/**
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
154
|
+
* Deletes all records from a single table, with optional WHERE filters.
|
|
155
|
+
*
|
|
156
|
+
* If `config.cleanTableFilters[table]` is configured, applies additional
|
|
157
|
+
* WHERE conditions before deleting — useful for preserving system/seed
|
|
158
|
+
* records while clearing user-generated test data.
|
|
159
|
+
*
|
|
160
|
+
* Only filter entries with a `fieldName` property are applied —
|
|
161
|
+
* entries missing `fieldName` are silently skipped.
|
|
162
|
+
*
|
|
163
|
+
* @param table Name of the table to clean
|
|
104
164
|
*/
|
|
105
165
|
async cleanDbTable(table) {
|
|
106
166
|
const query = this.knexHandle(table).withSchema(this.config.dbSchema).delete();
|
|
107
167
|
const cleanTableFilters = this.config?.cleanTableFilters?.[table];
|
|
108
|
-
if (cleanTableFilters !=
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
});
|
|
115
|
-
}
|
|
168
|
+
if (cleanTableFilters != null && Array.isArray(cleanTableFilters.where)) {
|
|
169
|
+
cleanTableFilters.where.forEach((whereItem) => {
|
|
170
|
+
if (whereItem.fieldName) {
|
|
171
|
+
query.where(whereItem.fieldName, whereItem.operand, whereItem.value);
|
|
172
|
+
}
|
|
173
|
+
});
|
|
116
174
|
}
|
|
117
175
|
await query;
|
|
118
176
|
}
|
|
119
177
|
/**
|
|
120
|
-
* Returns
|
|
121
|
-
*
|
|
178
|
+
* Returns the list of table names in the configured schema.
|
|
179
|
+
* Tables listed in `config.skipTables` are excluded from the result.
|
|
180
|
+
*
|
|
181
|
+
* Uses schema-scoped query when `config.dbSchema` is set,
|
|
182
|
+
* otherwise queries all tables in the database.
|
|
183
|
+
*
|
|
184
|
+
* Note: result extraction uses `tables.rows` which is pg-specific.
|
|
185
|
+
* Other drivers may return the array directly — handled with fallback.
|
|
186
|
+
*
|
|
187
|
+
* @returns Array of table names in the configured schema
|
|
122
188
|
*/
|
|
123
189
|
async listDbTables() {
|
|
124
190
|
const skipTables = this.config?.skipTables ?? [];
|
|
191
|
+
assertSupportedDbType(this.config.dbType);
|
|
125
192
|
const query = this.config.dbSchema
|
|
126
193
|
? SQLS[this.config.dbType].listTablesSchema(this.config)
|
|
127
194
|
: SQLS[this.config.dbType].listTables(this.config);
|
|
128
195
|
const tables = await this.knexHandle.raw(query);
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
196
|
+
// pg returns { rows: [...] }, other drivers may return the array directly
|
|
197
|
+
const rows = Array.isArray(tables) ? tables : tables.rows || [];
|
|
198
|
+
return rows.map((row) => row.table_name).filter((table) => !skipTables.includes(table));
|
|
132
199
|
}
|
|
200
|
+
/**
|
|
201
|
+
* Loads and executes seed generator functions from the provided file list,
|
|
202
|
+
* building a dependency-ordered array of seed groups.
|
|
203
|
+
*
|
|
204
|
+
* `seedFiles` is an array of groups (arrays of filenames). Within each group,
|
|
205
|
+
* seeds are generated sequentially and the results of earlier seeds are
|
|
206
|
+
* available to later seeds in the same group via the `seeds` accumulator.
|
|
207
|
+
* This allows seeds to reference the ids of previously generated records.
|
|
208
|
+
*
|
|
209
|
+
* Files are loaded from `dirname/objects/<filename>` without extension —
|
|
210
|
+
* the module resolver handles `.js`/`.ts` extension based on the runtime.
|
|
211
|
+
*
|
|
212
|
+
* Fix: removed hardcoded `.js` extension from dynamic imports — was breaking
|
|
213
|
+
* in TypeScript and ESM environments.
|
|
214
|
+
*
|
|
215
|
+
* @param dirname Absolute directory path containing the `objects/` folder
|
|
216
|
+
* @param seedFiles Array of filename groups, e.g. `[['users'], ['posts', 'comments']]`
|
|
217
|
+
* @returns Array of seed group objects ready for `insertRecords()`
|
|
218
|
+
*/
|
|
133
219
|
async generateSeeds(dirname, seedFiles) {
|
|
134
220
|
let seedGroups = [];
|
|
135
221
|
const seedFileNames = flatten(seedFiles);
|
|
136
|
-
|
|
137
|
-
const
|
|
222
|
+
// Load all seed modules in parallel
|
|
223
|
+
const seedFnExports = await Promise.all(seedFileNames.map((filename) =>
|
|
224
|
+
// Fix: removed hardcoded '.js' extension — let the module resolver handle it
|
|
225
|
+
import(path.join(dirname, `./objects/${filename}`))));
|
|
226
|
+
// Build a filename → default export map for O(1) lookup below
|
|
138
227
|
const seedFnsMap = {};
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
228
|
+
seedFileNames.forEach((filename, i) => {
|
|
229
|
+
seedFnsMap[filename] = seedFnExports[i].default;
|
|
230
|
+
});
|
|
231
|
+
// Process seed files group by group, carrying generated seeds forward
|
|
232
|
+
// so later seeds can reference ids from earlier ones
|
|
143
233
|
seedFiles.reduce((seeds, fileGroup) => {
|
|
144
234
|
seedGroups = seedGroups.concat(fileGroup.reduce((group, filename) => {
|
|
145
235
|
const seedFn = seedFnsMap[filename];
|
|
@@ -152,22 +242,45 @@ class DbMigratorAndSeeder {
|
|
|
152
242
|
}, {});
|
|
153
243
|
return seedGroups;
|
|
154
244
|
}
|
|
155
|
-
|
|
245
|
+
/**
|
|
246
|
+
* Deletes all records for the tables referenced by `seedFiles`, in reverse
|
|
247
|
+
* order to respect foreign key dependencies (children before parents).
|
|
248
|
+
*
|
|
249
|
+
* @param seedFiles Array of filename groups — table order is derived from
|
|
250
|
+
* the flattened + reversed list of filenames
|
|
251
|
+
*/
|
|
252
|
+
async removeSeedsFromDb(seedFiles) {
|
|
156
253
|
const tablesToReset = flatten(seedFiles).reverse();
|
|
157
|
-
this.logger.log('Deleting records from tables:
|
|
254
|
+
this.logger.log('Deleting records from tables:', tablesToReset);
|
|
158
255
|
return this.cleanDb(tablesToReset);
|
|
159
256
|
}
|
|
257
|
+
/**
|
|
258
|
+
* Inserts seed records group by group, in order.
|
|
259
|
+
* Groups are processed sequentially (each group waits for the previous)
|
|
260
|
+
* but records within a group are inserted in parallel via `Promise.all`.
|
|
261
|
+
*
|
|
262
|
+
* Sequential group processing preserves seed dependency order —
|
|
263
|
+
* a group that references records from a previous group can rely on
|
|
264
|
+
* those records being present before it runs.
|
|
265
|
+
*
|
|
266
|
+
* @param seedGroups Array of seed group objects from `generateSeeds()`
|
|
267
|
+
*/
|
|
160
268
|
async insertRecords(seedGroups) {
|
|
161
|
-
this.logger.log('Inserting
|
|
162
|
-
|
|
163
|
-
await
|
|
164
|
-
|
|
165
|
-
}, Promise.resolve());
|
|
269
|
+
this.logger.log('Inserting seed records into tables...');
|
|
270
|
+
for (const group of seedGroups) {
|
|
271
|
+
await Promise.all(Object.keys(group).map((table) => this.knexHandle(table).withSchema(this.config.dbSchema).insert(group[table])));
|
|
272
|
+
}
|
|
166
273
|
}
|
|
274
|
+
/**
|
|
275
|
+
* Full seed pipeline: generate seeds, remove existing records, then insert.
|
|
276
|
+
*
|
|
277
|
+
* @param dirname Absolute directory path containing the `objects/` folder
|
|
278
|
+
* @param seedFiles Array of filename groups
|
|
279
|
+
*/
|
|
167
280
|
async runSeeds(dirname, seedFiles) {
|
|
168
281
|
const groups = await this.generateSeeds(dirname, seedFiles);
|
|
169
282
|
await this.removeSeedsFromDb(seedFiles);
|
|
170
|
-
|
|
283
|
+
await this.insertRecords(groups);
|
|
171
284
|
}
|
|
172
285
|
}
|
|
173
286
|
export { DbMigratorAndSeeder };
|