@sdflc/backend-helpers 1.0.137 → 1.0.138

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.
@@ -535,6 +535,25 @@ declare class BaseGateway {
535
535
  * must be handled in the loader's priming logic or in the calling code.
536
536
  */
537
537
  protected transformOnOut(item: any): any;
538
+ /**
539
+ * Drop the given ids from the loader cache after a write.
540
+ *
541
+ * ⚠ AWAITED on purpose. `LoaderInterface.clear()` is declared sync + chainable, so it cannot
542
+ * report when the SHARED (Redis) copy is actually gone — it only starts the DELETE. On a single
543
+ * instance that is invisible; on several instances behind one Redis it is a window in which
544
+ * another instance answers a read with the value this write just replaced. Loaders that expose
545
+ * `clearAsync` (DataCache does) are awaited; anything implementing only the plain interface keeps
546
+ * the old fire-and-forget behaviour, so custom loaders are unaffected.
547
+ *
548
+ * The LOCAL copy is dropped synchronously by the loader either way, so a read later in THIS
549
+ * request is already correct before this resolves.
550
+ *
551
+ * PUBLIC on purpose: a gateway that writes ANOTHER table's rows in bulk (a cascade detach, say)
552
+ * cannot invalidate that table's cache itself — the entries belong to the gateway that owns the
553
+ * table. It reaches the right loader with `getGateways().thatGw.invalidate(ids)`, which is a
554
+ * supported call rather than a reach into another object's internals.
555
+ */
556
+ invalidate(ids: any[]): Promise<void>;
538
557
  /**
539
558
  * Loads a single record by id via the loader (DataCache/DataLoader).
540
559
  * Leverages DataLoader batching — multiple `get()` calls within the same
@@ -1093,6 +1093,35 @@ class BaseGateway {
1093
1093
  return item;
1094
1094
  }
1095
1095
  // ─── Loader operations ─────────────────────────────────────────────────────
1096
+ /**
1097
+ * Drop the given ids from the loader cache after a write.
1098
+ *
1099
+ * ⚠ AWAITED on purpose. `LoaderInterface.clear()` is declared sync + chainable, so it cannot
1100
+ * report when the SHARED (Redis) copy is actually gone — it only starts the DELETE. On a single
1101
+ * instance that is invisible; on several instances behind one Redis it is a window in which
1102
+ * another instance answers a read with the value this write just replaced. Loaders that expose
1103
+ * `clearAsync` (DataCache does) are awaited; anything implementing only the plain interface keeps
1104
+ * the old fire-and-forget behaviour, so custom loaders are unaffected.
1105
+ *
1106
+ * The LOCAL copy is dropped synchronously by the loader either way, so a read later in THIS
1107
+ * request is already correct before this resolves.
1108
+ *
1109
+ * PUBLIC on purpose: a gateway that writes ANOTHER table's rows in bulk (a cascade detach, say)
1110
+ * cannot invalidate that table's cache itself — the entries belong to the gateway that owns the
1111
+ * table. It reaches the right loader with `getGateways().thatGw.invalidate(ids)`, which is a
1112
+ * supported call rather than a reach into another object's internals.
1113
+ */
1114
+ async invalidate(ids) {
1115
+ if (!Array.isArray(ids) || ids.length === 0) {
1116
+ return;
1117
+ }
1118
+ const loader = this.loader;
1119
+ if (typeof loader?.clearAsync === 'function') {
1120
+ await loader.clearAsync(ids);
1121
+ return;
1122
+ }
1123
+ loader?.clear(ids);
1124
+ }
1096
1125
  /**
1097
1126
  * Loads a single record by id via the loader (DataCache/DataLoader).
1098
1127
  * Leverages DataLoader batching — multiple `get()` calls within the same
@@ -1245,11 +1274,7 @@ class BaseGateway {
1245
1274
  const items = await query;
1246
1275
  if (items.length > 0 && this.config.noCache !== true) {
1247
1276
  const idName = this.getIdFieldUpdateRemove();
1248
- items.forEach((item) => {
1249
- if (item[idName]) {
1250
- this.loader.clear(item[idName]);
1251
- }
1252
- });
1277
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1253
1278
  }
1254
1279
  return items.map((item) => this.transformOnOut(item));
1255
1280
  }
@@ -1331,11 +1356,7 @@ class BaseGateway {
1331
1356
  const items = await query;
1332
1357
  if (items.length > 0 && this.config.noCache !== true) {
1333
1358
  const idName = this.getIdFieldUpdateRemove();
1334
- items.forEach((item) => {
1335
- if (item[idName]) {
1336
- this.loader.clear(item[idName]);
1337
- }
1338
- });
1359
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1339
1360
  }
1340
1361
  return items.map((item) => this.transformOnOut(item));
1341
1362
  }
@@ -1362,11 +1383,7 @@ class BaseGateway {
1362
1383
  const items = await query;
1363
1384
  if (items.length > 0 && this.config.noCache !== true) {
1364
1385
  const idName = this.getIdFieldUpdateRemove();
1365
- items.forEach((item) => {
1366
- if (item[idName]) {
1367
- this.loader.clear(item[idName]);
1368
- }
1369
- });
1386
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1370
1387
  }
1371
1388
  return items.map((item) => this.transformOnOut(item));
1372
1389
  }
@@ -1474,11 +1491,7 @@ class BaseGateway {
1474
1491
  const items = await query;
1475
1492
  if (items.length > 0 && this.config.noCache !== true) {
1476
1493
  const idName = this.getIdFieldUpdateRemove();
1477
- items.forEach((item) => {
1478
- if (item[idName]) {
1479
- this.loader.clear(item[idName]);
1480
- }
1481
- });
1494
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1482
1495
  }
1483
1496
  return items.map((item) => this.transformOnOut(item));
1484
1497
  }
@@ -115,6 +115,17 @@ declare class DataCache implements LoaderInterface {
115
115
  * @param key A single record id or an array of record ids
116
116
  */
117
117
  clear(key: any | any[]): this;
118
+ /**
119
+ * The awaitable form of `clear()` — resolves once the SHARED (Redis) copy is gone, not merely
120
+ * once the local one is.
121
+ *
122
+ * ⚠ Why it matters on more than one server: `clear()` cannot be awaited without breaking
123
+ * `LoaderInterface`, so the Redis DELETE it starts is still in flight when the caller moves on.
124
+ * Another instance reading the same row inside that window is served the pre-write value from the
125
+ * shared cache. The local copy is dropped synchronously either way (see `RedisDataLoader.clear`),
126
+ * so this only closes the CROSS-INSTANCE race — which is the one that does not go away on its own.
127
+ */
128
+ clearAsync(key: any | any[]): Promise<void>;
118
129
  /**
119
130
  * Clears all cached values from the loader.
120
131
  * Rarely needed in normal operation — useful in tests or when a bulk
@@ -148,6 +148,12 @@ class DataCache {
148
148
  }, {
149
149
  cache: true,
150
150
  expire: this.config.cacheTtl,
151
+ // ⚠ Never seed the SHARED cache from inside a transaction — the rows read there may be the
152
+ // caller's own un-committed writes, and a rollback would leave a state that never existed
153
+ // being served to every instance until the TTL expired. See the batch loader in
154
+ // RedisDataLoader for the full reasoning. Falls back to "not in a transaction" for any db
155
+ // that does not expose `getTransaction`, which preserves the previous behaviour exactly.
156
+ skipWrite: () => !!this.config?.db?.getTransaction?.(),
151
157
  });
152
158
  }
153
159
  else {
@@ -212,14 +218,27 @@ class DataCache {
212
218
  * @param key A single record id or an array of record ids
213
219
  */
214
220
  clear(key) {
215
- if (Array.isArray(key)) {
216
- key.forEach((item) => this.loader?.clear(this.buildKey(item)));
217
- }
218
- else {
219
- this.loader?.clear(this.buildKey(key));
220
- }
221
+ // ⚠ Fire-and-forget by contract (`LoaderInterface.clear` is sync + chainable), but the backing
222
+ // loader may be Redis-backed and return a promise. Swallowing it silently would turn a failed
223
+ // DEL into an unhandled rejection that can take the process down, so it is caught here — and
224
+ // `clearAsync` exists for callers that can wait for the shared copy to actually be gone.
225
+ void this.clearAsync(key).catch(() => undefined);
221
226
  return this;
222
227
  }
228
+ /**
229
+ * The awaitable form of `clear()` — resolves once the SHARED (Redis) copy is gone, not merely
230
+ * once the local one is.
231
+ *
232
+ * ⚠ Why it matters on more than one server: `clear()` cannot be awaited without breaking
233
+ * `LoaderInterface`, so the Redis DELETE it starts is still in flight when the caller moves on.
234
+ * Another instance reading the same row inside that window is served the pre-write value from the
235
+ * shared cache. The local copy is dropped synchronously either way (see `RedisDataLoader.clear`),
236
+ * so this only closes the CROSS-INSTANCE race — which is the one that does not go away on its own.
237
+ */
238
+ async clearAsync(key) {
239
+ const keys = Array.isArray(key) ? key : [key];
240
+ await Promise.all(keys.map((item) => this.loader?.clear(this.buildKey(item))));
241
+ }
223
242
  /**
224
243
  * Clears all cached values from the loader.
225
244
  * Rarely needed in normal operation — useful in tests or when a bulk
@@ -141,8 +141,11 @@ declare class RedisDataLoader {
141
141
  /**
142
142
  * Removes a key from Redis and clears it from the DataLoader in-memory cache.
143
143
  *
144
- * Fix: was using raw `key` in `this.loader.clear()` — now uses `makeKey(key)`
145
- * to match the key format used internally by `load()`.
144
+ * ⚠ The LOCAL clear happens FIRST and synchronously, before the Redis round-trip is awaited.
145
+ * Callers are not required to await this method (`LoaderInterface.clear` is declared sync and
146
+ * chainable, and BaseGateway calls it that way), so anything done after the `await` below would
147
+ * not have happened yet when the caller's next `load()` runs — which is precisely how a write
148
+ * could still be followed by a stale read in the same tick.
146
149
  *
147
150
  * @param key Cache key
148
151
  */
@@ -157,7 +160,7 @@ declare class RedisDataLoader {
157
160
  * Clears a single key from the DataLoader in-memory cache only.
158
161
  * Does NOT delete from Redis.
159
162
  *
160
- * @param key Cache key (will have makeKey applied)
163
+ * @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
161
164
  */
162
165
  clearLocal(key: any): Promise<void>;
163
166
  }
@@ -11,7 +11,7 @@ const json_stable_stringify_1 = __importDefault(require("json-stable-stringify")
11
11
  /**
12
12
  * Options specific to RedisDataLoader — not passed through to DataLoader.
13
13
  */
14
- const customOptions = ['expire', 'serialize', 'deserialize', 'cacheKeyFn'];
14
+ const customOptions = ['expire', 'serialize', 'deserialize', 'cacheKeyFn', 'skipWrite'];
15
15
  /**
16
16
  * Convenience wrapper around Promise.all + Array.map.
17
17
  * Resolves an array of promises returned by `fn` applied to each item.
@@ -51,17 +51,19 @@ class RedisDataLoader {
51
51
  constructor(redisClient, keySpace, userLoader, opt) {
52
52
  this.redisClient = redisClient;
53
53
  this.opt = (0, lodash_1.pick)(opt, customOptions) || {};
54
- this.dataLoaderOpt = {
55
- ...(0, lodash_1.omit)(opt, customOptions),
56
- cacheKeyFn: this.opt.cacheKeyFn,
57
- };
58
54
  // Default cache key function: stringify objects for stable key generation,
59
- // pass primitive keys through as-is
55
+ // pass primitive keys through as-is.
56
+ // ⚠ Assigned BEFORE `dataLoaderOpt` is built. It used to be assigned after, so the object
57
+ // below captured `undefined` and a caller-supplied `cacheKeyFn` was silently dropped.
60
58
  this.opt.cacheKeyFn =
61
59
  typeof this.opt.cacheKeyFn === 'function'
62
60
  ? this.opt.cacheKeyFn
63
61
  : (key) => ((0, lodash_1.isObject)(key) ? (0, json_stable_stringify_1.default)(key) : key);
64
62
  this.keySpace = keySpace ? `${keySpace}:` : '';
63
+ this.dataLoaderOpt = {
64
+ ...(0, lodash_1.omit)(opt, customOptions),
65
+ cacheKeyFn: this.opt.cacheKeyFn,
66
+ };
65
67
  this.loader = new dataloader_1.default(async (keys) => {
66
68
  const results = await this.rMGet(keys);
67
69
  const keysToRead = [];
@@ -75,7 +77,23 @@ class RedisDataLoader {
75
77
  });
76
78
  if (keysToRead.length > 0) {
77
79
  const loadedData = await userLoader.load(keysToRead);
78
- const data = await this.rMSetAndGet(keysToRead, loadedData);
80
+ // ⚠ DO NOT PUBLISH UNCOMMITTED ROWS TO A SHARED CACHE.
81
+ //
82
+ // When the caller has a transaction open, the rows just read came through that transaction —
83
+ // so they may include its own un-committed writes. Storing them in Redis would hand that
84
+ // state to every other instance, and a ROLLBACK would leave a row state that never existed
85
+ // being served cluster-wide until its TTL ran out. Whoever opened the transaction decides,
86
+ // via `skipWrite` (DataCache asks its Database whether a transaction is active).
87
+ //
88
+ // Reads are still served from Redis in that case — those are committed values, and skipping
89
+ // only the WRITE keeps the transaction's own view correct without leaking it. The results are
90
+ // put through the same serialize/deserialize round-trip the cache would have applied, so a
91
+ // caller cannot tell the two paths apart by the shape of what comes back (Date columns become
92
+ // ISO strings either way).
93
+ const skipWrite = typeof this.opt.skipWrite === 'function' && this.opt.skipWrite();
94
+ const data = skipWrite
95
+ ? await mapPromise(loadedData, async (value) => this.parse(await this.toString(value)))
96
+ : await this.rMSetAndGet(keysToRead, loadedData);
79
97
  // Merge loaded data back into the results array at the correct positions
80
98
  keysIdxsToRead.forEach((keyIdx, idx) => {
81
99
  results[keyIdx] = data[idx];
@@ -298,16 +316,18 @@ class RedisDataLoader {
298
316
  throw new TypeError(RedisDataLoader.messages.valueRequired);
299
317
  }
300
318
  const result = await this.rSetAndGet(key, value);
301
- const fullKey = this.makeKey(key);
302
- // Fix: was using raw key in DataLoader cache — must use fullKey to match
303
- // the key format that load() uses internally
304
- return this.loader.clear(fullKey).prime(fullKey, result === '' ? null : result);
319
+ // ⚠ RAW key — same rule as `clear()`. DataLoader applies `cacheKeyFn` itself, so priming under
320
+ // `makeKey(key)` would seed an entry `load()` can never find and leave the real one untouched.
321
+ return this.loader.clear(key).prime(key, result === '' ? null : result);
305
322
  }
306
323
  /**
307
324
  * Removes a key from Redis and clears it from the DataLoader in-memory cache.
308
325
  *
309
- * Fix: was using raw `key` in `this.loader.clear()` — now uses `makeKey(key)`
310
- * to match the key format used internally by `load()`.
326
+ * ⚠ The LOCAL clear happens FIRST and synchronously, before the Redis round-trip is awaited.
327
+ * Callers are not required to await this method (`LoaderInterface.clear` is declared sync and
328
+ * chainable, and BaseGateway calls it that way), so anything done after the `await` below would
329
+ * not have happened yet when the caller's next `load()` runs — which is precisely how a write
330
+ * could still be followed by a stale read in the same tick.
311
331
  *
312
332
  * @param key Cache key
313
333
  */
@@ -315,10 +335,13 @@ class RedisDataLoader {
315
335
  if (key == null) {
316
336
  throw new TypeError(RedisDataLoader.messages.keyRequired);
317
337
  }
318
- const resp = await this.rDel(key);
319
- // Fix: was using raw key — must use fullKey to match load() key format
320
- this.loader.clear(this.makeKey(key));
321
- return resp;
338
+ // ⚠ RAW key, never `makeKey(key)`. DataLoader applies `cacheKeyFn` internally on EVERY public
339
+ // method — load, clear and prime alike — so handing it an already-prefixed key makes it look for
340
+ // `<space>:<space>:id`, which nothing ever created. `load()` passes the raw key, so this must
341
+ // too. Passing the prefixed key here is the defect this method shipped with: the Redis copy went,
342
+ // the in-memory copy stayed, and every later `get()` in that process returned the pre-write row.
343
+ this.loader.clear(key);
344
+ return this.rDel(key);
322
345
  }
323
346
  /**
324
347
  * Clears all entries from the DataLoader in-memory cache.
@@ -332,10 +355,10 @@ class RedisDataLoader {
332
355
  * Clears a single key from the DataLoader in-memory cache only.
333
356
  * Does NOT delete from Redis.
334
357
  *
335
- * @param key Cache key (will have makeKey applied)
358
+ * @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
336
359
  */
337
360
  async clearLocal(key) {
338
- return this.loader.clear(this.makeKey(key));
361
+ return this.loader.clear(key);
339
362
  }
340
363
  }
341
364
  exports.RedisDataLoader = RedisDataLoader;
@@ -535,6 +535,25 @@ declare class BaseGateway {
535
535
  * must be handled in the loader's priming logic or in the calling code.
536
536
  */
537
537
  protected transformOnOut(item: any): any;
538
+ /**
539
+ * Drop the given ids from the loader cache after a write.
540
+ *
541
+ * ⚠ AWAITED on purpose. `LoaderInterface.clear()` is declared sync + chainable, so it cannot
542
+ * report when the SHARED (Redis) copy is actually gone — it only starts the DELETE. On a single
543
+ * instance that is invisible; on several instances behind one Redis it is a window in which
544
+ * another instance answers a read with the value this write just replaced. Loaders that expose
545
+ * `clearAsync` (DataCache does) are awaited; anything implementing only the plain interface keeps
546
+ * the old fire-and-forget behaviour, so custom loaders are unaffected.
547
+ *
548
+ * The LOCAL copy is dropped synchronously by the loader either way, so a read later in THIS
549
+ * request is already correct before this resolves.
550
+ *
551
+ * PUBLIC on purpose: a gateway that writes ANOTHER table's rows in bulk (a cascade detach, say)
552
+ * cannot invalidate that table's cache itself — the entries belong to the gateway that owns the
553
+ * table. It reaches the right loader with `getGateways().thatGw.invalidate(ids)`, which is a
554
+ * supported call rather than a reach into another object's internals.
555
+ */
556
+ invalidate(ids: any[]): Promise<void>;
538
557
  /**
539
558
  * Loads a single record by id via the loader (DataCache/DataLoader).
540
559
  * Leverages DataLoader batching — multiple `get()` calls within the same
@@ -1087,6 +1087,35 @@ class BaseGateway {
1087
1087
  return item;
1088
1088
  }
1089
1089
  // ─── Loader operations ─────────────────────────────────────────────────────
1090
+ /**
1091
+ * Drop the given ids from the loader cache after a write.
1092
+ *
1093
+ * ⚠ AWAITED on purpose. `LoaderInterface.clear()` is declared sync + chainable, so it cannot
1094
+ * report when the SHARED (Redis) copy is actually gone — it only starts the DELETE. On a single
1095
+ * instance that is invisible; on several instances behind one Redis it is a window in which
1096
+ * another instance answers a read with the value this write just replaced. Loaders that expose
1097
+ * `clearAsync` (DataCache does) are awaited; anything implementing only the plain interface keeps
1098
+ * the old fire-and-forget behaviour, so custom loaders are unaffected.
1099
+ *
1100
+ * The LOCAL copy is dropped synchronously by the loader either way, so a read later in THIS
1101
+ * request is already correct before this resolves.
1102
+ *
1103
+ * PUBLIC on purpose: a gateway that writes ANOTHER table's rows in bulk (a cascade detach, say)
1104
+ * cannot invalidate that table's cache itself — the entries belong to the gateway that owns the
1105
+ * table. It reaches the right loader with `getGateways().thatGw.invalidate(ids)`, which is a
1106
+ * supported call rather than a reach into another object's internals.
1107
+ */
1108
+ async invalidate(ids) {
1109
+ if (!Array.isArray(ids) || ids.length === 0) {
1110
+ return;
1111
+ }
1112
+ const loader = this.loader;
1113
+ if (typeof loader?.clearAsync === 'function') {
1114
+ await loader.clearAsync(ids);
1115
+ return;
1116
+ }
1117
+ loader?.clear(ids);
1118
+ }
1090
1119
  /**
1091
1120
  * Loads a single record by id via the loader (DataCache/DataLoader).
1092
1121
  * Leverages DataLoader batching — multiple `get()` calls within the same
@@ -1239,11 +1268,7 @@ class BaseGateway {
1239
1268
  const items = await query;
1240
1269
  if (items.length > 0 && this.config.noCache !== true) {
1241
1270
  const idName = this.getIdFieldUpdateRemove();
1242
- items.forEach((item) => {
1243
- if (item[idName]) {
1244
- this.loader.clear(item[idName]);
1245
- }
1246
- });
1271
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1247
1272
  }
1248
1273
  return items.map((item) => this.transformOnOut(item));
1249
1274
  }
@@ -1325,11 +1350,7 @@ class BaseGateway {
1325
1350
  const items = await query;
1326
1351
  if (items.length > 0 && this.config.noCache !== true) {
1327
1352
  const idName = this.getIdFieldUpdateRemove();
1328
- items.forEach((item) => {
1329
- if (item[idName]) {
1330
- this.loader.clear(item[idName]);
1331
- }
1332
- });
1353
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1333
1354
  }
1334
1355
  return items.map((item) => this.transformOnOut(item));
1335
1356
  }
@@ -1356,11 +1377,7 @@ class BaseGateway {
1356
1377
  const items = await query;
1357
1378
  if (items.length > 0 && this.config.noCache !== true) {
1358
1379
  const idName = this.getIdFieldUpdateRemove();
1359
- items.forEach((item) => {
1360
- if (item[idName]) {
1361
- this.loader.clear(item[idName]);
1362
- }
1363
- });
1380
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1364
1381
  }
1365
1382
  return items.map((item) => this.transformOnOut(item));
1366
1383
  }
@@ -1468,11 +1485,7 @@ class BaseGateway {
1468
1485
  const items = await query;
1469
1486
  if (items.length > 0 && this.config.noCache !== true) {
1470
1487
  const idName = this.getIdFieldUpdateRemove();
1471
- items.forEach((item) => {
1472
- if (item[idName]) {
1473
- this.loader.clear(item[idName]);
1474
- }
1475
- });
1488
+ await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
1476
1489
  }
1477
1490
  return items.map((item) => this.transformOnOut(item));
1478
1491
  }
@@ -115,6 +115,17 @@ declare class DataCache implements LoaderInterface {
115
115
  * @param key A single record id or an array of record ids
116
116
  */
117
117
  clear(key: any | any[]): this;
118
+ /**
119
+ * The awaitable form of `clear()` — resolves once the SHARED (Redis) copy is gone, not merely
120
+ * once the local one is.
121
+ *
122
+ * ⚠ Why it matters on more than one server: `clear()` cannot be awaited without breaking
123
+ * `LoaderInterface`, so the Redis DELETE it starts is still in flight when the caller moves on.
124
+ * Another instance reading the same row inside that window is served the pre-write value from the
125
+ * shared cache. The local copy is dropped synchronously either way (see `RedisDataLoader.clear`),
126
+ * so this only closes the CROSS-INSTANCE race — which is the one that does not go away on its own.
127
+ */
128
+ clearAsync(key: any | any[]): Promise<void>;
118
129
  /**
119
130
  * Clears all cached values from the loader.
120
131
  * Rarely needed in normal operation — useful in tests or when a bulk
@@ -142,6 +142,12 @@ class DataCache {
142
142
  }, {
143
143
  cache: true,
144
144
  expire: this.config.cacheTtl,
145
+ // ⚠ Never seed the SHARED cache from inside a transaction — the rows read there may be the
146
+ // caller's own un-committed writes, and a rollback would leave a state that never existed
147
+ // being served to every instance until the TTL expired. See the batch loader in
148
+ // RedisDataLoader for the full reasoning. Falls back to "not in a transaction" for any db
149
+ // that does not expose `getTransaction`, which preserves the previous behaviour exactly.
150
+ skipWrite: () => !!this.config?.db?.getTransaction?.(),
145
151
  });
146
152
  }
147
153
  else {
@@ -206,14 +212,27 @@ class DataCache {
206
212
  * @param key A single record id or an array of record ids
207
213
  */
208
214
  clear(key) {
209
- if (Array.isArray(key)) {
210
- key.forEach((item) => this.loader?.clear(this.buildKey(item)));
211
- }
212
- else {
213
- this.loader?.clear(this.buildKey(key));
214
- }
215
+ // ⚠ Fire-and-forget by contract (`LoaderInterface.clear` is sync + chainable), but the backing
216
+ // loader may be Redis-backed and return a promise. Swallowing it silently would turn a failed
217
+ // DEL into an unhandled rejection that can take the process down, so it is caught here — and
218
+ // `clearAsync` exists for callers that can wait for the shared copy to actually be gone.
219
+ void this.clearAsync(key).catch(() => undefined);
215
220
  return this;
216
221
  }
222
+ /**
223
+ * The awaitable form of `clear()` — resolves once the SHARED (Redis) copy is gone, not merely
224
+ * once the local one is.
225
+ *
226
+ * ⚠ Why it matters on more than one server: `clear()` cannot be awaited without breaking
227
+ * `LoaderInterface`, so the Redis DELETE it starts is still in flight when the caller moves on.
228
+ * Another instance reading the same row inside that window is served the pre-write value from the
229
+ * shared cache. The local copy is dropped synchronously either way (see `RedisDataLoader.clear`),
230
+ * so this only closes the CROSS-INSTANCE race — which is the one that does not go away on its own.
231
+ */
232
+ async clearAsync(key) {
233
+ const keys = Array.isArray(key) ? key : [key];
234
+ await Promise.all(keys.map((item) => this.loader?.clear(this.buildKey(item))));
235
+ }
217
236
  /**
218
237
  * Clears all cached values from the loader.
219
238
  * Rarely needed in normal operation — useful in tests or when a bulk
@@ -141,8 +141,11 @@ declare class RedisDataLoader {
141
141
  /**
142
142
  * Removes a key from Redis and clears it from the DataLoader in-memory cache.
143
143
  *
144
- * Fix: was using raw `key` in `this.loader.clear()` — now uses `makeKey(key)`
145
- * to match the key format used internally by `load()`.
144
+ * ⚠ The LOCAL clear happens FIRST and synchronously, before the Redis round-trip is awaited.
145
+ * Callers are not required to await this method (`LoaderInterface.clear` is declared sync and
146
+ * chainable, and BaseGateway calls it that way), so anything done after the `await` below would
147
+ * not have happened yet when the caller's next `load()` runs — which is precisely how a write
148
+ * could still be followed by a stale read in the same tick.
146
149
  *
147
150
  * @param key Cache key
148
151
  */
@@ -157,7 +160,7 @@ declare class RedisDataLoader {
157
160
  * Clears a single key from the DataLoader in-memory cache only.
158
161
  * Does NOT delete from Redis.
159
162
  *
160
- * @param key Cache key (will have makeKey applied)
163
+ * @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
161
164
  */
162
165
  clearLocal(key: any): Promise<void>;
163
166
  }
@@ -5,7 +5,7 @@ import stringify from 'json-stable-stringify';
5
5
  /**
6
6
  * Options specific to RedisDataLoader — not passed through to DataLoader.
7
7
  */
8
- const customOptions = ['expire', 'serialize', 'deserialize', 'cacheKeyFn'];
8
+ const customOptions = ['expire', 'serialize', 'deserialize', 'cacheKeyFn', 'skipWrite'];
9
9
  /**
10
10
  * Convenience wrapper around Promise.all + Array.map.
11
11
  * Resolves an array of promises returned by `fn` applied to each item.
@@ -45,17 +45,19 @@ class RedisDataLoader {
45
45
  constructor(redisClient, keySpace, userLoader, opt) {
46
46
  this.redisClient = redisClient;
47
47
  this.opt = pick(opt, customOptions) || {};
48
- this.dataLoaderOpt = {
49
- ...omit(opt, customOptions),
50
- cacheKeyFn: this.opt.cacheKeyFn,
51
- };
52
48
  // Default cache key function: stringify objects for stable key generation,
53
- // pass primitive keys through as-is
49
+ // pass primitive keys through as-is.
50
+ // ⚠ Assigned BEFORE `dataLoaderOpt` is built. It used to be assigned after, so the object
51
+ // below captured `undefined` and a caller-supplied `cacheKeyFn` was silently dropped.
54
52
  this.opt.cacheKeyFn =
55
53
  typeof this.opt.cacheKeyFn === 'function'
56
54
  ? this.opt.cacheKeyFn
57
55
  : (key) => (isObject(key) ? stringify(key) : key);
58
56
  this.keySpace = keySpace ? `${keySpace}:` : '';
57
+ this.dataLoaderOpt = {
58
+ ...omit(opt, customOptions),
59
+ cacheKeyFn: this.opt.cacheKeyFn,
60
+ };
59
61
  this.loader = new DataLoader(async (keys) => {
60
62
  const results = await this.rMGet(keys);
61
63
  const keysToRead = [];
@@ -69,7 +71,23 @@ class RedisDataLoader {
69
71
  });
70
72
  if (keysToRead.length > 0) {
71
73
  const loadedData = await userLoader.load(keysToRead);
72
- const data = await this.rMSetAndGet(keysToRead, loadedData);
74
+ // ⚠ DO NOT PUBLISH UNCOMMITTED ROWS TO A SHARED CACHE.
75
+ //
76
+ // When the caller has a transaction open, the rows just read came through that transaction —
77
+ // so they may include its own un-committed writes. Storing them in Redis would hand that
78
+ // state to every other instance, and a ROLLBACK would leave a row state that never existed
79
+ // being served cluster-wide until its TTL ran out. Whoever opened the transaction decides,
80
+ // via `skipWrite` (DataCache asks its Database whether a transaction is active).
81
+ //
82
+ // Reads are still served from Redis in that case — those are committed values, and skipping
83
+ // only the WRITE keeps the transaction's own view correct without leaking it. The results are
84
+ // put through the same serialize/deserialize round-trip the cache would have applied, so a
85
+ // caller cannot tell the two paths apart by the shape of what comes back (Date columns become
86
+ // ISO strings either way).
87
+ const skipWrite = typeof this.opt.skipWrite === 'function' && this.opt.skipWrite();
88
+ const data = skipWrite
89
+ ? await mapPromise(loadedData, async (value) => this.parse(await this.toString(value)))
90
+ : await this.rMSetAndGet(keysToRead, loadedData);
73
91
  // Merge loaded data back into the results array at the correct positions
74
92
  keysIdxsToRead.forEach((keyIdx, idx) => {
75
93
  results[keyIdx] = data[idx];
@@ -292,16 +310,18 @@ class RedisDataLoader {
292
310
  throw new TypeError(RedisDataLoader.messages.valueRequired);
293
311
  }
294
312
  const result = await this.rSetAndGet(key, value);
295
- const fullKey = this.makeKey(key);
296
- // Fix: was using raw key in DataLoader cache — must use fullKey to match
297
- // the key format that load() uses internally
298
- return this.loader.clear(fullKey).prime(fullKey, result === '' ? null : result);
313
+ // ⚠ RAW key — same rule as `clear()`. DataLoader applies `cacheKeyFn` itself, so priming under
314
+ // `makeKey(key)` would seed an entry `load()` can never find and leave the real one untouched.
315
+ return this.loader.clear(key).prime(key, result === '' ? null : result);
299
316
  }
300
317
  /**
301
318
  * Removes a key from Redis and clears it from the DataLoader in-memory cache.
302
319
  *
303
- * Fix: was using raw `key` in `this.loader.clear()` — now uses `makeKey(key)`
304
- * to match the key format used internally by `load()`.
320
+ * ⚠ The LOCAL clear happens FIRST and synchronously, before the Redis round-trip is awaited.
321
+ * Callers are not required to await this method (`LoaderInterface.clear` is declared sync and
322
+ * chainable, and BaseGateway calls it that way), so anything done after the `await` below would
323
+ * not have happened yet when the caller's next `load()` runs — which is precisely how a write
324
+ * could still be followed by a stale read in the same tick.
305
325
  *
306
326
  * @param key Cache key
307
327
  */
@@ -309,10 +329,13 @@ class RedisDataLoader {
309
329
  if (key == null) {
310
330
  throw new TypeError(RedisDataLoader.messages.keyRequired);
311
331
  }
312
- const resp = await this.rDel(key);
313
- // Fix: was using raw key — must use fullKey to match load() key format
314
- this.loader.clear(this.makeKey(key));
315
- return resp;
332
+ // ⚠ RAW key, never `makeKey(key)`. DataLoader applies `cacheKeyFn` internally on EVERY public
333
+ // method — load, clear and prime alike — so handing it an already-prefixed key makes it look for
334
+ // `<space>:<space>:id`, which nothing ever created. `load()` passes the raw key, so this must
335
+ // too. Passing the prefixed key here is the defect this method shipped with: the Redis copy went,
336
+ // the in-memory copy stayed, and every later `get()` in that process returned the pre-write row.
337
+ this.loader.clear(key);
338
+ return this.rDel(key);
316
339
  }
317
340
  /**
318
341
  * Clears all entries from the DataLoader in-memory cache.
@@ -326,10 +349,10 @@ class RedisDataLoader {
326
349
  * Clears a single key from the DataLoader in-memory cache only.
327
350
  * Does NOT delete from Redis.
328
351
  *
329
- * @param key Cache key (will have makeKey applied)
352
+ * @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
330
353
  */
331
354
  async clearLocal(key) {
332
- return this.loader.clear(this.makeKey(key));
355
+ return this.loader.clear(key);
333
356
  }
334
357
  }
335
358
  export { RedisDataLoader };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.137",
3
+ "version": "1.0.138",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {