@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,6 +8,8 @@
8
8
  * shared, so only L1 needs cross-instance invalidation.
9
9
  */
10
10
 
11
+ import { type Duration, resolveTtlSeconds } from "../duration.js";
12
+ import { EchoError, L2CacheError } from "../errors.js";
11
13
  import type {
12
14
  CacheDriver,
13
15
  CacheEntry,
@@ -45,6 +47,40 @@ export interface BusMessage {
45
47
  * already did.
46
48
  */
47
49
  senderId?: string;
50
+ /**
51
+ * The store that published it. Several stores — and several applications
52
+ * — can share one channel, and a message carried no store: one store's
53
+ * write dropped another store's L1 copy of the same key, and its
54
+ * deleteByTag flushed every other store's L1. A tier with a store name
55
+ * acts only on messages carrying the same one, as upstream drops messages
56
+ * for caches it does not manage.
57
+ */
58
+ store?: string;
59
+ }
60
+
61
+ /**
62
+ * Whether a received frame is an invalidation message, field by field.
63
+ *
64
+ * A bus hands over whatever arrived on the channel. Trusted as is, a string
65
+ * `keys` was iterated character by character, any unknown `type` read as a
66
+ * delete, and a missing `keys` threw inside the handler.
67
+ */
68
+ export function isBusMessage(value: unknown): value is BusMessage {
69
+ if (typeof value !== "object" || value === null) return false;
70
+ const type = Reflect.get(value, "type");
71
+ const keys = Reflect.get(value, "keys");
72
+ const optional = (name: string): boolean => {
73
+ const field = Reflect.get(value, name);
74
+ return field === undefined || typeof field === "string";
75
+ };
76
+ return (
77
+ (type === "delete" || type === "clear") &&
78
+ Array.isArray(keys) &&
79
+ keys.every((key) => typeof key === "string") &&
80
+ optional("prefix") &&
81
+ optional("senderId") &&
82
+ optional("store")
83
+ );
48
84
  }
49
85
 
50
86
  /** Duck-typed pub/sub bus for cross-instance L1 invalidation (e.g. Redis pub/sub). */
@@ -81,6 +117,30 @@ export interface TieredDriverOptions {
81
117
  l1: CacheDriver;
82
118
  l2: CacheDriver;
83
119
  bus?: CacheBus;
120
+ /**
121
+ * Treat a failed L2 read as a miss and a failed L2 write as skipped,
122
+ * rather than failing the call (upstream `suppressL2Errors`). Default
123
+ * `true`: there is an L1 to serve from, so a Redis outage costs hit rate,
124
+ * not every request. `false` surfaces each failure as an
125
+ * {@link L2CacheError}.
126
+ *
127
+ * Invalidations — `delete`, `flush`, `deleteByTag` — report a failed L2
128
+ * either way: a removal that did not reach the shared tier leaves the
129
+ * value served to every other instance, and the caller has to know.
130
+ */
131
+ suppressL2Errors?: boolean;
132
+ /**
133
+ * After an L2 failure, skip the L2 for this long instead of waiting on a
134
+ * dead server for every call (upstream `l2CircuitBreakerDuration`).
135
+ * Off by default.
136
+ */
137
+ l2CircuitBreakerDuration?: Duration;
138
+ /**
139
+ * The store this tier belongs to, stamped on what it publishes and
140
+ * required on what it acts on. Set by the store manager from the config
141
+ * key; a tier without one acts on every well-formed message.
142
+ */
143
+ store?: string;
84
144
  }
85
145
 
86
146
  function isTaggable(driver: CacheDriver): driver is TaggableDriver {
@@ -148,14 +208,32 @@ export class TieredDriver implements TaggableDriver {
148
208
  /** This tier, as a bus sender. */
149
209
  readonly #id = crypto.randomUUID();
150
210
 
211
+ readonly #store: string | undefined;
212
+ readonly #suppressL2Errors: boolean;
213
+ /** How long the breaker stays open after an L2 failure; `0` for no breaker. */
214
+ readonly #breakerMs: number;
215
+ /** Until when (epoch ms) the L2 is skipped. */
216
+ #breakerUntil = 0;
217
+ /** Whether the last L2 call failed — so an outage is reported once, not per call. */
218
+ #l2Failing = false;
219
+
151
220
  constructor(options: TieredDriverOptions) {
152
221
  this.#l1 = options.l1;
153
222
  this.#l2 = options.l2;
154
223
  this.#bus = options.bus;
224
+ this.#suppressL2Errors = options.suppressL2Errors ?? true;
225
+ this.#breakerMs =
226
+ Math.max(0, resolveTtlSeconds(options.l2CircuitBreakerDuration, 0)) *
227
+ 1000;
228
+ this.#store = options.store;
155
229
  this.#onPeerMessage = (message: BusMessage): void => {
230
+ // Checked here and not only in the transport: a custom bus hands
231
+ // over whatever it received.
232
+ if (!isBusMessage(message)) return;
156
233
  // Our own invalidation, come back round the bus. Acting on it would
157
234
  // undo the write that sent it.
158
235
  if (message.senderId === this.#id) return;
236
+ if (this.#store !== undefined && message.store !== this.#store) return;
159
237
  // Peer invalidation: only the local L1 needs clearing (L2 is shared).
160
238
  if (message.type === "clear") {
161
239
  this.#invalidate("flush", () => this.#l1.flush(message.prefix));
@@ -226,11 +304,70 @@ export class TieredDriver implements TaggableDriver {
226
304
  });
227
305
  }
228
306
 
307
+ /**
308
+ * Run a read or write against L2, the way upstream's remote cache does:
309
+ * skipped while the breaker is open, and on failure either answered by
310
+ * `fallback` (suppressed) or raised as an {@link L2CacheError}.
311
+ */
312
+ async #onL2<T>(
313
+ operation: string,
314
+ run: () => Promise<T>,
315
+ fallback: T,
316
+ ): Promise<{ ok: true; value: T } | { ok: false; value: T }> {
317
+ if (Date.now() < this.#breakerUntil) return { ok: false, value: fallback };
318
+ try {
319
+ const value = await run();
320
+ this.#l2Failing = false;
321
+ return { ok: true, value };
322
+ } catch (error) {
323
+ this.#l2Failed(operation, error);
324
+ if (this.#suppressL2Errors) return { ok: false, value: fallback };
325
+ throw new L2CacheError(operation, error);
326
+ }
327
+ }
328
+
329
+ /** Open the breaker, and report the outage when it starts. */
330
+ #l2Failed(operation: string, error: unknown): void {
331
+ if (this.#breakerMs > 0) this.#breakerUntil = Date.now() + this.#breakerMs;
332
+ if (this.#l2Failing) return;
333
+ this.#l2Failing = true;
334
+ process.stderr.write(
335
+ `[echo] tiered L2 ${operation} failed; serving from L1 until it answers again: ${
336
+ error instanceof Error ? error.message : String(error)
337
+ }\n`,
338
+ );
339
+ }
340
+
341
+ /**
342
+ * Run an invalidation against L2. Never suppressed and never skipped by
343
+ * the breaker: a removal that did not reach the shared tier leaves the
344
+ * value there for every other instance. NAMED DEVIATION — upstream
345
+ * suppresses these too; reporting them is the safer side.
346
+ */
347
+ async #invalidateL2<T>(
348
+ operation: string,
349
+ run: () => Promise<T>,
350
+ ): Promise<{ ok: true; value: T } | { ok: false; error: unknown }> {
351
+ try {
352
+ const value = await run();
353
+ this.#l2Failing = false;
354
+ return { ok: true, value };
355
+ } catch (error) {
356
+ this.#l2Failed(operation, error);
357
+ return { ok: false, error: new L2CacheError(operation, error) };
358
+ }
359
+ }
360
+
229
361
  async getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null> {
230
362
  const l1 = await readEntry<T>(this.#l1, key);
231
363
  if (l1 && !l1.stale) return l1;
232
364
 
233
- const l2 = await readEntry<T>(this.#l2, key);
365
+ // A failed L2 read is a miss: the stale L1 copy, if any, still serves.
366
+ const { value: l2 } = await this.#onL2(
367
+ "read",
368
+ () => readEntry<T>(this.#l2, key),
369
+ null,
370
+ );
234
371
  if (l2 && !l2.stale) {
235
372
  // Promote a fresh L2 hit into L1 — preserving the remaining logical TTL
236
373
  // so L1 cannot outlive L2 (a promotion with no TTL left an immortal L1
@@ -240,7 +377,10 @@ export class TieredDriver implements TaggableDriver {
240
377
  // immortal L1 copy; skip promotion rather than cache it forever.
241
378
  return l2;
242
379
  }
243
- const opts: DriverSetOptions = {};
380
+ // With its tags: a copy promoted without them was invisible to
381
+ // deleteByTag on this very instance, which skips its own bus
382
+ // message — so a revoked entry kept being served from here.
383
+ const opts: DriverSetOptions = l2.tags ? { tags: l2.tags } : {};
244
384
  if (l2.expiresAt > 0) {
245
385
  const remainingSeconds = (l2.expiresAt - Date.now()) / 1000;
246
386
  // Raced past expiry between the stale check and now — don't promote
@@ -273,16 +413,26 @@ export class TieredDriver implements TaggableDriver {
273
413
  options: DriverSetOptions,
274
414
  ): Promise<void> {
275
415
  const l1 = await settle(() => writeEntry(this.#l1, key, value, options));
276
- const l2 = await settle(() => writeEntry(this.#l2, key, value, options));
416
+ const l2 = await settle(() =>
417
+ this.#onL2(
418
+ "write",
419
+ async () => {
420
+ await writeEntry(this.#l2, key, value, options);
421
+ return true;
422
+ },
423
+ false,
424
+ ),
425
+ );
277
426
  // Peers are told only when the shared write landed. Telling them to drop
278
427
  // their L1 for a value that never reached L2 sends every one of them to a
279
428
  // tier that does not have it. Upstream gates the same publish on the same
280
429
  // thing (`if (this.l2 && l2Success || !this.l2)`).
281
- if (l2.ok) {
430
+ if (l2.ok && l2.value.ok) {
282
431
  await this.#bus?.publish({
283
432
  type: "delete",
284
433
  keys: [key],
285
434
  senderId: this.#id,
435
+ store: this.#store,
286
436
  });
287
437
  }
288
438
  if (!l1.ok) throw l1.error;
@@ -291,12 +441,13 @@ export class TieredDriver implements TaggableDriver {
291
441
 
292
442
  async delete(key: string): Promise<boolean> {
293
443
  const l1 = await settle(() => this.#l1.delete(key));
294
- const l2 = await settle(() => this.#l2.delete(key));
444
+ const l2 = await this.#invalidateL2("delete", () => this.#l2.delete(key));
295
445
  if (l2.ok) {
296
446
  await this.#bus?.publish({
297
447
  type: "delete",
298
448
  keys: [key],
299
449
  senderId: this.#id,
450
+ store: this.#store,
300
451
  });
301
452
  }
302
453
  if (!l1.ok) throw l1.error;
@@ -306,7 +457,7 @@ export class TieredDriver implements TaggableDriver {
306
457
 
307
458
  async flush(prefix?: string): Promise<void> {
308
459
  const l1 = await settle(() => this.#l1.flush(prefix));
309
- const l2 = await settle(() => this.#l2.flush(prefix));
460
+ const l2 = await this.#invalidateL2("flush", () => this.#l2.flush(prefix));
310
461
  if (l2.ok) {
311
462
  // The prefix travels: a peer that flushed its WHOLE L1 on a
312
463
  // namespaced clear would throw away every other tenant's entries
@@ -316,6 +467,7 @@ export class TieredDriver implements TaggableDriver {
316
467
  keys: [],
317
468
  prefix,
318
469
  senderId: this.#id,
470
+ store: this.#store,
319
471
  });
320
472
  }
321
473
  if (!l1.ok) throw l1.error;
@@ -339,16 +491,24 @@ export class TieredDriver implements TaggableDriver {
339
491
  const l1 = this.#l1;
340
492
  const l2 = this.#l2;
341
493
  if (!isTaggable(l1) || !isTaggable(l2)) {
342
- throw new Error(
494
+ throw new EchoError(
495
+ "E_ECHO_NOT_TAGGABLE",
343
496
  "Echo: TieredDriver.deleteByTag requires both tiers to be taggable",
344
497
  );
345
498
  }
346
499
  const local = await settle(() => l1.deleteByTag(tags));
347
- const shared = await settle(() => l2.deleteByTag(tags));
500
+ const shared = await this.#invalidateL2("deleteByTag", () =>
501
+ l2.deleteByTag(tags),
502
+ );
348
503
  // Peers can't map tags → keys locally; broadcast a clear so their L1 drops
349
504
  // any tagged copies (conservative but correct).
350
505
  if (shared.ok) {
351
- await this.#bus?.publish({ type: "clear", keys: [], senderId: this.#id });
506
+ await this.#bus?.publish({
507
+ type: "clear",
508
+ keys: [],
509
+ senderId: this.#id,
510
+ store: this.#store,
511
+ });
352
512
  }
353
513
  if (!local.ok) throw local.error;
354
514
  if (!shared.ok) throw shared.error;
package/src/duration.ts CHANGED
@@ -47,6 +47,8 @@ const UNIT_SECONDS: Record<string, number> = {
47
47
  weeks: 604_800,
48
48
  };
49
49
 
50
+ import { InvalidDurationError } from "./errors.js";
51
+
50
52
  const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
51
53
 
52
54
  /**
@@ -56,14 +58,16 @@ const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
56
58
  export function parseDuration(value: string): number {
57
59
  const match = DURATION_RE.exec(value);
58
60
  if (!match) {
59
- throw new TypeError(`Echo: invalid duration string "${value}"`);
61
+ throw new InvalidDurationError(`Echo: invalid duration string "${value}"`);
60
62
  }
61
63
  const amount = Number(match[1]);
62
64
  const unit = match[2]?.toLowerCase();
63
65
  if (unit === undefined) return amount;
64
66
  const factor = UNIT_SECONDS[unit];
65
67
  if (factor === undefined) {
66
- throw new TypeError(`Echo: unknown duration unit "${unit}" in "${value}"`);
68
+ throw new InvalidDurationError(
69
+ `Echo: unknown duration unit "${unit}" in "${value}"`,
70
+ );
67
71
  }
68
72
  return amount * factor;
69
73
  }
@@ -71,9 +75,12 @@ export function parseDuration(value: string): number {
71
75
  /**
72
76
  * Resolve a {@link Duration} to a TTL in **seconds**.
73
77
  *
74
- * @returns the TTL in seconds; `0` means "never expires" (either an explicit
75
- * `null`, or a non-positive value, matching echo's driver convention where
76
- * `ttlSeconds <= 0` is treated as immortal).
78
+ * @returns the TTL in seconds. `0` means "never expires" — an explicit
79
+ * `null`, a `0` or `Infinity`. A NEGATIVE result is kept negative: a TTL in
80
+ * the past means already expired, and the writers drop the entry rather
81
+ * than store it. It used to map to `0`, so a TTL computed from data — a
82
+ * token that had already expired — cached its value forever.
83
+ * @throws {InvalidDurationError} for NaN, which means nothing at all.
77
84
  */
78
85
  export function resolveTtlSeconds(
79
86
  ttl: Duration | undefined,
@@ -81,6 +88,20 @@ export function resolveTtlSeconds(
81
88
  ): number {
82
89
  if (ttl === null) return 0;
83
90
  if (ttl === undefined) return defaultSeconds;
84
- const seconds = typeof ttl === "number" ? ttl : parseDuration(ttl);
85
- return seconds > 0 ? seconds : 0;
91
+ return checkTtlSeconds(typeof ttl === "number" ? ttl : parseDuration(ttl));
92
+ }
93
+
94
+ /**
95
+ * The driver-level reading of a TTL in seconds: `undefined`, `0` and
96
+ * `Infinity` never expire, a negative one has already expired, NaN is
97
+ * refused. Shared by the manager and the drivers, so a driver called directly
98
+ * cannot turn a NaN into an entry that never expires either.
99
+ */
100
+ export function checkTtlSeconds(seconds: number): number {
101
+ if (Number.isNaN(seconds)) {
102
+ throw new InvalidDurationError(
103
+ "Echo: a TTL of NaN is not a duration — pass a number of seconds, a string like '5m', or null for no expiry",
104
+ );
105
+ }
106
+ return seconds === Number.POSITIVE_INFINITY ? 0 : seconds;
86
107
  }
package/src/errors.ts CHANGED
@@ -1,12 +1,78 @@
1
1
  /**
2
2
  * Echo cache errors — bentocache parity (`errors.ts`).
3
+ *
4
+ * Every error carries a `code`. Upstream's are kept verbatim
5
+ * (`E_FACTORY_ERROR`, `E_FACTORY_HARD_TIMEOUT`, `E_UNDEFINED_VALUE`,
6
+ * `E_L2_CACHE_ERROR`): code written against a cache module already catches on
7
+ * them. Failures echo invents carry the `E_ECHO_` namespace.
3
8
  */
4
9
 
10
+ /**
11
+ * Base class for the errors echo raises with a code of its own, so a caller
12
+ * can match on `error.code`.
13
+ */
14
+ export class EchoError extends Error {
15
+ readonly code: string;
16
+
17
+ constructor(code: string, message: string, options?: ErrorOptions) {
18
+ super(message, options);
19
+ this.name = new.target.name;
20
+ this.code = code;
21
+ }
22
+ }
23
+
24
+ /**
25
+ * Raised for a duration that cannot mean anything: NaN, or a string the
26
+ * parser does not read. A `TypeError`, as the parser's refusals always were.
27
+ */
28
+ export class InvalidDurationError extends TypeError {
29
+ readonly code = "E_ECHO_INVALID_DURATION";
30
+
31
+ constructor(message: string) {
32
+ super(message);
33
+ this.name = "InvalidDurationError";
34
+ }
35
+ }
36
+
37
+ /**
38
+ * Raised when a caller waited `lockTimeout` on another caller's factory for
39
+ * the same key, had no stale value to fall back on, and gave up.
40
+ */
41
+ export class LockTimeoutError extends EchoError {
42
+ /** The cache key whose lock was not obtained. */
43
+ readonly key: string;
44
+
45
+ constructor(key: string, timeoutMs: number) {
46
+ super(
47
+ "E_ECHO_LOCK_TIMEOUT",
48
+ `Echo: waited ${timeoutMs}ms for another caller's factory for "${key}" and gave up`,
49
+ );
50
+ this.key = key;
51
+ }
52
+ }
53
+
54
+ /**
55
+ * Raised when a tiered store's L2 fails and the failure is not suppressed
56
+ * (upstream `E_L2_CACHE_ERROR`, kept verbatim). `cause` is the L2's error.
57
+ */
58
+ export class L2CacheError extends EchoError {
59
+ constructor(operation: string, cause: unknown) {
60
+ const reason = cause instanceof Error ? cause.message : String(cause);
61
+ super(
62
+ "E_L2_CACHE_ERROR",
63
+ `Echo: the L2 cache failed during ${operation}: ${reason}`,
64
+ { cause },
65
+ );
66
+ }
67
+ }
68
+
5
69
  /** Raised when a factory exceeds its configured `hardTimeout`. */
6
- export class TimeoutError extends Error {
70
+ export class TimeoutError extends EchoError {
7
71
  constructor(key: string, timeoutMs: number) {
8
- super(`Echo: factory for "${key}" timed out after ${timeoutMs}ms`);
9
- this.name = "TimeoutError";
72
+ super(
73
+ "E_FACTORY_HARD_TIMEOUT",
74
+ `Echo: factory for "${key}" timed out after ${timeoutMs}ms`,
75
+ );
10
76
  }
11
77
  }
12
78
 
@@ -14,7 +80,7 @@ export class TimeoutError extends Error {
14
80
  * Wraps an error thrown by a `getOrSet` factory. Passed to `onFactoryError`
15
81
  * so callers can observe both foreground and background factory failures.
16
82
  */
17
- export class FactoryError extends Error {
83
+ export class FactoryError extends EchoError {
18
84
  /** The cache key the factory was computing. */
19
85
  readonly key: string;
20
86
  /** The original error thrown by the factory. */
@@ -24,10 +90,41 @@ export class FactoryError extends Error {
24
90
 
25
91
  constructor(key: string, cause: unknown, isBackground: boolean) {
26
92
  const reason = cause instanceof Error ? cause.message : String(cause);
27
- super(`Echo: factory for "${key}" failed: ${reason}`);
28
- this.name = "FactoryError";
93
+ super("E_FACTORY_ERROR", `Echo: factory for "${key}" failed: ${reason}`);
29
94
  this.key = key;
30
95
  this.cause = cause;
31
96
  this.isBackground = isBackground;
32
97
  }
33
98
  }
99
+
100
+ /**
101
+ * Raised for a `null` or `undefined` value — upstream's `E_UNDEFINED_VALUE`.
102
+ * A `TypeError`, as this refusal always was. Echo refuses `null` as well: a
103
+ * null cache write is almost always a bug.
104
+ */
105
+ export class UndefinedValueError extends TypeError {
106
+ readonly code = "E_UNDEFINED_VALUE";
107
+
108
+ constructor() {
109
+ super("Echo: caching null/undefined values is not supported");
110
+ this.name = "UndefinedValueError";
111
+ }
112
+ }
113
+
114
+ /** Raised for an argument a method cannot work with. A `TypeError`. */
115
+ export class InvalidArgumentError extends TypeError {
116
+ readonly code = "E_ECHO_INVALID_ARGUMENT";
117
+
118
+ constructor(message: string) {
119
+ super(message);
120
+ this.name = "InvalidArgumentError";
121
+ }
122
+ }
123
+
124
+ /** Upstream's `errors` map, by code. */
125
+ export const errors = {
126
+ E_FACTORY_ERROR: FactoryError,
127
+ E_FACTORY_HARD_TIMEOUT: TimeoutError,
128
+ E_UNDEFINED_VALUE: UndefinedValueError,
129
+ E_L2_CACHE_ERROR: L2CacheError,
130
+ };
package/src/index.ts CHANGED
@@ -13,7 +13,10 @@ import "./augmentations.js";
13
13
 
14
14
  export type { CacheConfig, CacheDriver } from "./CacheManager.js";
15
15
  export { CacheManager } from "./CacheManager.js";
16
- export { MemoryDriver } from "./drivers/MemoryDriver.js";
16
+ export {
17
+ MemoryDriver,
18
+ type MemoryDriverOptions,
19
+ } from "./drivers/MemoryDriver.js";
17
20
  export type { RedisClient } from "./drivers/RedisDriver.js";
18
21
  export { RedisDriver } from "./drivers/RedisDriver.js";
19
22
  export type {
@@ -21,13 +24,24 @@ export type {
21
24
  CacheBus,
22
25
  TieredDriverOptions,
23
26
  } from "./drivers/TieredDriver.js";
24
- export { TieredDriver } from "./drivers/TieredDriver.js";
27
+ export { isBusMessage, TieredDriver } from "./drivers/TieredDriver.js";
25
28
  export type { Duration } from "./duration.js";
26
29
  export { parseDuration, resolveTtlSeconds } from "./duration.js";
27
30
  export type { EchoProviderConfig } from "./EchoProvider.js";
28
- export { FactoryError, TimeoutError } from "./errors.js";
31
+ export {
32
+ EchoError,
33
+ errors,
34
+ FactoryError,
35
+ InvalidArgumentError,
36
+ InvalidDurationError,
37
+ L2CacheError,
38
+ LockTimeoutError,
39
+ TimeoutError,
40
+ UndefinedValueError,
41
+ } from "./errors.js";
29
42
  export {
30
43
  CacheStoreManager,
44
+ type DriverContext,
31
45
  type DriverFactory,
32
46
  drivers,
33
47
  type MultiStoreConfig,