@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.
- package/README.md +1422 -146
- package/build/BaseController.d.ts +20 -0
- package/build/BaseController.js +64 -0
- package/build/BaseCore.d.ts +470 -33
- package/build/BaseCore.js +613 -126
- package/build/BaseExternalApiGateway.d.ts +16 -0
- package/build/BaseExternalApiGateway.js +54 -0
- package/build/BaseGateway.d.ts +455 -17
- package/build/BaseGateway.js +502 -56
- package/build/BaseRestApiCrudController.d.ts +37 -0
- package/build/BaseRestApiCrudController.js +134 -0
- package/build/DataCache.d.ts +116 -5
- package/build/DataCache.js +144 -22
- package/build/Database.d.ts +165 -4
- package/build/Database.js +224 -51
- package/build/DbMigratorAndSeeder.d.ts +127 -26
- package/build/DbMigratorAndSeeder.js +180 -69
- package/build/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +12 -27
- package/build/checkItHelpers.d.ts +32 -0
- package/build/checkItHelpers.js +73 -7
- package/build/commonValidators.d.ts +107 -16
- package/build/commonValidators.js +211 -106
- package/build/configBuilder.d.ts +23 -0
- package/build/configBuilder.js +73 -0
- package/build/constants.d.ts +134 -17
- package/build/constants.js +95 -15
- package/build/dbHelpers.d.ts +89 -29
- package/build/dbHelpers.js +175 -86
- package/build/dbSeeder.d.ts +10 -1
- package/build/dbSeeder.js +80 -15
- package/build/dbTableHelpers.d.ts +122 -5
- package/build/dbTableHelpers.js +151 -13
- package/build/downloadHelpers.d.ts +24 -1
- package/build/downloadHelpers.js +51 -21
- package/build/esm/BaseController.d.ts +20 -0
- package/build/esm/BaseController.js +58 -0
- package/build/esm/BaseCore.d.ts +470 -33
- package/build/esm/BaseCore.js +615 -128
- package/build/esm/BaseExternalApiGateway.d.ts +16 -0
- package/build/esm/BaseExternalApiGateway.js +48 -0
- package/build/esm/BaseGateway.d.ts +455 -17
- package/build/esm/BaseGateway.js +503 -57
- package/build/esm/BaseRestApiCrudController.d.ts +37 -0
- package/build/esm/BaseRestApiCrudController.js +131 -0
- package/build/esm/DataCache.d.ts +116 -5
- package/build/esm/DataCache.js +142 -20
- package/build/esm/Database.d.ts +165 -4
- package/build/esm/Database.js +224 -51
- package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
- package/build/esm/DbMigratorAndSeeder.js +184 -71
- package/build/esm/RedisDataLoader.d.ts +144 -21
- package/build/esm/RedisDataLoader.js +179 -50
- package/build/esm/apiContext.d.ts +0 -8
- package/build/esm/apiContext.js +12 -27
- package/build/esm/checkItHelpers.d.ts +32 -0
- package/build/esm/checkItHelpers.js +73 -7
- package/build/esm/commonValidators.d.ts +107 -16
- package/build/esm/commonValidators.js +209 -105
- package/build/esm/configBuilder.d.ts +23 -0
- package/build/esm/configBuilder.js +69 -0
- package/build/esm/constants.d.ts +134 -17
- package/build/esm/constants.js +94 -14
- package/build/esm/dbHelpers.d.ts +89 -29
- package/build/esm/dbHelpers.js +171 -81
- package/build/esm/dbSeeder.d.ts +10 -1
- package/build/esm/dbSeeder.js +81 -16
- package/build/esm/dbTableHelpers.d.ts +122 -5
- package/build/esm/dbTableHelpers.js +152 -14
- package/build/esm/downloadHelpers.d.ts +24 -1
- package/build/esm/downloadHelpers.js +51 -21
- package/build/esm/index.d.ts +5 -2
- package/build/esm/index.js +5 -2
- package/build/esm/interfaces/ApiContext.d.ts +7 -3
- package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/esm/interfaces/BaseCorePropsInterface.d.ts +87 -9
- package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
- package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/esm/interfaces/BuildConfigOptions.js +1 -0
- package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/esm/interfaces/CacheInterface.d.ts +18 -1
- package/build/esm/interfaces/CacheInterface.js +1 -0
- package/build/esm/interfaces/CoreActionInterface.d.ts +20 -0
- package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
- package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/esm/interfaces/DatabaseOptions.js +1 -0
- package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
- package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/esm/interfaces/ListArgsInterface.js +1 -0
- package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
- package/build/esm/interfaces/LoaderInterface.js +1 -0
- package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
- package/build/esm/interfaces/UserTokenParams.js +1 -0
- package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/esm/interfaces/index.d.ts +4 -0
- package/build/esm/interfaces/index.js +4 -0
- package/build/esm/knexConfigBuilder.d.ts +25 -0
- package/build/esm/knexConfigBuilder.js +100 -36
- package/build/esm/parseIds.d.ts +6 -0
- package/build/esm/parseIds.js +13 -0
- package/build/esm/passwordHelpers.d.ts +22 -0
- package/build/esm/passwordHelpers.js +40 -8
- package/build/esm/redisClient.d.ts +57 -4
- package/build/esm/redisClient.js +40 -54
- package/build/esm/resolveClientIp.d.ts +15 -0
- package/build/esm/resolveClientIp.js +34 -0
- package/build/esm/resolversHelpers.d.ts +21 -1
- package/build/esm/resolversHelpers.js +48 -26
- package/build/esm/userToken.d.ts +50 -1
- package/build/esm/userToken.js +85 -20
- package/build/esm/utils.d.ts +20 -0
- package/build/esm/utils.js +23 -1
- package/build/index.d.ts +5 -2
- package/build/index.js +5 -2
- package/build/interfaces/ApiContext.d.ts +7 -3
- package/build/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/interfaces/BaseControllerPropsInterface.js +2 -0
- package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/interfaces/BaseCorePropsInterface.d.ts +87 -9
- package/build/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
- package/build/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/interfaces/BuildConfigOptions.js +1 -0
- package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/interfaces/CacheInterface.d.ts +18 -1
- package/build/interfaces/CacheInterface.js +1 -0
- package/build/interfaces/CoreActionInterface.d.ts +20 -0
- package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/interfaces/DataCachePropsInterface.js +3 -0
- package/build/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/interfaces/DatabaseOptions.js +1 -0
- package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/interfaces/DatabaseReadInterface.js +1 -0
- package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/interfaces/ListArgsInterface.js +1 -0
- package/build/interfaces/LoaderInterface.d.ts +36 -1
- package/build/interfaces/LoaderInterface.js +1 -0
- package/build/interfaces/UserTokenParams.d.ts +23 -5
- package/build/interfaces/UserTokenParams.js +1 -0
- package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/interfaces/index.d.ts +4 -0
- package/build/interfaces/index.js +4 -0
- package/build/knexConfigBuilder.d.ts +25 -0
- package/build/knexConfigBuilder.js +99 -35
- package/build/parseIds.d.ts +6 -0
- package/build/parseIds.js +17 -0
- package/build/passwordHelpers.d.ts +22 -0
- package/build/passwordHelpers.js +40 -8
- package/build/redisClient.d.ts +57 -4
- package/build/redisClient.js +40 -54
- package/build/resolveClientIp.d.ts +15 -0
- package/build/resolveClientIp.js +38 -0
- package/build/resolversHelpers.d.ts +21 -1
- package/build/resolversHelpers.js +48 -26
- package/build/userToken.d.ts +50 -1
- package/build/userToken.js +85 -20
- package/build/utils.d.ts +20 -0
- package/build/utils.js +23 -1
- package/package.json +19 -18
- package/build/baseController.d.ts +0 -17
- package/build/baseController.js +0 -63
- package/build/configBulder.d.ts +0 -2
- package/build/configBulder.js +0 -36
- package/build/esm/baseController.d.ts +0 -17
- package/build/esm/baseController.js +0 -57
- package/build/esm/configBulder.d.ts +0 -2
- package/build/esm/configBulder.js +0 -32
package/build/esm/dbHelpers.js
CHANGED
|
@@ -1,144 +1,234 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
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 !=
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
* @param
|
|
87
|
-
* @
|
|
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 (
|
|
91
|
-
await dbCleanTable(
|
|
148
|
+
for (const table of tablesToClean) {
|
|
149
|
+
await dbCleanTable(table, knexHandle, appSettings);
|
|
92
150
|
}
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
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
|
|
127
|
-
|
|
128
|
-
|
|
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
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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 };
|
package/build/esm/dbSeeder.d.ts
CHANGED
|
@@ -1,2 +1,11 @@
|
|
|
1
|
-
|
|
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 };
|
package/build/esm/dbSeeder.js
CHANGED
|
@@ -1,16 +1,47 @@
|
|
|
1
|
+
// ./src/seedHelpers.ts
|
|
1
2
|
import path from 'path';
|
|
2
|
-
import { camelCase, flatten
|
|
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
|
-
|
|
8
|
-
const
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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.
|
|
68
|
+
console.info('Deleting records from tables:', tablesToReset);
|
|
29
69
|
return dbClean(tablesToReset, knexHandle, config);
|
|
30
70
|
};
|
|
31
|
-
|
|
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.
|
|
34
|
-
|
|
35
|
-
await
|
|
36
|
-
|
|
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
|
-
|
|
107
|
+
await insertRecords(groups, knexHandle, config);
|
|
43
108
|
};
|
|
44
109
|
export { dbSeed };
|
|
@@ -1,14 +1,131 @@
|
|
|
1
1
|
import { DbFieldAddDefaultInterface } from './interfaces';
|
|
2
|
-
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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>;
|