@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.
@@ -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
  *
@@ -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
- if (limit && !isNaN(limit) && limit > 0) {
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
  *
@@ -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
- if (limit && !isNaN(limit) && limit > 0) {
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.142",
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",