@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
@@ -9,8 +9,17 @@
9
9
  * canonical one; the positional form is kept for back-compat.
10
10
  */
11
11
 
12
+ import { claimed, hasUnref } from "./claim.js";
12
13
  import { type Duration, parseDuration, resolveTtlSeconds } from "./duration.js";
13
- import { FactoryError, TimeoutError } from "./errors.js";
14
+ import {
15
+ EchoError,
16
+ FactoryError,
17
+ InvalidArgumentError,
18
+ InvalidDurationError,
19
+ LockTimeoutError,
20
+ TimeoutError,
21
+ UndefinedValueError,
22
+ } from "./errors.js";
14
23
  import type {
15
24
  CacheEmitter,
16
25
  CacheEntry,
@@ -42,25 +51,66 @@ function isTaggableDriver(driver: CacheDriver): driver is TaggableDriver {
42
51
  );
43
52
  }
44
53
 
45
- /** Resolve an optional {@link Duration} to milliseconds; `undefined` when unset. */
54
+ function notTaggable(): EchoError {
55
+ return new EchoError(
56
+ "E_ECHO_NOT_TAGGABLE",
57
+ "Echo: the configured driver does not support tag-based invalidation",
58
+ );
59
+ }
60
+
61
+ /** The longest delay `setTimeout` honours; past it Node fires after 1 ms. */
62
+ const MAX_TIMER_MS = 2_147_483_647;
63
+
64
+ /**
65
+ * Resolve an optional timeout {@link Duration} to milliseconds; `undefined`
66
+ * when unset or `Infinity` (no timeout).
67
+ *
68
+ * Checked, because `setTimeout` reads NaN, Infinity and anything past
69
+ * 2^31-1 ms as 1 ms: "never time out" became "time out at once", and every
70
+ * getOrSet rejected. A longer one is clamped to the longest timer there is
71
+ * (24.8 days); NaN and negatives mean nothing and are refused.
72
+ */
46
73
  function resolveMs(duration: Duration | undefined): number | undefined {
47
74
  if (duration === undefined || duration === null) return undefined;
48
75
  const seconds =
49
76
  typeof duration === "number" ? duration : parseDuration(duration);
50
- return Math.max(0, seconds) * 1000;
77
+ if (seconds === Number.POSITIVE_INFINITY) return undefined;
78
+ if (Number.isNaN(seconds) || seconds < 0) {
79
+ throw new InvalidDurationError(
80
+ `Echo: a timeout must be a non-negative duration, or null for none — got ${String(duration)}`,
81
+ );
82
+ }
83
+ return Math.min(seconds * 1000, MAX_TIMER_MS);
51
84
  }
52
85
 
53
- const TIMEOUT: unique symbol = Symbol("echo.timeout");
86
+ /**
87
+ * A resolved TTL as a write event reports it: `null` for an entry that never
88
+ * expires, which the driver level spells `0`, so a listener does not read
89
+ * "lives zero seconds".
90
+ */
91
+ function reportedTtl(seconds: number): number | null {
92
+ return seconds === 0 ? null : seconds;
93
+ }
54
94
 
55
- /** A timer handle that can be unreferenced — Node's, not the browser's. */
56
- function hasUnref(timer: unknown): timer is { unref(): void } {
57
- return (
58
- typeof timer === "object" &&
59
- timer !== null &&
60
- typeof Reflect.get(timer, "unref") === "function"
61
- );
95
+ /** The default `graceBackoff`, as upstream's: 10 seconds. */
96
+ const DEFAULT_GRACE_BACKOFF_SECONDS = 10;
97
+
98
+ /**
99
+ * Resolve `graceBackoff` to seconds: the default when unset, `0` (off) for
100
+ * `null` or `0`. A negative or NaN one means nothing and is refused.
101
+ */
102
+ function resolveBackoffSeconds(duration: Duration | undefined): number {
103
+ const seconds = resolveTtlSeconds(duration, DEFAULT_GRACE_BACKOFF_SECONDS);
104
+ if (seconds < 0) {
105
+ throw new InvalidDurationError(
106
+ `Echo: graceBackoff must be a non-negative duration, or null for none — got ${String(duration)}`,
107
+ );
108
+ }
109
+ return seconds;
62
110
  }
63
111
 
112
+ const TIMEOUT: unique symbol = Symbol("echo.timeout");
113
+
64
114
  function withTimeout<T>(
65
115
  promise: Promise<T>,
66
116
  ms: number,
@@ -96,6 +146,12 @@ export interface CacheConfig {
96
146
  ttl?: Duration;
97
147
  /** Default grace period (stale-while-revalidate) as a {@link Duration}. */
98
148
  grace?: Duration;
149
+ /**
150
+ * How long a stale value is served as fresh after its factory failed,
151
+ * before the factory is tried again. Default `'10s'`; `0` or `null` retries
152
+ * on the next call.
153
+ */
154
+ graceBackoff?: Duration;
99
155
  /** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
100
156
  timeout?: Duration;
101
157
  /** Default hard timeout for `getOrSet`. */
@@ -104,10 +160,17 @@ export interface CacheConfig {
104
160
  lockTimeout?: Duration;
105
161
  /** Store name reported in events (default `"default"`). */
106
162
  name?: string;
107
- /** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared`). */
163
+ /** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared` / `expire`). */
108
164
  emitter?: CacheEmitter;
109
165
  }
110
166
 
167
+ /** What a factory run settled to: its own value, or the stale one standing in. */
168
+ interface FactoryOutcome<T> {
169
+ value: T;
170
+ /** `true` when the factory produced `value`; `false` for the stale fallback. */
171
+ fresh: boolean;
172
+ }
173
+
111
174
  /** Shared single-flight state — one map per store, threaded through namespaces. */
112
175
  interface SharedState {
113
176
  inflight: Map<string, { promise: Promise<unknown> }>;
@@ -118,11 +181,14 @@ interface NormalizedGetOrSet<T> {
118
181
  factory: Factory<T>;
119
182
  ttlSeconds: number;
120
183
  graceSeconds: number;
184
+ graceBackoffSeconds: number;
121
185
  timeoutMs: number | undefined;
122
186
  hardTimeoutMs: number | undefined;
123
187
  lockTimeoutMs: number | undefined;
124
188
  tags: string[];
125
189
  onFactoryError?: (error: FactoryError) => void;
190
+ /** `performance.now()` when the call came in: what its events time from. */
191
+ started: number;
126
192
  }
127
193
 
128
194
  /** The slice of `CacheStoreManager` a store it built needs to reach back into. */
@@ -137,6 +203,7 @@ export class CacheManager {
137
203
  #prefix: string;
138
204
  #defaultTtl: number;
139
205
  #defaultGrace: Duration | undefined;
206
+ #defaultGraceBackoff: Duration | undefined;
140
207
  #defaultTimeout: Duration | undefined;
141
208
  #defaultHardTimeout: Duration | undefined;
142
209
  #defaultLockTimeout: Duration | undefined;
@@ -154,6 +221,7 @@ export class CacheManager {
154
221
  "cache:written": new Set(),
155
222
  "cache:deleted": new Set(),
156
223
  "cache:cleared": new Set(),
224
+ "cache:expire": new Set(),
157
225
  };
158
226
  #shared: SharedState;
159
227
  /**
@@ -175,6 +243,7 @@ export class CacheManager {
175
243
  this.#prefix = config?.prefix ?? "";
176
244
  this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
177
245
  this.#defaultGrace = config?.grace;
246
+ this.#defaultGraceBackoff = config?.graceBackoff;
178
247
  this.#defaultTimeout = config?.timeout;
179
248
  this.#defaultHardTimeout = config?.hardTimeout;
180
249
  this.#defaultLockTimeout = config?.lockTimeout;
@@ -183,10 +252,30 @@ export class CacheManager {
183
252
  this.#shared = shared ?? { inflight: new Map() };
184
253
  }
185
254
 
255
+ /** The store's name, as events report it (upstream `cache.name`). */
256
+ get name(): string {
257
+ return this.#name;
258
+ }
259
+
186
260
  #prefixKey(key: string): string {
187
261
  return this.#prefix ? `${this.#prefix}:${key}` : key;
188
262
  }
189
263
 
264
+ /**
265
+ * Tags live inside the namespace, exactly as keys do. They reached the
266
+ * driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
267
+ * also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
268
+ * same way: its tag invalidations are entries of the namespaced stack.
269
+ */
270
+ #prefixTags(tags: string[]): string[] {
271
+ return tags.map((tag) => this.#prefixKey(tag));
272
+ }
273
+
274
+ /** Milliseconds since `started`, to two decimals: an event's `duration`. */
275
+ #since(started: number): number {
276
+ return Math.round((performance.now() - started) * 100) / 100;
277
+ }
278
+
190
279
  #emit<E extends keyof CacheEventMap>(
191
280
  event: E,
192
281
  payload: CacheEventMap[E],
@@ -287,7 +376,8 @@ export class CacheManager {
287
376
  use(name?: string): CacheManager {
288
377
  if (this.#stores) return this.#stores.use(name);
289
378
  if (name === undefined) return this;
290
- throw new Error(
379
+ throw new EchoError(
380
+ "E_ECHO_UNKNOWN_STORE",
291
381
  `Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
292
382
  "Declare `{ default, stores }` in config/cache.ts to name several.",
293
383
  );
@@ -397,25 +487,43 @@ export class CacheManager {
397
487
  if (value === null || value === undefined) {
398
488
  // Named divergence (fail-loud): unlike bento (which no-ops), echo throws
399
489
  // on caching null/undefined — a null cache write is almost always a bug.
400
- throw new TypeError(
401
- "Echo: caching null/undefined values is not supported",
402
- );
490
+ throw new UndefinedValueError();
491
+ }
492
+ if (ttlSeconds < 0) {
493
+ // A TTL in the past: the value has already expired. Kept only as
494
+ // a stale copy for its grace window, otherwise dropped — and the
495
+ // key's previous value with it, which a skipped write would have
496
+ // left being served. Upstream deletes the same way when the TTL
497
+ // is not positive and grace is off.
498
+ if (graceSeconds > 0 && this.#driver.setEntry) {
499
+ await this.#driver.setEntry(prefixed, value, {
500
+ expiresAt: Date.now() - 1,
501
+ graceSeconds,
502
+ tags: this.#prefixTags(tags),
503
+ });
504
+ return;
505
+ }
506
+ await this.#driver.delete(prefixed);
507
+ return;
403
508
  }
404
509
  if (this.#driver.setEntry) {
405
510
  await this.#driver.setEntry(prefixed, value, {
406
511
  ttlSeconds,
407
512
  graceSeconds,
408
- tags,
513
+ tags: this.#prefixTags(tags),
409
514
  });
410
515
  return;
411
516
  }
412
517
  if (tags.length > 0) {
413
518
  if (!isTaggableDriver(this.#driver)) {
414
- throw new Error(
415
- "Echo: the configured driver does not support tag-based invalidation",
416
- );
519
+ throw notTaggable();
417
520
  }
418
- await this.#driver.setWithTags(prefixed, value, tags, ttlSeconds);
521
+ await this.#driver.setWithTags(
522
+ prefixed,
523
+ value,
524
+ this.#prefixTags(tags),
525
+ ttlSeconds,
526
+ );
419
527
  return;
420
528
  }
421
529
  await this.#driver.set(prefixed, value, ttlSeconds);
@@ -428,6 +536,7 @@ export class CacheManager {
428
536
  async get<T = unknown>(
429
537
  keyOrOptions: string | GetOptions<T>,
430
538
  ): Promise<T | undefined> {
539
+ const started = performance.now();
431
540
  await this.#whenConnected();
432
541
  const key =
433
542
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
@@ -445,6 +554,7 @@ export class CacheManager {
445
554
  value: entry.value,
446
555
  store: this.#name,
447
556
  graced: false,
557
+ duration: this.#since(started),
448
558
  });
449
559
  return entry.value;
450
560
  }
@@ -454,11 +564,16 @@ export class CacheManager {
454
564
  value: entry.value,
455
565
  store: this.#name,
456
566
  graced: true,
567
+ duration: this.#since(started),
457
568
  });
458
569
  return entry.value;
459
570
  }
460
571
 
461
- this.#emit("cache:miss", { key, store: this.#name });
572
+ this.#emit("cache:miss", {
573
+ key,
574
+ store: this.#name,
575
+ duration: this.#since(started),
576
+ });
462
577
  if (defaultValue !== undefined) {
463
578
  return defaultValue instanceof Function ? defaultValue() : defaultValue;
464
579
  }
@@ -479,6 +594,7 @@ export class CacheManager {
479
594
  value?: unknown,
480
595
  ttlSeconds?: number,
481
596
  ): Promise<void> {
597
+ const started = performance.now();
482
598
  await this.#whenConnected();
483
599
  let key: string;
484
600
  let val: unknown;
@@ -488,7 +604,7 @@ export class CacheManager {
488
604
  if (typeof keyOrOptions === "string") {
489
605
  key = keyOrOptions;
490
606
  val = value;
491
- ttl = ttlSeconds ?? this.#defaultTtl;
607
+ ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
492
608
  graceSeconds = 0;
493
609
  tags = [];
494
610
  } else {
@@ -502,7 +618,13 @@ export class CacheManager {
502
618
  tags = keyOrOptions.tags ?? [];
503
619
  }
504
620
  await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
505
- this.#emit("cache:written", { key, value: val, store: this.#name });
621
+ this.#emit("cache:written", {
622
+ key,
623
+ value: val,
624
+ store: this.#name,
625
+ ttl: reportedTtl(ttl),
626
+ duration: this.#since(started),
627
+ });
506
628
  }
507
629
 
508
630
  /** Set a value that never expires (bento `setForever`). */
@@ -515,11 +637,16 @@ export class CacheManager {
515
637
  delete(key: string): Promise<boolean>;
516
638
  delete(options: DeleteOptions): Promise<boolean>;
517
639
  async delete(keyOrOptions: string | DeleteOptions): Promise<boolean> {
640
+ const started = performance.now();
518
641
  await this.#whenConnected();
519
642
  const key =
520
643
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
521
644
  const deleted = await this.#driver.delete(this.#prefixKey(key));
522
- this.#emit("cache:deleted", { key, store: this.#name });
645
+ this.#emit("cache:deleted", {
646
+ key,
647
+ store: this.#name,
648
+ duration: this.#since(started),
649
+ });
523
650
  return deleted;
524
651
  }
525
652
 
@@ -533,8 +660,13 @@ export class CacheManager {
533
660
  : keysOrOptions.keys;
534
661
  let all = true;
535
662
  for (const key of keys) {
663
+ const started = performance.now();
536
664
  const ok = await this.#driver.delete(this.#prefixKey(key));
537
- this.#emit("cache:deleted", { key, store: this.#name });
665
+ this.#emit("cache:deleted", {
666
+ key,
667
+ store: this.#name,
668
+ duration: this.#since(started),
669
+ });
538
670
  if (!ok) all = false;
539
671
  }
540
672
  return all;
@@ -556,7 +688,10 @@ export class CacheManager {
556
688
  return !(await this.has(key));
557
689
  }
558
690
 
559
- /** Read a key and delete it in one step (bento `pull`). Returns `null` on miss. */
691
+ /**
692
+ * Read a key and delete it in one step (bento `pull`). Resolves to
693
+ * `undefined` on a miss, as `get` does, and deletes nothing then.
694
+ */
560
695
  async pull<T = unknown>(key: string): Promise<T | undefined> {
561
696
  await this.#whenConnected();
562
697
  const value = await this.get<T>(key);
@@ -569,6 +704,7 @@ export class CacheManager {
569
704
  * window (bento `expire`). Without grace this is equivalent to a delete.
570
705
  */
571
706
  async expire(keyOrOptions: string | ExpireOptions): Promise<boolean> {
707
+ const started = performance.now();
572
708
  await this.#whenConnected();
573
709
  const key =
574
710
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
@@ -576,18 +712,33 @@ export class CacheManager {
576
712
  const graceSeconds = resolveTtlSeconds(this.#defaultGrace, 0);
577
713
  const entry = await this.#readEntry<unknown>(prefixed);
578
714
  if (entry === null) return false;
715
+ let expired: boolean;
579
716
  if (graceSeconds > 0 && this.#driver.setEntry) {
580
717
  // Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
581
718
  // keeping it physically for the grace window. A positive `ttlSeconds`
582
719
  // would leave a brief fresh window during which the value is still served
583
720
  // and the factory never runs.
721
+ //
722
+ // With its tags, as the driver read them (already scoped to this
723
+ // namespace): rewritten without them, the stale copy was served for
724
+ // the whole grace window while deleteByTag no longer reached it.
584
725
  await this.#driver.setEntry(prefixed, entry.value, {
585
726
  expiresAt: Date.now() - 1,
586
727
  graceSeconds,
728
+ tags: entry.tags ?? [],
729
+ });
730
+ expired = true;
731
+ } else {
732
+ expired = await this.#driver.delete(prefixed);
733
+ }
734
+ if (expired) {
735
+ this.#emit("cache:expire", {
736
+ key,
737
+ store: this.#name,
738
+ duration: this.#since(started),
587
739
  });
588
- return true;
589
740
  }
590
- return this.#driver.delete(prefixed);
741
+ return expired;
591
742
  }
592
743
 
593
744
  /**
@@ -599,11 +750,15 @@ export class CacheManager {
599
750
  * handing the driver the prefix.
600
751
  */
601
752
  async clear(): Promise<void> {
753
+ const started = performance.now();
602
754
  await this.#whenConnected();
603
755
  // The separator is part of it: `tenant-a` must not take `tenant-abc`
604
756
  // with it, and every key under this view is written `<prefix>:<key>`.
605
757
  await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
606
- this.#emit("cache:cleared", { store: this.#name });
758
+ this.#emit("cache:cleared", {
759
+ store: this.#name,
760
+ duration: this.#since(started),
761
+ });
607
762
  }
608
763
 
609
764
  // ---- tags ------------------------------------------------------------
@@ -615,15 +770,17 @@ export class CacheManager {
615
770
  tags: string[],
616
771
  ttlSeconds?: number,
617
772
  ): Promise<void> {
773
+ const started = performance.now();
618
774
  await this.#whenConnected();
619
- await this.#writeValue(
620
- this.#prefixKey(key),
775
+ const ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
776
+ await this.#writeValue(this.#prefixKey(key), value, ttl, 0, tags);
777
+ this.#emit("cache:written", {
778
+ key,
621
779
  value,
622
- ttlSeconds ?? this.#defaultTtl,
623
- 0,
624
- tags,
625
- );
626
- this.#emit("cache:written", { key, value, store: this.#name });
780
+ store: this.#name,
781
+ ttl: reportedTtl(ttl),
782
+ duration: this.#since(started),
783
+ });
627
784
  }
628
785
 
629
786
  /** Invalidate all entries carrying any of the given tags (bento `deleteByTag`). */
@@ -637,14 +794,13 @@ export class CacheManager {
637
794
  ? tagsOrOptions
638
795
  : tagsOrOptions.tags;
639
796
  if (!isTaggableDriver(this.#driver)) {
640
- throw new Error(
641
- "Echo: the configured driver does not support tag-based invalidation",
642
- );
797
+ throw notTaggable();
643
798
  }
799
+ const scoped = this.#prefixTags(tags);
644
800
  if (typeof this.#driver.deleteByTag === "function") {
645
- return this.#driver.deleteByTag(tags);
801
+ return this.#driver.deleteByTag(scoped);
646
802
  }
647
- return this.#driver.flushTags(tags);
803
+ return this.#driver.flushTags(scoped);
648
804
  }
649
805
 
650
806
  /** @deprecated alias of {@link deleteByTag}. */
@@ -666,6 +822,7 @@ export class CacheManager {
666
822
  prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
667
823
  ttl: this.#defaultTtl,
668
824
  grace: this.#defaultGrace,
825
+ graceBackoff: this.#defaultGraceBackoff,
669
826
  timeout: this.#defaultTimeout,
670
827
  hardTimeout: this.#defaultHardTimeout,
671
828
  lockTimeout: this.#defaultLockTimeout,
@@ -682,10 +839,11 @@ export class CacheManager {
682
839
  a: string | GetOrSetOptions<T>,
683
840
  b: number | undefined,
684
841
  c: Factory<T> | undefined,
842
+ started: number,
685
843
  ): NormalizedGetOrSet<T> {
686
844
  if (typeof a === "string") {
687
845
  if (typeof c !== "function") {
688
- throw new TypeError(
846
+ throw new InvalidArgumentError(
689
847
  "Echo: getOrSet(key, ttl, factory) requires a factory function",
690
848
  );
691
849
  }
@@ -694,39 +852,68 @@ export class CacheManager {
694
852
  factory: c,
695
853
  ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
696
854
  graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
855
+ graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
697
856
  timeoutMs: resolveMs(this.#defaultTimeout),
698
857
  hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
699
858
  lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
700
859
  tags: [],
860
+ started,
701
861
  };
702
862
  }
863
+ // Checked in this form too: a config value or a JSON body reaching here
864
+ // untyped made the call fail with a bare TypeError from deep inside the
865
+ // single-flight bookkeeping, instead of a refusal naming the argument.
866
+ if (typeof a.factory !== "function") {
867
+ throw new InvalidArgumentError(
868
+ "Echo: getOrSet({ key, factory }) requires a factory function",
869
+ );
870
+ }
703
871
  return {
704
872
  key: a.key,
705
873
  factory: a.factory,
706
874
  ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
707
875
  graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
876
+ graceBackoffSeconds: resolveBackoffSeconds(
877
+ a.graceBackoff === undefined
878
+ ? this.#defaultGraceBackoff
879
+ : a.graceBackoff,
880
+ ),
708
881
  timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
709
882
  hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
710
883
  lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
711
884
  tags: a.tags ?? [],
712
885
  onFactoryError: a.onFactoryError,
886
+ started,
713
887
  };
714
888
  }
715
889
 
716
890
  /**
717
- * Run (or join) the single-flight factory for `prefixed`. Resolves to the
718
- * fresh value on success; on failure it calls `onFactoryError` and either
719
- * resolves to `staleValue` (when a stale fallback exists) or rejects.
891
+ * Run the single-flight factory for `prefixed` and register it as the
892
+ * key's in-flight record. Resolves to the fresh value on success; on
893
+ * failure it calls `onFactoryError` and either resolves to `staleValue`
894
+ * (when a stale fallback exists) or rejects. The record is removed once it
895
+ * settles, whichever way.
720
896
  */
721
897
  #invokeFactory<T>(
722
898
  prefixed: string,
723
899
  o: NormalizedGetOrSet<T>,
724
900
  hasStale: boolean,
725
901
  staleValue: T | undefined,
726
- ): Promise<T> {
727
- const run = async (): Promise<T> => {
902
+ staleTags: string[],
903
+ ): Promise<FactoryOutcome<T>> {
904
+ const run = async (): Promise<FactoryOutcome<T>> => {
728
905
  try {
729
- const value = await o.factory();
906
+ // Called a microtask later, never inline. A factory that throws
907
+ // before returning a promise ran this `finally` synchronously,
908
+ // BEFORE the record below was stored: the rejected promise then
909
+ // stayed in the map for good, and every later call for the key
910
+ // joined it instead of running the factory again.
911
+ const value = await Promise.resolve().then(() => o.factory());
912
+ // The write is timed on its own: the factory's time is the
913
+ // miss's, reported once the call is served. Timed from the call,
914
+ // the two overlapped and a profiler summing them counted the
915
+ // factory twice.
916
+ const writing = performance.now();
730
917
  await this.#writeValue(
731
918
  prefixed,
732
919
  value,
@@ -738,17 +925,102 @@ export class CacheManager {
738
925
  key: o.key,
739
926
  value,
740
927
  store: this.#name,
928
+ ttl: reportedTtl(o.ttlSeconds),
929
+ duration: this.#since(writing),
741
930
  });
742
- return value;
931
+ return { value, fresh: true };
743
932
  } catch (error) {
744
933
  o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
745
- if (hasStale && staleValue !== undefined) return staleValue;
934
+ if (hasStale && staleValue !== undefined) {
935
+ await this.#applyGraceBackoff(prefixed, staleValue, staleTags, o);
936
+ return { value: staleValue, fresh: false };
937
+ }
746
938
  throw error;
747
939
  } finally {
748
- this.#shared.inflight.delete(prefixed);
940
+ // Only this run's own record: a later leader's must survive it.
941
+ if (this.#shared.inflight.get(prefixed) === record) {
942
+ this.#shared.inflight.delete(prefixed);
943
+ }
749
944
  }
750
945
  };
751
- return run();
946
+ const outcome = run();
947
+ // What a joiner reads: the value alone. Marked handled here, since
948
+ // nobody may ever join; each joiner still sees a rejection on its own
949
+ // chain, and the leader on `outcome`.
950
+ const shared = outcome.then((settled) => settled.value);
951
+ shared.catch(() => {});
952
+ const record = { promise: shared };
953
+ this.#shared.inflight.set(prefixed, record);
954
+ return outcome;
955
+ }
956
+
957
+ /**
958
+ * Serve the stale value as fresh for `graceBackoff` after its factory
959
+ * failed (upstream `graceBackoff`, default 10 s).
960
+ *
961
+ * Without it the entry stayed stale, and every request for the grace
962
+ * window ran the factory again: a backend that was down got hit once per
963
+ * request, since single-flight only collapses callers that overlap.
964
+ *
965
+ * NAMED DEVIATION: the backoff runs from NOW. Upstream adds it to the
966
+ * entry's old logical expiry, which leaves an entry that went stale more
967
+ * than `graceBackoff` ago still stale, so the factory is retried at once.
968
+ *
969
+ * Written only over the stale copy it read: an entry rewritten or deleted
970
+ * while the factory ran (a `set`, a `deleteByTag`) is not overwritten, nor
971
+ * an invalidated one brought back.
972
+ */
973
+ async #applyGraceBackoff<T>(
974
+ prefixed: string,
975
+ value: T,
976
+ tags: string[],
977
+ o: NormalizedGetOrSet<T>,
978
+ ): Promise<void> {
979
+ if (o.graceBackoffSeconds <= 0 || !this.#driver.setEntry) return;
980
+ try {
981
+ const current = await this.#readEntry<T>(prefixed);
982
+ if (current === null || !current.stale) return;
983
+ await this.#driver.setEntry(prefixed, value, {
984
+ expiresAt: Date.now() + o.graceBackoffSeconds * 1000,
985
+ graceSeconds: o.graceSeconds,
986
+ // Already scoped to the namespace: they are what the driver read.
987
+ tags,
988
+ });
989
+ } catch {
990
+ // The stale value is still served. The factory's own failure is
991
+ // what `onFactoryError` reports; a store too unwell to take the
992
+ // backoff only means the factory is tried again sooner.
993
+ }
994
+ }
995
+
996
+ /**
997
+ * Report how the LEADER's call was served, once its factory settled: a
998
+ * miss when the factory produced the value, as upstream reports it after
999
+ * the factory has run; a graced hit when the factory failed and the stale
1000
+ * value stood in for it. A joiner ran no factory and reports neither.
1001
+ */
1002
+ #settled<T>(
1003
+ o: NormalizedGetOrSet<T>,
1004
+ outcome: FactoryOutcome<T>,
1005
+ leader: boolean,
1006
+ ): T {
1007
+ if (!leader) return outcome.value;
1008
+ if (outcome.fresh) {
1009
+ this.#emit("cache:miss", {
1010
+ key: o.key,
1011
+ store: this.#name,
1012
+ duration: this.#since(o.started),
1013
+ });
1014
+ } else {
1015
+ this.#emit("cache:hit", {
1016
+ key: o.key,
1017
+ value: outcome.value,
1018
+ store: this.#name,
1019
+ graced: true,
1020
+ duration: this.#since(o.started),
1021
+ });
1022
+ }
1023
+ return outcome.value;
752
1024
  }
753
1025
 
754
1026
  getOrSet<T>(key: string, ttlSeconds: number, factory: Factory<T>): Promise<T>;
@@ -758,8 +1030,9 @@ export class CacheManager {
758
1030
  b?: number,
759
1031
  c?: Factory<T>,
760
1032
  ): Promise<T> {
1033
+ const started = performance.now();
761
1034
  await this.#whenConnected();
762
- const o = this.#normalizeGetOrSet<T>(a, b, c);
1035
+ const o = this.#normalizeGetOrSet<T>(a, b, c, started);
763
1036
  const prefixed = this.#prefixKey(o.key);
764
1037
 
765
1038
  const entry = await this.#readEntry<T>(prefixed);
@@ -769,23 +1042,35 @@ export class CacheManager {
769
1042
  value: entry.value,
770
1043
  store: this.#name,
771
1044
  graced: false,
1045
+ duration: this.#since(started),
772
1046
  });
773
1047
  return entry.value;
774
1048
  }
775
1049
 
776
1050
  const hasStale = entry?.stale === true && o.graceSeconds > 0;
777
1051
  const staleValue = hasStale ? entry.value : undefined;
1052
+ const staleTags = hasStale ? (entry.tags ?? []) : [];
778
1053
 
779
- let record = this.#shared.inflight.get(prefixed);
780
- if (!record) {
781
- record = {
782
- promise: this.#invokeFactory<T>(prefixed, o, hasStale, staleValue),
783
- };
784
- this.#shared.inflight.set(prefixed, record);
1054
+ const record = this.#shared.inflight.get(prefixed);
1055
+ // Joining another caller's factory, rather than running our own.
1056
+ const joined = record !== undefined;
1057
+ let factoryPromise: Promise<FactoryOutcome<T>>;
1058
+ if (record === undefined) {
1059
+ factoryPromise = this.#invokeFactory<T>(
1060
+ prefixed,
1061
+ o,
1062
+ hasStale,
1063
+ staleValue,
1064
+ staleTags,
1065
+ );
1066
+ } else {
1067
+ // The map holds every key's factory, whatever its type; what the
1068
+ // leader computes for this key is what this caller reads.
1069
+ factoryPromise = record.promise.then((value) => ({
1070
+ value: claimed<T>(value),
1071
+ fresh: false,
1072
+ }));
785
1073
  }
786
- // Single-flight join point: the shared map is heterogeneous (many T), so
787
- // this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
788
- const factoryPromise = record.promise as Promise<T>;
789
1074
 
790
1075
  if (hasStale && staleValue !== undefined) {
791
1076
  // Stale-while-revalidate: serve stale up to the soft timeout (default 0
@@ -802,21 +1087,34 @@ export class CacheManager {
802
1087
  value: staleValue,
803
1088
  store: this.#name,
804
1089
  graced: true,
1090
+ duration: this.#since(started),
805
1091
  });
806
1092
  return staleValue;
807
1093
  }
808
- return result;
1094
+ return this.#settled(o, result, !joined);
809
1095
  }
810
1096
 
811
- if (o.hardTimeoutMs !== undefined) {
812
- const result = await withTimeout(factoryPromise, o.hardTimeoutMs);
1097
+ // A joiner waits at most `lockTimeout` for the leader, stale value or
1098
+ // not, as upstream bounds its lock acquisition either way. It was read
1099
+ // on the stale path only, so behind a factory that hung every caller
1100
+ // for the key waited forever. The leader is not bound by it: it holds
1101
+ // the lock, and `hardTimeout` is what bounds its factory.
1102
+ const lockMs = joined ? o.lockTimeoutMs : undefined;
1103
+ const hardMs = o.hardTimeoutMs;
1104
+ if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
1105
+ const result = await withTimeout(factoryPromise, lockMs);
1106
+ if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
1107
+ return this.#settled(o, result, !joined);
1108
+ }
1109
+ if (hardMs !== undefined) {
1110
+ const result = await withTimeout(factoryPromise, hardMs);
813
1111
  if (result === TIMEOUT) {
814
- throw new TimeoutError(o.key, o.hardTimeoutMs);
1112
+ throw new TimeoutError(o.key, hardMs);
815
1113
  }
816
- return result;
1114
+ return this.#settled(o, result, !joined);
817
1115
  }
818
1116
 
819
- return factoryPromise;
1117
+ return this.#settled(o, await factoryPromise, !joined);
820
1118
  }
821
1119
 
822
1120
  /** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */