@sdflc/backend-helpers 1.0.120 → 1.0.122
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/build/BaseGateway.d.ts +1 -1
- package/build/BaseGateway.js +6 -4
- package/build/esm/BaseGateway.d.ts +1 -1
- package/build/esm/BaseGateway.js +6 -4
- package/build/esm/interfaces/CacheInterface.d.ts +8 -1
- package/build/esm/knexConfigBuilder.d.ts +2 -0
- package/build/esm/knexConfigBuilder.js +57 -3
- package/build/interfaces/CacheInterface.d.ts +8 -1
- package/build/knexConfigBuilder.d.ts +2 -0
- package/build/knexConfigBuilder.js +57 -3
- package/package.json +1 -1
package/build/BaseGateway.d.ts
CHANGED
|
@@ -285,7 +285,7 @@ declare class BaseGateway {
|
|
|
285
285
|
* Returns the Database instance from config.
|
|
286
286
|
* All query builders are derived from this instance.
|
|
287
287
|
*/
|
|
288
|
-
getDb(): Database;
|
|
288
|
+
getDb(): Database | undefined;
|
|
289
289
|
/**
|
|
290
290
|
* Returns a Knex query builder scoped to this gateway's table.
|
|
291
291
|
* The builder is a fresh instance each time — it does not carry state
|
package/build/BaseGateway.js
CHANGED
|
@@ -482,10 +482,11 @@ class BaseGateway {
|
|
|
482
482
|
obj[constants_1.FIELDS.REMOVED_BY] = this.getContext()?.userId;
|
|
483
483
|
}
|
|
484
484
|
}
|
|
485
|
-
|
|
485
|
+
const db = this.getDb();
|
|
486
|
+
if (hasLang && localizationForField && db) {
|
|
486
487
|
// Append removal timestamp to the id to free the original localisation key
|
|
487
488
|
// for future re-use (e.g. if a new record with the same lang + slug is created).
|
|
488
|
-
obj[this.getIdField()] =
|
|
489
|
+
obj[this.getIdField()] = db.raw(`CONCAT(id, '-${removalTimeStr}')`);
|
|
489
490
|
}
|
|
490
491
|
return obj;
|
|
491
492
|
}
|
|
@@ -634,10 +635,11 @@ class BaseGateway {
|
|
|
634
635
|
*/
|
|
635
636
|
async list(args) {
|
|
636
637
|
const { filter, params, useCache } = args || {};
|
|
637
|
-
const
|
|
638
|
-
if (!this.config.table) {
|
|
638
|
+
const db = this.getDb();
|
|
639
|
+
if (!this.config.table || !db) {
|
|
639
640
|
return [];
|
|
640
641
|
}
|
|
642
|
+
const { limit, offset, sortBy } = db.createLimitOffsetSortBy(params, this.config.defaultSorting || []);
|
|
641
643
|
const shouldUseCache = useCache != null ? useCache : !this.config.noCache;
|
|
642
644
|
const fieldsToUse = !shouldUseCache && Array.isArray(this.config.selectFields) ? this.config.selectFields : this.getIdField();
|
|
643
645
|
const { query } = await this.buildListQuery({ filter, params, fieldsToUse, useCache: shouldUseCache });
|
|
@@ -285,7 +285,7 @@ declare class BaseGateway {
|
|
|
285
285
|
* Returns the Database instance from config.
|
|
286
286
|
* All query builders are derived from this instance.
|
|
287
287
|
*/
|
|
288
|
-
getDb(): Database;
|
|
288
|
+
getDb(): Database | undefined;
|
|
289
289
|
/**
|
|
290
290
|
* Returns a Knex query builder scoped to this gateway's table.
|
|
291
291
|
* The builder is a fresh instance each time — it does not carry state
|
package/build/esm/BaseGateway.js
CHANGED
|
@@ -476,10 +476,11 @@ class BaseGateway {
|
|
|
476
476
|
obj[FIELDS.REMOVED_BY] = this.getContext()?.userId;
|
|
477
477
|
}
|
|
478
478
|
}
|
|
479
|
-
|
|
479
|
+
const db = this.getDb();
|
|
480
|
+
if (hasLang && localizationForField && db) {
|
|
480
481
|
// Append removal timestamp to the id to free the original localisation key
|
|
481
482
|
// for future re-use (e.g. if a new record with the same lang + slug is created).
|
|
482
|
-
obj[this.getIdField()] =
|
|
483
|
+
obj[this.getIdField()] = db.raw(`CONCAT(id, '-${removalTimeStr}')`);
|
|
483
484
|
}
|
|
484
485
|
return obj;
|
|
485
486
|
}
|
|
@@ -628,10 +629,11 @@ class BaseGateway {
|
|
|
628
629
|
*/
|
|
629
630
|
async list(args) {
|
|
630
631
|
const { filter, params, useCache } = args || {};
|
|
631
|
-
const
|
|
632
|
-
if (!this.config.table) {
|
|
632
|
+
const db = this.getDb();
|
|
633
|
+
if (!this.config.table || !db) {
|
|
633
634
|
return [];
|
|
634
635
|
}
|
|
636
|
+
const { limit, offset, sortBy } = db.createLimitOffsetSortBy(params, this.config.defaultSorting || []);
|
|
635
637
|
const shouldUseCache = useCache != null ? useCache : !this.config.noCache;
|
|
636
638
|
const fieldsToUse = !shouldUseCache && Array.isArray(this.config.selectFields) ? this.config.selectFields : this.getIdField();
|
|
637
639
|
const { query } = await this.buildListQuery({ filter, params, fieldsToUse, useCache: shouldUseCache });
|
|
@@ -1,6 +1,13 @@
|
|
|
1
1
|
import { Database } from '../Database';
|
|
2
2
|
export interface CacheInterface {
|
|
3
|
-
|
|
3
|
+
/**
|
|
4
|
+
* Database instance used by the default batch loader (batchLoaderDefault).
|
|
5
|
+
* Optional when a custom `loaderFn` is provided — in that case the loader
|
|
6
|
+
* function is responsible for its own data fetching and `db` is not used.
|
|
7
|
+
* Runtime safety is enforced in DataCache.batchLoaderDefault(), which throws
|
|
8
|
+
* if `db` is missing and no `loaderFn` was supplied.
|
|
9
|
+
*/
|
|
10
|
+
db?: Database;
|
|
4
11
|
/**
|
|
5
12
|
* Namespace prefix for DataLoader cache keys.
|
|
6
13
|
* Resolved in BaseGateway as: context.keyPrefix → config.keyPrefix → table name.
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Built-in behaviours:
|
|
10
10
|
* - All query results are post-processed to camelCase via `camelResponse`
|
|
11
|
+
* - For MSSQL, UUID values in query results are lowercased automatically
|
|
12
|
+
* so application code never needs to handle uppercase GUIDs
|
|
11
13
|
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
12
14
|
* with an optional override map for exceptions
|
|
13
15
|
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
// ./src/knexConfigBuilder.ts
|
|
2
1
|
import path from 'path';
|
|
3
2
|
import { snakeCase } from 'lodash';
|
|
4
3
|
import { camelKeys } from '@sdflc/utils';
|
|
@@ -6,6 +5,49 @@ const defaultMigrationsTable = 'migrations';
|
|
|
6
5
|
const defaultMigrationsFolder = 'migrations';
|
|
7
6
|
const defaultMigrationsTemplateFileName = 'migrations-template.js';
|
|
8
7
|
const defaultSeedsFolder = 'seeds';
|
|
8
|
+
/**
|
|
9
|
+
* Matches a standard UUID v1–v5 in any casing.
|
|
10
|
+
* Used to detect UUID values returned by MSSQL in uppercase so they can be
|
|
11
|
+
* normalised to lowercase before reaching application code.
|
|
12
|
+
*
|
|
13
|
+
* The pattern requires the canonical 8-4-4-4-12 hyphenated format — it will
|
|
14
|
+
* not match stripped (non-hyphenated) GUIDs or other ID formats.
|
|
15
|
+
*/
|
|
16
|
+
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
17
|
+
/**
|
|
18
|
+
* Returns true when `value` is a string in canonical UUID format.
|
|
19
|
+
* The check is intentionally loose on casing (the `i` flag) so it catches
|
|
20
|
+
* both the uppercase UUIDs that MSSQL returns and already-lowercase ones.
|
|
21
|
+
*/
|
|
22
|
+
const isUuid = (value) => typeof value === 'string' && UUID_REGEX.test(value);
|
|
23
|
+
/**
|
|
24
|
+
* Recursively walks a query result value and lowercases any UUID strings.
|
|
25
|
+
*
|
|
26
|
+
* Handles the three shapes Knex passes to postProcessResponse:
|
|
27
|
+
* - Arrays of row objects (SELECT queries)
|
|
28
|
+
* - Plain objects (single rows, aggregates, RETURNING results)
|
|
29
|
+
* - Primitive values (scalars — returned unchanged unless they are UUIDs)
|
|
30
|
+
*
|
|
31
|
+
* Non-UUID strings, numbers, booleans, null, and undefined are returned
|
|
32
|
+
* unchanged. This is purely a value transform — key casing is handled
|
|
33
|
+
* separately by camelKeys() in camelResponse().
|
|
34
|
+
*/
|
|
35
|
+
const lowercaseUuids = (value) => {
|
|
36
|
+
if (Array.isArray(value)) {
|
|
37
|
+
return value.map(lowercaseUuids);
|
|
38
|
+
}
|
|
39
|
+
if (value !== null && typeof value === 'object') {
|
|
40
|
+
const result = {};
|
|
41
|
+
for (const [k, v] of Object.entries(value)) {
|
|
42
|
+
result[k] = lowercaseUuids(v);
|
|
43
|
+
}
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
46
|
+
if (isUuid(value)) {
|
|
47
|
+
return value.toLowerCase();
|
|
48
|
+
}
|
|
49
|
+
return value;
|
|
50
|
+
};
|
|
9
51
|
/**
|
|
10
52
|
* Post-processes Knex query results by converting all keys to camelCase.
|
|
11
53
|
*
|
|
@@ -17,13 +59,20 @@ const defaultSeedsFolder = 'seeds';
|
|
|
17
59
|
* shape leaks through — in that case we return it unchanged since Knex's
|
|
18
60
|
* own processing has not yet run.
|
|
19
61
|
*
|
|
62
|
+
* When `normaliseMssqlUuids` is true (i.e. dbType is 'mssql'), UUID values
|
|
63
|
+
* are lowercased before camelKeys() runs. This ensures that UUID foreign keys
|
|
64
|
+
* and primary keys are always lowercase throughout the application regardless
|
|
65
|
+
* of how MSSQL stored or returned them, eliminating the need for per-gateway
|
|
66
|
+
* or per-core UUID normalisation.
|
|
67
|
+
*
|
|
20
68
|
* See: https://knexjs.org/guide/#post-process-response
|
|
21
69
|
*/
|
|
22
|
-
const
|
|
70
|
+
const buildCamelResponse = (normaliseMssqlUuids) => (result) => {
|
|
23
71
|
if (!result || result.rows) {
|
|
24
72
|
return result;
|
|
25
73
|
}
|
|
26
|
-
|
|
74
|
+
const normalised = normaliseMssqlUuids ? lowercaseUuids(result) : result;
|
|
75
|
+
return camelKeys(normalised);
|
|
27
76
|
};
|
|
28
77
|
/**
|
|
29
78
|
* Builds a Knex configuration object for the current environment.
|
|
@@ -35,6 +84,8 @@ const camelResponse = (result) => {
|
|
|
35
84
|
*
|
|
36
85
|
* Built-in behaviours:
|
|
37
86
|
* - All query results are post-processed to camelCase via `camelResponse`
|
|
87
|
+
* - For MSSQL, UUID values in query results are lowercased automatically
|
|
88
|
+
* so application code never needs to handle uppercase GUIDs
|
|
38
89
|
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
39
90
|
* with an optional override map for exceptions
|
|
40
91
|
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
@@ -53,6 +104,9 @@ const camelResponse = (result) => {
|
|
|
53
104
|
export const buildKnexConfig = (dirName, appConfig) => {
|
|
54
105
|
const { dbType, dbHost, dbPort, dbName, dbSchema, dbUser, dbPassword, dbPoolMin, dbPoolMax, debug, nodeEnv, migrationsTemplateFileName, migrationsFolder, migrationsTable, useSchemaForMigrationsTable, seedsFolder, seedsFolderDev, seedsFolderProd, wrapIdentifierOverrideMap, dbPool, } = appConfig;
|
|
55
106
|
const resolvedDbType = dbType || 'pg';
|
|
107
|
+
// Build the post-processor once per config — closed over resolvedDbType so
|
|
108
|
+
// UUID lowercasing is applied only for MSSQL without branching on every row.
|
|
109
|
+
const camelResponse = buildCamelResponse(resolvedDbType === 'mssql');
|
|
56
110
|
// ─── Connection ──────────────────────────────────────────────────────────
|
|
57
111
|
const connection = {
|
|
58
112
|
host: dbHost,
|
|
@@ -1,6 +1,13 @@
|
|
|
1
1
|
import { Database } from '../Database';
|
|
2
2
|
export interface CacheInterface {
|
|
3
|
-
|
|
3
|
+
/**
|
|
4
|
+
* Database instance used by the default batch loader (batchLoaderDefault).
|
|
5
|
+
* Optional when a custom `loaderFn` is provided — in that case the loader
|
|
6
|
+
* function is responsible for its own data fetching and `db` is not used.
|
|
7
|
+
* Runtime safety is enforced in DataCache.batchLoaderDefault(), which throws
|
|
8
|
+
* if `db` is missing and no `loaderFn` was supplied.
|
|
9
|
+
*/
|
|
10
|
+
db?: Database;
|
|
4
11
|
/**
|
|
5
12
|
* Namespace prefix for DataLoader cache keys.
|
|
6
13
|
* Resolved in BaseGateway as: context.keyPrefix → config.keyPrefix → table name.
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Built-in behaviours:
|
|
10
10
|
* - All query results are post-processed to camelCase via `camelResponse`
|
|
11
|
+
* - For MSSQL, UUID values in query results are lowercased automatically
|
|
12
|
+
* so application code never needs to handle uppercase GUIDs
|
|
11
13
|
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
12
14
|
* with an optional override map for exceptions
|
|
13
15
|
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
// ./src/knexConfigBuilder.ts
|
|
3
2
|
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
4
3
|
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
5
4
|
};
|
|
@@ -12,6 +11,49 @@ const defaultMigrationsTable = 'migrations';
|
|
|
12
11
|
const defaultMigrationsFolder = 'migrations';
|
|
13
12
|
const defaultMigrationsTemplateFileName = 'migrations-template.js';
|
|
14
13
|
const defaultSeedsFolder = 'seeds';
|
|
14
|
+
/**
|
|
15
|
+
* Matches a standard UUID v1–v5 in any casing.
|
|
16
|
+
* Used to detect UUID values returned by MSSQL in uppercase so they can be
|
|
17
|
+
* normalised to lowercase before reaching application code.
|
|
18
|
+
*
|
|
19
|
+
* The pattern requires the canonical 8-4-4-4-12 hyphenated format — it will
|
|
20
|
+
* not match stripped (non-hyphenated) GUIDs or other ID formats.
|
|
21
|
+
*/
|
|
22
|
+
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
23
|
+
/**
|
|
24
|
+
* Returns true when `value` is a string in canonical UUID format.
|
|
25
|
+
* The check is intentionally loose on casing (the `i` flag) so it catches
|
|
26
|
+
* both the uppercase UUIDs that MSSQL returns and already-lowercase ones.
|
|
27
|
+
*/
|
|
28
|
+
const isUuid = (value) => typeof value === 'string' && UUID_REGEX.test(value);
|
|
29
|
+
/**
|
|
30
|
+
* Recursively walks a query result value and lowercases any UUID strings.
|
|
31
|
+
*
|
|
32
|
+
* Handles the three shapes Knex passes to postProcessResponse:
|
|
33
|
+
* - Arrays of row objects (SELECT queries)
|
|
34
|
+
* - Plain objects (single rows, aggregates, RETURNING results)
|
|
35
|
+
* - Primitive values (scalars — returned unchanged unless they are UUIDs)
|
|
36
|
+
*
|
|
37
|
+
* Non-UUID strings, numbers, booleans, null, and undefined are returned
|
|
38
|
+
* unchanged. This is purely a value transform — key casing is handled
|
|
39
|
+
* separately by camelKeys() in camelResponse().
|
|
40
|
+
*/
|
|
41
|
+
const lowercaseUuids = (value) => {
|
|
42
|
+
if (Array.isArray(value)) {
|
|
43
|
+
return value.map(lowercaseUuids);
|
|
44
|
+
}
|
|
45
|
+
if (value !== null && typeof value === 'object') {
|
|
46
|
+
const result = {};
|
|
47
|
+
for (const [k, v] of Object.entries(value)) {
|
|
48
|
+
result[k] = lowercaseUuids(v);
|
|
49
|
+
}
|
|
50
|
+
return result;
|
|
51
|
+
}
|
|
52
|
+
if (isUuid(value)) {
|
|
53
|
+
return value.toLowerCase();
|
|
54
|
+
}
|
|
55
|
+
return value;
|
|
56
|
+
};
|
|
15
57
|
/**
|
|
16
58
|
* Post-processes Knex query results by converting all keys to camelCase.
|
|
17
59
|
*
|
|
@@ -23,13 +65,20 @@ const defaultSeedsFolder = 'seeds';
|
|
|
23
65
|
* shape leaks through — in that case we return it unchanged since Knex's
|
|
24
66
|
* own processing has not yet run.
|
|
25
67
|
*
|
|
68
|
+
* When `normaliseMssqlUuids` is true (i.e. dbType is 'mssql'), UUID values
|
|
69
|
+
* are lowercased before camelKeys() runs. This ensures that UUID foreign keys
|
|
70
|
+
* and primary keys are always lowercase throughout the application regardless
|
|
71
|
+
* of how MSSQL stored or returned them, eliminating the need for per-gateway
|
|
72
|
+
* or per-core UUID normalisation.
|
|
73
|
+
*
|
|
26
74
|
* See: https://knexjs.org/guide/#post-process-response
|
|
27
75
|
*/
|
|
28
|
-
const
|
|
76
|
+
const buildCamelResponse = (normaliseMssqlUuids) => (result) => {
|
|
29
77
|
if (!result || result.rows) {
|
|
30
78
|
return result;
|
|
31
79
|
}
|
|
32
|
-
|
|
80
|
+
const normalised = normaliseMssqlUuids ? lowercaseUuids(result) : result;
|
|
81
|
+
return (0, utils_1.camelKeys)(normalised);
|
|
33
82
|
};
|
|
34
83
|
/**
|
|
35
84
|
* Builds a Knex configuration object for the current environment.
|
|
@@ -41,6 +90,8 @@ const camelResponse = (result) => {
|
|
|
41
90
|
*
|
|
42
91
|
* Built-in behaviours:
|
|
43
92
|
* - All query results are post-processed to camelCase via `camelResponse`
|
|
93
|
+
* - For MSSQL, UUID values in query results are lowercased automatically
|
|
94
|
+
* so application code never needs to handle uppercase GUIDs
|
|
44
95
|
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
45
96
|
* with an optional override map for exceptions
|
|
46
97
|
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
@@ -59,6 +110,9 @@ const camelResponse = (result) => {
|
|
|
59
110
|
const buildKnexConfig = (dirName, appConfig) => {
|
|
60
111
|
const { dbType, dbHost, dbPort, dbName, dbSchema, dbUser, dbPassword, dbPoolMin, dbPoolMax, debug, nodeEnv, migrationsTemplateFileName, migrationsFolder, migrationsTable, useSchemaForMigrationsTable, seedsFolder, seedsFolderDev, seedsFolderProd, wrapIdentifierOverrideMap, dbPool, } = appConfig;
|
|
61
112
|
const resolvedDbType = dbType || 'pg';
|
|
113
|
+
// Build the post-processor once per config — closed over resolvedDbType so
|
|
114
|
+
// UUID lowercasing is applied only for MSSQL without branching on every row.
|
|
115
|
+
const camelResponse = buildCamelResponse(resolvedDbType === 'mssql');
|
|
62
116
|
// ─── Connection ──────────────────────────────────────────────────────────
|
|
63
117
|
const connection = {
|
|
64
118
|
host: dbHost,
|