@c9up/echo 0.2.3 → 0.2.5

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.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/dist/CacheManager.d.ts +13 -2
  3. package/dist/CacheManager.d.ts.map +1 -1
  4. package/dist/CacheManager.js +309 -56
  5. package/dist/CacheManager.js.map +1 -1
  6. package/dist/EchoProvider.d.ts.map +1 -1
  7. package/dist/EchoProvider.js +32 -3
  8. package/dist/EchoProvider.js.map +1 -1
  9. package/dist/StoreManager.d.ts +38 -11
  10. package/dist/StoreManager.d.ts.map +1 -1
  11. package/dist/StoreManager.js +80 -22
  12. package/dist/StoreManager.js.map +1 -1
  13. package/dist/bytes.d.ts +13 -0
  14. package/dist/bytes.d.ts.map +1 -0
  15. package/dist/bytes.js +35 -0
  16. package/dist/bytes.js.map +1 -0
  17. package/dist/claim.d.ts +15 -0
  18. package/dist/claim.d.ts.map +1 -0
  19. package/dist/claim.js +10 -0
  20. package/dist/claim.js.map +1 -0
  21. package/dist/configure.d.ts +1 -0
  22. package/dist/configure.d.ts.map +1 -1
  23. package/dist/configure.js +3 -0
  24. package/dist/configure.js.map +1 -1
  25. package/dist/console/cacheClear.d.ts +13 -0
  26. package/dist/console/cacheClear.d.ts.map +1 -0
  27. package/dist/console/cacheClear.js +69 -0
  28. package/dist/console/cacheClear.js.map +1 -0
  29. package/dist/console/cacheDelete.d.ts +11 -0
  30. package/dist/console/cacheDelete.d.ts.map +1 -0
  31. package/dist/console/cacheDelete.js +42 -0
  32. package/dist/console/cacheDelete.js.map +1 -0
  33. package/dist/console/cachePrune.d.ts +9 -0
  34. package/dist/console/cachePrune.d.ts.map +1 -0
  35. package/dist/console/cachePrune.js +35 -0
  36. package/dist/console/cachePrune.js.map +1 -0
  37. package/dist/console/contract.d.ts +64 -0
  38. package/dist/console/contract.d.ts.map +1 -0
  39. package/dist/console/contract.js +32 -0
  40. package/dist/console/contract.js.map +1 -0
  41. package/dist/console/index.d.ts +25 -0
  42. package/dist/console/index.d.ts.map +1 -0
  43. package/dist/console/index.js +38 -0
  44. package/dist/console/index.js.map +1 -0
  45. package/dist/console/store.d.ts +14 -0
  46. package/dist/console/store.d.ts.map +1 -0
  47. package/dist/console/store.js +35 -0
  48. package/dist/console/store.js.map +1 -0
  49. package/dist/drivers/MemoryDriver.d.ts +37 -1
  50. package/dist/drivers/MemoryDriver.d.ts.map +1 -1
  51. package/dist/drivers/MemoryDriver.js +170 -72
  52. package/dist/drivers/MemoryDriver.js.map +1 -1
  53. package/dist/drivers/RedisDriver.d.ts +15 -8
  54. package/dist/drivers/RedisDriver.d.ts.map +1 -1
  55. package/dist/drivers/RedisDriver.js +198 -97
  56. package/dist/drivers/RedisDriver.js.map +1 -1
  57. package/dist/drivers/TieredDriver.d.ts +42 -0
  58. package/dist/drivers/TieredDriver.d.ts.map +1 -1
  59. package/dist/drivers/TieredDriver.js +114 -9
  60. package/dist/drivers/TieredDriver.js.map +1 -1
  61. package/dist/duration.d.ts +13 -3
  62. package/dist/duration.d.ts.map +1 -1
  63. package/dist/duration.js +22 -7
  64. package/dist/duration.js.map +1 -1
  65. package/dist/errors.d.ts +60 -2
  66. package/dist/errors.d.ts.map +1 -1
  67. package/dist/errors.js +81 -6
  68. package/dist/errors.js.map +1 -1
  69. package/dist/index.d.ts +4 -4
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +3 -3
  72. package/dist/index.js.map +1 -1
  73. package/dist/quasar.d.ts +1 -1
  74. package/dist/quasar.d.ts.map +1 -1
  75. package/dist/quasar.js +106 -19
  76. package/dist/quasar.js.map +1 -1
  77. package/dist/services/main.d.ts +1 -1
  78. package/dist/services/main.d.ts.map +1 -1
  79. package/dist/services/main.js +22 -5
  80. package/dist/services/main.js.map +1 -1
  81. package/dist/types.d.ts +44 -2
  82. package/dist/types.d.ts.map +1 -1
  83. package/dist/vendor/quasarConnection.d.ts +44 -3
  84. package/dist/vendor/quasarConnection.d.ts.map +1 -1
  85. package/dist/vendor/quasarConnection.js +64 -23
  86. package/dist/vendor/quasarConnection.js.map +1 -1
  87. package/package.json +5 -1
  88. package/src/CacheManager.ts +367 -69
  89. package/src/EchoProvider.ts +45 -4
  90. package/src/StoreManager.ts +131 -35
  91. package/src/bytes.ts +38 -0
  92. package/src/claim.ts +22 -0
  93. package/src/configure.ts +4 -0
  94. package/src/console/cacheClear.ts +96 -0
  95. package/src/console/cacheDelete.ts +65 -0
  96. package/src/console/cachePrune.ts +57 -0
  97. package/src/console/contract.ts +93 -0
  98. package/src/console/index.ts +61 -0
  99. package/src/console/store.ts +47 -0
  100. package/src/drivers/MemoryDriver.ts +221 -69
  101. package/src/drivers/RedisDriver.ts +234 -104
  102. package/src/drivers/TieredDriver.ts +169 -9
  103. package/src/duration.ts +28 -7
  104. package/src/errors.ts +103 -6
  105. package/src/index.ts +17 -3
  106. package/src/quasar.ts +145 -30
  107. package/src/services/main.ts +26 -8
  108. package/src/types.ts +46 -7
  109. package/src/vendor/quasarConnection.ts +105 -22
@@ -8,28 +8,62 @@
8
8
  * ttlSeconds)`, `getOrSet(key, ttlSeconds, factory)`). The object form is the
9
9
  * canonical one; the positional form is kept for back-compat.
10
10
  */
11
+ import { claimed, hasUnref } from "./claim.js";
11
12
  import { parseDuration, resolveTtlSeconds } from "./duration.js";
12
- import { FactoryError, TimeoutError } from "./errors.js";
13
+ import { EchoError, FactoryError, InvalidArgumentError, InvalidDurationError, LockTimeoutError, TimeoutError, UndefinedValueError, } from "./errors.js";
13
14
  function isTaggableDriver(driver) {
14
15
  const candidate = driver;
15
16
  return (typeof candidate.setWithTags === "function" &&
16
17
  (typeof candidate.deleteByTag === "function" ||
17
18
  typeof candidate.flushTags === "function"));
18
19
  }
19
- /** Resolve an optional {@link Duration} to milliseconds; `undefined` when unset. */
20
+ function notTaggable() {
21
+ return new EchoError("E_ECHO_NOT_TAGGABLE", "Echo: the configured driver does not support tag-based invalidation");
22
+ }
23
+ /** The longest delay `setTimeout` honours; past it Node fires after 1 ms. */
24
+ const MAX_TIMER_MS = 2_147_483_647;
25
+ /**
26
+ * Resolve an optional timeout {@link Duration} to milliseconds; `undefined`
27
+ * when unset or `Infinity` (no timeout).
28
+ *
29
+ * Checked, because `setTimeout` reads NaN, Infinity and anything past
30
+ * 2^31-1 ms as 1 ms: "never time out" became "time out at once", and every
31
+ * getOrSet rejected. A longer one is clamped to the longest timer there is
32
+ * (24.8 days); NaN and negatives mean nothing and are refused.
33
+ */
20
34
  function resolveMs(duration) {
21
35
  if (duration === undefined || duration === null)
22
36
  return undefined;
23
37
  const seconds = typeof duration === "number" ? duration : parseDuration(duration);
24
- return Math.max(0, seconds) * 1000;
38
+ if (seconds === Number.POSITIVE_INFINITY)
39
+ return undefined;
40
+ if (Number.isNaN(seconds) || seconds < 0) {
41
+ throw new InvalidDurationError(`Echo: a timeout must be a non-negative duration, or null for none — got ${String(duration)}`);
42
+ }
43
+ return Math.min(seconds * 1000, MAX_TIMER_MS);
25
44
  }
26
- const TIMEOUT = Symbol("echo.timeout");
27
- /** A timer handle that can be unreferenced — Node's, not the browser's. */
28
- function hasUnref(timer) {
29
- return (typeof timer === "object" &&
30
- timer !== null &&
31
- typeof Reflect.get(timer, "unref") === "function");
45
+ /**
46
+ * A resolved TTL as a write event reports it: `null` for an entry that never
47
+ * expires, which the driver level spells `0`, so a listener does not read
48
+ * "lives zero seconds".
49
+ */
50
+ function reportedTtl(seconds) {
51
+ return seconds === 0 ? null : seconds;
32
52
  }
53
+ /** The default `graceBackoff`, as upstream's: 10 seconds. */
54
+ const DEFAULT_GRACE_BACKOFF_SECONDS = 10;
55
+ /**
56
+ * Resolve `graceBackoff` to seconds: the default when unset, `0` (off) for
57
+ * `null` or `0`. A negative or NaN one means nothing and is refused.
58
+ */
59
+ function resolveBackoffSeconds(duration) {
60
+ const seconds = resolveTtlSeconds(duration, DEFAULT_GRACE_BACKOFF_SECONDS);
61
+ if (seconds < 0) {
62
+ throw new InvalidDurationError(`Echo: graceBackoff must be a non-negative duration, or null for none — got ${String(duration)}`);
63
+ }
64
+ return seconds;
65
+ }
66
+ const TIMEOUT = Symbol("echo.timeout");
33
67
  function withTimeout(promise, ms) {
34
68
  return new Promise((resolve, reject) => {
35
69
  const timer = setTimeout(() => resolve(TIMEOUT), ms);
@@ -52,6 +86,7 @@ export class CacheManager {
52
86
  #prefix;
53
87
  #defaultTtl;
54
88
  #defaultGrace;
89
+ #defaultGraceBackoff;
55
90
  #defaultTimeout;
56
91
  #defaultHardTimeout;
57
92
  #defaultLockTimeout;
@@ -67,6 +102,7 @@ export class CacheManager {
67
102
  "cache:written": new Set(),
68
103
  "cache:deleted": new Set(),
69
104
  "cache:cleared": new Set(),
105
+ "cache:expire": new Set(),
70
106
  };
71
107
  #shared;
72
108
  /**
@@ -87,6 +123,7 @@ export class CacheManager {
87
123
  this.#prefix = config?.prefix ?? "";
88
124
  this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
89
125
  this.#defaultGrace = config?.grace;
126
+ this.#defaultGraceBackoff = config?.graceBackoff;
90
127
  this.#defaultTimeout = config?.timeout;
91
128
  this.#defaultHardTimeout = config?.hardTimeout;
92
129
  this.#defaultLockTimeout = config?.lockTimeout;
@@ -94,9 +131,26 @@ export class CacheManager {
94
131
  this.#emitter = config?.emitter;
95
132
  this.#shared = shared ?? { inflight: new Map() };
96
133
  }
134
+ /** The store's name, as events report it (upstream `cache.name`). */
135
+ get name() {
136
+ return this.#name;
137
+ }
97
138
  #prefixKey(key) {
98
139
  return this.#prefix ? `${this.#prefix}:${key}` : key;
99
140
  }
141
+ /**
142
+ * Tags live inside the namespace, exactly as keys do. They reached the
143
+ * driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
144
+ * also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
145
+ * same way: its tag invalidations are entries of the namespaced stack.
146
+ */
147
+ #prefixTags(tags) {
148
+ return tags.map((tag) => this.#prefixKey(tag));
149
+ }
150
+ /** Milliseconds since `started`, to two decimals: an event's `duration`. */
151
+ #since(started) {
152
+ return Math.round((performance.now() - started) * 100) / 100;
153
+ }
100
154
  #emit(event, payload) {
101
155
  // Not just called: an Adonis emitter's `emit` is `async` and REJECTS when
102
156
  // a listener throws and the application registered no error handler
@@ -177,7 +231,7 @@ export class CacheManager {
177
231
  return this.#stores.use(name);
178
232
  if (name === undefined)
179
233
  return this;
180
- throw new Error(`Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
234
+ throw new EchoError("E_ECHO_UNKNOWN_STORE", `Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
181
235
  "Declare `{ default, stores }` in config/cache.ts to name several.");
182
236
  }
183
237
  /** @internal Called by `CacheStoreManager` on the store it builds. */
@@ -279,26 +333,44 @@ export class CacheManager {
279
333
  if (value === null || value === undefined) {
280
334
  // Named divergence (fail-loud): unlike bento (which no-ops), echo throws
281
335
  // on caching null/undefined — a null cache write is almost always a bug.
282
- throw new TypeError("Echo: caching null/undefined values is not supported");
336
+ throw new UndefinedValueError();
337
+ }
338
+ if (ttlSeconds < 0) {
339
+ // A TTL in the past: the value has already expired. Kept only as
340
+ // a stale copy for its grace window, otherwise dropped — and the
341
+ // key's previous value with it, which a skipped write would have
342
+ // left being served. Upstream deletes the same way when the TTL
343
+ // is not positive and grace is off.
344
+ if (graceSeconds > 0 && this.#driver.setEntry) {
345
+ await this.#driver.setEntry(prefixed, value, {
346
+ expiresAt: Date.now() - 1,
347
+ graceSeconds,
348
+ tags: this.#prefixTags(tags),
349
+ });
350
+ return;
351
+ }
352
+ await this.#driver.delete(prefixed);
353
+ return;
283
354
  }
284
355
  if (this.#driver.setEntry) {
285
356
  await this.#driver.setEntry(prefixed, value, {
286
357
  ttlSeconds,
287
358
  graceSeconds,
288
- tags,
359
+ tags: this.#prefixTags(tags),
289
360
  });
290
361
  return;
291
362
  }
292
363
  if (tags.length > 0) {
293
364
  if (!isTaggableDriver(this.#driver)) {
294
- throw new Error("Echo: the configured driver does not support tag-based invalidation");
365
+ throw notTaggable();
295
366
  }
296
- await this.#driver.setWithTags(prefixed, value, tags, ttlSeconds);
367
+ await this.#driver.setWithTags(prefixed, value, this.#prefixTags(tags), ttlSeconds);
297
368
  return;
298
369
  }
299
370
  await this.#driver.set(prefixed, value, ttlSeconds);
300
371
  }
301
372
  async get(keyOrOptions) {
373
+ const started = performance.now();
302
374
  await this.#whenConnected();
303
375
  const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
304
376
  const graceSeconds = typeof keyOrOptions === "string"
@@ -312,6 +384,7 @@ export class CacheManager {
312
384
  value: entry.value,
313
385
  store: this.#name,
314
386
  graced: false,
387
+ duration: this.#since(started),
315
388
  });
316
389
  return entry.value;
317
390
  }
@@ -321,10 +394,15 @@ export class CacheManager {
321
394
  value: entry.value,
322
395
  store: this.#name,
323
396
  graced: true,
397
+ duration: this.#since(started),
324
398
  });
325
399
  return entry.value;
326
400
  }
327
- this.#emit("cache:miss", { key, store: this.#name });
401
+ this.#emit("cache:miss", {
402
+ key,
403
+ store: this.#name,
404
+ duration: this.#since(started),
405
+ });
328
406
  if (defaultValue !== undefined) {
329
407
  return defaultValue instanceof Function ? defaultValue() : defaultValue;
330
408
  }
@@ -336,6 +414,7 @@ export class CacheManager {
336
414
  return undefined;
337
415
  }
338
416
  async set(keyOrOptions, value, ttlSeconds) {
417
+ const started = performance.now();
339
418
  await this.#whenConnected();
340
419
  let key;
341
420
  let val;
@@ -345,7 +424,7 @@ export class CacheManager {
345
424
  if (typeof keyOrOptions === "string") {
346
425
  key = keyOrOptions;
347
426
  val = value;
348
- ttl = ttlSeconds ?? this.#defaultTtl;
427
+ ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
349
428
  graceSeconds = 0;
350
429
  tags = [];
351
430
  }
@@ -357,17 +436,28 @@ export class CacheManager {
357
436
  tags = keyOrOptions.tags ?? [];
358
437
  }
359
438
  await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
360
- this.#emit("cache:written", { key, value: val, store: this.#name });
439
+ this.#emit("cache:written", {
440
+ key,
441
+ value: val,
442
+ store: this.#name,
443
+ ttl: reportedTtl(ttl),
444
+ duration: this.#since(started),
445
+ });
361
446
  }
362
447
  /** Set a value that never expires (bento `setForever`). */
363
448
  setForever(options) {
364
449
  return this.set({ ...options, ttl: null });
365
450
  }
366
451
  async delete(keyOrOptions) {
452
+ const started = performance.now();
367
453
  await this.#whenConnected();
368
454
  const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
369
455
  const deleted = await this.#driver.delete(this.#prefixKey(key));
370
- this.#emit("cache:deleted", { key, store: this.#name });
456
+ this.#emit("cache:deleted", {
457
+ key,
458
+ store: this.#name,
459
+ duration: this.#since(started),
460
+ });
371
461
  return deleted;
372
462
  }
373
463
  /** Delete multiple keys (bento `deleteMany`). */
@@ -378,8 +468,13 @@ export class CacheManager {
378
468
  : keysOrOptions.keys;
379
469
  let all = true;
380
470
  for (const key of keys) {
471
+ const started = performance.now();
381
472
  const ok = await this.#driver.delete(this.#prefixKey(key));
382
- this.#emit("cache:deleted", { key, store: this.#name });
473
+ this.#emit("cache:deleted", {
474
+ key,
475
+ store: this.#name,
476
+ duration: this.#since(started),
477
+ });
383
478
  if (!ok)
384
479
  all = false;
385
480
  }
@@ -395,7 +490,10 @@ export class CacheManager {
395
490
  const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
396
491
  return !(await this.has(key));
397
492
  }
398
- /** Read a key and delete it in one step (bento `pull`). Returns `null` on miss. */
493
+ /**
494
+ * Read a key and delete it in one step (bento `pull`). Resolves to
495
+ * `undefined` on a miss, as `get` does, and deletes nothing then.
496
+ */
399
497
  async pull(key) {
400
498
  await this.#whenConnected();
401
499
  const value = await this.get(key);
@@ -408,6 +506,7 @@ export class CacheManager {
408
506
  * window (bento `expire`). Without grace this is equivalent to a delete.
409
507
  */
410
508
  async expire(keyOrOptions) {
509
+ const started = performance.now();
411
510
  await this.#whenConnected();
412
511
  const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
413
512
  const prefixed = this.#prefixKey(key);
@@ -415,18 +514,34 @@ export class CacheManager {
415
514
  const entry = await this.#readEntry(prefixed);
416
515
  if (entry === null)
417
516
  return false;
517
+ let expired;
418
518
  if (graceSeconds > 0 && this.#driver.setEntry) {
419
519
  // Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
420
520
  // keeping it physically for the grace window. A positive `ttlSeconds`
421
521
  // would leave a brief fresh window during which the value is still served
422
522
  // and the factory never runs.
523
+ //
524
+ // With its tags, as the driver read them (already scoped to this
525
+ // namespace): rewritten without them, the stale copy was served for
526
+ // the whole grace window while deleteByTag no longer reached it.
423
527
  await this.#driver.setEntry(prefixed, entry.value, {
424
528
  expiresAt: Date.now() - 1,
425
529
  graceSeconds,
530
+ tags: entry.tags ?? [],
531
+ });
532
+ expired = true;
533
+ }
534
+ else {
535
+ expired = await this.#driver.delete(prefixed);
536
+ }
537
+ if (expired) {
538
+ this.#emit("cache:expire", {
539
+ key,
540
+ store: this.#name,
541
+ duration: this.#since(started),
426
542
  });
427
- return true;
428
543
  }
429
- return this.#driver.delete(prefixed);
544
+ return expired;
430
545
  }
431
546
  /**
432
547
  * Clear this cache — the whole store, or only this namespace's subtree.
@@ -437,18 +552,30 @@ export class CacheManager {
437
552
  * handing the driver the prefix.
438
553
  */
439
554
  async clear() {
555
+ const started = performance.now();
440
556
  await this.#whenConnected();
441
557
  // The separator is part of it: `tenant-a` must not take `tenant-abc`
442
558
  // with it, and every key under this view is written `<prefix>:<key>`.
443
559
  await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
444
- this.#emit("cache:cleared", { store: this.#name });
560
+ this.#emit("cache:cleared", {
561
+ store: this.#name,
562
+ duration: this.#since(started),
563
+ });
445
564
  }
446
565
  // ---- tags ------------------------------------------------------------
447
566
  /** Set a value with tags for grouped invalidation (bento parity). */
448
567
  async setWithTags(key, value, tags, ttlSeconds) {
568
+ const started = performance.now();
449
569
  await this.#whenConnected();
450
- await this.#writeValue(this.#prefixKey(key), value, ttlSeconds ?? this.#defaultTtl, 0, tags);
451
- this.#emit("cache:written", { key, value, store: this.#name });
570
+ const ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
571
+ await this.#writeValue(this.#prefixKey(key), value, ttl, 0, tags);
572
+ this.#emit("cache:written", {
573
+ key,
574
+ value,
575
+ store: this.#name,
576
+ ttl: reportedTtl(ttl),
577
+ duration: this.#since(started),
578
+ });
452
579
  }
453
580
  async deleteByTag(tagsOrOptions) {
454
581
  await this.#whenConnected();
@@ -456,12 +583,13 @@ export class CacheManager {
456
583
  ? tagsOrOptions
457
584
  : tagsOrOptions.tags;
458
585
  if (!isTaggableDriver(this.#driver)) {
459
- throw new Error("Echo: the configured driver does not support tag-based invalidation");
586
+ throw notTaggable();
460
587
  }
588
+ const scoped = this.#prefixTags(tags);
461
589
  if (typeof this.#driver.deleteByTag === "function") {
462
- return this.#driver.deleteByTag(tags);
590
+ return this.#driver.deleteByTag(scoped);
463
591
  }
464
- return this.#driver.flushTags(tags);
592
+ return this.#driver.flushTags(scoped);
465
593
  }
466
594
  /** @deprecated alias of {@link deleteByTag}. */
467
595
  async flushTags(tags) {
@@ -478,6 +606,7 @@ export class CacheManager {
478
606
  prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
479
607
  ttl: this.#defaultTtl,
480
608
  grace: this.#defaultGrace,
609
+ graceBackoff: this.#defaultGraceBackoff,
481
610
  timeout: this.#defaultTimeout,
482
611
  hardTimeout: this.#defaultHardTimeout,
483
612
  lockTimeout: this.#defaultLockTimeout,
@@ -486,66 +615,169 @@ export class CacheManager {
486
615
  }, this.#shared);
487
616
  }
488
617
  // ---- getOrSet --------------------------------------------------------
489
- #normalizeGetOrSet(a, b, c) {
618
+ #normalizeGetOrSet(a, b, c, started) {
490
619
  if (typeof a === "string") {
491
620
  if (typeof c !== "function") {
492
- throw new TypeError("Echo: getOrSet(key, ttl, factory) requires a factory function");
621
+ throw new InvalidArgumentError("Echo: getOrSet(key, ttl, factory) requires a factory function");
493
622
  }
494
623
  return {
495
624
  key: a,
496
625
  factory: c,
497
626
  ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
498
627
  graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
628
+ graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
499
629
  timeoutMs: resolveMs(this.#defaultTimeout),
500
630
  hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
501
631
  lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
502
632
  tags: [],
633
+ started,
503
634
  };
504
635
  }
636
+ // Checked in this form too: a config value or a JSON body reaching here
637
+ // untyped made the call fail with a bare TypeError from deep inside the
638
+ // single-flight bookkeeping, instead of a refusal naming the argument.
639
+ if (typeof a.factory !== "function") {
640
+ throw new InvalidArgumentError("Echo: getOrSet({ key, factory }) requires a factory function");
641
+ }
505
642
  return {
506
643
  key: a.key,
507
644
  factory: a.factory,
508
645
  ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
509
646
  graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
647
+ graceBackoffSeconds: resolveBackoffSeconds(a.graceBackoff === undefined
648
+ ? this.#defaultGraceBackoff
649
+ : a.graceBackoff),
510
650
  timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
511
651
  hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
512
652
  lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
513
653
  tags: a.tags ?? [],
514
654
  onFactoryError: a.onFactoryError,
655
+ started,
515
656
  };
516
657
  }
517
658
  /**
518
- * Run (or join) the single-flight factory for `prefixed`. Resolves to the
519
- * fresh value on success; on failure it calls `onFactoryError` and either
520
- * resolves to `staleValue` (when a stale fallback exists) or rejects.
659
+ * Run the single-flight factory for `prefixed` and register it as the
660
+ * key's in-flight record. Resolves to the fresh value on success; on
661
+ * failure it calls `onFactoryError` and either resolves to `staleValue`
662
+ * (when a stale fallback exists) or rejects. The record is removed once it
663
+ * settles, whichever way.
521
664
  */
522
- #invokeFactory(prefixed, o, hasStale, staleValue) {
665
+ #invokeFactory(prefixed, o, hasStale, staleValue, staleTags) {
523
666
  const run = async () => {
524
667
  try {
525
- const value = await o.factory();
668
+ // Called a microtask later, never inline. A factory that throws
669
+ // before returning a promise ran this `finally` synchronously,
670
+ // BEFORE the record below was stored: the rejected promise then
671
+ // stayed in the map for good, and every later call for the key
672
+ // joined it instead of running the factory again.
673
+ const value = await Promise.resolve().then(() => o.factory());
674
+ // The write is timed on its own: the factory's time is the
675
+ // miss's, reported once the call is served. Timed from the call,
676
+ // the two overlapped and a profiler summing them counted the
677
+ // factory twice.
678
+ const writing = performance.now();
526
679
  await this.#writeValue(prefixed, value, o.ttlSeconds, o.graceSeconds, o.tags);
527
680
  this.#emit("cache:written", {
528
681
  key: o.key,
529
682
  value,
530
683
  store: this.#name,
684
+ ttl: reportedTtl(o.ttlSeconds),
685
+ duration: this.#since(writing),
531
686
  });
532
- return value;
687
+ return { value, fresh: true };
533
688
  }
534
689
  catch (error) {
535
690
  o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
536
- if (hasStale && staleValue !== undefined)
537
- return staleValue;
691
+ if (hasStale && staleValue !== undefined) {
692
+ await this.#applyGraceBackoff(prefixed, staleValue, staleTags, o);
693
+ return { value: staleValue, fresh: false };
694
+ }
538
695
  throw error;
539
696
  }
540
697
  finally {
541
- this.#shared.inflight.delete(prefixed);
698
+ // Only this run's own record: a later leader's must survive it.
699
+ if (this.#shared.inflight.get(prefixed) === record) {
700
+ this.#shared.inflight.delete(prefixed);
701
+ }
542
702
  }
543
703
  };
544
- return run();
704
+ const outcome = run();
705
+ // What a joiner reads: the value alone. Marked handled here, since
706
+ // nobody may ever join; each joiner still sees a rejection on its own
707
+ // chain, and the leader on `outcome`.
708
+ const shared = outcome.then((settled) => settled.value);
709
+ shared.catch(() => { });
710
+ const record = { promise: shared };
711
+ this.#shared.inflight.set(prefixed, record);
712
+ return outcome;
713
+ }
714
+ /**
715
+ * Serve the stale value as fresh for `graceBackoff` after its factory
716
+ * failed (upstream `graceBackoff`, default 10 s).
717
+ *
718
+ * Without it the entry stayed stale, and every request for the grace
719
+ * window ran the factory again: a backend that was down got hit once per
720
+ * request, since single-flight only collapses callers that overlap.
721
+ *
722
+ * NAMED DEVIATION: the backoff runs from NOW. Upstream adds it to the
723
+ * entry's old logical expiry, which leaves an entry that went stale more
724
+ * than `graceBackoff` ago still stale, so the factory is retried at once.
725
+ *
726
+ * Written only over the stale copy it read: an entry rewritten or deleted
727
+ * while the factory ran (a `set`, a `deleteByTag`) is not overwritten, nor
728
+ * an invalidated one brought back.
729
+ */
730
+ async #applyGraceBackoff(prefixed, value, tags, o) {
731
+ if (o.graceBackoffSeconds <= 0 || !this.#driver.setEntry)
732
+ return;
733
+ try {
734
+ const current = await this.#readEntry(prefixed);
735
+ if (current === null || !current.stale)
736
+ return;
737
+ await this.#driver.setEntry(prefixed, value, {
738
+ expiresAt: Date.now() + o.graceBackoffSeconds * 1000,
739
+ graceSeconds: o.graceSeconds,
740
+ // Already scoped to the namespace: they are what the driver read.
741
+ tags,
742
+ });
743
+ }
744
+ catch {
745
+ // The stale value is still served. The factory's own failure is
746
+ // what `onFactoryError` reports; a store too unwell to take the
747
+ // backoff only means the factory is tried again sooner.
748
+ }
749
+ }
750
+ /**
751
+ * Report how the LEADER's call was served, once its factory settled: a
752
+ * miss when the factory produced the value, as upstream reports it after
753
+ * the factory has run; a graced hit when the factory failed and the stale
754
+ * value stood in for it. A joiner ran no factory and reports neither.
755
+ */
756
+ #settled(o, outcome, leader) {
757
+ if (!leader)
758
+ return outcome.value;
759
+ if (outcome.fresh) {
760
+ this.#emit("cache:miss", {
761
+ key: o.key,
762
+ store: this.#name,
763
+ duration: this.#since(o.started),
764
+ });
765
+ }
766
+ else {
767
+ this.#emit("cache:hit", {
768
+ key: o.key,
769
+ value: outcome.value,
770
+ store: this.#name,
771
+ graced: true,
772
+ duration: this.#since(o.started),
773
+ });
774
+ }
775
+ return outcome.value;
545
776
  }
546
777
  async getOrSet(a, b, c) {
778
+ const started = performance.now();
547
779
  await this.#whenConnected();
548
- const o = this.#normalizeGetOrSet(a, b, c);
780
+ const o = this.#normalizeGetOrSet(a, b, c, started);
549
781
  const prefixed = this.#prefixKey(o.key);
550
782
  const entry = await this.#readEntry(prefixed);
551
783
  if (entry && !entry.stale) {
@@ -554,21 +786,28 @@ export class CacheManager {
554
786
  value: entry.value,
555
787
  store: this.#name,
556
788
  graced: false,
789
+ duration: this.#since(started),
557
790
  });
558
791
  return entry.value;
559
792
  }
560
793
  const hasStale = entry?.stale === true && o.graceSeconds > 0;
561
794
  const staleValue = hasStale ? entry.value : undefined;
562
- let record = this.#shared.inflight.get(prefixed);
563
- if (!record) {
564
- record = {
565
- promise: this.#invokeFactory(prefixed, o, hasStale, staleValue),
566
- };
567
- this.#shared.inflight.set(prefixed, record);
795
+ const staleTags = hasStale ? (entry.tags ?? []) : [];
796
+ const record = this.#shared.inflight.get(prefixed);
797
+ // Joining another caller's factory, rather than running our own.
798
+ const joined = record !== undefined;
799
+ let factoryPromise;
800
+ if (record === undefined) {
801
+ factoryPromise = this.#invokeFactory(prefixed, o, hasStale, staleValue, staleTags);
802
+ }
803
+ else {
804
+ // The map holds every key's factory, whatever its type; what the
805
+ // leader computes for this key is what this caller reads.
806
+ factoryPromise = record.promise.then((value) => ({
807
+ value: claimed(value),
808
+ fresh: false,
809
+ }));
568
810
  }
569
- // Single-flight join point: the shared map is heterogeneous (many T), so
570
- // this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
571
- const factoryPromise = record.promise;
572
811
  if (hasStale && staleValue !== undefined) {
573
812
  // Stale-while-revalidate: serve stale up to the soft timeout (default 0
574
813
  // = serve immediately), let the factory refresh in the background.
@@ -583,19 +822,33 @@ export class CacheManager {
583
822
  value: staleValue,
584
823
  store: this.#name,
585
824
  graced: true,
825
+ duration: this.#since(started),
586
826
  });
587
827
  return staleValue;
588
828
  }
589
- return result;
829
+ return this.#settled(o, result, !joined);
830
+ }
831
+ // A joiner waits at most `lockTimeout` for the leader, stale value or
832
+ // not, as upstream bounds its lock acquisition either way. It was read
833
+ // on the stale path only, so behind a factory that hung every caller
834
+ // for the key waited forever. The leader is not bound by it: it holds
835
+ // the lock, and `hardTimeout` is what bounds its factory.
836
+ const lockMs = joined ? o.lockTimeoutMs : undefined;
837
+ const hardMs = o.hardTimeoutMs;
838
+ if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
839
+ const result = await withTimeout(factoryPromise, lockMs);
840
+ if (result === TIMEOUT)
841
+ throw new LockTimeoutError(o.key, lockMs);
842
+ return this.#settled(o, result, !joined);
590
843
  }
591
- if (o.hardTimeoutMs !== undefined) {
592
- const result = await withTimeout(factoryPromise, o.hardTimeoutMs);
844
+ if (hardMs !== undefined) {
845
+ const result = await withTimeout(factoryPromise, hardMs);
593
846
  if (result === TIMEOUT) {
594
- throw new TimeoutError(o.key, o.hardTimeoutMs);
847
+ throw new TimeoutError(o.key, hardMs);
595
848
  }
596
- return result;
849
+ return this.#settled(o, result, !joined);
597
850
  }
598
- return factoryPromise;
851
+ return this.#settled(o, await factoryPromise, !joined);
599
852
  }
600
853
  /** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
601
854
  getOrSetForever(options) {