@sdflc/backend-helpers 1.0.111 → 1.0.113

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/README.md +1422 -146
  2. package/build/BaseController.d.ts +20 -0
  3. package/build/BaseController.js +64 -0
  4. package/build/BaseCore.d.ts +470 -33
  5. package/build/BaseCore.js +613 -126
  6. package/build/BaseExternalApiGateway.d.ts +16 -0
  7. package/build/BaseExternalApiGateway.js +54 -0
  8. package/build/BaseGateway.d.ts +455 -17
  9. package/build/BaseGateway.js +502 -56
  10. package/build/BaseRestApiCrudController.d.ts +37 -0
  11. package/build/BaseRestApiCrudController.js +134 -0
  12. package/build/DataCache.d.ts +116 -5
  13. package/build/DataCache.js +144 -22
  14. package/build/Database.d.ts +165 -4
  15. package/build/Database.js +224 -51
  16. package/build/DbMigratorAndSeeder.d.ts +127 -26
  17. package/build/DbMigratorAndSeeder.js +180 -69
  18. package/build/RedisDataLoader.d.ts +144 -21
  19. package/build/RedisDataLoader.js +178 -49
  20. package/build/apiContext.d.ts +0 -8
  21. package/build/apiContext.js +12 -27
  22. package/build/checkItHelpers.d.ts +32 -0
  23. package/build/checkItHelpers.js +73 -7
  24. package/build/commonValidators.d.ts +107 -16
  25. package/build/commonValidators.js +211 -106
  26. package/build/configBuilder.d.ts +23 -0
  27. package/build/configBuilder.js +73 -0
  28. package/build/constants.d.ts +134 -17
  29. package/build/constants.js +95 -15
  30. package/build/dbHelpers.d.ts +89 -29
  31. package/build/dbHelpers.js +175 -86
  32. package/build/dbSeeder.d.ts +10 -1
  33. package/build/dbSeeder.js +80 -15
  34. package/build/dbTableHelpers.d.ts +122 -5
  35. package/build/dbTableHelpers.js +151 -13
  36. package/build/downloadHelpers.d.ts +24 -1
  37. package/build/downloadHelpers.js +51 -21
  38. package/build/esm/BaseController.d.ts +20 -0
  39. package/build/esm/BaseController.js +58 -0
  40. package/build/esm/BaseCore.d.ts +470 -33
  41. package/build/esm/BaseCore.js +615 -128
  42. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  43. package/build/esm/BaseExternalApiGateway.js +48 -0
  44. package/build/esm/BaseGateway.d.ts +455 -17
  45. package/build/esm/BaseGateway.js +503 -57
  46. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  47. package/build/esm/BaseRestApiCrudController.js +131 -0
  48. package/build/esm/DataCache.d.ts +116 -5
  49. package/build/esm/DataCache.js +142 -20
  50. package/build/esm/Database.d.ts +165 -4
  51. package/build/esm/Database.js +224 -51
  52. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  53. package/build/esm/DbMigratorAndSeeder.js +184 -71
  54. package/build/esm/RedisDataLoader.d.ts +144 -21
  55. package/build/esm/RedisDataLoader.js +179 -50
  56. package/build/esm/apiContext.d.ts +0 -8
  57. package/build/esm/apiContext.js +12 -27
  58. package/build/esm/checkItHelpers.d.ts +32 -0
  59. package/build/esm/checkItHelpers.js +73 -7
  60. package/build/esm/commonValidators.d.ts +107 -16
  61. package/build/esm/commonValidators.js +209 -105
  62. package/build/esm/configBuilder.d.ts +23 -0
  63. package/build/esm/configBuilder.js +69 -0
  64. package/build/esm/constants.d.ts +134 -17
  65. package/build/esm/constants.js +94 -14
  66. package/build/esm/dbHelpers.d.ts +89 -29
  67. package/build/esm/dbHelpers.js +171 -81
  68. package/build/esm/dbSeeder.d.ts +10 -1
  69. package/build/esm/dbSeeder.js +81 -16
  70. package/build/esm/dbTableHelpers.d.ts +122 -5
  71. package/build/esm/dbTableHelpers.js +152 -14
  72. package/build/esm/downloadHelpers.d.ts +24 -1
  73. package/build/esm/downloadHelpers.js +51 -21
  74. package/build/esm/index.d.ts +5 -2
  75. package/build/esm/index.js +5 -2
  76. package/build/esm/interfaces/ApiContext.d.ts +7 -3
  77. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  78. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  79. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  80. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  81. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  82. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +87 -9
  83. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  84. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  85. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  86. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  87. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  88. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  89. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  90. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  91. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  92. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  93. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  94. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  95. package/build/esm/interfaces/CacheInterface.js +1 -0
  96. package/build/esm/interfaces/CoreActionInterface.d.ts +20 -0
  97. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  98. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  99. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  100. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  101. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  102. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  103. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  104. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  105. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  106. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  107. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  108. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  109. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  110. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  111. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  112. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  113. package/build/esm/interfaces/LoaderInterface.js +1 -0
  114. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  115. package/build/esm/interfaces/UserTokenParams.js +1 -0
  116. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  117. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  118. package/build/esm/interfaces/index.d.ts +4 -0
  119. package/build/esm/interfaces/index.js +4 -0
  120. package/build/esm/knexConfigBuilder.d.ts +25 -0
  121. package/build/esm/knexConfigBuilder.js +100 -36
  122. package/build/esm/parseIds.d.ts +6 -0
  123. package/build/esm/parseIds.js +13 -0
  124. package/build/esm/passwordHelpers.d.ts +22 -0
  125. package/build/esm/passwordHelpers.js +40 -8
  126. package/build/esm/redisClient.d.ts +57 -4
  127. package/build/esm/redisClient.js +40 -54
  128. package/build/esm/resolveClientIp.d.ts +15 -0
  129. package/build/esm/resolveClientIp.js +34 -0
  130. package/build/esm/resolversHelpers.d.ts +21 -1
  131. package/build/esm/resolversHelpers.js +48 -26
  132. package/build/esm/userToken.d.ts +50 -1
  133. package/build/esm/userToken.js +85 -20
  134. package/build/esm/utils.d.ts +20 -0
  135. package/build/esm/utils.js +23 -1
  136. package/build/index.d.ts +5 -2
  137. package/build/index.js +5 -2
  138. package/build/interfaces/ApiContext.d.ts +7 -3
  139. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  140. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  141. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  142. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  143. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  144. package/build/interfaces/BaseCorePropsInterface.d.ts +87 -9
  145. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  146. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  147. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  148. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  149. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  150. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  151. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  152. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  153. package/build/interfaces/BuildConfigOptions.js +1 -0
  154. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  155. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  156. package/build/interfaces/CacheInterface.d.ts +18 -1
  157. package/build/interfaces/CacheInterface.js +1 -0
  158. package/build/interfaces/CoreActionInterface.d.ts +20 -0
  159. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  160. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  161. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  162. package/build/interfaces/DataCachePropsInterface.js +3 -0
  163. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  164. package/build/interfaces/DatabaseOptions.js +1 -0
  165. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  166. package/build/interfaces/DatabaseReadInterface.js +1 -0
  167. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  168. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  169. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  170. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  171. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  172. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  173. package/build/interfaces/ListArgsInterface.js +1 -0
  174. package/build/interfaces/LoaderInterface.d.ts +36 -1
  175. package/build/interfaces/LoaderInterface.js +1 -0
  176. package/build/interfaces/UserTokenParams.d.ts +23 -5
  177. package/build/interfaces/UserTokenParams.js +1 -0
  178. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  179. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  180. package/build/interfaces/index.d.ts +4 -0
  181. package/build/interfaces/index.js +4 -0
  182. package/build/knexConfigBuilder.d.ts +25 -0
  183. package/build/knexConfigBuilder.js +99 -35
  184. package/build/parseIds.d.ts +6 -0
  185. package/build/parseIds.js +17 -0
  186. package/build/passwordHelpers.d.ts +22 -0
  187. package/build/passwordHelpers.js +40 -8
  188. package/build/redisClient.d.ts +57 -4
  189. package/build/redisClient.js +40 -54
  190. package/build/resolveClientIp.d.ts +15 -0
  191. package/build/resolveClientIp.js +38 -0
  192. package/build/resolversHelpers.d.ts +21 -1
  193. package/build/resolversHelpers.js +48 -26
  194. package/build/userToken.d.ts +50 -1
  195. package/build/userToken.js +85 -20
  196. package/build/utils.d.ts +20 -0
  197. package/build/utils.js +23 -1
  198. package/package.json +19 -18
  199. package/build/baseController.d.ts +0 -17
  200. package/build/baseController.js +0 -63
  201. package/build/configBulder.d.ts +0 -2
  202. package/build/configBulder.js +0 -36
  203. package/build/esm/baseController.d.ts +0 -17
  204. package/build/esm/baseController.js +0 -57
  205. package/build/esm/configBulder.d.ts +0 -2
  206. package/build/esm/configBulder.js +0 -32
@@ -1,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
- * Go from array of objects which contain keys of object names which have an array value of seeded objects
9
- * to a single object with keys of object names and arrays of seeded objects
10
- * ie from [{table1: [], table2: [] }, { table3: [] }]
11
- * to { table1: [], table2: [], table3: []}
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
- * Drop all tables, run migrations, then seed the tables
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
- * Selects all the tables in the schema and drops them.
20
- * This approach does not work in case we have constraints.
21
- * TODO: Remove all constraints and then drop tables.
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
- * Removes all the records from provided list of tables
26
- * @param tablesToClean array of table names
27
- * @param knexHandle Knex handle object with configured connection to DB
28
- * @param appSettings settings with db related information
29
- * @returns promise
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: any[]): Promise<unknown>;
75
+ cleanDb(tablesToClean: string[]): Promise<string[]>;
32
76
  /**
33
- * Removes all the records from provided table.
34
- * If appSettings has cleanTable object with table names then
35
- * it is used to add extra filters to clear the table to avoid for example users data
36
- * @param table Name of table from which to remove all the records
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 a list of tables in db schedm specified in settings
41
- * @returns arrays of table names in the provided db schema
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
- listDbTables(): Promise<any>;
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 BPromise from 'bluebird';
3
- import { reduce, camelCase, flatten, map } from 'lodash';
4
- import { Logger, LoggerLevels } from '@sdflc/utils';
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: (appSettings) => `
15
+ listTablesSchema: (config) => `
8
16
  SELECT TABLE_NAME as table_name
9
17
  FROM INFORMATION_SCHEMA.TABLES
10
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
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: (appSettings) => `
17
- SELECT 'DROP TABLE IF EXISTS ${appSettings?.dbSchema}.' || TABLE_NAME || ';' as cmd
18
- FROM INFORMATION_SCHEMA.TABLES
19
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
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
- this.logger = config?.logger instanceof Logger ? config.logger : new Logger({ level: LoggerLevels.LOG });
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 && this.config.runDbSeed && result[1].length > 0) {
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
- const version = this.knexHandle.migrate.currentVersion();
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
- * Go from array of objects which contain keys of object names which have an array value of seeded objects
47
- * to a single object with keys of object names and arrays of seeded objects
48
- * ie from [{table1: [], table2: [] }, { table3: [] }]
49
- * to { table1: [], table2: [], table3: []}
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(generatedSeedArrays, (acc, cur) => {
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
- * Drop all tables, run migrations, then seed the tables
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: ', ex);
107
+ this.logger.error('An exception has occurred on resetting database:', ex);
108
+ throw ex;
69
109
  }
70
110
  }
71
111
  /**
72
- * Selects all the tables in the schema and drops them.
73
- * This approach does not work in case we have constraints.
74
- * TODO: Remove all constraints and then drop tables.
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(commands, (cmd) => this.knexHandle.raw(cmd));
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
- * Removes all the records from provided list of tables
86
- * @param tablesToClean array of table names
87
- * @param knexHandle Knex handle object with configured connection to DB
88
- * @param appSettings settings with db related information
89
- * @returns promise
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 (let idx = 0, len = tablesToClean.length; idx < len; ++idx) {
93
- await this.cleanDbTable(tablesToClean[idx]);
148
+ for (const table of tablesToClean) {
149
+ await this.cleanDbTable(table);
94
150
  }
95
- return new BPromise((resolve) => {
96
- resolve(tablesToClean);
97
- });
151
+ return tablesToClean;
98
152
  }
99
153
  /**
100
- * Removes all the records from provided table.
101
- * If appSettings has cleanTable object with table names then
102
- * it is used to add extra filters to clear the table to avoid for example users data
103
- * @param table Name of table from which to remove all the records
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 != undefined) {
109
- if (Array.isArray(cleanTableFilters.where)) {
110
- cleanTableFilters.where.forEach((whereItem) => {
111
- if (whereItem.fieldName) {
112
- query.where(whereItem.fieldName, whereItem.operand, whereItem.value);
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 a list of tables in db schedm specified in settings
121
- * @returns arrays of table names in the provided db schema
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
- return (tables.rows || [])
130
- .map((row) => row.table_name)
131
- .filter((table) => skipTables.indexOf(table) === -1);
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
- const seedFnExports = await Promise.all(map(seedFileNames, (filename) => import(path.join(dirname, `./objects/${filename}.js`))));
137
- const seedFns = map(seedFnExports, 'default');
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
- for (let i = 0; i < seedFileNames.length; i++) {
140
- const seedFileName = seedFileNames[i];
141
- seedFnsMap[seedFileName] = seedFns[i];
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
- removeSeedsFromDb(seedFiles) {
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: ', tablesToReset);
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 seeds records into tables...');
162
- return seedGroups.reduce(async (previousGroup, group) => {
163
- await previousGroup;
164
- return Promise.all(Object.keys(group).map((table) => this.knexHandle(table).withSchema(this.config.dbSchema).insert(group[table])));
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
- return await this.insertRecords(groups);
283
+ await this.insertRecords(groups);
171
284
  }
172
285
  }
173
286
  export { DbMigratorAndSeeder };