@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.
- package/build/BaseGateway.d.ts +19 -0
- package/build/BaseGateway.js +33 -20
- package/build/DataCache.d.ts +11 -0
- package/build/DataCache.js +25 -6
- package/build/RedisDataLoader.d.ts +6 -3
- package/build/RedisDataLoader.js +42 -19
- package/build/esm/BaseGateway.d.ts +19 -0
- package/build/esm/BaseGateway.js +33 -20
- package/build/esm/DataCache.d.ts +11 -0
- package/build/esm/DataCache.js +25 -6
- package/build/esm/RedisDataLoader.d.ts +6 -3
- package/build/esm/RedisDataLoader.js +42 -19
- package/package.json +1 -1
package/build/BaseGateway.d.ts
CHANGED
|
@@ -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
|
package/build/BaseGateway.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
}
|
package/build/DataCache.d.ts
CHANGED
|
@@ -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
|
package/build/DataCache.js
CHANGED
|
@@ -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
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
-
*
|
|
145
|
-
* to
|
|
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
|
|
163
|
+
* @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
|
|
161
164
|
*/
|
|
162
165
|
clearLocal(key: any): Promise<void>;
|
|
163
166
|
}
|
package/build/RedisDataLoader.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
302
|
-
//
|
|
303
|
-
|
|
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
|
-
*
|
|
310
|
-
* to
|
|
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
|
-
|
|
319
|
-
//
|
|
320
|
-
|
|
321
|
-
|
|
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
|
|
358
|
+
* @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
|
|
336
359
|
*/
|
|
337
360
|
async clearLocal(key) {
|
|
338
|
-
return this.loader.clear(
|
|
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
|
package/build/esm/BaseGateway.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
}
|
package/build/esm/DataCache.d.ts
CHANGED
|
@@ -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
|
package/build/esm/DataCache.js
CHANGED
|
@@ -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
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
*
|
|
145
|
-
* to
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
296
|
-
//
|
|
297
|
-
|
|
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
|
-
*
|
|
304
|
-
* to
|
|
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
|
-
|
|
313
|
-
//
|
|
314
|
-
|
|
315
|
-
|
|
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
|
|
352
|
+
* @param key Raw cache key — DataLoader applies `cacheKeyFn` itself (see `clear`).
|
|
330
353
|
*/
|
|
331
354
|
async clearLocal(key) {
|
|
332
|
-
return this.loader.clear(
|
|
355
|
+
return this.loader.clear(key);
|
|
333
356
|
}
|
|
334
357
|
}
|
|
335
358
|
export { RedisDataLoader };
|