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