@sdflc/backend-helpers 1.0.137 → 1.0.139
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 +51 -22
- 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 +51 -22
- 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
|
|
@@ -1201,10 +1230,26 @@ class BaseGateway {
|
|
|
1201
1230
|
if (!args || objects.length === 0) {
|
|
1202
1231
|
return [];
|
|
1203
1232
|
}
|
|
1233
|
+
// The framework's OWN id is applied AFTER transformOnCreate, never through it.
|
|
1234
|
+
// transformOnCreate strips `id` — deliberately, so a CALLER-supplied id is never
|
|
1235
|
+
// honoured — and it cannot tell the caller's id from ours once both are merged into
|
|
1236
|
+
// one payload. Passing the generated id in that payload (as this did until now) meant
|
|
1237
|
+
// the strip deleted the id we had just made: `generateId()` became inert, every insert
|
|
1238
|
+
// silently fell back to the column's own default, and every create logged
|
|
1239
|
+
// `field "id" is not writable on create and was stripped from the payload`.
|
|
1240
|
+
// A caller id is still dropped — it is stripped before we get here.
|
|
1241
|
+
// Mirrors what `set()` below already does, and restores the pre-1.0.135 insert payload
|
|
1242
|
+
// (the strip landed in 1.0.135 and started swallowing this id).
|
|
1243
|
+
const idField = String(this.getIdField()).split('.').pop();
|
|
1204
1244
|
for (let idx = 0, len = objects.length; idx < len; ++idx) {
|
|
1205
1245
|
const object = objects[idx];
|
|
1206
|
-
const
|
|
1207
|
-
|
|
1246
|
+
const transformed = await this.transformOnCreate({ ...object });
|
|
1247
|
+
// Only when nothing else has set it — `hasLang` + `localizationForField` builds a
|
|
1248
|
+
// COMPOSITE id in transformOnCreate, and that one must stand.
|
|
1249
|
+
if (transformed[idField] == null) {
|
|
1250
|
+
transformed[idField] = await this.generateId(object);
|
|
1251
|
+
}
|
|
1252
|
+
objects[idx] = transformed;
|
|
1208
1253
|
}
|
|
1209
1254
|
const result = [];
|
|
1210
1255
|
const chunks = (0, utils_1.arrToChunks)(objects, this.config?.insertChunkSize || DEFAULT_CHUNCK_SIZE);
|
|
@@ -1245,11 +1290,7 @@ class BaseGateway {
|
|
|
1245
1290
|
const items = await query;
|
|
1246
1291
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1247
1292
|
const idName = this.getIdFieldUpdateRemove();
|
|
1248
|
-
items.
|
|
1249
|
-
if (item[idName]) {
|
|
1250
|
-
this.loader.clear(item[idName]);
|
|
1251
|
-
}
|
|
1252
|
-
});
|
|
1293
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1253
1294
|
}
|
|
1254
1295
|
return items.map((item) => this.transformOnOut(item));
|
|
1255
1296
|
}
|
|
@@ -1331,11 +1372,7 @@ class BaseGateway {
|
|
|
1331
1372
|
const items = await query;
|
|
1332
1373
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1333
1374
|
const idName = this.getIdFieldUpdateRemove();
|
|
1334
|
-
items.
|
|
1335
|
-
if (item[idName]) {
|
|
1336
|
-
this.loader.clear(item[idName]);
|
|
1337
|
-
}
|
|
1338
|
-
});
|
|
1375
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1339
1376
|
}
|
|
1340
1377
|
return items.map((item) => this.transformOnOut(item));
|
|
1341
1378
|
}
|
|
@@ -1362,11 +1399,7 @@ class BaseGateway {
|
|
|
1362
1399
|
const items = await query;
|
|
1363
1400
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1364
1401
|
const idName = this.getIdFieldUpdateRemove();
|
|
1365
|
-
items.
|
|
1366
|
-
if (item[idName]) {
|
|
1367
|
-
this.loader.clear(item[idName]);
|
|
1368
|
-
}
|
|
1369
|
-
});
|
|
1402
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1370
1403
|
}
|
|
1371
1404
|
return items.map((item) => this.transformOnOut(item));
|
|
1372
1405
|
}
|
|
@@ -1474,11 +1507,7 @@ class BaseGateway {
|
|
|
1474
1507
|
const items = await query;
|
|
1475
1508
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1476
1509
|
const idName = this.getIdFieldUpdateRemove();
|
|
1477
|
-
items.
|
|
1478
|
-
if (item[idName]) {
|
|
1479
|
-
this.loader.clear(item[idName]);
|
|
1480
|
-
}
|
|
1481
|
-
});
|
|
1510
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1482
1511
|
}
|
|
1483
1512
|
return items.map((item) => this.transformOnOut(item));
|
|
1484
1513
|
}
|
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
|
|
@@ -1195,10 +1224,26 @@ class BaseGateway {
|
|
|
1195
1224
|
if (!args || objects.length === 0) {
|
|
1196
1225
|
return [];
|
|
1197
1226
|
}
|
|
1227
|
+
// The framework's OWN id is applied AFTER transformOnCreate, never through it.
|
|
1228
|
+
// transformOnCreate strips `id` — deliberately, so a CALLER-supplied id is never
|
|
1229
|
+
// honoured — and it cannot tell the caller's id from ours once both are merged into
|
|
1230
|
+
// one payload. Passing the generated id in that payload (as this did until now) meant
|
|
1231
|
+
// the strip deleted the id we had just made: `generateId()` became inert, every insert
|
|
1232
|
+
// silently fell back to the column's own default, and every create logged
|
|
1233
|
+
// `field "id" is not writable on create and was stripped from the payload`.
|
|
1234
|
+
// A caller id is still dropped — it is stripped before we get here.
|
|
1235
|
+
// Mirrors what `set()` below already does, and restores the pre-1.0.135 insert payload
|
|
1236
|
+
// (the strip landed in 1.0.135 and started swallowing this id).
|
|
1237
|
+
const idField = String(this.getIdField()).split('.').pop();
|
|
1198
1238
|
for (let idx = 0, len = objects.length; idx < len; ++idx) {
|
|
1199
1239
|
const object = objects[idx];
|
|
1200
|
-
const
|
|
1201
|
-
|
|
1240
|
+
const transformed = await this.transformOnCreate({ ...object });
|
|
1241
|
+
// Only when nothing else has set it — `hasLang` + `localizationForField` builds a
|
|
1242
|
+
// COMPOSITE id in transformOnCreate, and that one must stand.
|
|
1243
|
+
if (transformed[idField] == null) {
|
|
1244
|
+
transformed[idField] = await this.generateId(object);
|
|
1245
|
+
}
|
|
1246
|
+
objects[idx] = transformed;
|
|
1202
1247
|
}
|
|
1203
1248
|
const result = [];
|
|
1204
1249
|
const chunks = arrToChunks(objects, this.config?.insertChunkSize || DEFAULT_CHUNCK_SIZE);
|
|
@@ -1239,11 +1284,7 @@ class BaseGateway {
|
|
|
1239
1284
|
const items = await query;
|
|
1240
1285
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1241
1286
|
const idName = this.getIdFieldUpdateRemove();
|
|
1242
|
-
items.
|
|
1243
|
-
if (item[idName]) {
|
|
1244
|
-
this.loader.clear(item[idName]);
|
|
1245
|
-
}
|
|
1246
|
-
});
|
|
1287
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1247
1288
|
}
|
|
1248
1289
|
return items.map((item) => this.transformOnOut(item));
|
|
1249
1290
|
}
|
|
@@ -1325,11 +1366,7 @@ class BaseGateway {
|
|
|
1325
1366
|
const items = await query;
|
|
1326
1367
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1327
1368
|
const idName = this.getIdFieldUpdateRemove();
|
|
1328
|
-
items.
|
|
1329
|
-
if (item[idName]) {
|
|
1330
|
-
this.loader.clear(item[idName]);
|
|
1331
|
-
}
|
|
1332
|
-
});
|
|
1369
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1333
1370
|
}
|
|
1334
1371
|
return items.map((item) => this.transformOnOut(item));
|
|
1335
1372
|
}
|
|
@@ -1356,11 +1393,7 @@ class BaseGateway {
|
|
|
1356
1393
|
const items = await query;
|
|
1357
1394
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1358
1395
|
const idName = this.getIdFieldUpdateRemove();
|
|
1359
|
-
items.
|
|
1360
|
-
if (item[idName]) {
|
|
1361
|
-
this.loader.clear(item[idName]);
|
|
1362
|
-
}
|
|
1363
|
-
});
|
|
1396
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1364
1397
|
}
|
|
1365
1398
|
return items.map((item) => this.transformOnOut(item));
|
|
1366
1399
|
}
|
|
@@ -1468,11 +1501,7 @@ class BaseGateway {
|
|
|
1468
1501
|
const items = await query;
|
|
1469
1502
|
if (items.length > 0 && this.config.noCache !== true) {
|
|
1470
1503
|
const idName = this.getIdFieldUpdateRemove();
|
|
1471
|
-
items.
|
|
1472
|
-
if (item[idName]) {
|
|
1473
|
-
this.loader.clear(item[idName]);
|
|
1474
|
-
}
|
|
1475
|
-
});
|
|
1504
|
+
await this.invalidate(items.map((item) => item[idName]).filter((id) => id != null));
|
|
1476
1505
|
}
|
|
1477
1506
|
return items.map((item) => this.transformOnOut(item));
|
|
1478
1507
|
}
|
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 };
|