@c9up/echo 0.2.2 → 0.2.4

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 (114) hide show
  1. package/dist/CacheManager.d.ts +2 -0
  2. package/dist/CacheManager.d.ts.map +1 -1
  3. package/dist/CacheManager.js +92 -32
  4. package/dist/CacheManager.js.map +1 -1
  5. package/dist/EchoProvider.d.ts.map +1 -1
  6. package/dist/EchoProvider.js +32 -3
  7. package/dist/EchoProvider.js.map +1 -1
  8. package/dist/StoreManager.d.ts +28 -9
  9. package/dist/StoreManager.d.ts.map +1 -1
  10. package/dist/StoreManager.js +42 -18
  11. package/dist/StoreManager.js.map +1 -1
  12. package/dist/bytes.d.ts +13 -0
  13. package/dist/bytes.d.ts.map +1 -0
  14. package/dist/bytes.js +35 -0
  15. package/dist/bytes.js.map +1 -0
  16. package/dist/claim.d.ts +15 -0
  17. package/dist/claim.d.ts.map +1 -0
  18. package/dist/claim.js +10 -0
  19. package/dist/claim.js.map +1 -0
  20. package/dist/configure.d.ts +7 -0
  21. package/dist/configure.d.ts.map +1 -1
  22. package/dist/configure.js +5 -18
  23. package/dist/configure.js.map +1 -1
  24. package/dist/console/cacheClear.d.ts +13 -0
  25. package/dist/console/cacheClear.d.ts.map +1 -0
  26. package/dist/console/cacheClear.js +69 -0
  27. package/dist/console/cacheClear.js.map +1 -0
  28. package/dist/console/cacheDelete.d.ts +11 -0
  29. package/dist/console/cacheDelete.d.ts.map +1 -0
  30. package/dist/console/cacheDelete.js +42 -0
  31. package/dist/console/cacheDelete.js.map +1 -0
  32. package/dist/console/cachePrune.d.ts +9 -0
  33. package/dist/console/cachePrune.d.ts.map +1 -0
  34. package/dist/console/cachePrune.js +35 -0
  35. package/dist/console/cachePrune.js.map +1 -0
  36. package/dist/console/contract.d.ts +64 -0
  37. package/dist/console/contract.d.ts.map +1 -0
  38. package/dist/console/contract.js +32 -0
  39. package/dist/console/contract.js.map +1 -0
  40. package/dist/console/index.d.ts +25 -0
  41. package/dist/console/index.d.ts.map +1 -0
  42. package/dist/console/index.js +38 -0
  43. package/dist/console/index.js.map +1 -0
  44. package/dist/console/store.d.ts +14 -0
  45. package/dist/console/store.d.ts.map +1 -0
  46. package/dist/console/store.js +35 -0
  47. package/dist/console/store.js.map +1 -0
  48. package/dist/drivers/MemoryDriver.d.ts +36 -1
  49. package/dist/drivers/MemoryDriver.d.ts.map +1 -1
  50. package/dist/drivers/MemoryDriver.js +157 -62
  51. package/dist/drivers/MemoryDriver.js.map +1 -1
  52. package/dist/drivers/RedisDriver.d.ts +13 -8
  53. package/dist/drivers/RedisDriver.d.ts.map +1 -1
  54. package/dist/drivers/RedisDriver.js +171 -94
  55. package/dist/drivers/RedisDriver.js.map +1 -1
  56. package/dist/drivers/TieredDriver.d.ts +42 -0
  57. package/dist/drivers/TieredDriver.d.ts.map +1 -1
  58. package/dist/drivers/TieredDriver.js +114 -9
  59. package/dist/drivers/TieredDriver.js.map +1 -1
  60. package/dist/duration.d.ts +13 -3
  61. package/dist/duration.d.ts.map +1 -1
  62. package/dist/duration.js +22 -7
  63. package/dist/duration.js.map +1 -1
  64. package/dist/errors.d.ts +60 -2
  65. package/dist/errors.d.ts.map +1 -1
  66. package/dist/errors.js +81 -6
  67. package/dist/errors.js.map +1 -1
  68. package/dist/index.d.ts +4 -4
  69. package/dist/index.d.ts.map +1 -1
  70. package/dist/index.js +3 -3
  71. package/dist/index.js.map +1 -1
  72. package/dist/quasar.d.ts +1 -1
  73. package/dist/quasar.d.ts.map +1 -1
  74. package/dist/quasar.js +27 -6
  75. package/dist/quasar.js.map +1 -1
  76. package/dist/services/main.d.ts +1 -1
  77. package/dist/services/main.d.ts.map +1 -1
  78. package/dist/services/main.js +22 -5
  79. package/dist/services/main.js.map +1 -1
  80. package/dist/stubs.d.ts +14 -0
  81. package/dist/stubs.d.ts.map +1 -0
  82. package/dist/stubs.js +15 -0
  83. package/dist/stubs.js.map +1 -0
  84. package/dist/types.d.ts +12 -1
  85. package/dist/types.d.ts.map +1 -1
  86. package/dist/vendor/quasarConnection.d.ts +26 -3
  87. package/dist/vendor/quasarConnection.d.ts.map +1 -1
  88. package/dist/vendor/quasarConnection.js +44 -23
  89. package/dist/vendor/quasarConnection.js.map +1 -1
  90. package/package.json +8 -3
  91. package/src/CacheManager.ts +117 -41
  92. package/src/EchoProvider.ts +45 -4
  93. package/src/StoreManager.ts +86 -31
  94. package/src/bytes.ts +38 -0
  95. package/src/claim.ts +22 -0
  96. package/src/configure.ts +13 -21
  97. package/src/console/cacheClear.ts +96 -0
  98. package/src/console/cacheDelete.ts +65 -0
  99. package/src/console/cachePrune.ts +57 -0
  100. package/src/console/contract.ts +93 -0
  101. package/src/console/index.ts +61 -0
  102. package/src/console/store.ts +47 -0
  103. package/src/drivers/MemoryDriver.ts +205 -60
  104. package/src/drivers/RedisDriver.ts +205 -101
  105. package/src/drivers/TieredDriver.ts +169 -9
  106. package/src/duration.ts +28 -7
  107. package/src/errors.ts +103 -6
  108. package/src/index.ts +17 -3
  109. package/src/quasar.ts +44 -8
  110. package/src/services/main.ts +26 -8
  111. package/src/stubs.ts +16 -0
  112. package/src/types.ts +13 -2
  113. package/src/vendor/quasarConnection.ts +84 -22
  114. package/stubs/config/cache.stub +21 -0
@@ -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,40 @@ 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
86
  const TIMEOUT: unique symbol = Symbol("echo.timeout");
54
87
 
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
- );
62
- }
63
-
64
88
  function withTimeout<T>(
65
89
  promise: Promise<T>,
66
90
  ms: number,
@@ -183,10 +207,25 @@ export class CacheManager {
183
207
  this.#shared = shared ?? { inflight: new Map() };
184
208
  }
185
209
 
210
+ /** The store's name, as events report it (upstream `cache.name`). */
211
+ get name(): string {
212
+ return this.#name;
213
+ }
214
+
186
215
  #prefixKey(key: string): string {
187
216
  return this.#prefix ? `${this.#prefix}:${key}` : key;
188
217
  }
189
218
 
219
+ /**
220
+ * Tags live inside the namespace, exactly as keys do. They reached the
221
+ * driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
222
+ * also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
223
+ * same way: its tag invalidations are entries of the namespaced stack.
224
+ */
225
+ #prefixTags(tags: string[]): string[] {
226
+ return tags.map((tag) => this.#prefixKey(tag));
227
+ }
228
+
190
229
  #emit<E extends keyof CacheEventMap>(
191
230
  event: E,
192
231
  payload: CacheEventMap[E],
@@ -287,7 +326,8 @@ export class CacheManager {
287
326
  use(name?: string): CacheManager {
288
327
  if (this.#stores) return this.#stores.use(name);
289
328
  if (name === undefined) return this;
290
- throw new Error(
329
+ throw new EchoError(
330
+ "E_ECHO_UNKNOWN_STORE",
291
331
  `Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
292
332
  "Declare `{ default, stores }` in config/cache.ts to name several.",
293
333
  );
@@ -397,25 +437,43 @@ export class CacheManager {
397
437
  if (value === null || value === undefined) {
398
438
  // Named divergence (fail-loud): unlike bento (which no-ops), echo throws
399
439
  // 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
- );
440
+ throw new UndefinedValueError();
441
+ }
442
+ if (ttlSeconds < 0) {
443
+ // A TTL in the past: the value has already expired. Kept only as
444
+ // a stale copy for its grace window, otherwise dropped — and the
445
+ // key's previous value with it, which a skipped write would have
446
+ // left being served. Upstream deletes the same way when the TTL
447
+ // is not positive and grace is off.
448
+ if (graceSeconds > 0 && this.#driver.setEntry) {
449
+ await this.#driver.setEntry(prefixed, value, {
450
+ expiresAt: Date.now() - 1,
451
+ graceSeconds,
452
+ tags: this.#prefixTags(tags),
453
+ });
454
+ return;
455
+ }
456
+ await this.#driver.delete(prefixed);
457
+ return;
403
458
  }
404
459
  if (this.#driver.setEntry) {
405
460
  await this.#driver.setEntry(prefixed, value, {
406
461
  ttlSeconds,
407
462
  graceSeconds,
408
- tags,
463
+ tags: this.#prefixTags(tags),
409
464
  });
410
465
  return;
411
466
  }
412
467
  if (tags.length > 0) {
413
468
  if (!isTaggableDriver(this.#driver)) {
414
- throw new Error(
415
- "Echo: the configured driver does not support tag-based invalidation",
416
- );
469
+ throw notTaggable();
417
470
  }
418
- await this.#driver.setWithTags(prefixed, value, tags, ttlSeconds);
471
+ await this.#driver.setWithTags(
472
+ prefixed,
473
+ value,
474
+ this.#prefixTags(tags),
475
+ ttlSeconds,
476
+ );
419
477
  return;
420
478
  }
421
479
  await this.#driver.set(prefixed, value, ttlSeconds);
@@ -488,7 +546,7 @@ export class CacheManager {
488
546
  if (typeof keyOrOptions === "string") {
489
547
  key = keyOrOptions;
490
548
  val = value;
491
- ttl = ttlSeconds ?? this.#defaultTtl;
549
+ ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
492
550
  graceSeconds = 0;
493
551
  tags = [];
494
552
  } else {
@@ -619,7 +677,7 @@ export class CacheManager {
619
677
  await this.#writeValue(
620
678
  this.#prefixKey(key),
621
679
  value,
622
- ttlSeconds ?? this.#defaultTtl,
680
+ resolveTtlSeconds(ttlSeconds, this.#defaultTtl),
623
681
  0,
624
682
  tags,
625
683
  );
@@ -637,14 +695,13 @@ export class CacheManager {
637
695
  ? tagsOrOptions
638
696
  : tagsOrOptions.tags;
639
697
  if (!isTaggableDriver(this.#driver)) {
640
- throw new Error(
641
- "Echo: the configured driver does not support tag-based invalidation",
642
- );
698
+ throw notTaggable();
643
699
  }
700
+ const scoped = this.#prefixTags(tags);
644
701
  if (typeof this.#driver.deleteByTag === "function") {
645
- return this.#driver.deleteByTag(tags);
702
+ return this.#driver.deleteByTag(scoped);
646
703
  }
647
- return this.#driver.flushTags(tags);
704
+ return this.#driver.flushTags(scoped);
648
705
  }
649
706
 
650
707
  /** @deprecated alias of {@link deleteByTag}. */
@@ -685,7 +742,7 @@ export class CacheManager {
685
742
  ): NormalizedGetOrSet<T> {
686
743
  if (typeof a === "string") {
687
744
  if (typeof c !== "function") {
688
- throw new TypeError(
745
+ throw new InvalidArgumentError(
689
746
  "Echo: getOrSet(key, ttl, factory) requires a factory function",
690
747
  );
691
748
  }
@@ -776,16 +833,23 @@ export class CacheManager {
776
833
  const hasStale = entry?.stale === true && o.graceSeconds > 0;
777
834
  const staleValue = hasStale ? entry.value : undefined;
778
835
 
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);
836
+ const record = this.#shared.inflight.get(prefixed);
837
+ // Joining another caller's factory, rather than running our own.
838
+ const joined = record !== undefined;
839
+ let factoryPromise: Promise<T>;
840
+ if (record === undefined) {
841
+ factoryPromise = this.#invokeFactory<T>(
842
+ prefixed,
843
+ o,
844
+ hasStale,
845
+ staleValue,
846
+ );
847
+ this.#shared.inflight.set(prefixed, { promise: factoryPromise });
848
+ } else {
849
+ // The map holds every key's factory, whatever its type; what the
850
+ // leader computes for this key is what this caller reads.
851
+ factoryPromise = record.promise.then((value) => claimed<T>(value));
785
852
  }
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
853
 
790
854
  if (hasStale && staleValue !== undefined) {
791
855
  // Stale-while-revalidate: serve stale up to the soft timeout (default 0
@@ -808,10 +872,22 @@ export class CacheManager {
808
872
  return result;
809
873
  }
810
874
 
811
- if (o.hardTimeoutMs !== undefined) {
812
- const result = await withTimeout(factoryPromise, o.hardTimeoutMs);
875
+ // A joiner waits at most `lockTimeout` for the leader, stale value or
876
+ // not, as upstream bounds its lock acquisition either way. It was read
877
+ // on the stale path only, so behind a factory that hung every caller
878
+ // for the key waited forever. The leader is not bound by it: it holds
879
+ // the lock, and `hardTimeout` is what bounds its factory.
880
+ const lockMs = joined ? o.lockTimeoutMs : undefined;
881
+ const hardMs = o.hardTimeoutMs;
882
+ if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
883
+ const result = await withTimeout(factoryPromise, lockMs);
884
+ if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
885
+ return result;
886
+ }
887
+ if (hardMs !== undefined) {
888
+ const result = await withTimeout(factoryPromise, hardMs);
813
889
  if (result === TIMEOUT) {
814
- throw new TimeoutError(o.key, o.hardTimeoutMs);
890
+ throw new TimeoutError(o.key, hardMs);
815
891
  }
816
892
  return result;
817
893
  }
@@ -1,6 +1,7 @@
1
1
  import "./augmentations.js";
2
2
  import { type CacheConfig, CacheManager } from "./CacheManager.js";
3
3
  import { MemoryDriver } from "./drivers/MemoryDriver.js";
4
+ import { EchoError } from "./errors.js";
4
5
  import { CacheStoreManager, type MultiStoreConfig } from "./StoreManager.js";
5
6
  import { clearCache, getCache, setCache } from "./services/main.js";
6
7
  import type { CacheEmitter } from "./types.js";
@@ -43,6 +44,34 @@ function isEmitter(value: unknown): value is CacheEmitter {
43
44
  );
44
45
  }
45
46
 
47
+ function isDuration(value: unknown): boolean {
48
+ return (
49
+ value === undefined ||
50
+ value === null ||
51
+ typeof value === "number" ||
52
+ typeof value === "string"
53
+ );
54
+ }
55
+
56
+ /** A single-store config, field by field. */
57
+ function isSingleStoreConfig(value: unknown): value is EchoProviderConfig {
58
+ if (typeof value !== "object" || value === null) return false;
59
+ const read = (name: string): unknown => Reflect.get(value, name);
60
+ const driver = read("driver");
61
+ const prefix = read("prefix");
62
+ const name = read("name");
63
+ const emitter = read("emitter");
64
+ return (
65
+ (driver === undefined || driver === "memory") &&
66
+ (prefix === undefined || typeof prefix === "string") &&
67
+ (name === undefined || typeof name === "string") &&
68
+ (emitter === undefined || isEmitter(emitter)) &&
69
+ ["ttl", "grace", "timeout", "hardTimeout", "lockTimeout"].every((field) =>
70
+ isDuration(read(field)),
71
+ )
72
+ );
73
+ }
74
+
46
75
  function isMultiStoreConfig(value: unknown): value is MultiStoreConfig {
47
76
  return (
48
77
  typeof value === "object" &&
@@ -94,15 +123,27 @@ export default class EchoProvider {
94
123
  return manager.use();
95
124
  }
96
125
 
97
- const config = (raw ?? {}) as EchoProviderConfig;
98
- const driver = config.driver ?? "memory";
126
+ const config: unknown = raw ?? {};
127
+ const driver =
128
+ typeof config === "object" && config !== null
129
+ ? (Reflect.get(config, "driver") ?? "memory")
130
+ : "memory";
99
131
  if (driver !== "memory") {
100
- throw new Error(
101
- `[echo] Unsupported driver '${driver}' for default provider — ` +
132
+ throw new EchoError(
133
+ "E_ECHO_UNSUPPORTED_DRIVER",
134
+ `[echo] Unsupported driver '${String(driver)}' for default provider — ` +
102
135
  "wire CacheManager yourself for non-memory drivers, or use the " +
103
136
  "multi-store `{ default, stores }` config.",
104
137
  );
105
138
  }
139
+ // Checked, not asserted: a config file is the application's, and
140
+ // a prefix that is not a string would otherwise reach every key.
141
+ if (!isSingleStoreConfig(config)) {
142
+ throw new EchoError(
143
+ "E_ECHO_INVALID_CONFIG",
144
+ "[echo] config/cache.ts must export an object — `{ prefix, ttl, … }` for one store, or `{ default, stores }` for several.",
145
+ );
146
+ }
106
147
  return new CacheManager(new MemoryDriver(), { ...config, emitter });
107
148
  });
108
149
  // Namespaced by the package that owns it, the way upstream namespaces
@@ -16,15 +16,33 @@
16
16
  */
17
17
 
18
18
  import { CacheManager } from "./CacheManager.js";
19
- import { MemoryDriver } from "./drivers/MemoryDriver.js";
19
+ import {
20
+ MemoryDriver,
21
+ type MemoryDriverOptions,
22
+ } from "./drivers/MemoryDriver.js";
20
23
  import { type RedisClient, RedisDriver } from "./drivers/RedisDriver.js";
21
- import { type CacheBus, TieredDriver } from "./drivers/TieredDriver.js";
24
+ import {
25
+ type CacheBus,
26
+ TieredDriver,
27
+ type TieredDriverOptions,
28
+ } from "./drivers/TieredDriver.js";
22
29
  import type { Duration } from "./duration.js";
30
+ import { EchoError } from "./errors.js";
23
31
  import { quasarBus, quasarConnection } from "./quasar.js";
24
32
  import type { CacheDriver, CacheEmitter, CacheEventMap } from "./types.js";
25
33
 
26
- /** A lazily-instantiated driver (built once per store, on first `use`). */
27
- export type DriverFactory = () => CacheDriver;
34
+ /**
35
+ * A lazily-instantiated driver (built once per store, on first `use`). The
36
+ * store manager passes the store's name, which a tiered driver stamps on its
37
+ * bus messages so stores sharing a channel leave each other alone.
38
+ */
39
+ export type DriverFactory = (context?: DriverContext) => CacheDriver;
40
+
41
+ /** What the store manager tells a driver factory about the store it builds. */
42
+ export interface DriverContext {
43
+ /** The store's key in the config. */
44
+ store: string;
45
+ }
28
46
 
29
47
  export interface StoreConfig {
30
48
  driver: DriverFactory;
@@ -42,6 +60,14 @@ export interface StoreConfig {
42
60
  timeout?: Duration;
43
61
  hardTimeout?: Duration;
44
62
  lockTimeout?: Duration;
63
+ /**
64
+ * For a two-layer store: serve from L1 and the factory when the L2 fails,
65
+ * rather than failing the call. Default `true` (see
66
+ * {@link TieredDriverOptions.suppressL2Errors}).
67
+ */
68
+ suppressL2Errors?: boolean;
69
+ /** For a two-layer store: how long to skip a failing L2. Off by default. */
70
+ l2CircuitBreakerDuration?: Duration;
45
71
  }
46
72
 
47
73
  export interface MultiStoreConfig {
@@ -109,20 +135,28 @@ export class Store {
109
135
  entry(): StoreConfig {
110
136
  const l1 = this.#l1;
111
137
  const l2 = this.#l2;
112
- if (!l1 && !l2) {
113
- throw new Error(
114
- "Echo: a store needs a layer — call useL1Layer() or useL2Layer() on it.",
115
- );
116
- }
117
138
  if (l1 && l2) {
118
139
  return {
119
140
  ...this.#options,
120
- driver: drivers.tiered({ l1, l2, bus: this.#bus }),
141
+ driver: drivers.tiered({
142
+ l1,
143
+ l2,
144
+ bus: this.#bus,
145
+ suppressL2Errors: this.#options.suppressL2Errors,
146
+ l2CircuitBreakerDuration: this.#options.l2CircuitBreakerDuration,
147
+ }),
121
148
  };
122
149
  }
123
- const only = (l1 ?? l2) as DriverFactory;
150
+ const only = l1 ?? l2;
151
+ if (only === undefined) {
152
+ throw new EchoError(
153
+ "E_ECHO_INVALID_CONFIG",
154
+ "Echo: a store needs a layer — call useL1Layer() or useL2Layer() on it.",
155
+ );
156
+ }
124
157
  if (this.#bus) {
125
- throw new Error(
158
+ throw new EchoError(
159
+ "E_ECHO_INVALID_CONFIG",
126
160
  "Echo: a bus only means something with two layers — it keeps each instance's L1 in step. Add useL2Layer(), or drop useBus().",
127
161
  );
128
162
  }
@@ -146,12 +180,12 @@ export const drivers = {
146
180
  * `maxItems` bounds the store by COUNT, which a TTL cannot: a cache keyed by
147
181
  * a user id or a search term grows until the process runs out of memory,
148
182
  * however short each entry's life. Omit it for no ceiling.
183
+ *
184
+ * Values are stored as JSON and read back as copies; `serialize: false`
185
+ * keeps references instead (see {@link MemoryDriverOptions.serialize}).
149
186
  */
150
- memory(options?: {
151
- sweepIntervalMs?: number;
152
- maxItems?: number;
153
- }): DriverFactory {
154
- return () => new MemoryDriver(options?.sweepIntervalMs, options?.maxItems);
187
+ memory(options?: MemoryDriverOptions): DriverFactory {
188
+ return () => new MemoryDriver({ ...options });
155
189
  },
156
190
  /**
157
191
  * Either hand it a client, or name a quasar connection — the AdonisJS shape,
@@ -181,16 +215,18 @@ export const drivers = {
181
215
  redisBus(options?: { connection?: string; channel?: string }): CacheBus {
182
216
  return quasarBus(options);
183
217
  },
184
- tiered(options: {
185
- l1: DriverFactory;
186
- l2: DriverFactory;
187
- bus?: CacheBus;
188
- }): DriverFactory {
189
- return () =>
218
+ tiered(
219
+ options: {
220
+ l1: DriverFactory;
221
+ l2: DriverFactory;
222
+ } & Omit<TieredDriverOptions, "l1" | "l2">,
223
+ ): DriverFactory {
224
+ return (context) =>
190
225
  new TieredDriver({
191
- l1: options.l1(),
192
- l2: options.l2(),
193
- bus: options.bus,
226
+ ...options,
227
+ l1: options.l1(context),
228
+ l2: options.l2(context),
229
+ store: options.store ?? context?.store,
194
230
  });
195
231
  },
196
232
  };
@@ -219,25 +255,44 @@ export class CacheStoreManager {
219
255
 
220
256
  constructor(config: MultiStoreConfig) {
221
257
  this.#config = config;
222
- if (!config.stores[config.default]) {
223
- throw new Error(
258
+ if (!this.#declared(config.default)) {
259
+ throw new EchoError(
260
+ "E_ECHO_UNKNOWN_STORE",
224
261
  `Echo: default store "${config.default}" is not defined in stores`,
225
262
  );
226
263
  }
227
264
  }
228
265
 
266
+ /**
267
+ * A store declared under `name` in the config's OWN keys: a plain lookup
268
+ * would answer `toString` or `constructor` with an Object.prototype member.
269
+ */
270
+ #declared(name: string): MultiStoreConfig["stores"][string] | undefined {
271
+ return Object.hasOwn(this.#config.stores, name)
272
+ ? this.#config.stores[name]
273
+ : undefined;
274
+ }
275
+
276
+ /** The store `use()` answers with no name (upstream `defaultStoreName`). */
277
+ get defaultStoreName(): string {
278
+ return this.#config.default;
279
+ }
280
+
229
281
  /** Resolve a store by name (or the default). Instances are built once and cached. */
230
282
  use(name?: string): CacheManager {
231
283
  const store = name ?? this.#config.default;
232
284
  const existing = this.#built.get(store);
233
285
  if (existing) return existing;
234
286
 
235
- const declared = this.#config.stores[store];
287
+ const declared = this.#declared(store);
236
288
  if (!declared) {
237
- throw new Error(`Echo: unknown cache store "${store}"`);
289
+ throw new EchoError(
290
+ "E_ECHO_UNKNOWN_STORE",
291
+ `Echo: unknown cache store "${store}"`,
292
+ );
238
293
  }
239
294
  const cfg = entryOf(declared);
240
- const manager = new CacheManager(cfg.driver(), {
295
+ const manager = new CacheManager(cfg.driver({ store }), {
241
296
  prefix: cfg.prefix,
242
297
  // The store's own, or the one every store inherits.
243
298
  ttl: cfg.ttl ?? this.#config.ttl,
package/src/bytes.ts ADDED
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Byte sizes for the memory driver's bounds — upstream takes a number of bytes
3
+ * or a human string (`'10mb'`), in powers of 1024.
4
+ */
5
+
6
+ import { EchoError } from "./errors.js";
7
+
8
+ const UNIT_BYTES: Record<string, number> = {
9
+ b: 1,
10
+ kb: 1024,
11
+ mb: 1024 ** 2,
12
+ gb: 1024 ** 3,
13
+ tb: 1024 ** 4,
14
+ pb: 1024 ** 5,
15
+ };
16
+
17
+ const BYTES_RE = /^\s*(\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
18
+
19
+ /**
20
+ * A size in bytes, from a number of bytes or a string like `'512kb'`.
21
+ *
22
+ * @throws {EchoError} `E_ECHO_INVALID_CONFIG` for anything that is not a
23
+ * finite, non-negative size: a bound that cannot be read would otherwise
24
+ * leave the store silently unbounded.
25
+ */
26
+ export function parseBytes(value: number | string, option: string): number {
27
+ if (typeof value === "number") {
28
+ if (Number.isFinite(value) && value >= 0) return value;
29
+ } else {
30
+ const match = BYTES_RE.exec(value);
31
+ const factor = UNIT_BYTES[(match?.[2] ?? "b").toLowerCase()];
32
+ if (match && factor !== undefined) return Number(match[1]) * factor;
33
+ }
34
+ throw new EchoError(
35
+ "E_ECHO_INVALID_CONFIG",
36
+ `Echo: ${option} must be a number of bytes or a size like '10mb' — got ${String(value)}`,
37
+ );
38
+ }
package/src/claim.ts ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The one place a cached value becomes the caller's `T`.
3
+ *
4
+ * A cache hands back what was written under a key. The type parameter of
5
+ * `get<T>()` is the caller's statement of what that was — nothing the cache
6
+ * can check, and upstream's `get<T>()` makes the same claim. It lives in this
7
+ * one named function rather than as an assertion at every read site, so the
8
+ * boundary is visible and there is exactly one of it.
9
+ */
10
+ export function claimed<T>(value: unknown): T;
11
+ export function claimed(value: unknown): unknown {
12
+ return value;
13
+ }
14
+
15
+ /** A timer handle that can be unreferenced — Node's, not the browser's. */
16
+ export function hasUnref(timer: unknown): timer is { unref(): void } {
17
+ return (
18
+ typeof timer === "object" &&
19
+ timer !== null &&
20
+ typeof Reflect.get(timer, "unref") === "function"
21
+ );
22
+ }
package/src/configure.ts CHANGED
@@ -7,14 +7,23 @@
7
7
  * installed AND working.
8
8
  */
9
9
 
10
+ import { stubsRoot } from "./stubs.js";
11
+
10
12
  interface Codemods {
11
13
  addProvider(importPath: string): Promise<void>;
14
+ registerCommand(importPath: string): Promise<void>;
12
15
  addEnvVars(vars: Record<string, string>): Promise<void>;
13
16
  writeFile(
14
17
  filePath: string,
15
18
  content: string,
16
19
  options?: { force?: boolean },
17
20
  ): Promise<void>;
21
+ makeUsingStub(
22
+ stubsRoot: string,
23
+ stubPath: string,
24
+ state?: Record<string, string | number | boolean>,
25
+ options?: { force?: boolean },
26
+ ): Promise<{ path: string; contents: string }>;
18
27
  }
19
28
 
20
29
  export async function configure(codemods: Codemods): Promise<void> {
@@ -26,25 +35,8 @@ export async function configure(codemods: Codemods): Promise<void> {
26
35
  });
27
36
 
28
37
  await codemods.addProvider("@c9up/echo/provider");
29
- await codemods.writeFile(
30
- "config/cache.ts",
31
- `import { defineConfig, drivers, store } from '@c9up/echo'
32
- import env from '#start/env'
33
-
34
- export default defineConfig({
35
- default: env.get('CACHE_STORE', 'memory'),
36
-
37
- stores: {
38
- // One layer, in this process.
39
- memory: store().useL1Layer(drivers.memory({ maxItems: 1000 })),
40
-
41
- // Two layers: memory in front of Redis, with a bus so every instance
42
- // drops its own L1 entry when another writes.
43
- tiered: store()
44
- .useL1Layer(drivers.memory({ maxItems: 1000 }))
45
- .useL2Layer(drivers.redis({ connection: 'main' }))
46
- .useBus(drivers.redisBus({ connection: 'main' })),
47
- },
48
- })`,
49
- );
38
+ // `cache:clear`, `cache:delete` and `cache:prune` are the package's, not the
39
+ // binary's: a project reaches them by listing the module.
40
+ await codemods.registerCommand("@c9up/echo/commands");
41
+ await codemods.makeUsingStub(stubsRoot, "config/cache.stub");
50
42
  }