@sdflc/backend-helpers 1.0.142 → 1.0.143
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 +7 -0
- package/build/BaseGateway.js +52 -1
- package/build/esm/BaseGateway.d.ts +7 -0
- package/build/esm/BaseGateway.js +52 -1
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +11 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +11 -0
- package/package.json +2 -2
package/build/BaseGateway.d.ts
CHANGED
|
@@ -153,6 +153,13 @@ declare class BaseGateway {
|
|
|
153
153
|
* (e.g. a table with a UUID primary key but a separate "slug" as update target).
|
|
154
154
|
*/
|
|
155
155
|
getIdFieldUpdateRemove(): string;
|
|
156
|
+
/**
|
|
157
|
+
* The column `list()` appends as the last sort term when it applies a limit — so tied rows keep one order across
|
|
158
|
+
* pages. `config.listTieBreaker` when set (a string names the column, `false` turns it off → null); otherwise the id
|
|
159
|
+
* field, qualified with the table's OWN name (the last segment of `config.table`, so `SCHEMA.Table` gives `Table.id`)
|
|
160
|
+
* — a list query that joins another table with an `id` stays unambiguous. Override to compute it differently.
|
|
161
|
+
*/
|
|
162
|
+
getListTieBreaker(): string | null;
|
|
156
163
|
/**
|
|
157
164
|
* Applies a whereIn or where-equals filter for scalar or array values.
|
|
158
165
|
*
|
package/build/BaseGateway.js
CHANGED
|
@@ -18,6 +18,24 @@ const DEFAULT_CHUNCK_SIZE = 2500;
|
|
|
18
18
|
* filters must be precise identifiers, not fuzzy searches or time windows.
|
|
19
19
|
*/
|
|
20
20
|
const UPDATE_REMOVE_SUPPORTED_TYPES = new Set(['array', 'eq', 'bool', 'nullableBool']);
|
|
21
|
+
/** `[table, column]` of a column reference, lower-cased; the table is '' when unqualified. */
|
|
22
|
+
const splitColumn = (reference) => {
|
|
23
|
+
const parts = String(reference || '').split('.');
|
|
24
|
+
const column = (parts.pop() || '').toLowerCase();
|
|
25
|
+
const table = (parts.pop() || '').toLowerCase();
|
|
26
|
+
return [table, column];
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Whether a sort already orders by `column` — matched by the column's own name, and by its table when BOTH name one:
|
|
30
|
+
* a bare `id` and `party_appearance.id` are the same column here (a duplicate would be refused by SQL Server).
|
|
31
|
+
*/
|
|
32
|
+
const sortNamesColumn = (sortBy, column) => {
|
|
33
|
+
const [table, name] = splitColumn(column);
|
|
34
|
+
return (sortBy || []).some((item) => {
|
|
35
|
+
const [itemTable, itemName] = splitColumn(String(item?.column ?? ''));
|
|
36
|
+
return itemName === name && (!itemTable || !table || itemTable === table);
|
|
37
|
+
});
|
|
38
|
+
};
|
|
21
39
|
/**
|
|
22
40
|
* BaseGateway is the foundation for all database-backed gateway classes.
|
|
23
41
|
*
|
|
@@ -229,6 +247,29 @@ class BaseGateway {
|
|
|
229
247
|
getIdFieldUpdateRemove() {
|
|
230
248
|
return this.config.idFieldUpdateRemove || this.config.idField || constants_1.ID_FIELD;
|
|
231
249
|
}
|
|
250
|
+
/**
|
|
251
|
+
* The column `list()` appends as the last sort term when it applies a limit — so tied rows keep one order across
|
|
252
|
+
* pages. `config.listTieBreaker` when set (a string names the column, `false` turns it off → null); otherwise the id
|
|
253
|
+
* field, qualified with the table's OWN name (the last segment of `config.table`, so `SCHEMA.Table` gives `Table.id`)
|
|
254
|
+
* — a list query that joins another table with an `id` stays unambiguous. Override to compute it differently.
|
|
255
|
+
*/
|
|
256
|
+
getListTieBreaker() {
|
|
257
|
+
const configured = this.config.listTieBreaker;
|
|
258
|
+
if (configured === false) {
|
|
259
|
+
return null;
|
|
260
|
+
}
|
|
261
|
+
if (typeof configured === 'string' && configured) {
|
|
262
|
+
return configured;
|
|
263
|
+
}
|
|
264
|
+
const idField = this.getIdField();
|
|
265
|
+
if (idField.includes('.')) {
|
|
266
|
+
return idField;
|
|
267
|
+
}
|
|
268
|
+
const table = String(this.config.table || '')
|
|
269
|
+
.split('.')
|
|
270
|
+
.pop();
|
|
271
|
+
return table ? `${table}.${idField}` : idField;
|
|
272
|
+
}
|
|
232
273
|
// ─── Protected filter helpers ───────────────────────────────────────────────
|
|
233
274
|
//
|
|
234
275
|
// These helpers encode the common WHERE clause patterns used across gateway
|
|
@@ -1198,12 +1239,22 @@ class BaseGateway {
|
|
|
1198
1239
|
const fieldsToUse = !shouldUseCache && Array.isArray(this.config.selectFields) ? this.config.selectFields : this.getIdField();
|
|
1199
1240
|
const { query } = await this.buildListQuery({ filter, params, fieldsToUse, useCache: shouldUseCache });
|
|
1200
1241
|
await this.onListFilter(query, filter);
|
|
1201
|
-
|
|
1242
|
+
const isLimited = !!limit && !isNaN(limit) && limit > 0;
|
|
1243
|
+
if (isLimited) {
|
|
1202
1244
|
query.offset(offset).limit(limit);
|
|
1203
1245
|
}
|
|
1204
1246
|
if (sortBy) {
|
|
1205
1247
|
query.orderBy(sortBy);
|
|
1206
1248
|
}
|
|
1249
|
+
// A limited read ends its order with a unique column, so rows that tie on the sort (one bulk insert's created_at,
|
|
1250
|
+
// a shared order_no or name) come back in the same order on every page: without it Postgres may hand page 2 a row
|
|
1251
|
+
// page 1 already had and never hand over another. Not when the sort already names that column (SQL Server refuses
|
|
1252
|
+
// a column twice in ORDER BY), and not on an unlimited read (it returns every row whatever their order). An empty
|
|
1253
|
+
// sort gets it too — that is exactly the read with no order at all.
|
|
1254
|
+
const tieBreaker = isLimited ? this.getListTieBreaker() : null;
|
|
1255
|
+
if (tieBreaker && !sortNamesColumn(sortBy, tieBreaker)) {
|
|
1256
|
+
query.orderBy(tieBreaker, 'asc');
|
|
1257
|
+
}
|
|
1207
1258
|
const items = await query;
|
|
1208
1259
|
const result = shouldUseCache ? await this.getMany(items.map((row) => row.id)) : items;
|
|
1209
1260
|
return result.map((item) => this.transformOnOut(item));
|
|
@@ -153,6 +153,13 @@ declare class BaseGateway {
|
|
|
153
153
|
* (e.g. a table with a UUID primary key but a separate "slug" as update target).
|
|
154
154
|
*/
|
|
155
155
|
getIdFieldUpdateRemove(): string;
|
|
156
|
+
/**
|
|
157
|
+
* The column `list()` appends as the last sort term when it applies a limit — so tied rows keep one order across
|
|
158
|
+
* pages. `config.listTieBreaker` when set (a string names the column, `false` turns it off → null); otherwise the id
|
|
159
|
+
* field, qualified with the table's OWN name (the last segment of `config.table`, so `SCHEMA.Table` gives `Table.id`)
|
|
160
|
+
* — a list query that joins another table with an `id` stays unambiguous. Override to compute it differently.
|
|
161
|
+
*/
|
|
162
|
+
getListTieBreaker(): string | null;
|
|
156
163
|
/**
|
|
157
164
|
* Applies a whereIn or where-equals filter for scalar or array values.
|
|
158
165
|
*
|
package/build/esm/BaseGateway.js
CHANGED
|
@@ -12,6 +12,24 @@ const DEFAULT_CHUNCK_SIZE = 2500;
|
|
|
12
12
|
* filters must be precise identifiers, not fuzzy searches or time windows.
|
|
13
13
|
*/
|
|
14
14
|
const UPDATE_REMOVE_SUPPORTED_TYPES = new Set(['array', 'eq', 'bool', 'nullableBool']);
|
|
15
|
+
/** `[table, column]` of a column reference, lower-cased; the table is '' when unqualified. */
|
|
16
|
+
const splitColumn = (reference) => {
|
|
17
|
+
const parts = String(reference || '').split('.');
|
|
18
|
+
const column = (parts.pop() || '').toLowerCase();
|
|
19
|
+
const table = (parts.pop() || '').toLowerCase();
|
|
20
|
+
return [table, column];
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Whether a sort already orders by `column` — matched by the column's own name, and by its table when BOTH name one:
|
|
24
|
+
* a bare `id` and `party_appearance.id` are the same column here (a duplicate would be refused by SQL Server).
|
|
25
|
+
*/
|
|
26
|
+
const sortNamesColumn = (sortBy, column) => {
|
|
27
|
+
const [table, name] = splitColumn(column);
|
|
28
|
+
return (sortBy || []).some((item) => {
|
|
29
|
+
const [itemTable, itemName] = splitColumn(String(item?.column ?? ''));
|
|
30
|
+
return itemName === name && (!itemTable || !table || itemTable === table);
|
|
31
|
+
});
|
|
32
|
+
};
|
|
15
33
|
/**
|
|
16
34
|
* BaseGateway is the foundation for all database-backed gateway classes.
|
|
17
35
|
*
|
|
@@ -223,6 +241,29 @@ class BaseGateway {
|
|
|
223
241
|
getIdFieldUpdateRemove() {
|
|
224
242
|
return this.config.idFieldUpdateRemove || this.config.idField || ID_FIELD;
|
|
225
243
|
}
|
|
244
|
+
/**
|
|
245
|
+
* The column `list()` appends as the last sort term when it applies a limit — so tied rows keep one order across
|
|
246
|
+
* pages. `config.listTieBreaker` when set (a string names the column, `false` turns it off → null); otherwise the id
|
|
247
|
+
* field, qualified with the table's OWN name (the last segment of `config.table`, so `SCHEMA.Table` gives `Table.id`)
|
|
248
|
+
* — a list query that joins another table with an `id` stays unambiguous. Override to compute it differently.
|
|
249
|
+
*/
|
|
250
|
+
getListTieBreaker() {
|
|
251
|
+
const configured = this.config.listTieBreaker;
|
|
252
|
+
if (configured === false) {
|
|
253
|
+
return null;
|
|
254
|
+
}
|
|
255
|
+
if (typeof configured === 'string' && configured) {
|
|
256
|
+
return configured;
|
|
257
|
+
}
|
|
258
|
+
const idField = this.getIdField();
|
|
259
|
+
if (idField.includes('.')) {
|
|
260
|
+
return idField;
|
|
261
|
+
}
|
|
262
|
+
const table = String(this.config.table || '')
|
|
263
|
+
.split('.')
|
|
264
|
+
.pop();
|
|
265
|
+
return table ? `${table}.${idField}` : idField;
|
|
266
|
+
}
|
|
226
267
|
// ─── Protected filter helpers ───────────────────────────────────────────────
|
|
227
268
|
//
|
|
228
269
|
// These helpers encode the common WHERE clause patterns used across gateway
|
|
@@ -1192,12 +1233,22 @@ class BaseGateway {
|
|
|
1192
1233
|
const fieldsToUse = !shouldUseCache && Array.isArray(this.config.selectFields) ? this.config.selectFields : this.getIdField();
|
|
1193
1234
|
const { query } = await this.buildListQuery({ filter, params, fieldsToUse, useCache: shouldUseCache });
|
|
1194
1235
|
await this.onListFilter(query, filter);
|
|
1195
|
-
|
|
1236
|
+
const isLimited = !!limit && !isNaN(limit) && limit > 0;
|
|
1237
|
+
if (isLimited) {
|
|
1196
1238
|
query.offset(offset).limit(limit);
|
|
1197
1239
|
}
|
|
1198
1240
|
if (sortBy) {
|
|
1199
1241
|
query.orderBy(sortBy);
|
|
1200
1242
|
}
|
|
1243
|
+
// A limited read ends its order with a unique column, so rows that tie on the sort (one bulk insert's created_at,
|
|
1244
|
+
// a shared order_no or name) come back in the same order on every page: without it Postgres may hand page 2 a row
|
|
1245
|
+
// page 1 already had and never hand over another. Not when the sort already names that column (SQL Server refuses
|
|
1246
|
+
// a column twice in ORDER BY), and not on an unlimited read (it returns every row whatever their order). An empty
|
|
1247
|
+
// sort gets it too — that is exactly the read with no order at all.
|
|
1248
|
+
const tieBreaker = isLimited ? this.getListTieBreaker() : null;
|
|
1249
|
+
if (tieBreaker && !sortNamesColumn(sortBy, tieBreaker)) {
|
|
1250
|
+
query.orderBy(tieBreaker, 'asc');
|
|
1251
|
+
}
|
|
1201
1252
|
const items = await query;
|
|
1202
1253
|
const result = shouldUseCache ? await this.getMany(items.map((row) => row.id)) : items;
|
|
1203
1254
|
return result.map((item) => this.transformOnOut(item));
|
|
@@ -74,6 +74,17 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
74
74
|
*/
|
|
75
75
|
localizationForField?: string;
|
|
76
76
|
defaultSorting?: SortItemInterface[];
|
|
77
|
+
/**
|
|
78
|
+
* The column `list()` adds as the LAST sort term whenever it applies a limit, so rows that tie on the caller's sort
|
|
79
|
+
* come back in the same order on every page. Defaults to the id field, qualified with the table's own name
|
|
80
|
+
* (`getListTieBreaker()`). `false` turns it off — for a list query it would break (one that groups, selects
|
|
81
|
+
* DISTINCT, or reads the table under an alias). A string names a different unique column.
|
|
82
|
+
*
|
|
83
|
+
* ⚠ Without it, Postgres does not promise the same order of tied rows from one LIMIT/OFFSET to the next: page 2 can
|
|
84
|
+
* repeat a row from page 1 and skip another for good — rows created together (one bulk insert = one created_at) or a
|
|
85
|
+
* shared `order_no` / name tie all the time. (SQL Server also refuses OFFSET/FETCH — page 2 — with no ORDER BY.)
|
|
86
|
+
*/
|
|
87
|
+
listTieBreaker?: string | false;
|
|
77
88
|
/**
|
|
78
89
|
* Field to apply keyword (ILIKE) search against when filterParams.keyword is set.
|
|
79
90
|
*/
|
|
@@ -74,6 +74,17 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
74
74
|
*/
|
|
75
75
|
localizationForField?: string;
|
|
76
76
|
defaultSorting?: SortItemInterface[];
|
|
77
|
+
/**
|
|
78
|
+
* The column `list()` adds as the LAST sort term whenever it applies a limit, so rows that tie on the caller's sort
|
|
79
|
+
* come back in the same order on every page. Defaults to the id field, qualified with the table's own name
|
|
80
|
+
* (`getListTieBreaker()`). `false` turns it off — for a list query it would break (one that groups, selects
|
|
81
|
+
* DISTINCT, or reads the table under an alias). A string names a different unique column.
|
|
82
|
+
*
|
|
83
|
+
* ⚠ Without it, Postgres does not promise the same order of tied rows from one LIMIT/OFFSET to the next: page 2 can
|
|
84
|
+
* repeat a row from page 1 and skip another for good — rows created together (one bulk insert = one created_at) or a
|
|
85
|
+
* shared `order_no` / name tie all the time. (SQL Server also refuses OFFSET/FETCH — page 2 — with no ORDER BY.)
|
|
86
|
+
*/
|
|
87
|
+
listTieBreaker?: string | false;
|
|
77
88
|
/**
|
|
78
89
|
* Field to apply keyword (ILIKE) search against when filterParams.keyword is set.
|
|
79
90
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sdflc/backend-helpers",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.143",
|
|
4
4
|
"description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"exports": {
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"lint": "ESLINT_USE_FLAT_CONFIG=true eslint .",
|
|
21
21
|
"test": "echo No Tests Available Yet",
|
|
22
22
|
"testToDo": "jest --config jest.config.ts",
|
|
23
|
-
"prove": "node scripts/proveCreateId.cjs && node scripts/proveGateways.cjs && node scripts/proveEmergencyAlerter.cjs",
|
|
23
|
+
"prove": "node scripts/proveCreateId.cjs && node scripts/proveGateways.cjs && node scripts/proveEmergencyAlerter.cjs && node scripts/proveListOrder.cjs",
|
|
24
24
|
"format": "prettier --write \"src/**/*.ts\"",
|
|
25
25
|
"prepare": "husky",
|
|
26
26
|
"prepare1": "husky install",
|