@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.
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 +608 -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/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 +599 -118
  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 -2
  135. package/build/esm/utils.js +23 -13
  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 -2
  197. package/build/utils.js +24 -16
  198. package/package.json +19 -18
  199. package/build/baseController.d.ts +0 -17
  200. package/build/baseController.js +0 -64
  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 -58
  205. package/build/esm/configBulder.d.ts +0 -2
  206. package/build/esm/configBulder.js +0 -32
@@ -1,144 +1,234 @@
1
- import BPromise from 'bluebird';
1
+ // ./src/dbHelpers.ts
2
2
  import { reduce } from 'lodash';
3
+ /**
4
+ * Database utility helpers for development, testing, and migration tooling.
5
+ *
6
+ * These functions are NOT intended for production runtime use — they are
7
+ * designed for test setup/teardown, CI pipelines, and local development.
8
+ *
9
+ * Supported database types: 'pg', 'mssql'
10
+ * All functions accept a raw Knex handle (not a Database instance) since
11
+ * they operate outside the normal request lifecycle.
12
+ */
13
+ // ─── SQL templates ────────────────────────────────────────────────────────────
14
+ /**
15
+ * Raw SQL query templates per database type.
16
+ * Schema names are injected via sanitiseIdentifier() before use to prevent
17
+ * SQL injection — schema names must be alphanumeric + underscores only.
18
+ *
19
+ * Fix: removed stray `'` before `;` in pg.dropTables and mssql.dropTables
20
+ * which produced invalid SQL.
21
+ */
3
22
  const SQLS = {
4
23
  pg: {
5
24
  listTablesSchema: (appSettings) => `
6
25
  SELECT TABLE_NAME as table_name
7
26
  FROM INFORMATION_SCHEMA.TABLES
8
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
27
+ WHERE TABLE_SCHEMA = '${sanitiseIdentifier(appSettings?.dbSchema)}';
9
28
  `,
10
29
  listTables: () => `
11
30
  SELECT TABLE_NAME as table_name
12
- FROM INFORMATION_SCHEMA.TABLES
31
+ FROM INFORMATION_SCHEMA.TABLES;
13
32
  `,
14
33
  dropTablesSchema: (appSettings) => `
15
- SELECT 'DROP TABLE IF EXISTS ${appSettings?.dbSchema}.' || TABLE_NAME || ';' as cmd
16
- FROM INFORMATION_SCHEMA.TABLES
17
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
34
+ SELECT 'DROP TABLE IF EXISTS ${sanitiseIdentifier(appSettings?.dbSchema)}.' || TABLE_NAME || ';' as cmd
35
+ FROM INFORMATION_SCHEMA.TABLES
36
+ WHERE TABLE_SCHEMA = '${sanitiseIdentifier(appSettings?.dbSchema)}';
18
37
  `,
19
38
  dropTables: () => `
20
39
  SELECT 'DROP TABLE IF EXISTS ' || TABLE_NAME || ';' as cmd
21
- FROM INFORMATION_SCHEMA.TABLES';
40
+ FROM INFORMATION_SCHEMA.TABLES;
22
41
  `,
23
42
  },
24
43
  mssql: {
25
44
  listTablesSchema: (appSettings) => `
26
45
  SELECT TABLE_NAME as table_name
27
46
  FROM INFORMATION_SCHEMA.TABLES
28
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
47
+ WHERE TABLE_SCHEMA = '${sanitiseIdentifier(appSettings?.dbSchema)}';
29
48
  `,
30
49
  listTables: () => `
31
50
  SELECT TABLE_NAME as table_name
32
- FROM INFORMATION_SCHEMA.TABLES
51
+ FROM INFORMATION_SCHEMA.TABLES;
33
52
  `,
34
53
  dropTablesSchema: (appSettings) => `
35
- SELECT 'DROP TABLE IF EXISTS [${appSettings?.dbSchema}].[' + TABLE_NAME + '];' as cmd
54
+ SELECT 'DROP TABLE IF EXISTS [${sanitiseIdentifier(appSettings?.dbSchema)}].[' + TABLE_NAME + '];' as cmd
36
55
  FROM INFORMATION_SCHEMA.TABLES
37
- WHERE TABLE_SCHEMA = '${appSettings?.dbSchema}';
56
+ WHERE TABLE_SCHEMA = '${sanitiseIdentifier(appSettings?.dbSchema)}';
38
57
  `,
39
58
  dropTables: () => `
40
59
  SELECT 'DROP TABLE IF EXISTS ' + TABLE_NAME + ';' as cmd
41
- FROM INFORMATION_SCHEMA.TABLES';
60
+ FROM INFORMATION_SCHEMA.TABLES;
42
61
  `,
43
62
  },
44
63
  };
64
+ // ─── Internal helpers ─────────────────────────────────────────────────────────
65
+ /**
66
+ * Validates that a database identifier (schema name, table name) contains
67
+ * only safe characters — alphanumeric and underscores.
68
+ * Throws if the identifier contains anything else to prevent SQL injection
69
+ * via template-interpolated schema names in SQLS above.
70
+ *
71
+ * @param identifier Schema or table name to validate
72
+ */
73
+ export const sanitiseIdentifier = (identifier) => {
74
+ if (!identifier)
75
+ return '';
76
+ if (!/^[a-zA-Z0-9_]+$/.test(identifier)) {
77
+ throw new Error(`Invalid database identifier: "${identifier}". ` + `Only alphanumeric characters and underscores are allowed.`);
78
+ }
79
+ return identifier;
80
+ };
81
+ /**
82
+ * Guards that the provided dbType is supported by SQLS.
83
+ * Throws a clear error rather than letting the caller hit
84
+ * `TypeError: Cannot read properties of undefined`.
85
+ *
86
+ * @param dbType Database type string from appSettings
87
+ */
88
+ export const assertSupportedDbType = (dbType) => {
89
+ if (!SQLS[dbType]) {
90
+ throw new Error(`Unsupported database type: "${dbType}". ` + `Supported types are: ${Object.keys(SQLS).join(', ')}`);
91
+ }
92
+ };
93
+ // ─── Exported utilities ───────────────────────────────────────────────────────
45
94
  /**
46
- * Removes all the records from provided table.
47
- * If appSettings has cleanTable object with table names then
48
- * it is used to add extra filters to clear the table to avoid for example users data
49
- * @param table Name of table from which to remove all the records
50
- * @param knexHandle Knex handle object with configured connection to DB
51
- * @param appSettings settings with db related information
95
+ * Removes all records from the specified table.
96
+ *
97
+ * If `appSettings.cleanTableFilters[table]` is configured, applies additional
98
+ * WHERE conditions before deleting — useful for preserving seed/system records
99
+ * while clearing user-generated data during test teardown.
100
+ *
101
+ * @param table Name of the table to clean
102
+ * @param knexHandle Knex instance with configured DB connection
103
+ * @param appSettings Settings object with dbSchema and optional cleanTableFilters
52
104
  */
53
105
  const dbCleanTable = async (table, knexHandle, appSettings) => {
54
106
  const query = knexHandle(table).withSchema(appSettings.dbSchema).delete();
55
107
  const cleanTableFilters = appSettings?.cleanTableFilters?.[table];
56
- if (cleanTableFilters != undefined) {
57
- if (Array.isArray(cleanTableFilters.where)) {
58
- cleanTableFilters.where.forEach((whereItem) => {
59
- query.where(whereItem.fieldName, whereItem.operand, whereItem.value);
60
- });
61
- }
108
+ if (cleanTableFilters != null && Array.isArray(cleanTableFilters.where)) {
109
+ cleanTableFilters.where.forEach((whereItem) => {
110
+ query.where(whereItem.fieldName, whereItem.operand, whereItem.value);
111
+ });
62
112
  }
63
113
  await query;
64
114
  };
65
115
  /**
66
- * Returns a list of tables in db schedm specified in settings
67
- * @param knexHandle Knex handle object with configured connection to DB
68
- * @param appSettings settings with db related information
69
- * @returns arrays of table names in the provided db schema
116
+ * Returns the list of table names in the configured schema.
117
+ * Tables listed in `appSettings.skipTables` are excluded from the result.
118
+ *
119
+ * Uses schema-scoped query when `appSettings.dbSchema` is set,
120
+ * otherwise queries all tables in the database.
121
+ *
122
+ * Handles both pg (result.rows array) and mssql (direct array) result formats.
123
+ *
124
+ * @param knexHandle Knex instance with configured DB connection
125
+ * @param appSettings Settings object with dbType, dbSchema, and optional skipTables
70
126
  */
71
127
  const dbListTables = async (knexHandle, appSettings) => {
72
128
  const skipTables = (appSettings || {}).skipTables || [];
73
- let query = SQLS[appSettings.dbType].listTablesSchema(appSettings);
74
- if (!appSettings.dbSchema) {
75
- query = SQLS[appSettings.dbType].listTables(appSettings);
76
- }
129
+ assertSupportedDbType(appSettings.dbType);
130
+ const query = appSettings.dbSchema
131
+ ? SQLS[appSettings.dbType].listTablesSchema(appSettings)
132
+ : SQLS[appSettings.dbType].listTables(appSettings);
77
133
  const tables = await knexHandle.raw(query);
78
- return (tables.rows || [])
79
- .map((row) => row.table_name)
80
- .filter((table) => skipTables.indexOf(table) === -1);
134
+ // pg returns { rows: [...] }, mssql and others return the array directly
135
+ const rows = Array.isArray(tables) ? tables : tables.rows || [];
136
+ return rows.map((row) => row.table_name).filter((table) => !skipTables.includes(table));
81
137
  };
82
138
  /**
83
- * Removes all the records from provided list of tables
84
- * @param tablesToClean array of table names
85
- * @param knexHandle Knex handle object with configured connection to DB
86
- * @param appSettings settings with db related information
87
- * @returns promise
139
+ * Deletes all records from the provided list of tables, one at a time.
140
+ * Order matters if foreign key constraints exist — pass tables in dependency order.
141
+ *
142
+ * @param tablesToClean Array of table names to clean
143
+ * @param knexHandle Knex instance with configured DB connection
144
+ * @param appSettings Settings object passed through to dbCleanTable
145
+ * @returns The list of cleaned table names
88
146
  */
89
147
  const dbClean = async (tablesToClean, knexHandle, appSettings) => {
90
- for (let idx = 0, len = tablesToClean.length; idx < len; ++idx) {
91
- await dbCleanTable(tablesToClean[idx], knexHandle, appSettings);
148
+ for (const table of tablesToClean) {
149
+ await dbCleanTable(table, knexHandle, appSettings);
92
150
  }
93
- return new BPromise((resolve) => {
94
- resolve(tablesToClean);
95
- });
151
+ // Fix: removed redundant `new BPromise(resolve => resolve(...))` wrapper —
152
+ // function is already async so returning directly is equivalent
153
+ return tablesToClean;
96
154
  };
97
155
  /**
98
- * Selects all the tables in the schema and drops them.
99
- * This approach does not work in case we have constraints.
100
- * TODO: Remove all constraints and then drop tables.
156
+ * Drops all tables in the configured schema (or entire database if no schema set).
157
+ *
158
+ * WARNING: Destructive — permanently removes all tables and their data.
159
+ * Does not handle foreign key constraints — tables with dependencies may
160
+ * fail to drop. See TODO below.
161
+ *
162
+ * TODO: Remove all constraints before dropping tables to handle FK dependencies.
163
+ *
164
+ * @param knexHandle Knex instance with configured DB connection
165
+ * @param appSettings Settings object with dbType and optional dbSchema
101
166
  */
102
- const dbWipe = (knexHandle, appSettings) => {
103
- let query = SQLS[appSettings.dbType].dropTablesSchema(appSettings);
104
- if (!appSettings.dbSchema) {
105
- query = SQLS[appSettings.dbType].dropTables(appSettings);
167
+ const dbWipe = async (knexHandle, appSettings) => {
168
+ assertSupportedDbType(appSettings.dbType);
169
+ const query = appSettings.dbSchema
170
+ ? SQLS[appSettings.dbType].dropTablesSchema(appSettings)
171
+ : SQLS[appSettings.dbType].dropTables(appSettings);
172
+ const result = await knexHandle.raw(query);
173
+ const commands = result.rows.map((r) => r.cmd);
174
+ // Fix: replaced BPromise.each() with for...of to remove bluebird dependency
175
+ // and align with async/await style used throughout the codebase
176
+ for (const cmd of commands) {
177
+ await knexHandle.raw(cmd);
106
178
  }
107
- return knexHandle
108
- .raw(query)
109
- .then((result) => result.rows.map((r) => r.cmd))
110
- .then((commands) => BPromise.each(commands, (cmd) => knexHandle.raw(cmd)));
111
179
  };
112
180
  /**
113
- * Drop all tables, run migrations, then seed
181
+ * Drops all tables, runs all pending migrations, then optionally seeds the database.
182
+ * Intended for test environment reset between test suites.
183
+ *
184
+ * Fix: now re-throws after logging so callers know the reset failed rather
185
+ * than silently continuing with a broken database state.
186
+ *
187
+ * @param knexHandle Knex instance with configured DB connection
188
+ * @param appSettings Settings object passed through to dbWipe and dbRunMigrations
114
189
  */
115
- const dbReset = (knexHandle, appSettings) => {
116
- return dbWipe(knexHandle, appSettings)
117
- .then(() => dbRunMigrations(knexHandle, appSettings))
118
- .catch((error) => console.log('An exception has occurred on resetting database: ', error));
190
+ const dbReset = async (knexHandle, appSettings) => {
191
+ try {
192
+ await dbWipe(knexHandle, appSettings);
193
+ await dbRunMigrations(knexHandle, appSettings);
194
+ }
195
+ catch (ex) {
196
+ console.error('An exception has occurred on resetting database:', ex);
197
+ throw ex;
198
+ }
119
199
  };
120
200
  /**
121
- * Go from array of objects which contain keys of object names which have an array value of seeded objects
122
- * to a single object with keys of object names and arrays of seeded objects
123
- * ie from [{table1: [], table2: [] }, { table3: [] }]
124
- * to { table1: [], table2: [], table3: []}
201
+ * Merges an array of seed result objects into a single flat object.
202
+ *
203
+ * Converts: `[{ table1: [...], table2: [...] }, { table3: [...] }]`
204
+ * Into: `{ table1: [...], table2: [...], table3: [...] }`
205
+ *
206
+ * Useful for collecting the results of multiple seed generators before
207
+ * inserting or asserting on them in tests.
208
+ *
209
+ * Fix: replaced `for...in` (which includes inherited properties) with
210
+ * `Object.assign()` which only copies own enumerable properties.
211
+ *
212
+ * @param generatedSeedArrays Array of seed result objects to merge
213
+ */
214
+ const dbTransformSeedsToObject = (generatedSeedArrays) => reduce(generatedSeedArrays, (acc, cur) => Object.assign(acc, cur), {});
215
+ /**
216
+ * Runs all pending Knex migrations and optionally seeds the database.
217
+ * Seeds are only run if `appSettings.runDbSeed` is true AND at least one
218
+ * migration was applied — prevents re-seeding an already-seeded database.
219
+ *
220
+ * Logs the number of migrations run and the resulting schema version.
221
+ *
222
+ * @param knexHandle Knex instance with configured DB connection
223
+ * @param appSettings Settings object with optional runDbSeed flag
125
224
  */
126
- const dbTransformSeedsToObject = (generatedSeedArrays) => reduce(generatedSeedArrays, (acc, cur) => {
127
- for (const key in cur) {
128
- acc[key] = cur[key];
225
+ const dbRunMigrations = async (knexHandle, appSettings) => {
226
+ const result = await knexHandle.migrate.latest();
227
+ if (appSettings?.runDbSeed && result[1].length > 0) {
228
+ await knexHandle.seed.run();
129
229
  }
130
- return acc;
131
- }, {});
132
- const dbRunMigrations = (knexHandle, appSettings) => {
133
- return knexHandle.migrate
134
- .latest()
135
- .then(async (result) => {
136
- if (appSettings && appSettings.runDbSeed && result[1].length > 0) {
137
- await knexHandle.seed.run();
138
- }
139
- console.log('Ran', result[1].length, 'migration(s)');
140
- return knexHandle.migrate.currentVersion();
141
- })
142
- .then((version) => console.log('Current version of database: ', version));
230
+ console.info('Ran', result[1].length, 'migration(s)');
231
+ const version = await knexHandle.migrate.currentVersion();
232
+ console.info('Current version of database:', version);
143
233
  };
144
234
  export { dbCleanTable, dbListTables, dbClean, dbWipe, dbReset, dbTransformSeedsToObject, dbRunMigrations };
@@ -1,2 +1,11 @@
1
- declare const dbSeed: (dirname: string, seedFiles: any, knexHandle: any, config: any) => Promise<any>;
1
+ /**
2
+ * Full seed pipeline: generate seeds from files, delete existing records,
3
+ * then insert the generated seeds.
4
+ *
5
+ * @param dirname Absolute directory path containing the `objects/` folder
6
+ * @param seedFiles Array of filename groups
7
+ * @param knexHandle Knex instance with configured DB connection
8
+ * @param config Config object with dbSchema and other db settings
9
+ */
10
+ declare const dbSeed: (dirname: string, seedFiles: string[][], knexHandle: any, config: any) => Promise<void>;
2
11
  export { dbSeed };
@@ -1,16 +1,47 @@
1
+ // ./src/seedHelpers.ts
1
2
  import path from 'path';
2
- import { camelCase, flatten, map } from 'lodash';
3
+ import { camelCase, flatten } from 'lodash';
3
4
  import { dbClean } from './dbHelpers';
5
+ /**
6
+ * Seed utility functions for use outside of the DbMigratorAndSeeder class.
7
+ *
8
+ * Note: the logic in generateSeeds, removeSeedsFromDb, and insertRecords
9
+ * mirrors DbMigratorAndSeeder's instance methods of the same name.
10
+ * If you update the seeding logic here, keep DbMigratorAndSeeder in sync
11
+ * (or consolidate by having DbMigratorAndSeeder delegate to these functions).
12
+ */
13
+ /**
14
+ * Loads and executes seed generator functions from the provided file list,
15
+ * building a dependency-ordered array of seed groups.
16
+ *
17
+ * `seedFiles` is an array of groups (arrays of filenames). Within each group,
18
+ * seeds are generated sequentially and results of earlier seeds are available
19
+ * to later seeds via the `seeds` accumulator — allowing seeds to reference
20
+ * ids of previously generated records.
21
+ *
22
+ * Files are loaded from `dirname/objects/<filename>` without extension —
23
+ * the module resolver handles `.js`/`.ts` based on the runtime.
24
+ *
25
+ * Fix: removed hardcoded `.js` extension — was breaking in TypeScript/ESM.
26
+ *
27
+ * @param dirname Absolute directory path containing the `objects/` folder
28
+ * @param seedFiles Array of filename groups, e.g. `[['users'], ['posts', 'comments']]`
29
+ * @returns Array of seed group objects ready for `insertRecords()`
30
+ */
4
31
  const generateSeeds = async (dirname, seedFiles) => {
5
32
  let seedGroups = [];
6
33
  const seedFileNames = flatten(seedFiles);
7
- const seedFnExports = await Promise.all(map(seedFileNames, (filename) => import(path.join(dirname, `./objects/${filename}.js`))));
8
- const seedFns = map(seedFnExports, 'default');
34
+ // Load all seed modules in parallel
35
+ const seedFnExports = await Promise.all(
36
+ // Fix: removed hardcoded '.js' extension — let the module resolver handle it
37
+ seedFileNames.map((filename) => import(path.join(dirname, `./objects/${filename}`))));
38
+ // Build a filename → default export map for O(1) lookup in the reduce below
9
39
  const seedFnsMap = {};
10
- for (let i = 0; i < seedFileNames.length; i++) {
11
- const seedFileName = seedFileNames[i];
12
- seedFnsMap[seedFileName] = seedFns[i];
13
- }
40
+ seedFileNames.forEach((filename, i) => {
41
+ seedFnsMap[filename] = seedFnExports[i].default;
42
+ });
43
+ // Process seed files group by group, carrying generated seeds forward
44
+ // so later seeds can reference ids from earlier ones
14
45
  seedFiles.reduce((seeds, fileGroup) => {
15
46
  seedGroups = seedGroups.concat(fileGroup.reduce((group, filename) => {
16
47
  const seedFn = seedFnsMap[filename];
@@ -23,22 +54,56 @@ const generateSeeds = async (dirname, seedFiles) => {
23
54
  }, {});
24
55
  return seedGroups;
25
56
  };
26
- const removeSeedsFromDb = (seedFiles, knexHandle, config) => {
57
+ /**
58
+ * Deletes all records for the tables referenced by `seedFiles`, in reverse
59
+ * order to respect foreign key dependencies (children before parents).
60
+ *
61
+ * @param seedFiles Array of filename groups — table order derived from
62
+ * the flattened + reversed list of filenames
63
+ * @param knexHandle Knex instance with configured DB connection
64
+ * @param config Config object passed through to dbClean
65
+ */
66
+ const removeSeedsFromDb = async (seedFiles, knexHandle, config) => {
27
67
  const tablesToReset = flatten(seedFiles).reverse();
28
- console.log('Deleting records from tables: ', tablesToReset);
68
+ console.info('Deleting records from tables:', tablesToReset);
29
69
  return dbClean(tablesToReset, knexHandle, config);
30
70
  };
31
- const insertRecords = (seedGroups, knexHandle, config) => {
71
+ /**
72
+ * Inserts seed records group by group, in order.
73
+ * Groups are processed sequentially (each group waits for the previous)
74
+ * but records within a group are inserted in parallel via `Promise.all`.
75
+ *
76
+ * Sequential group processing preserves seed dependency order —
77
+ * a group that references records from a previous group can rely on
78
+ * those records being present before it runs.
79
+ *
80
+ * Fix: replaced async reduce anti-pattern with `for...of` + `await`
81
+ * for clarity — behaviour is identical (sequential groups, parallel within group).
82
+ * Fix: corrected log message typo ('tables tables' → 'into tables').
83
+ *
84
+ * @param seedGroups Array of seed group objects from `generateSeeds()`
85
+ * @param knexHandle Knex instance with configured DB connection
86
+ * @param config Config object with dbSchema
87
+ */
88
+ const insertRecords = async (seedGroups, knexHandle, config) => {
32
89
  const { dbSchema } = config || {};
33
- console.log('Inserting seeds records tables tables...');
34
- return seedGroups.reduce(async (previousGroup, group) => {
35
- await previousGroup;
36
- return Promise.all(Object.keys(group).map((table) => knexHandle(table).withSchema(dbSchema).insert(group[table])));
37
- }, Promise.resolve());
90
+ console.info('Inserting seed records into tables...');
91
+ for (const group of seedGroups) {
92
+ await Promise.all(Object.keys(group).map((table) => knexHandle(table).withSchema(dbSchema).insert(group[table])));
93
+ }
38
94
  };
95
+ /**
96
+ * Full seed pipeline: generate seeds from files, delete existing records,
97
+ * then insert the generated seeds.
98
+ *
99
+ * @param dirname Absolute directory path containing the `objects/` folder
100
+ * @param seedFiles Array of filename groups
101
+ * @param knexHandle Knex instance with configured DB connection
102
+ * @param config Config object with dbSchema and other db settings
103
+ */
39
104
  const dbSeed = async (dirname, seedFiles, knexHandle, config) => {
40
105
  const groups = await generateSeeds(dirname, seedFiles);
41
106
  await removeSeedsFromDb(seedFiles, knexHandle, config);
42
- return await insertRecords(groups, knexHandle, config);
107
+ await insertRecords(groups, knexHandle, config);
43
108
  };
44
109
  export { dbSeed };
@@ -1,14 +1,131 @@
1
1
  import { DbFieldAddDefaultInterface } from './interfaces';
2
- import { FIELDS } from './constants';
2
+ /**
3
+ * Knex migration helper functions for adding standard column sets to tables.
4
+ *
5
+ * All functions accept a Knex `TableBuilder` instance as their first argument
6
+ * (`table: any` — typed as any to avoid coupling to a specific Knex version).
7
+ * They are intended to be called inside `knex.schema.createTable()` or
8
+ * `knex.schema.alterTable()` callbacks.
9
+ *
10
+ * Example usage in a migration:
11
+ * exports.up = (knex) =>
12
+ * knex.schema.createTable('post', (table) => {
13
+ * table.uuid('id').primary();
14
+ * table.text('title').notNullable();
15
+ * dbFieldAddDefaults(table, { addStatus: true, addUserInfo: true });
16
+ * });
17
+ */
18
+ /**
19
+ * Adds a standard set of default columns to a table.
20
+ *
21
+ * Columns added based on options:
22
+ * - `addStatus` → status (integer, indexed)
23
+ * - `addVersion` → version (integer)
24
+ * - `addUserInfo` → created_by, updated_by, removed_by (uuid)
25
+ * - `!skipTimestamps` → created_at, updated_at (via knex timestamps()),
26
+ * removed_at (dateTime, nullable),
27
+ * removed_at_str (string, indexed) unless skipRemovedAtStr
28
+ *
29
+ * Fix: `removed_at_str` index was added whenever `skipRemovedAtStr !== true`,
30
+ * regardless of `skipTimestamps`. If `skipTimestamps === true`, the column is
31
+ * never created but the index was still attempted — causing a migration error.
32
+ * Index is now only added when both `skipTimestamps` and `skipRemovedAtStr` are false.
33
+ *
34
+ * Note on `addUserInfo` + `removed_by`:
35
+ * `removed_by` is added whenever `addUserInfo` is true, even if the table
36
+ * uses hard deletes. On hard-delete tables this column exists but is never
37
+ * written — acceptable for schema consistency but worth noting.
38
+ *
39
+ * @param table Knex TableBuilder instance
40
+ * @param opt Column selection options
41
+ */
3
42
  export declare const dbFieldAddDefaults: (table: any, opt?: DbFieldAddDefaultInterface) => void;
43
+ /**
44
+ * Adds a text-based `order_no` column for lexicographic ordering.
45
+ * Uses string ordering — suitable for drag-and-drop reordering scenarios
46
+ * where records can be inserted between existing values without renumbering.
47
+ *
48
+ * Default value matches DEFAULT_ORDER_NO from constants ('10000000').
49
+ * Large starting value leaves room for manual insertions before the first
50
+ * auto-assigned record.
51
+ *
52
+ * @param table Knex TableBuilder instance
53
+ * @param opt Options: `addIndex` — whether to add an index on order_no
54
+ * @returns The Knex column chain for further modification
55
+ */
4
56
  export declare const addOrderNo: (table: any, opt?: any) => any;
57
+ /**
58
+ * Adds a decimal `order_no` column for numeric ordering.
59
+ * Uses a high-precision decimal (30, 15) to support fractional insertion
60
+ * between existing values.
61
+ *
62
+ * Note: default value (1000000) intentionally differs from addOrderNo's
63
+ * DEFAULT_ORDER_NO (10000000) — numeric sequences start lower since
64
+ * fractional values can be inserted between any two integers.
65
+ *
66
+ * @param table Knex TableBuilder instance
67
+ * @param opt Options: `addIndex` — whether to add an index on order_no
68
+ * @returns The Knex column chain for further modification
69
+ */
5
70
  export declare const addOrderNoNum: (table: any, opt?: any) => any;
71
+ /**
72
+ * Adds a high-precision decimal column for monetary or other precise amounts.
73
+ * Uses decimal(19, 4) — sufficient for most financial amounts up to
74
+ * 999,999,999,999,999 with 4 decimal places.
75
+ *
76
+ * @param table Knex TableBuilder instance
77
+ * @param fieldName Column name for the amount field
78
+ * @returns The Knex column chain for further modification
79
+ */
6
80
  export declare const addAmount: (table: any, fieldName: string) => any;
81
+ /**
82
+ * Adds a `space_id` string column (128 chars) with an optional foreign key
83
+ * to the `space` table.
84
+ *
85
+ * Typed as string(128) since space identifiers are strings, not UUIDs.
86
+ *
87
+ * @param table Knex TableBuilder instance
88
+ * @param opt Options: `addForeignKey` — whether to add FK to space table
89
+ * @returns The Knex column chain for further modification
90
+ */
7
91
  export declare const addSpaceId: (table: any, opt?: any) => any;
92
+ /**
93
+ * Adds a `user_id` UUID column with optional foreign key to the `user` table
94
+ * and optional index.
95
+ *
96
+ * @param table Knex TableBuilder instance
97
+ * @param opt Options: `addForeignKey`, `addIndex`
98
+ * @returns The Knex column chain for further modification
99
+ */
8
100
  export declare const addUserId: (table: any, opt?: any) => any;
101
+ /**
102
+ * Adds an `account_id` UUID column with optional foreign key to the `account`
103
+ * table and optional index.
104
+ *
105
+ * @param table Knex TableBuilder instance
106
+ * @param opt Options: `addForeignKey`, `addIndex`
107
+ * @returns The Knex column chain for further modification
108
+ */
9
109
  export declare const addAccountId: (table: any, opt?: any) => any;
110
+ /**
111
+ * Adds a `lang` text column defaulting to 'en' with optional foreign key
112
+ * to a `language` table and optional index.
113
+ *
114
+ * @param table Knex TableBuilder instance
115
+ * @param opt Options: `addForeignKey`, `addIndex`
116
+ * @returns The Knex column chain for further modification
117
+ */
10
118
  export declare const addLang: (table: any, opt?: any) => any;
11
- export declare const defaultFields: (opt?: any) => {
12
- [FIELDS.CREATED_AT]: string;
13
- [FIELDS.UPDATED_AT]: string;
14
- };
119
+ /**
120
+ * Returns a plain object with default field values for use in Knex seed files.
121
+ *
122
+ * Provides consistent baseline timestamps for seeded records.
123
+ * The hardcoded date ('2021-01-01T00:00:00Z') is intentional for seeds —
124
+ * using a static past date ensures seed data is reproducible and
125
+ * distinguishable from records created at runtime.
126
+ *
127
+ * @param opt Options: `addUserInfo` — whether to include created_by/updated_by
128
+ * UUID fields (set to UUID_EMPTY as placeholder values)
129
+ * @returns Plain object with default field values
130
+ */
131
+ export declare const defaultFields: (opt?: any) => Record<string, any>;