@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
@@ -4,15 +4,64 @@
4
4
  * as the L1 tier of {@link TieredDriver}.
5
5
  */
6
6
 
7
+ import { parseBytes } from "../bytes.js";
8
+ import { claimed, hasUnref } from "../claim.js";
9
+ import { checkTtlSeconds } from "../duration.js";
10
+ import { EchoError, UndefinedValueError } from "../errors.js";
7
11
  import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
8
12
 
13
+ export interface MemoryDriverOptions {
14
+ /** How often expired entries are swept, in milliseconds (default 60 000). */
15
+ sweepIntervalMs?: number;
16
+ /**
17
+ * How many entries the store holds before it evicts the least recently
18
+ * used. Default 1000, as upstream; `0` or `Infinity` for no ceiling.
19
+ */
20
+ maxItems?: number;
21
+ /**
22
+ * Total size of the stored values, in bytes or as `'10mb'`; past it the
23
+ * least recently used entries go. Needs `serialize`, since it measures
24
+ * the JSON.
25
+ */
26
+ maxSize?: number | string;
27
+ /**
28
+ * Largest single value, in bytes or as `'1mb'`. A bigger one is not
29
+ * stored, and the key's previous value goes with it. Defaults to
30
+ * `maxSize` when that is set. Needs `serialize`.
31
+ */
32
+ maxEntrySize?: number | string;
33
+ /**
34
+ * Store values as JSON and hand out a fresh copy on every read (default).
35
+ *
36
+ * `false` keeps the caller's object and returns that same reference, which
37
+ * is faster and keeps class instances, Dates and Maps intact — but any
38
+ * reader that mutates what it got rewrites the value for every later one.
39
+ */
40
+ serialize?: boolean;
41
+ }
42
+
9
43
  interface StoredEntry {
44
+ /** The JSON text when the driver serializes, the value itself when it does not. */
10
45
  value: unknown;
11
46
  /** Logical expiry (epoch ms); `0` means never. Past this the entry is stale. */
12
47
  expiresAt: number;
13
48
  /** Physical eviction (epoch ms); `0` means never. Grace window ends here. */
14
49
  staleUntil: number;
15
50
  tags: string[];
51
+ /** Bytes of JSON; `0` when the driver keeps references. */
52
+ size: number;
53
+ }
54
+
55
+ /** The JSON a value is stored as; refused when JSON cannot carry it. */
56
+ function toJson(value: unknown): string {
57
+ const json = JSON.stringify(value);
58
+ if (json === undefined) {
59
+ throw new EchoError(
60
+ "E_ECHO_UNSERIALIZABLE_VALUE",
61
+ "Echo: the memory driver stores values as JSON, and this one has no JSON form — pass `serialize: false` to keep it as is",
62
+ );
63
+ }
64
+ return json;
16
65
  }
17
66
 
18
67
  export class MemoryDriver implements TaggableDriver {
@@ -20,45 +69,100 @@ export class MemoryDriver implements TaggableDriver {
20
69
  #tagIndex: Map<string, Set<string>> = new Map();
21
70
  #sweepInterval: ReturnType<typeof setInterval>;
22
71
  /**
23
- * How many entries this driver holds before it starts dropping the oldest.
72
+ * How many entries this driver holds before it evicts.
24
73
  *
25
- * Eviction was by TTL alone, which bounds how long an entry lives and not
26
- * how many there are: a cache keyed by anything unbounded — a user id, a
27
- * search term — grew until the process ran out of memory, and only a key
28
- * that was written ever left. `0` keeps the old behaviour for a caller that
29
- * genuinely wants no ceiling.
74
+ * 1000 unless told otherwise, as upstream's LRU. It had no ceiling by
75
+ * default, so a cache keyed by anything a user controls — an id, a search
76
+ * term — grew until the process ran out of memory. `0` is an explicit "no
77
+ * ceiling".
30
78
  */
31
79
  readonly #maxItems: number;
80
+ /** Byte bound on all values together; `0` for none. */
81
+ readonly #maxSize: number;
82
+ /** Byte bound on one value; `0` for none. */
83
+ readonly #maxEntrySize: number;
84
+ /** Bytes held, kept in step with every write and removal. */
85
+ #size = 0;
86
+ /**
87
+ * Whether values go in as JSON and come out as a copy.
88
+ *
89
+ * On by default, as upstream serializes its L1 by default: the driver kept
90
+ * the caller's object and returned that same reference, so a request that
91
+ * mutated what it read — a cached permission set, say — changed it for
92
+ * every later reader. JSON is also what the Redis driver stores, so a
93
+ * value reads back the same in development and in production.
94
+ */
95
+ readonly #serialize: boolean;
32
96
 
33
- constructor(sweepIntervalMs = 60_000, maxItems = 0) {
34
- this.#maxItems = maxItems > 0 ? maxItems : 0;
35
- this.#sweepInterval = setInterval(() => this.#sweep(), sweepIntervalMs);
97
+ /**
98
+ * @param options the options, or the sweep interval in milliseconds (the
99
+ * original positional form, kept with `maxItems` beside it).
100
+ */
101
+ constructor(options: MemoryDriverOptions | number = {}, maxItems?: number) {
102
+ const config: MemoryDriverOptions =
103
+ typeof options === "number"
104
+ ? { sweepIntervalMs: options, maxItems }
105
+ : options;
106
+ const ceiling = config.maxItems ?? 1000;
107
+ if (Number.isNaN(ceiling) || ceiling < 0) {
108
+ throw new EchoError(
109
+ "E_ECHO_INVALID_CONFIG",
110
+ `Echo: maxItems must be a count, 0 or Infinity for no ceiling — got ${String(ceiling)}`,
111
+ );
112
+ }
113
+ this.#maxItems = Number.isFinite(ceiling) ? ceiling : 0;
114
+ this.#serialize = config.serialize ?? true;
36
115
  if (
37
- typeof this.#sweepInterval === "object" &&
38
- "unref" in this.#sweepInterval
116
+ !this.#serialize &&
117
+ (config.maxSize !== undefined || config.maxEntrySize !== undefined)
39
118
  ) {
40
- (this.#sweepInterval as { unref(): void }).unref();
119
+ // What it would measure is the JSON, and a driver keeping
120
+ // references has none. Upstream refuses the same combination.
121
+ throw new EchoError(
122
+ "E_ECHO_INVALID_CONFIG",
123
+ "Echo: maxSize and maxEntrySize measure the stored JSON, so they need `serialize` — drop `serialize: false` or the byte bound",
124
+ );
41
125
  }
126
+ this.#maxSize =
127
+ config.maxSize === undefined ? 0 : parseBytes(config.maxSize, "maxSize");
128
+ this.#maxEntrySize =
129
+ config.maxEntrySize === undefined
130
+ ? this.#maxSize
131
+ : parseBytes(config.maxEntrySize, "maxEntrySize");
132
+ this.#sweepInterval = setInterval(
133
+ () => this.#sweep(),
134
+ config.sweepIntervalMs ?? 60_000,
135
+ );
136
+ // The sweep is housekeeping, not a reason for the process to stay up.
137
+ if (hasUnref(this.#sweepInterval)) this.#sweepInterval.unref();
138
+ }
139
+
140
+ #fits(): boolean {
141
+ return (
142
+ (this.#maxItems === 0 || this.#store.size <= this.#maxItems) &&
143
+ (this.#maxSize === 0 || this.#size <= this.#maxSize)
144
+ );
42
145
  }
43
146
 
44
147
  /**
45
- * Drop the oldest entries until the store fits under its ceiling.
148
+ * Drop entries until the store fits under its ceilings.
46
149
  *
47
150
  * Expired ones go first — evicting a live entry while a dead one sits in
48
151
  * the map would throw away a value someone still wants. Only if that is not
49
- * enough does it take the least recently written.
152
+ * enough does it take the least recently used: the Map's order, since a
153
+ * read moves its key to the end as a write does.
50
154
  */
51
155
  #enforceCeiling(): void {
52
- if (this.#maxItems === 0 || this.#store.size <= this.#maxItems) return;
156
+ if (this.#fits()) return;
53
157
  const now = Date.now();
54
158
  for (const [key, entry] of this.#store) {
55
- if (this.#store.size <= this.#maxItems) return;
159
+ if (this.#fits()) return;
56
160
  if (entry.staleUntil > 0 && entry.staleUntil < now) {
57
161
  this.#evict(key, entry);
58
162
  }
59
163
  }
60
164
  for (const [key, entry] of this.#store) {
61
- if (this.#store.size <= this.#maxItems) return;
165
+ if (this.#fits()) return;
62
166
  this.#evict(key, entry);
63
167
  }
64
168
  }
@@ -113,8 +217,21 @@ export class MemoryDriver implements TaggableDriver {
113
217
  this.#evict(key, entry);
114
218
  return null;
115
219
  }
220
+ // Least recently USED, not written: a read moves the key to the end of
221
+ // the eviction order. Without it the hottest key was the first to go.
222
+ this.#store.delete(key);
223
+ this.#store.set(key, entry);
116
224
  const stale = entry.expiresAt > 0 && entry.expiresAt < now;
117
- return { value: entry.value as T, stale, expiresAt: entry.expiresAt };
225
+ const value =
226
+ this.#serialize && typeof entry.value === "string"
227
+ ? JSON.parse(entry.value)
228
+ : entry.value;
229
+ return {
230
+ value: claimed<T>(value),
231
+ stale,
232
+ expiresAt: entry.expiresAt,
233
+ tags: [...entry.tags],
234
+ };
118
235
  }
119
236
 
120
237
  /**
@@ -124,8 +241,30 @@ export class MemoryDriver implements TaggableDriver {
124
241
  * into a wrong-purge under deleteByTag (audit 2026-06-13).
125
242
  */
126
243
  #evict(key: string, entry: StoredEntry): void {
127
- for (const tag of entry.tags) this.#tagIndex.get(tag)?.delete(key);
244
+ this.#untag(key, entry.tags);
128
245
  this.#store.delete(key);
246
+ this.#size -= entry.size;
247
+ }
248
+
249
+ /**
250
+ * Take `key` out of each tag's set, and drop a set it leaves empty.
251
+ *
252
+ * Emptied sets were kept, so per-user or per-id tags grew the index by one
253
+ * set per entry ever written: a store capped at ten entries held hundreds
254
+ * of megabytes of empty sets.
255
+ */
256
+ #untag(key: string, tags: string[]): void {
257
+ for (const tag of tags) {
258
+ const keys = this.#tagIndex.get(tag);
259
+ if (keys === undefined) continue;
260
+ keys.delete(key);
261
+ if (keys.size === 0) this.#tagIndex.delete(tag);
262
+ }
263
+ }
264
+
265
+ /** How many tags the index holds — what bounds its memory, for diagnostics. */
266
+ tagCount(): number {
267
+ return this.#tagIndex.size;
129
268
  }
130
269
 
131
270
  #write(
@@ -137,21 +276,38 @@ export class MemoryDriver implements TaggableDriver {
137
276
  expiresAtOverride?: number,
138
277
  ): void {
139
278
  if (value === null || value === undefined) {
140
- throw new TypeError(
141
- "Echo: caching null/undefined values is not supported",
142
- );
279
+ throw new UndefinedValueError();
280
+ }
281
+ // Before anything is touched: a value JSON cannot carry must leave the
282
+ // previous entry and its tags exactly as they were.
283
+ const stored = this.#serialize ? toJson(value) : value;
284
+ const size = typeof stored === "string" ? Buffer.byteLength(stored) : 0;
285
+ if (this.#maxEntrySize > 0 && size > this.#maxEntrySize) {
286
+ // Too big to keep. The previous value goes too, as upstream's LRU
287
+ // does: a skipped write must not leave an older value served.
288
+ this.#deleteEntry(key);
289
+ return;
143
290
  }
144
291
  const now = Date.now();
145
- const hasTtl = ttlSeconds != null && ttlSeconds > 0;
292
+ const ttl = ttlSeconds === undefined ? 0 : checkTtlSeconds(ttlSeconds);
293
+ const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
294
+ if (expiresAtOverride === undefined && ttl < 0 && graceMs === 0) {
295
+ // Already expired, and no grace to keep a stale copy for: nothing
296
+ // to store, and the previous value must not survive it.
297
+ this.#deleteEntry(key);
298
+ return;
299
+ }
146
300
  // An absolute `expiresAtOverride` (e.g. `expire()` marking stale-now) wins
147
- // over the ttl-derived expiry; a past value makes the entry immediately stale.
301
+ // over the ttl-derived expiry; a past value makes the entry immediately
302
+ // stale. So does a negative TTL — it never reads as "no expiry".
148
303
  const expiresAt =
149
304
  expiresAtOverride !== undefined
150
305
  ? expiresAtOverride
151
- : hasTtl
152
- ? now + ttlSeconds * 1000
153
- : 0;
154
- const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
306
+ : ttl < 0
307
+ ? now - 1
308
+ : ttl > 0
309
+ ? now + ttl * 1000
310
+ : 0;
155
311
  // A never-expiring entry never goes stale either; otherwise grace extends
156
312
  // physical retention past the logical expiry. Measure grace from the LATER
157
313
  // of the expiry and now, so an already-past expiry still survives its grace.
@@ -160,14 +316,16 @@ export class MemoryDriver implements TaggableDriver {
160
316
  // its old tag-index refs, or a later deleteByTag could purge this fresh
161
317
  // value (audit 2026-05-22 F3).
162
318
  const prev = this.#store.get(key);
163
- if (prev !== undefined) {
164
- for (const t of prev.tags) this.#tagIndex.get(t)?.delete(key);
165
- }
166
- // Re-inserting moves the key to the end of the Map's iteration order, so
167
- // the first entry is always the least recently WRITTEN — which is the
168
- // order this evicts in.
169
- this.#store.delete(key);
170
- this.#store.set(key, { value, expiresAt, staleUntil, tags });
319
+ if (prev !== undefined) this.#evict(key, prev);
320
+ // Inserted last, so it is the most recently used.
321
+ this.#store.set(key, {
322
+ value: stored,
323
+ expiresAt,
324
+ staleUntil,
325
+ tags,
326
+ size,
327
+ });
328
+ this.#size += size;
171
329
  this.#enforceCeiling();
172
330
  for (const tag of tags) {
173
331
  let set = this.#tagIndex.get(tag);
@@ -199,30 +357,25 @@ export class MemoryDriver implements TaggableDriver {
199
357
  }
200
358
 
201
359
  async delete(key: string): Promise<boolean> {
360
+ return this.#deleteEntry(key);
361
+ }
362
+
363
+ #deleteEntry(key: string): boolean {
202
364
  const entry = this.#store.get(key);
203
- if (entry) {
204
- for (const tag of entry.tags) {
205
- this.#tagIndex.get(tag)?.delete(key);
206
- }
207
- }
208
- return this.#store.delete(key);
365
+ if (entry === undefined) return false;
366
+ this.#evict(key, entry);
367
+ return true;
209
368
  }
210
369
 
211
370
  async flush(prefix?: string): Promise<void> {
212
371
  if (prefix === undefined) {
213
372
  this.#store.clear();
214
373
  this.#tagIndex.clear();
374
+ this.#size = 0;
215
375
  return;
216
376
  }
217
- for (const key of [...this.#store.keys()]) {
218
- if (key.startsWith(prefix)) this.#store.delete(key);
219
- }
220
- // The tag index points at keys; the ones that are gone go with them.
221
- for (const [tag, keys] of [...this.#tagIndex.entries()]) {
222
- for (const key of [...keys]) {
223
- if (key.startsWith(prefix)) keys.delete(key);
224
- }
225
- if (keys.size === 0) this.#tagIndex.delete(tag);
377
+ for (const [key, entry] of [...this.#store]) {
378
+ if (key.startsWith(prefix)) this.#evict(key, entry);
226
379
  }
227
380
  }
228
381
 
@@ -252,15 +405,7 @@ export class MemoryDriver implements TaggableDriver {
252
405
  for (const key of keys) toDelete.add(key);
253
406
  }
254
407
  }
255
- for (const key of toDelete) {
256
- const entry = this.#store.get(key);
257
- if (entry) {
258
- for (const t of entry.tags) {
259
- this.#tagIndex.get(t)?.delete(key);
260
- }
261
- }
262
- this.#store.delete(key);
263
- }
408
+ for (const key of toDelete) this.#deleteEntry(key);
264
409
  for (const tag of tags) this.#tagIndex.delete(tag);
265
410
  }
266
411