@c9up/echo 0.2.4 → 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.
@@ -83,6 +83,32 @@ function resolveMs(duration: Duration | undefined): number | undefined {
83
83
  return Math.min(seconds * 1000, MAX_TIMER_MS);
84
84
  }
85
85
 
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
+ }
94
+
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;
110
+ }
111
+
86
112
  const TIMEOUT: unique symbol = Symbol("echo.timeout");
87
113
 
88
114
  function withTimeout<T>(
@@ -120,6 +146,12 @@ export interface CacheConfig {
120
146
  ttl?: Duration;
121
147
  /** Default grace period (stale-while-revalidate) as a {@link Duration}. */
122
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;
123
155
  /** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
124
156
  timeout?: Duration;
125
157
  /** Default hard timeout for `getOrSet`. */
@@ -128,10 +160,17 @@ export interface CacheConfig {
128
160
  lockTimeout?: Duration;
129
161
  /** Store name reported in events (default `"default"`). */
130
162
  name?: string;
131
- /** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared`). */
163
+ /** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared` / `expire`). */
132
164
  emitter?: CacheEmitter;
133
165
  }
134
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
+
135
174
  /** Shared single-flight state — one map per store, threaded through namespaces. */
136
175
  interface SharedState {
137
176
  inflight: Map<string, { promise: Promise<unknown> }>;
@@ -142,11 +181,14 @@ interface NormalizedGetOrSet<T> {
142
181
  factory: Factory<T>;
143
182
  ttlSeconds: number;
144
183
  graceSeconds: number;
184
+ graceBackoffSeconds: number;
145
185
  timeoutMs: number | undefined;
146
186
  hardTimeoutMs: number | undefined;
147
187
  lockTimeoutMs: number | undefined;
148
188
  tags: string[];
149
189
  onFactoryError?: (error: FactoryError) => void;
190
+ /** `performance.now()` when the call came in: what its events time from. */
191
+ started: number;
150
192
  }
151
193
 
152
194
  /** The slice of `CacheStoreManager` a store it built needs to reach back into. */
@@ -161,6 +203,7 @@ export class CacheManager {
161
203
  #prefix: string;
162
204
  #defaultTtl: number;
163
205
  #defaultGrace: Duration | undefined;
206
+ #defaultGraceBackoff: Duration | undefined;
164
207
  #defaultTimeout: Duration | undefined;
165
208
  #defaultHardTimeout: Duration | undefined;
166
209
  #defaultLockTimeout: Duration | undefined;
@@ -178,6 +221,7 @@ export class CacheManager {
178
221
  "cache:written": new Set(),
179
222
  "cache:deleted": new Set(),
180
223
  "cache:cleared": new Set(),
224
+ "cache:expire": new Set(),
181
225
  };
182
226
  #shared: SharedState;
183
227
  /**
@@ -199,6 +243,7 @@ export class CacheManager {
199
243
  this.#prefix = config?.prefix ?? "";
200
244
  this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
201
245
  this.#defaultGrace = config?.grace;
246
+ this.#defaultGraceBackoff = config?.graceBackoff;
202
247
  this.#defaultTimeout = config?.timeout;
203
248
  this.#defaultHardTimeout = config?.hardTimeout;
204
249
  this.#defaultLockTimeout = config?.lockTimeout;
@@ -226,6 +271,11 @@ export class CacheManager {
226
271
  return tags.map((tag) => this.#prefixKey(tag));
227
272
  }
228
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
+
229
279
  #emit<E extends keyof CacheEventMap>(
230
280
  event: E,
231
281
  payload: CacheEventMap[E],
@@ -486,6 +536,7 @@ export class CacheManager {
486
536
  async get<T = unknown>(
487
537
  keyOrOptions: string | GetOptions<T>,
488
538
  ): Promise<T | undefined> {
539
+ const started = performance.now();
489
540
  await this.#whenConnected();
490
541
  const key =
491
542
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
@@ -503,6 +554,7 @@ export class CacheManager {
503
554
  value: entry.value,
504
555
  store: this.#name,
505
556
  graced: false,
557
+ duration: this.#since(started),
506
558
  });
507
559
  return entry.value;
508
560
  }
@@ -512,11 +564,16 @@ export class CacheManager {
512
564
  value: entry.value,
513
565
  store: this.#name,
514
566
  graced: true,
567
+ duration: this.#since(started),
515
568
  });
516
569
  return entry.value;
517
570
  }
518
571
 
519
- 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
+ });
520
577
  if (defaultValue !== undefined) {
521
578
  return defaultValue instanceof Function ? defaultValue() : defaultValue;
522
579
  }
@@ -537,6 +594,7 @@ export class CacheManager {
537
594
  value?: unknown,
538
595
  ttlSeconds?: number,
539
596
  ): Promise<void> {
597
+ const started = performance.now();
540
598
  await this.#whenConnected();
541
599
  let key: string;
542
600
  let val: unknown;
@@ -560,7 +618,13 @@ export class CacheManager {
560
618
  tags = keyOrOptions.tags ?? [];
561
619
  }
562
620
  await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
563
- 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
+ });
564
628
  }
565
629
 
566
630
  /** Set a value that never expires (bento `setForever`). */
@@ -573,11 +637,16 @@ export class CacheManager {
573
637
  delete(key: string): Promise<boolean>;
574
638
  delete(options: DeleteOptions): Promise<boolean>;
575
639
  async delete(keyOrOptions: string | DeleteOptions): Promise<boolean> {
640
+ const started = performance.now();
576
641
  await this.#whenConnected();
577
642
  const key =
578
643
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
579
644
  const deleted = await this.#driver.delete(this.#prefixKey(key));
580
- 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
+ });
581
650
  return deleted;
582
651
  }
583
652
 
@@ -591,8 +660,13 @@ export class CacheManager {
591
660
  : keysOrOptions.keys;
592
661
  let all = true;
593
662
  for (const key of keys) {
663
+ const started = performance.now();
594
664
  const ok = await this.#driver.delete(this.#prefixKey(key));
595
- 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
+ });
596
670
  if (!ok) all = false;
597
671
  }
598
672
  return all;
@@ -614,7 +688,10 @@ export class CacheManager {
614
688
  return !(await this.has(key));
615
689
  }
616
690
 
617
- /** 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
+ */
618
695
  async pull<T = unknown>(key: string): Promise<T | undefined> {
619
696
  await this.#whenConnected();
620
697
  const value = await this.get<T>(key);
@@ -627,6 +704,7 @@ export class CacheManager {
627
704
  * window (bento `expire`). Without grace this is equivalent to a delete.
628
705
  */
629
706
  async expire(keyOrOptions: string | ExpireOptions): Promise<boolean> {
707
+ const started = performance.now();
630
708
  await this.#whenConnected();
631
709
  const key =
632
710
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
@@ -634,18 +712,33 @@ export class CacheManager {
634
712
  const graceSeconds = resolveTtlSeconds(this.#defaultGrace, 0);
635
713
  const entry = await this.#readEntry<unknown>(prefixed);
636
714
  if (entry === null) return false;
715
+ let expired: boolean;
637
716
  if (graceSeconds > 0 && this.#driver.setEntry) {
638
717
  // Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
639
718
  // keeping it physically for the grace window. A positive `ttlSeconds`
640
719
  // would leave a brief fresh window during which the value is still served
641
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.
642
725
  await this.#driver.setEntry(prefixed, entry.value, {
643
726
  expiresAt: Date.now() - 1,
644
727
  graceSeconds,
728
+ tags: entry.tags ?? [],
645
729
  });
646
- return true;
730
+ expired = true;
731
+ } else {
732
+ expired = await this.#driver.delete(prefixed);
647
733
  }
648
- return this.#driver.delete(prefixed);
734
+ if (expired) {
735
+ this.#emit("cache:expire", {
736
+ key,
737
+ store: this.#name,
738
+ duration: this.#since(started),
739
+ });
740
+ }
741
+ return expired;
649
742
  }
650
743
 
651
744
  /**
@@ -657,11 +750,15 @@ export class CacheManager {
657
750
  * handing the driver the prefix.
658
751
  */
659
752
  async clear(): Promise<void> {
753
+ const started = performance.now();
660
754
  await this.#whenConnected();
661
755
  // The separator is part of it: `tenant-a` must not take `tenant-abc`
662
756
  // with it, and every key under this view is written `<prefix>:<key>`.
663
757
  await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
664
- this.#emit("cache:cleared", { store: this.#name });
758
+ this.#emit("cache:cleared", {
759
+ store: this.#name,
760
+ duration: this.#since(started),
761
+ });
665
762
  }
666
763
 
667
764
  // ---- tags ------------------------------------------------------------
@@ -673,15 +770,17 @@ export class CacheManager {
673
770
  tags: string[],
674
771
  ttlSeconds?: number,
675
772
  ): Promise<void> {
773
+ const started = performance.now();
676
774
  await this.#whenConnected();
677
- await this.#writeValue(
678
- 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,
679
779
  value,
680
- resolveTtlSeconds(ttlSeconds, this.#defaultTtl),
681
- 0,
682
- tags,
683
- );
684
- this.#emit("cache:written", { key, value, store: this.#name });
780
+ store: this.#name,
781
+ ttl: reportedTtl(ttl),
782
+ duration: this.#since(started),
783
+ });
685
784
  }
686
785
 
687
786
  /** Invalidate all entries carrying any of the given tags (bento `deleteByTag`). */
@@ -723,6 +822,7 @@ export class CacheManager {
723
822
  prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
724
823
  ttl: this.#defaultTtl,
725
824
  grace: this.#defaultGrace,
825
+ graceBackoff: this.#defaultGraceBackoff,
726
826
  timeout: this.#defaultTimeout,
727
827
  hardTimeout: this.#defaultHardTimeout,
728
828
  lockTimeout: this.#defaultLockTimeout,
@@ -739,6 +839,7 @@ export class CacheManager {
739
839
  a: string | GetOrSetOptions<T>,
740
840
  b: number | undefined,
741
841
  c: Factory<T> | undefined,
842
+ started: number,
742
843
  ): NormalizedGetOrSet<T> {
743
844
  if (typeof a === "string") {
744
845
  if (typeof c !== "function") {
@@ -751,39 +852,68 @@ export class CacheManager {
751
852
  factory: c,
752
853
  ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
753
854
  graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
855
+ graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
754
856
  timeoutMs: resolveMs(this.#defaultTimeout),
755
857
  hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
756
858
  lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
757
859
  tags: [],
860
+ started,
758
861
  };
759
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
+ }
760
871
  return {
761
872
  key: a.key,
762
873
  factory: a.factory,
763
874
  ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
764
875
  graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
876
+ graceBackoffSeconds: resolveBackoffSeconds(
877
+ a.graceBackoff === undefined
878
+ ? this.#defaultGraceBackoff
879
+ : a.graceBackoff,
880
+ ),
765
881
  timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
766
882
  hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
767
883
  lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
768
884
  tags: a.tags ?? [],
769
885
  onFactoryError: a.onFactoryError,
886
+ started,
770
887
  };
771
888
  }
772
889
 
773
890
  /**
774
- * Run (or join) the single-flight factory for `prefixed`. Resolves to the
775
- * fresh value on success; on failure it calls `onFactoryError` and either
776
- * 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.
777
896
  */
778
897
  #invokeFactory<T>(
779
898
  prefixed: string,
780
899
  o: NormalizedGetOrSet<T>,
781
900
  hasStale: boolean,
782
901
  staleValue: T | undefined,
783
- ): Promise<T> {
784
- const run = async (): Promise<T> => {
902
+ staleTags: string[],
903
+ ): Promise<FactoryOutcome<T>> {
904
+ const run = async (): Promise<FactoryOutcome<T>> => {
785
905
  try {
786
- 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();
787
917
  await this.#writeValue(
788
918
  prefixed,
789
919
  value,
@@ -795,17 +925,102 @@ export class CacheManager {
795
925
  key: o.key,
796
926
  value,
797
927
  store: this.#name,
928
+ ttl: reportedTtl(o.ttlSeconds),
929
+ duration: this.#since(writing),
798
930
  });
799
- return value;
931
+ return { value, fresh: true };
800
932
  } catch (error) {
801
933
  o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
802
- 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
+ }
803
938
  throw error;
804
939
  } finally {
805
- 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
+ }
806
944
  }
807
945
  };
808
- 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;
809
1024
  }
810
1025
 
811
1026
  getOrSet<T>(key: string, ttlSeconds: number, factory: Factory<T>): Promise<T>;
@@ -815,8 +1030,9 @@ export class CacheManager {
815
1030
  b?: number,
816
1031
  c?: Factory<T>,
817
1032
  ): Promise<T> {
1033
+ const started = performance.now();
818
1034
  await this.#whenConnected();
819
- const o = this.#normalizeGetOrSet<T>(a, b, c);
1035
+ const o = this.#normalizeGetOrSet<T>(a, b, c, started);
820
1036
  const prefixed = this.#prefixKey(o.key);
821
1037
 
822
1038
  const entry = await this.#readEntry<T>(prefixed);
@@ -826,29 +1042,34 @@ export class CacheManager {
826
1042
  value: entry.value,
827
1043
  store: this.#name,
828
1044
  graced: false,
1045
+ duration: this.#since(started),
829
1046
  });
830
1047
  return entry.value;
831
1048
  }
832
1049
 
833
1050
  const hasStale = entry?.stale === true && o.graceSeconds > 0;
834
1051
  const staleValue = hasStale ? entry.value : undefined;
1052
+ const staleTags = hasStale ? (entry.tags ?? []) : [];
835
1053
 
836
1054
  const record = this.#shared.inflight.get(prefixed);
837
1055
  // Joining another caller's factory, rather than running our own.
838
1056
  const joined = record !== undefined;
839
- let factoryPromise: Promise<T>;
1057
+ let factoryPromise: Promise<FactoryOutcome<T>>;
840
1058
  if (record === undefined) {
841
1059
  factoryPromise = this.#invokeFactory<T>(
842
1060
  prefixed,
843
1061
  o,
844
1062
  hasStale,
845
1063
  staleValue,
1064
+ staleTags,
846
1065
  );
847
- this.#shared.inflight.set(prefixed, { promise: factoryPromise });
848
1066
  } else {
849
1067
  // The map holds every key's factory, whatever its type; what the
850
1068
  // leader computes for this key is what this caller reads.
851
- factoryPromise = record.promise.then((value) => claimed<T>(value));
1069
+ factoryPromise = record.promise.then((value) => ({
1070
+ value: claimed<T>(value),
1071
+ fresh: false,
1072
+ }));
852
1073
  }
853
1074
 
854
1075
  if (hasStale && staleValue !== undefined) {
@@ -866,10 +1087,11 @@ export class CacheManager {
866
1087
  value: staleValue,
867
1088
  store: this.#name,
868
1089
  graced: true,
1090
+ duration: this.#since(started),
869
1091
  });
870
1092
  return staleValue;
871
1093
  }
872
- return result;
1094
+ return this.#settled(o, result, !joined);
873
1095
  }
874
1096
 
875
1097
  // A joiner waits at most `lockTimeout` for the leader, stale value or
@@ -882,17 +1104,17 @@ export class CacheManager {
882
1104
  if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
883
1105
  const result = await withTimeout(factoryPromise, lockMs);
884
1106
  if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
885
- return result;
1107
+ return this.#settled(o, result, !joined);
886
1108
  }
887
1109
  if (hardMs !== undefined) {
888
1110
  const result = await withTimeout(factoryPromise, hardMs);
889
1111
  if (result === TIMEOUT) {
890
1112
  throw new TimeoutError(o.key, hardMs);
891
1113
  }
892
- return result;
1114
+ return this.#settled(o, result, !joined);
893
1115
  }
894
1116
 
895
- return factoryPromise;
1117
+ return this.#settled(o, await factoryPromise, !joined);
896
1118
  }
897
1119
 
898
1120
  /** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
@@ -57,6 +57,8 @@ export interface StoreConfig {
57
57
  */
58
58
  ttl?: Duration;
59
59
  grace?: Duration;
60
+ /** How long a stale value stands in after its factory failed (default `'10s'`). */
61
+ graceBackoff?: Duration;
60
62
  timeout?: Duration;
61
63
  hardTimeout?: Duration;
62
64
  lockTimeout?: Duration;
@@ -169,6 +171,16 @@ export function store(options?: Omit<StoreConfig, "driver">): Store {
169
171
  return new Store(options);
170
172
  }
171
173
 
174
+ /** Either accepted form of a store: a {@link Store} builder, or `{ driver, … }`. */
175
+ function isStoreDeclaration(value: unknown): value is StoreConfig | Store {
176
+ if (value instanceof Store) return true;
177
+ return (
178
+ typeof value === "object" &&
179
+ value !== null &&
180
+ typeof Reflect.get(value, "driver") === "function"
181
+ );
182
+ }
183
+
172
184
  /** Normalise either accepted form to the one the manager reads. */
173
185
  function entryOf(config: StoreConfig | Store): StoreConfig {
174
186
  return config instanceof Store ? config.entry() : config;
@@ -251,6 +263,7 @@ export class CacheStoreManager {
251
263
  "cache:written": new Set(),
252
264
  "cache:deleted": new Set(),
253
265
  "cache:cleared": new Set(),
266
+ "cache:expire": new Set(),
254
267
  };
255
268
 
256
269
  constructor(config: MultiStoreConfig) {
@@ -266,11 +279,22 @@ export class CacheStoreManager {
266
279
  /**
267
280
  * A store declared under `name` in the config's OWN keys: a plain lookup
268
281
  * would answer `toString` or `constructor` with an Object.prototype member.
282
+ *
283
+ * And one that IS a store. A config is read at runtime, from a file the
284
+ * type checker may never have seen: an own key holding `{}` or `null`
285
+ * passed the lookup, then failed on `cfg.driver(...)` with a bare
286
+ * TypeError, far from the line at fault.
269
287
  */
270
288
  #declared(name: string): MultiStoreConfig["stores"][string] | undefined {
271
- return Object.hasOwn(this.#config.stores, name)
272
- ? this.#config.stores[name]
273
- : undefined;
289
+ if (!Object.hasOwn(this.#config.stores, name)) return undefined;
290
+ const declared: unknown = this.#config.stores[name];
291
+ if (!isStoreDeclaration(declared)) {
292
+ throw new EchoError(
293
+ "E_ECHO_INVALID_CONFIG",
294
+ `Echo: cache store "${name}" is not a store — declare it with store().useL1Layer(…) or as { driver: drivers.memory() }`,
295
+ );
296
+ }
297
+ return declared;
274
298
  }
275
299
 
276
300
  /** The store `use()` answers with no name (upstream `defaultStoreName`). */
@@ -297,6 +321,7 @@ export class CacheStoreManager {
297
321
  // The store's own, or the one every store inherits.
298
322
  ttl: cfg.ttl ?? this.#config.ttl,
299
323
  grace: cfg.grace,
324
+ graceBackoff: cfg.graceBackoff,
300
325
  timeout: cfg.timeout,
301
326
  hardTimeout: cfg.hardTimeout,
302
327
  lockTimeout: cfg.lockTimeout,
@@ -316,6 +341,7 @@ export class CacheStoreManager {
316
341
  replay("cache:written");
317
342
  replay("cache:deleted");
318
343
  replay("cache:cleared");
344
+ replay("cache:expire");
319
345
  // So `cache.use('other')` works on whichever store the provider
320
346
  // published — upstream's manager is one object that both operates on
321
347
  // the default store and reaches the named ones.
@@ -367,14 +393,29 @@ export class CacheStoreManager {
367
393
  return this;
368
394
  }
369
395
 
370
- /** Clear every store that has been built (bentocache `clearAll`). */
396
+ /**
397
+ * Every store the config declares, built here if this process has not
398
+ * used it yet. Walking only the built ones skipped a store another
399
+ * process writes to: a maintenance script's `clearAll` left its keys.
400
+ */
401
+ #everyStore(): CacheManager[] {
402
+ return Object.keys(this.#config.stores).map((name) => this.use(name));
403
+ }
404
+
405
+ /** Clear every configured store (bentocache `clearAll`). */
371
406
  async clearAll(): Promise<void> {
372
- await Promise.all([...this.#built.values()].map((m) => m.clear()));
407
+ await Promise.all(this.#everyStore().map((m) => m.clear()));
373
408
  }
374
409
 
375
- /** Prune expired entries in every built store (bentocache `prune`). */
410
+ /**
411
+ * Prune expired entries in every configured store (bentocache `prune`).
412
+ *
413
+ * NAMED DEVIATION: upstream's manager prunes the default store only; a
414
+ * store that needs pruning is no less in need of it for not being the
415
+ * default, so every configured one is reached, as `clearAll` does.
416
+ */
376
417
  async prune(): Promise<void> {
377
- await Promise.all([...this.#built.values()].map((m) => m.prune()));
418
+ await Promise.all(this.#everyStore().map((m) => m.prune()));
378
419
  }
379
420
 
380
421
  /**