@sdflc/backend-helpers 1.0.112 → 1.0.114

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 (214) 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 +586 -33
  5. package/build/BaseCore.js +821 -127
  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/IpRateLimiter.d.ts +105 -0
  19. package/build/IpRateLimiter.js +104 -0
  20. package/build/RedisDataLoader.d.ts +144 -21
  21. package/build/RedisDataLoader.js +178 -49
  22. package/build/apiContext.d.ts +0 -8
  23. package/build/apiContext.js +30 -32
  24. package/build/checkItHelpers.d.ts +32 -0
  25. package/build/checkItHelpers.js +73 -7
  26. package/build/commonValidators.d.ts +107 -16
  27. package/build/commonValidators.js +211 -106
  28. package/build/configBuilder.d.ts +23 -0
  29. package/build/configBuilder.js +73 -0
  30. package/build/constants.d.ts +134 -17
  31. package/build/constants.js +95 -15
  32. package/build/dbHelpers.d.ts +89 -29
  33. package/build/dbHelpers.js +175 -86
  34. package/build/dbSeeder.d.ts +10 -1
  35. package/build/dbSeeder.js +80 -15
  36. package/build/dbTableHelpers.d.ts +122 -5
  37. package/build/dbTableHelpers.js +151 -13
  38. package/build/downloadHelpers.d.ts +24 -1
  39. package/build/downloadHelpers.js +51 -21
  40. package/build/esm/BaseController.d.ts +20 -0
  41. package/build/esm/BaseController.js +58 -0
  42. package/build/esm/BaseCore.d.ts +586 -33
  43. package/build/esm/BaseCore.js +812 -118
  44. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  45. package/build/esm/BaseExternalApiGateway.js +48 -0
  46. package/build/esm/BaseGateway.d.ts +455 -17
  47. package/build/esm/BaseGateway.js +503 -57
  48. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  49. package/build/esm/BaseRestApiCrudController.js +131 -0
  50. package/build/esm/DataCache.d.ts +116 -5
  51. package/build/esm/DataCache.js +142 -20
  52. package/build/esm/Database.d.ts +165 -4
  53. package/build/esm/Database.js +224 -51
  54. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  55. package/build/esm/DbMigratorAndSeeder.js +184 -71
  56. package/build/esm/IpRateLimiter.d.ts +105 -0
  57. package/build/esm/IpRateLimiter.js +100 -0
  58. package/build/esm/RedisDataLoader.d.ts +144 -21
  59. package/build/esm/RedisDataLoader.js +179 -50
  60. package/build/esm/apiContext.d.ts +0 -8
  61. package/build/esm/apiContext.js +30 -32
  62. package/build/esm/checkItHelpers.d.ts +32 -0
  63. package/build/esm/checkItHelpers.js +73 -7
  64. package/build/esm/commonValidators.d.ts +107 -16
  65. package/build/esm/commonValidators.js +209 -105
  66. package/build/esm/configBuilder.d.ts +23 -0
  67. package/build/esm/configBuilder.js +69 -0
  68. package/build/esm/constants.d.ts +134 -17
  69. package/build/esm/constants.js +94 -14
  70. package/build/esm/dbHelpers.d.ts +89 -29
  71. package/build/esm/dbHelpers.js +171 -81
  72. package/build/esm/dbSeeder.d.ts +10 -1
  73. package/build/esm/dbSeeder.js +81 -16
  74. package/build/esm/dbTableHelpers.d.ts +122 -5
  75. package/build/esm/dbTableHelpers.js +152 -14
  76. package/build/esm/downloadHelpers.d.ts +24 -1
  77. package/build/esm/downloadHelpers.js +51 -21
  78. package/build/esm/index.d.ts +6 -2
  79. package/build/esm/index.js +6 -2
  80. package/build/esm/interfaces/ApiContext.d.ts +33 -3
  81. package/build/esm/interfaces/ApiContext.js +1 -0
  82. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  83. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  84. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  85. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  86. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  87. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
  88. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  89. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  90. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  91. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  92. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  93. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  94. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  95. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  96. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  97. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  98. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  99. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  100. package/build/esm/interfaces/CacheInterface.js +1 -0
  101. package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
  102. package/build/esm/interfaces/CoreActionInterface.js +1 -0
  103. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  104. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  105. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  106. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  107. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  108. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  109. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  110. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  111. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  112. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  113. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  114. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  115. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  116. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  117. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  118. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  119. package/build/esm/interfaces/LoaderInterface.js +1 -0
  120. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  121. package/build/esm/interfaces/UserTokenParams.js +1 -0
  122. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  123. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  124. package/build/esm/interfaces/index.d.ts +4 -0
  125. package/build/esm/interfaces/index.js +4 -0
  126. package/build/esm/knexConfigBuilder.d.ts +25 -0
  127. package/build/esm/knexConfigBuilder.js +100 -36
  128. package/build/esm/parseIds.d.ts +6 -0
  129. package/build/esm/parseIds.js +13 -0
  130. package/build/esm/passwordHelpers.d.ts +22 -0
  131. package/build/esm/passwordHelpers.js +40 -8
  132. package/build/esm/redisClient.d.ts +57 -4
  133. package/build/esm/redisClient.js +40 -54
  134. package/build/esm/resolveClientIp.d.ts +15 -0
  135. package/build/esm/resolveClientIp.js +34 -0
  136. package/build/esm/resolversHelpers.d.ts +21 -1
  137. package/build/esm/resolversHelpers.js +48 -26
  138. package/build/esm/userToken.d.ts +50 -1
  139. package/build/esm/userToken.js +85 -20
  140. package/build/esm/utils.d.ts +20 -2
  141. package/build/esm/utils.js +23 -13
  142. package/build/index.d.ts +6 -2
  143. package/build/index.js +6 -2
  144. package/build/interfaces/ApiContext.d.ts +33 -3
  145. package/build/interfaces/ApiContext.js +1 -0
  146. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  147. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  148. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  149. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  150. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  151. package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
  152. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  153. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  154. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  155. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  156. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  157. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  158. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  159. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  160. package/build/interfaces/BuildConfigOptions.js +1 -0
  161. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  162. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  163. package/build/interfaces/CacheInterface.d.ts +18 -1
  164. package/build/interfaces/CacheInterface.js +1 -0
  165. package/build/interfaces/CoreActionInterface.d.ts +60 -0
  166. package/build/interfaces/CoreActionInterface.js +1 -0
  167. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  168. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  169. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  170. package/build/interfaces/DataCachePropsInterface.js +3 -0
  171. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  172. package/build/interfaces/DatabaseOptions.js +1 -0
  173. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  174. package/build/interfaces/DatabaseReadInterface.js +1 -0
  175. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  176. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  177. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  178. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  179. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  180. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  181. package/build/interfaces/ListArgsInterface.js +1 -0
  182. package/build/interfaces/LoaderInterface.d.ts +36 -1
  183. package/build/interfaces/LoaderInterface.js +1 -0
  184. package/build/interfaces/UserTokenParams.d.ts +23 -5
  185. package/build/interfaces/UserTokenParams.js +1 -0
  186. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  187. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  188. package/build/interfaces/index.d.ts +4 -0
  189. package/build/interfaces/index.js +4 -0
  190. package/build/knexConfigBuilder.d.ts +25 -0
  191. package/build/knexConfigBuilder.js +99 -35
  192. package/build/parseIds.d.ts +6 -0
  193. package/build/parseIds.js +17 -0
  194. package/build/passwordHelpers.d.ts +22 -0
  195. package/build/passwordHelpers.js +40 -8
  196. package/build/redisClient.d.ts +57 -4
  197. package/build/redisClient.js +40 -54
  198. package/build/resolveClientIp.d.ts +15 -0
  199. package/build/resolveClientIp.js +38 -0
  200. package/build/resolversHelpers.d.ts +21 -1
  201. package/build/resolversHelpers.js +48 -26
  202. package/build/userToken.d.ts +50 -1
  203. package/build/userToken.js +85 -20
  204. package/build/utils.d.ts +20 -2
  205. package/build/utils.js +24 -16
  206. package/package.json +19 -18
  207. package/build/baseController.d.ts +0 -17
  208. package/build/baseController.js +0 -64
  209. package/build/configBulder.d.ts +0 -2
  210. package/build/configBulder.js +0 -36
  211. package/build/esm/baseController.d.ts +0 -17
  212. package/build/esm/baseController.js +0 -58
  213. package/build/esm/configBulder.d.ts +0 -2
  214. 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,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: (appSettings) => `
54
+ listTablesSchema: (config) => `
47
55
  SELECT TABLE_NAME as table_name
48
56
  FROM INFORMATION_SCHEMA.TABLES
49
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
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: (appSettings) => `
56
- SELECT 'DROP TABLE IF EXISTS ${appSettings?.dbSchema}.' || TABLE_NAME || ';' as cmd
57
- FROM INFORMATION_SCHEMA.TABLES
58
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
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
- this.logger = config?.logger instanceof utils_1.Logger ? config.logger : new utils_1.Logger({ level: utils_1.LoggerLevels.LOG });
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 && this.config.runDbSeed && result[1].length > 0) {
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
- const version = this.knexHandle.migrate.currentVersion();
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
- * Go from array of objects which contain keys of object names which have an array value of seeded objects
86
- * to a single object with keys of object names and arrays of seeded objects
87
- * ie from [{table1: [], table2: [] }, { table3: [] }]
88
- * to { table1: [], table2: [], table3: []}
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 (0, lodash_1.reduce)(generatedSeedArrays, (acc, cur) => {
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
- * Drop all tables, run migrations, then seed the tables
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: ', ex);
146
+ this.logger.error('An exception has occurred on resetting database:', ex);
147
+ throw ex;
108
148
  }
109
149
  }
110
150
  /**
111
- * Selects all the tables in the schema and drops them.
112
- * This approach does not work in case we have constraints.
113
- * TODO: Remove all constraints and then drop tables.
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
- bluebird_1.default.each(commands, (cmd) => this.knexHandle.raw(cmd));
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
- * Removes all the records from provided list of tables
125
- * @param tablesToClean array of table names
126
- * @param knexHandle Knex handle object with configured connection to DB
127
- * @param appSettings settings with db related information
128
- * @returns promise
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 (let idx = 0, len = tablesToClean.length; idx < len; ++idx) {
132
- await this.cleanDbTable(tablesToClean[idx]);
187
+ for (const table of tablesToClean) {
188
+ await this.cleanDbTable(table);
133
189
  }
134
- return new bluebird_1.default((resolve) => {
135
- resolve(tablesToClean);
136
- });
190
+ return tablesToClean;
137
191
  }
138
192
  /**
139
- * Removes all the records from provided table.
140
- * If appSettings has cleanTable object with table names then
141
- * it is used to add extra filters to clear the table to avoid for example users data
142
- * @param table Name of table from which to remove all the records
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 != undefined) {
148
- if (Array.isArray(cleanTableFilters.where)) {
149
- cleanTableFilters.where.forEach((whereItem) => {
150
- if (whereItem.fieldName) {
151
- query.where(whereItem.fieldName, whereItem.operand, whereItem.value);
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 a list of tables in db schedm specified in settings
160
- * @returns arrays of table names in the provided db schema
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
- return (tables.rows || [])
169
- .map((row) => row.table_name)
170
- .filter((table) => skipTables.indexOf(table) === -1);
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
- const seedFnExports = await Promise.all((0, lodash_1.map)(seedFileNames, (filename) => Promise.resolve(`${path_1.default.join(dirname, `./objects/${filename}.js`)}`).then(s => __importStar(require(s)))));
176
- const seedFns = (0, lodash_1.map)(seedFnExports, 'default');
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
- for (let i = 0; i < seedFileNames.length; i++) {
179
- const seedFileName = seedFileNames[i];
180
- seedFnsMap[seedFileName] = seedFns[i];
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
- removeSeedsFromDb(seedFiles) {
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: ', tablesToReset);
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 seeds records into tables...');
201
- return seedGroups.reduce(async (previousGroup, group) => {
202
- await previousGroup;
203
- return Promise.all(Object.keys(group).map((table) => this.knexHandle(table).withSchema(this.config.dbSchema).insert(group[table])));
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
- return await this.insertRecords(groups);
320
+ await this.insertRecords(groups);
210
321
  }
211
322
  }
212
323
  exports.DbMigratorAndSeeder = DbMigratorAndSeeder;
@@ -0,0 +1,105 @@
1
+ /**
2
+ * IpRateLimiter
3
+ *
4
+ * A reusable Redis-backed sliding-window rate limiter keyed on (action, IP).
5
+ * Designed for auth endpoints where Redis is optional infrastructure: if the
6
+ * client is null (Redis not configured) the limiter silently allows all
7
+ * requests — it never throws and never blocks the caller.
8
+ *
9
+ * Usage:
10
+ * const limiter = new IpRateLimiter(redisClient, logger);
11
+ *
12
+ * const result = await limiter.check({
13
+ * action: 'signIn',
14
+ * ip: '1.2.3.4',
15
+ * spaceId: 'my-space',
16
+ * limit: 20,
17
+ * windowSec: 900,
18
+ * });
19
+ *
20
+ * if (result.blocked) {
21
+ * // return 429 / rate limit failure
22
+ * }
23
+ *
24
+ * Redis key format: rl:{spaceId}:{action}:{ip}
25
+ * Strategy: INCR + EXPIRE (atomic for the first hit via SET NX)
26
+ * Each key lives exactly `windowSec` seconds. On first
27
+ * hit the key is created with TTL = windowSec. Subsequent
28
+ * hits within the window increment the counter. When the
29
+ * window expires Redis deletes the key automatically.
30
+ *
31
+ * This is a fixed-window counter (not a true sliding window), which is the
32
+ * right trade-off here: it is O(1) per request, uses a single key, and the
33
+ * 2× burst risk at window boundaries is acceptable for auth rate-limiting
34
+ * where the window is measured in minutes, not milliseconds.
35
+ */
36
+ /**
37
+ * A single rate-limit rule. Embed this in core props or per-action config
38
+ * to declaratively attach limiting without touching runAction call sites.
39
+ *
40
+ * Set `action` to override the Redis key segment; if omitted, BaseCore uses
41
+ * the CoreActionInterface.actionName (or doingWhat as fallback) so the key
42
+ * is always stable across deploys and language changes.
43
+ */
44
+ export interface RateLimitRule {
45
+ /** Maximum number of requests allowed within the window. */
46
+ limit: number;
47
+ /** Window length in seconds. */
48
+ windowSec: number;
49
+ /**
50
+ * Optional explicit action key for the Redis counter.
51
+ * When omitted, BaseCore fills this from actionName / doingWhat at call time.
52
+ */
53
+ action?: string;
54
+ }
55
+ export interface RateLimitCheckArgs {
56
+ /** Short label for the action being rate-limited, e.g. 'signIn', 'signUp' */
57
+ action: string;
58
+ /** Client IP address */
59
+ ip: string;
60
+ /** Space ID so different spaces get independent counters */
61
+ spaceId: string;
62
+ /** Maximum number of requests allowed within the window */
63
+ limit: number;
64
+ /** Window length in seconds */
65
+ windowSec: number;
66
+ }
67
+ export interface RateLimitResult {
68
+ /** True when the caller should be blocked */
69
+ blocked: boolean;
70
+ /** How many hits have been recorded in the current window (0 if Redis unavailable) */
71
+ count: number;
72
+ /** How many seconds remain in the current window (-1 if Redis unavailable) */
73
+ ttlSec: number;
74
+ }
75
+ export interface RateLimiterLogger {
76
+ log(message: string, ...args: any[]): void;
77
+ error(message: string, ...args: any[]): void;
78
+ }
79
+ /**
80
+ * Structural interface for any rate-limiter implementation.
81
+ * BaseCore accepts anything that satisfies this shape — callers are not
82
+ * required to use IpRateLimiter specifically. Duck-typed to avoid coupling
83
+ * across package versions, consistent with how spaceGw is typed in
84
+ * BaseCorePropsInterface.
85
+ */
86
+ export interface RateLimiterInterface {
87
+ check(args: RateLimitCheckArgs): Promise<RateLimitResult>;
88
+ reset(args: Pick<RateLimitCheckArgs, 'action' | 'ip' | 'spaceId'>): Promise<void>;
89
+ }
90
+ export declare class IpRateLimiter implements RateLimiterInterface {
91
+ private readonly client;
92
+ private readonly logger;
93
+ constructor(redisClient: any | null, logger: RateLimiterLogger);
94
+ /**
95
+ * Check and increment the rate-limit counter for a given action + IP.
96
+ * Always resolves — never rejects.
97
+ */
98
+ check(args: RateLimitCheckArgs): Promise<RateLimitResult>;
99
+ /**
100
+ * Manually reset the counter for a given action + IP.
101
+ * Useful after a successful sign-in to clear the failed-attempt counter.
102
+ * Silently no-ops if Redis is unavailable.
103
+ */
104
+ reset(args: Pick<RateLimitCheckArgs, 'action' | 'ip' | 'spaceId'>): Promise<void>;
105
+ }