@sdflc/backend-helpers 1.0.121 → 1.0.123
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 +231 -50
- package/build/BaseGateway.js +471 -64
- package/build/Database.d.ts +15 -0
- package/build/Database.js +17 -1
- package/build/esm/BaseGateway.d.ts +231 -50
- package/build/esm/BaseGateway.js +471 -64
- package/build/esm/Database.d.ts +15 -0
- package/build/esm/Database.js +17 -1
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +54 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +0 -1
- package/build/esm/interfaces/GatewayFilterRule.d.ts +109 -0
- package/build/esm/interfaces/GatewayFilterRule.js +1 -0
- package/build/esm/interfaces/index.d.ts +1 -0
- package/build/esm/interfaces/index.js +1 -0
- package/build/esm/knexConfigBuilder.d.ts +2 -0
- package/build/esm/knexConfigBuilder.js +57 -3
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +54 -0
- package/build/interfaces/BaseGatewayPropsInterface.js +0 -1
- package/build/interfaces/GatewayFilterRule.d.ts +109 -0
- package/build/interfaces/GatewayFilterRule.js +2 -0
- package/build/interfaces/index.d.ts +1 -0
- package/build/interfaces/index.js +1 -0
- package/build/knexConfigBuilder.d.ts +2 -0
- package/build/knexConfigBuilder.js +57 -3
- package/package.json +1 -1
package/build/esm/Database.js
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
// ./src/Database.ts (capitalised to match class name convention)
|
|
2
1
|
import camelCase from 'lodash/camelCase';
|
|
3
2
|
import knex from 'knex';
|
|
4
3
|
import { buildKey as defaultBuildKey, Logger, LoggerLevels, isLogger } from '@sdflc/utils';
|
|
@@ -100,6 +99,23 @@ class Database {
|
|
|
100
99
|
return [false, ''];
|
|
101
100
|
}
|
|
102
101
|
}
|
|
102
|
+
/**
|
|
103
|
+
* Returns the SQL LIKE operator appropriate for the connected database engine.
|
|
104
|
+
*
|
|
105
|
+
* PostgreSQL supports ILIKE natively — a case-insensitive variant of LIKE.
|
|
106
|
+
* MS Azure SQL Server and MySQL do not have ILIKE; they use plain LIKE, which
|
|
107
|
+
* is case-insensitive by default under the collations used in this project
|
|
108
|
+
* (e.g. SQL_Latin1_General_CP1_CI_AS on MSSQL, utf8_general_ci on MySQL).
|
|
109
|
+
*
|
|
110
|
+
* Use this wherever a case-insensitive pattern match is needed so the
|
|
111
|
+
* correct operator is chosen automatically without branching in gateway code.
|
|
112
|
+
*
|
|
113
|
+
* Knex client strings: 'pg' | 'pg-native' for PostgreSQL; 'mssql' | 'tedious'
|
|
114
|
+
* for SQL Server; 'mysql' | 'mysql2' for MySQL.
|
|
115
|
+
*/
|
|
116
|
+
getSqlLikeOperator() {
|
|
117
|
+
return this.dbType === 'pg' || this.dbType === 'pg-native' ? 'ilike' : 'like';
|
|
118
|
+
}
|
|
103
119
|
/**
|
|
104
120
|
* Creates a new Knex transaction.
|
|
105
121
|
* If `trx` is provided, creates a nested transaction on the existing one.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { Logger } from '@sdflc/utils';
|
|
2
2
|
import { ApiContext } from '.';
|
|
3
3
|
import { CacheInterface } from '..';
|
|
4
|
+
import { GatewayFilterRule } from './GatewayFilterRule';
|
|
4
5
|
import { LoaderInterface } from './LoaderInterface';
|
|
5
6
|
import { SortItemInterface } from './SortItemInterface';
|
|
6
7
|
export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
@@ -111,4 +112,57 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
111
112
|
* between production and non-production environments.
|
|
112
113
|
*/
|
|
113
114
|
isProduction?: boolean;
|
|
115
|
+
/**
|
|
116
|
+
* Declarative WHERE rules applied by onListFilter() after base logic.
|
|
117
|
+
*
|
|
118
|
+
* All filter types are supported. Rules are applied against the filter
|
|
119
|
+
* object passed to list() via args.filter.
|
|
120
|
+
*
|
|
121
|
+
* Example:
|
|
122
|
+
* listFilters: [
|
|
123
|
+
* { field: 'partyId', column: 'Party_Guest.Party_ID', type: 'array' },
|
|
124
|
+
* { field: 'isStarred', column: 'Party_Guest.Is_Starred', type: 'bool' },
|
|
125
|
+
* { field: 'wasInvited', column: 'Party_Guest.Invited_At', type: 'nullableBool' },
|
|
126
|
+
* { field: 'rsvpAt', column: 'Party_Guest.Rsvp_At', type: 'nullableDateRange' },
|
|
127
|
+
* {
|
|
128
|
+
* field: 'search', column: '', type: 'search',
|
|
129
|
+
* columns: ['Person.First_Name', 'Person.Email'],
|
|
130
|
+
* },
|
|
131
|
+
* ]
|
|
132
|
+
*/
|
|
133
|
+
listFilters?: GatewayFilterRule[];
|
|
134
|
+
/**
|
|
135
|
+
* Declarative WHERE rules applied by onUpdateFilter() after base logic.
|
|
136
|
+
*
|
|
137
|
+
* Intended for simple equality / array filters on the update path.
|
|
138
|
+
* Each rule that matches increments the filtersAppliedQty counter,
|
|
139
|
+
* contributing to the safety guard that prevents unfiltered UPDATEs.
|
|
140
|
+
*
|
|
141
|
+
* 'search', 'dateRange', and 'nullableDateRange' are NOT supported here —
|
|
142
|
+
* update filters should be precise identifiers, not fuzzy searches or ranges.
|
|
143
|
+
* Rules with unsupported types are silently skipped and logged as a warning.
|
|
144
|
+
*
|
|
145
|
+
* Example:
|
|
146
|
+
* updateFilters: [
|
|
147
|
+
* { field: 'partyId', column: 'Party_ID', type: 'array' },
|
|
148
|
+
* ]
|
|
149
|
+
*/
|
|
150
|
+
updateFilters?: GatewayFilterRule[];
|
|
151
|
+
/**
|
|
152
|
+
* Declarative WHERE rules applied by onRemoveFilter() after base logic.
|
|
153
|
+
*
|
|
154
|
+
* The remove path operates on castArray(whereParams) — an array of filter
|
|
155
|
+
* objects. For 'array' rules, values are collected across ALL entries in
|
|
156
|
+
* the array and applied as a single whereIn, matching the bulk-remove
|
|
157
|
+
* pattern established in PartyGuestGw.onRemoveFilter.
|
|
158
|
+
*
|
|
159
|
+
* As with updateFilters, 'search', 'dateRange', and 'nullableDateRange'
|
|
160
|
+
* are not supported and will be skipped with a warning.
|
|
161
|
+
*
|
|
162
|
+
* Example:
|
|
163
|
+
* removeFilters: [
|
|
164
|
+
* { field: 'partyId', column: 'Party_ID', type: 'array' },
|
|
165
|
+
* ]
|
|
166
|
+
*/
|
|
167
|
+
removeFilters?: GatewayFilterRule[];
|
|
114
168
|
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GatewayFilterRule
|
|
3
|
+
*
|
|
4
|
+
* Discriminator for the declarative filter rules accepted by BaseGateway.
|
|
5
|
+
* Each type maps to a specific WHERE clause strategy:
|
|
6
|
+
*
|
|
7
|
+
* 'array' — whereIn(column, values) for arrays; where(column, value)
|
|
8
|
+
* for scalars. Skipped when value is null / undefined / ''.
|
|
9
|
+
*
|
|
10
|
+
* 'eq' — where(column, value). Skipped when value is null/undefined.
|
|
11
|
+
* Use when you want a strict single-value equality and never
|
|
12
|
+
* want array expansion (e.g. an enum code, a boolean stored
|
|
13
|
+
* as a number).
|
|
14
|
+
*
|
|
15
|
+
* 'bool' — where(column, true|false). Only fires when the filter value
|
|
16
|
+
* is strictly true or false — null and undefined are ignored.
|
|
17
|
+
* Use for boolean columns where you want to filter on the
|
|
18
|
+
* value itself (e.g. IS_STARRED = true).
|
|
19
|
+
*
|
|
20
|
+
* 'nullableBool' — true → whereNotNull(column)
|
|
21
|
+
* false → whereNull(column)
|
|
22
|
+
* null/undefined → skipped (no constraint added).
|
|
23
|
+
* Use when a nullable datetime/column encodes presence:
|
|
24
|
+
* e.g. wasInvited ↔ Invited_At IS [NOT] NULL.
|
|
25
|
+
*
|
|
26
|
+
* 'dateRange' — Reads filterParams[field + 'From'] and filterParams[field + 'To'].
|
|
27
|
+
* Applies where(column, '>=', from) and/or where(column, '<=', to).
|
|
28
|
+
* Either bound is independently optional.
|
|
29
|
+
* The 'field' on the rule is the base name (e.g. 'rsvpAt');
|
|
30
|
+
* the actual filter keys are 'rsvpAtFrom' / 'rsvpAtTo'.
|
|
31
|
+
*
|
|
32
|
+
* 'nullableDateRange' — Extends 'dateRange' with a null-check phase.
|
|
33
|
+
* Also reads filterParams[field + 'Null'] (boolean):
|
|
34
|
+
* true → whereNull(column); from/to skipped
|
|
35
|
+
* false → whereNotNull(column); from/to still applied
|
|
36
|
+
* null/undefined → null-ness unconstrained; from/to applied
|
|
37
|
+
*
|
|
38
|
+
* 'search' — LIKE / ILIKE across one or more columns (OR semantics).
|
|
39
|
+
* Reads filterParams[field] (string). Trims whitespace; skipped
|
|
40
|
+
* when the result is empty.
|
|
41
|
+
* Requires the 'columns' array on the rule — must be non-empty.
|
|
42
|
+
* The operator ('like' vs 'ilike') is resolved per-database
|
|
43
|
+
* via Database.getSqlLikeOperator() so behaviour is correct on
|
|
44
|
+
* both PostgreSQL (ilike) and MS Azure SQL Server (like, which
|
|
45
|
+
* is case-insensitive under _CI_ collations).
|
|
46
|
+
*/
|
|
47
|
+
export type GatewayFilterType = 'array' | 'eq' | 'bool' | 'nullableBool' | 'dateRange' | 'nullableDateRange' | 'search';
|
|
48
|
+
/**
|
|
49
|
+
* GatewayFilterRule
|
|
50
|
+
*
|
|
51
|
+
* A single declarative filter rule for use in BaseGatewayPropsInterface.listFilters,
|
|
52
|
+
* updateFilters, and removeFilters.
|
|
53
|
+
*
|
|
54
|
+
* Rules are applied in declaration order by BaseGateway after the standard
|
|
55
|
+
* base-class filter logic runs. They supplement — never replace — the existing
|
|
56
|
+
* onListFilter / onUpdateFilter / onRemoveFilter override chain.
|
|
57
|
+
*
|
|
58
|
+
* Example — array filter:
|
|
59
|
+
* { field: 'partyId', column: `${TABLES.PARTY_GUEST}.${FIELDS.PARTY_ID}`, type: 'array' }
|
|
60
|
+
*
|
|
61
|
+
* Example — nullable bool (wasInvited ↔ Invited_At IS [NOT] NULL):
|
|
62
|
+
* { field: 'wasInvited', column: `${TABLES.PARTY_GUEST}.${FIELDS.INVITED_AT}`, type: 'nullableBool' }
|
|
63
|
+
*
|
|
64
|
+
* Example — nullable date range:
|
|
65
|
+
* { field: 'rsvpAt', column: `${TABLES.PARTY_GUEST}.${FIELDS.RSVP_AT}`, type: 'nullableDateRange' }
|
|
66
|
+
* reads: filter.rsvpAtNull, filter.rsvpAtFrom, filter.rsvpAtTo
|
|
67
|
+
*
|
|
68
|
+
* Example — full-text search across Person columns:
|
|
69
|
+
* {
|
|
70
|
+
* field: 'search',
|
|
71
|
+
* column: '', // unused for 'search' — columns[] drives the OR
|
|
72
|
+
* type: 'search',
|
|
73
|
+
* columns: [
|
|
74
|
+
* `${TABLES.PERSON}.${FIELDS.FIRST_NAME}`,
|
|
75
|
+
* `${TABLES.PERSON}.${FIELDS.EMAIL}`,
|
|
76
|
+
* ],
|
|
77
|
+
* }
|
|
78
|
+
*/
|
|
79
|
+
export interface GatewayFilterRule {
|
|
80
|
+
/**
|
|
81
|
+
* The key read from filterParams.
|
|
82
|
+
*
|
|
83
|
+
* For 'dateRange' / 'nullableDateRange': this is the base name; the actual
|
|
84
|
+
* keys read are field+'From', field+'To', and (for nullableDateRange) field+'Null'.
|
|
85
|
+
*
|
|
86
|
+
* For 'search': this is the key that holds the search string.
|
|
87
|
+
*/
|
|
88
|
+
field: string;
|
|
89
|
+
/**
|
|
90
|
+
* The fully-qualified database column the filter is applied to.
|
|
91
|
+
* Should include the table name to prevent ambiguity in joined queries
|
|
92
|
+
* (e.g. 'Party_Guest.Party_ID', not just 'Party_ID').
|
|
93
|
+
*
|
|
94
|
+
* Unused for 'search' (which uses the 'columns' array instead) but
|
|
95
|
+
* must still be present as an empty string for type safety.
|
|
96
|
+
*/
|
|
97
|
+
column: string;
|
|
98
|
+
/**
|
|
99
|
+
* The filter strategy. See GatewayFilterType for full documentation.
|
|
100
|
+
*/
|
|
101
|
+
type: GatewayFilterType;
|
|
102
|
+
/**
|
|
103
|
+
* Required for type: 'search' — the list of columns to OR across.
|
|
104
|
+
* Must contain at least one entry; the rule is silently skipped otherwise.
|
|
105
|
+
* Each entry should be table-qualified for joined query safety.
|
|
106
|
+
* Ignored for all other filter types.
|
|
107
|
+
*/
|
|
108
|
+
columns?: string[];
|
|
109
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -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,7 @@
|
|
|
1
1
|
import { Logger } from '@sdflc/utils';
|
|
2
2
|
import { ApiContext } from '.';
|
|
3
3
|
import { CacheInterface } from '..';
|
|
4
|
+
import { GatewayFilterRule } from './GatewayFilterRule';
|
|
4
5
|
import { LoaderInterface } from './LoaderInterface';
|
|
5
6
|
import { SortItemInterface } from './SortItemInterface';
|
|
6
7
|
export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
@@ -111,4 +112,57 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
111
112
|
* between production and non-production environments.
|
|
112
113
|
*/
|
|
113
114
|
isProduction?: boolean;
|
|
115
|
+
/**
|
|
116
|
+
* Declarative WHERE rules applied by onListFilter() after base logic.
|
|
117
|
+
*
|
|
118
|
+
* All filter types are supported. Rules are applied against the filter
|
|
119
|
+
* object passed to list() via args.filter.
|
|
120
|
+
*
|
|
121
|
+
* Example:
|
|
122
|
+
* listFilters: [
|
|
123
|
+
* { field: 'partyId', column: 'Party_Guest.Party_ID', type: 'array' },
|
|
124
|
+
* { field: 'isStarred', column: 'Party_Guest.Is_Starred', type: 'bool' },
|
|
125
|
+
* { field: 'wasInvited', column: 'Party_Guest.Invited_At', type: 'nullableBool' },
|
|
126
|
+
* { field: 'rsvpAt', column: 'Party_Guest.Rsvp_At', type: 'nullableDateRange' },
|
|
127
|
+
* {
|
|
128
|
+
* field: 'search', column: '', type: 'search',
|
|
129
|
+
* columns: ['Person.First_Name', 'Person.Email'],
|
|
130
|
+
* },
|
|
131
|
+
* ]
|
|
132
|
+
*/
|
|
133
|
+
listFilters?: GatewayFilterRule[];
|
|
134
|
+
/**
|
|
135
|
+
* Declarative WHERE rules applied by onUpdateFilter() after base logic.
|
|
136
|
+
*
|
|
137
|
+
* Intended for simple equality / array filters on the update path.
|
|
138
|
+
* Each rule that matches increments the filtersAppliedQty counter,
|
|
139
|
+
* contributing to the safety guard that prevents unfiltered UPDATEs.
|
|
140
|
+
*
|
|
141
|
+
* 'search', 'dateRange', and 'nullableDateRange' are NOT supported here —
|
|
142
|
+
* update filters should be precise identifiers, not fuzzy searches or ranges.
|
|
143
|
+
* Rules with unsupported types are silently skipped and logged as a warning.
|
|
144
|
+
*
|
|
145
|
+
* Example:
|
|
146
|
+
* updateFilters: [
|
|
147
|
+
* { field: 'partyId', column: 'Party_ID', type: 'array' },
|
|
148
|
+
* ]
|
|
149
|
+
*/
|
|
150
|
+
updateFilters?: GatewayFilterRule[];
|
|
151
|
+
/**
|
|
152
|
+
* Declarative WHERE rules applied by onRemoveFilter() after base logic.
|
|
153
|
+
*
|
|
154
|
+
* The remove path operates on castArray(whereParams) — an array of filter
|
|
155
|
+
* objects. For 'array' rules, values are collected across ALL entries in
|
|
156
|
+
* the array and applied as a single whereIn, matching the bulk-remove
|
|
157
|
+
* pattern established in PartyGuestGw.onRemoveFilter.
|
|
158
|
+
*
|
|
159
|
+
* As with updateFilters, 'search', 'dateRange', and 'nullableDateRange'
|
|
160
|
+
* are not supported and will be skipped with a warning.
|
|
161
|
+
*
|
|
162
|
+
* Example:
|
|
163
|
+
* removeFilters: [
|
|
164
|
+
* { field: 'partyId', column: 'Party_ID', type: 'array' },
|
|
165
|
+
* ]
|
|
166
|
+
*/
|
|
167
|
+
removeFilters?: GatewayFilterRule[];
|
|
114
168
|
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GatewayFilterRule
|
|
3
|
+
*
|
|
4
|
+
* Discriminator for the declarative filter rules accepted by BaseGateway.
|
|
5
|
+
* Each type maps to a specific WHERE clause strategy:
|
|
6
|
+
*
|
|
7
|
+
* 'array' — whereIn(column, values) for arrays; where(column, value)
|
|
8
|
+
* for scalars. Skipped when value is null / undefined / ''.
|
|
9
|
+
*
|
|
10
|
+
* 'eq' — where(column, value). Skipped when value is null/undefined.
|
|
11
|
+
* Use when you want a strict single-value equality and never
|
|
12
|
+
* want array expansion (e.g. an enum code, a boolean stored
|
|
13
|
+
* as a number).
|
|
14
|
+
*
|
|
15
|
+
* 'bool' — where(column, true|false). Only fires when the filter value
|
|
16
|
+
* is strictly true or false — null and undefined are ignored.
|
|
17
|
+
* Use for boolean columns where you want to filter on the
|
|
18
|
+
* value itself (e.g. IS_STARRED = true).
|
|
19
|
+
*
|
|
20
|
+
* 'nullableBool' — true → whereNotNull(column)
|
|
21
|
+
* false → whereNull(column)
|
|
22
|
+
* null/undefined → skipped (no constraint added).
|
|
23
|
+
* Use when a nullable datetime/column encodes presence:
|
|
24
|
+
* e.g. wasInvited ↔ Invited_At IS [NOT] NULL.
|
|
25
|
+
*
|
|
26
|
+
* 'dateRange' — Reads filterParams[field + 'From'] and filterParams[field + 'To'].
|
|
27
|
+
* Applies where(column, '>=', from) and/or where(column, '<=', to).
|
|
28
|
+
* Either bound is independently optional.
|
|
29
|
+
* The 'field' on the rule is the base name (e.g. 'rsvpAt');
|
|
30
|
+
* the actual filter keys are 'rsvpAtFrom' / 'rsvpAtTo'.
|
|
31
|
+
*
|
|
32
|
+
* 'nullableDateRange' — Extends 'dateRange' with a null-check phase.
|
|
33
|
+
* Also reads filterParams[field + 'Null'] (boolean):
|
|
34
|
+
* true → whereNull(column); from/to skipped
|
|
35
|
+
* false → whereNotNull(column); from/to still applied
|
|
36
|
+
* null/undefined → null-ness unconstrained; from/to applied
|
|
37
|
+
*
|
|
38
|
+
* 'search' — LIKE / ILIKE across one or more columns (OR semantics).
|
|
39
|
+
* Reads filterParams[field] (string). Trims whitespace; skipped
|
|
40
|
+
* when the result is empty.
|
|
41
|
+
* Requires the 'columns' array on the rule — must be non-empty.
|
|
42
|
+
* The operator ('like' vs 'ilike') is resolved per-database
|
|
43
|
+
* via Database.getSqlLikeOperator() so behaviour is correct on
|
|
44
|
+
* both PostgreSQL (ilike) and MS Azure SQL Server (like, which
|
|
45
|
+
* is case-insensitive under _CI_ collations).
|
|
46
|
+
*/
|
|
47
|
+
export type GatewayFilterType = 'array' | 'eq' | 'bool' | 'nullableBool' | 'dateRange' | 'nullableDateRange' | 'search';
|
|
48
|
+
/**
|
|
49
|
+
* GatewayFilterRule
|
|
50
|
+
*
|
|
51
|
+
* A single declarative filter rule for use in BaseGatewayPropsInterface.listFilters,
|
|
52
|
+
* updateFilters, and removeFilters.
|
|
53
|
+
*
|
|
54
|
+
* Rules are applied in declaration order by BaseGateway after the standard
|
|
55
|
+
* base-class filter logic runs. They supplement — never replace — the existing
|
|
56
|
+
* onListFilter / onUpdateFilter / onRemoveFilter override chain.
|
|
57
|
+
*
|
|
58
|
+
* Example — array filter:
|
|
59
|
+
* { field: 'partyId', column: `${TABLES.PARTY_GUEST}.${FIELDS.PARTY_ID}`, type: 'array' }
|
|
60
|
+
*
|
|
61
|
+
* Example — nullable bool (wasInvited ↔ Invited_At IS [NOT] NULL):
|
|
62
|
+
* { field: 'wasInvited', column: `${TABLES.PARTY_GUEST}.${FIELDS.INVITED_AT}`, type: 'nullableBool' }
|
|
63
|
+
*
|
|
64
|
+
* Example — nullable date range:
|
|
65
|
+
* { field: 'rsvpAt', column: `${TABLES.PARTY_GUEST}.${FIELDS.RSVP_AT}`, type: 'nullableDateRange' }
|
|
66
|
+
* reads: filter.rsvpAtNull, filter.rsvpAtFrom, filter.rsvpAtTo
|
|
67
|
+
*
|
|
68
|
+
* Example — full-text search across Person columns:
|
|
69
|
+
* {
|
|
70
|
+
* field: 'search',
|
|
71
|
+
* column: '', // unused for 'search' — columns[] drives the OR
|
|
72
|
+
* type: 'search',
|
|
73
|
+
* columns: [
|
|
74
|
+
* `${TABLES.PERSON}.${FIELDS.FIRST_NAME}`,
|
|
75
|
+
* `${TABLES.PERSON}.${FIELDS.EMAIL}`,
|
|
76
|
+
* ],
|
|
77
|
+
* }
|
|
78
|
+
*/
|
|
79
|
+
export interface GatewayFilterRule {
|
|
80
|
+
/**
|
|
81
|
+
* The key read from filterParams.
|
|
82
|
+
*
|
|
83
|
+
* For 'dateRange' / 'nullableDateRange': this is the base name; the actual
|
|
84
|
+
* keys read are field+'From', field+'To', and (for nullableDateRange) field+'Null'.
|
|
85
|
+
*
|
|
86
|
+
* For 'search': this is the key that holds the search string.
|
|
87
|
+
*/
|
|
88
|
+
field: string;
|
|
89
|
+
/**
|
|
90
|
+
* The fully-qualified database column the filter is applied to.
|
|
91
|
+
* Should include the table name to prevent ambiguity in joined queries
|
|
92
|
+
* (e.g. 'Party_Guest.Party_ID', not just 'Party_ID').
|
|
93
|
+
*
|
|
94
|
+
* Unused for 'search' (which uses the 'columns' array instead) but
|
|
95
|
+
* must still be present as an empty string for type safety.
|
|
96
|
+
*/
|
|
97
|
+
column: string;
|
|
98
|
+
/**
|
|
99
|
+
* The filter strategy. See GatewayFilterType for full documentation.
|
|
100
|
+
*/
|
|
101
|
+
type: GatewayFilterType;
|
|
102
|
+
/**
|
|
103
|
+
* Required for type: 'search' — the list of columns to OR across.
|
|
104
|
+
* Must contain at least one entry; the rule is silently skipped otherwise.
|
|
105
|
+
* Each entry should be table-qualified for joined query safety.
|
|
106
|
+
* Ignored for all other filter types.
|
|
107
|
+
*/
|
|
108
|
+
columns?: string[];
|
|
109
|
+
}
|
|
@@ -45,3 +45,4 @@ __exportStar(require("./BaseControllerPropsInterface"), exports);
|
|
|
45
45
|
__exportStar(require("./BaseRestApiCrudControllerPropsInterface"), exports);
|
|
46
46
|
__exportStar(require("./BaseExternalApiGatewayPropsInterface"), exports);
|
|
47
47
|
__exportStar(require("./DataCachePropsInterface"), exports);
|
|
48
|
+
__exportStar(require("./GatewayFilterRule"), exports);
|
|
@@ -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,
|