@sdflc/backend-helpers 1.0.121 → 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.
@@ -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 camelResponse = (result) => {
70
+ const buildCamelResponse = (normaliseMssqlUuids) => (result) => {
23
71
  if (!result || result.rows) {
24
72
  return result;
25
73
  }
26
- return camelKeys(result);
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,
@@ -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 camelResponse = (result) => {
76
+ const buildCamelResponse = (normaliseMssqlUuids) => (result) => {
29
77
  if (!result || result.rows) {
30
78
  return result;
31
79
  }
32
- return (0, utils_1.camelKeys)(result);
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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.121",
3
+ "version": "1.0.122",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {