@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
@@ -0,0 +1,93 @@
1
+ /**
2
+ * The console command contract, declared locally.
3
+ *
4
+ * Echo stays framework-agnostic: it must not import `@c9up/ream`, so it
5
+ * describes the shape Ream's console kernel dispatches against rather than
6
+ * importing it. The kernel assigns `logger`, `prompt` and — for a command that
7
+ * starts the app — `app` before it calls `run()`.
8
+ */
9
+
10
+ export interface CommandOptions {
11
+ /** Boot the application before `run()`. */
12
+ startApp?: boolean;
13
+ }
14
+
15
+ export interface ArgumentMetaData {
16
+ type: "string" | "spread";
17
+ propertyName: string;
18
+ argumentName: string;
19
+ description?: string;
20
+ required: boolean;
21
+ default?: string | string[];
22
+ }
23
+
24
+ export interface FlagMetaData {
25
+ type: "string" | "boolean" | "number" | "array";
26
+ propertyName: string;
27
+ flagName: string;
28
+ description?: string;
29
+ alias: string[];
30
+ default?: string | string[] | number | boolean;
31
+ required: boolean;
32
+ }
33
+
34
+ /** The slice of the kernel's logger these commands write to. */
35
+ export interface CommandLogger {
36
+ success(message: string): void;
37
+ warning(message: string): void;
38
+ error(message: string): void;
39
+ }
40
+
41
+ /** The slice of the kernel's prompt these commands ask through. */
42
+ export interface CommandPrompt {
43
+ confirm(message: string): Promise<boolean>;
44
+ }
45
+
46
+ /** The slice of the booted application these commands read. */
47
+ export interface CommandApp {
48
+ readonly inProduction: boolean;
49
+ }
50
+
51
+ /** The static side the kernel reads. */
52
+ export interface EchoCommandClass {
53
+ new (): { run(): Promise<void> | void };
54
+ commandName: string;
55
+ description: string;
56
+ options?: CommandOptions;
57
+ args?: readonly ArgumentMetaData[];
58
+ flags?: readonly FlagMetaData[];
59
+ help?: string | string[];
60
+ }
61
+
62
+ /** `startServer` → `start-server`, matching the framework's decorators. */
63
+ function dashCase(value: string): string {
64
+ return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
65
+ }
66
+
67
+ export function flag(
68
+ propertyName: string,
69
+ type: FlagMetaData["type"],
70
+ options: { description?: string; alias?: string[] } = {},
71
+ ): FlagMetaData {
72
+ return {
73
+ type,
74
+ propertyName,
75
+ flagName: dashCase(propertyName),
76
+ description: options.description,
77
+ alias: options.alias ?? [],
78
+ required: false,
79
+ };
80
+ }
81
+
82
+ export function argument(
83
+ propertyName: string,
84
+ options: { description?: string; required?: boolean } = {},
85
+ ): ArgumentMetaData {
86
+ return {
87
+ type: "string",
88
+ propertyName,
89
+ argumentName: dashCase(propertyName),
90
+ description: options.description,
91
+ required: options.required ?? true,
92
+ };
93
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * `@c9up/echo/commands` — the commands echo ships.
3
+ *
4
+ * // reamrc.ts, written by `configure()`
5
+ * commands: [() => import('@c9up/echo/commands')]
6
+ *
7
+ * A module answering `getMetaData()` / `getCommand()`, which is how a package
8
+ * adds commands: by shipping them, never by a change to the `ream` binary.
9
+ */
10
+
11
+ import { cacheClearCommand } from "./cacheClear.js";
12
+ import { cacheDeleteCommand } from "./cacheDelete.js";
13
+ import { cachePruneCommand } from "./cachePrune.js";
14
+ import type { EchoCommandClass } from "./contract.js";
15
+
16
+ const COMMANDS: readonly EchoCommandClass[] = [
17
+ cacheClearCommand(),
18
+ cacheDeleteCommand(),
19
+ cachePruneCommand(),
20
+ ];
21
+
22
+ /** What the kernel reads to list a command without importing it. */
23
+ interface CommandMetaData {
24
+ commandName: string;
25
+ namespace: string | null;
26
+ description: string;
27
+ help?: string | string[];
28
+ aliases: string[];
29
+ options: Record<string, unknown>;
30
+ args: readonly unknown[];
31
+ flags: readonly unknown[];
32
+ }
33
+
34
+ function serialize(command: EchoCommandClass): CommandMetaData {
35
+ const colon = command.commandName.indexOf(":");
36
+ return {
37
+ commandName: command.commandName,
38
+ namespace: colon === -1 ? null : command.commandName.slice(0, colon),
39
+ description: command.description,
40
+ help: command.help,
41
+ aliases: [],
42
+ options: { ...command.options },
43
+ args: command.args ?? [],
44
+ flags: command.flags ?? [],
45
+ };
46
+ }
47
+
48
+ export async function getMetaData(): Promise<CommandMetaData[]> {
49
+ return COMMANDS.map(serialize);
50
+ }
51
+
52
+ export async function getCommand(
53
+ metadata: CommandMetaData,
54
+ ): Promise<EchoCommandClass | null> {
55
+ return (
56
+ COMMANDS.find((command) => command.commandName === metadata.commandName) ??
57
+ null
58
+ );
59
+ }
60
+
61
+ export type { EchoCommandClass } from "./contract.js";
@@ -0,0 +1,47 @@
1
+ /**
2
+ * What the three cache commands share: reaching the store they were given,
3
+ * and asking before they touch a production cache.
4
+ */
5
+
6
+ import type { CacheManager } from "../CacheManager.js";
7
+ import { getCache } from "../services/main.js";
8
+ import type { CommandLogger, CommandPrompt } from "./contract.js";
9
+
10
+ /**
11
+ * The store a command names, or the default one — `undefined` after reporting
12
+ * why there is none, so the command can stop with a non-zero exit.
13
+ */
14
+ export function resolveStore(
15
+ name: string | undefined,
16
+ logger: CommandLogger,
17
+ ): CacheManager | undefined {
18
+ const cache = getCache();
19
+ if (cache === undefined) {
20
+ // Naming the wiring beats a stack trace out of the service proxy: the
21
+ // usual cause is a project that never added the provider.
22
+ logger.error(
23
+ "No cache is configured. Add `() => import('@c9up/echo/provider')` to the providers in reamrc.ts.",
24
+ );
25
+ return undefined;
26
+ }
27
+ try {
28
+ return cache.use(name);
29
+ } catch {
30
+ logger.error(
31
+ `"${name ?? "default"}" is not a valid cache store. Double check config/cache.ts file`,
32
+ );
33
+ return undefined;
34
+ }
35
+ }
36
+
37
+ /** A yes from the operator; a prompt that cannot be answered is a no. */
38
+ export async function consent(
39
+ prompt: CommandPrompt,
40
+ question: string,
41
+ ): Promise<boolean> {
42
+ try {
43
+ return await prompt.confirm(question);
44
+ } catch {
45
+ return false;
46
+ }
47
+ }
@@ -4,15 +4,65 @@
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, and a value over `maxSize` is never stored
31
+ * whatever this says. Needs `serialize`.
32
+ */
33
+ maxEntrySize?: number | string;
34
+ /**
35
+ * Store values as JSON and hand out a fresh copy on every read (default).
36
+ *
37
+ * `false` keeps the caller's object and returns that same reference, which
38
+ * is faster and keeps class instances, Dates and Maps intact — but any
39
+ * reader that mutates what it got rewrites the value for every later one.
40
+ */
41
+ serialize?: boolean;
42
+ }
43
+
9
44
  interface StoredEntry {
45
+ /** The JSON text when the driver serializes, the value itself when it does not. */
10
46
  value: unknown;
11
47
  /** Logical expiry (epoch ms); `0` means never. Past this the entry is stale. */
12
48
  expiresAt: number;
13
49
  /** Physical eviction (epoch ms); `0` means never. Grace window ends here. */
14
50
  staleUntil: number;
15
51
  tags: string[];
52
+ /** Bytes of JSON; `0` when the driver keeps references. */
53
+ size: number;
54
+ }
55
+
56
+ /** The JSON a value is stored as; refused when JSON cannot carry it. */
57
+ function toJson(value: unknown): string {
58
+ const json = JSON.stringify(value);
59
+ if (json === undefined) {
60
+ throw new EchoError(
61
+ "E_ECHO_UNSERIALIZABLE_VALUE",
62
+ "Echo: the memory driver stores values as JSON, and this one has no JSON form — pass `serialize: false` to keep it as is",
63
+ );
64
+ }
65
+ return json;
16
66
  }
17
67
 
18
68
  export class MemoryDriver implements TaggableDriver {
@@ -20,45 +70,96 @@ export class MemoryDriver implements TaggableDriver {
20
70
  #tagIndex: Map<string, Set<string>> = new Map();
21
71
  #sweepInterval: ReturnType<typeof setInterval>;
22
72
  /**
23
- * How many entries this driver holds before it starts dropping the oldest.
73
+ * How many entries this driver holds before it evicts.
24
74
  *
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.
75
+ * 1000 unless told otherwise, as upstream's LRU. It had no ceiling by
76
+ * default, so a cache keyed by anything a user controls — an id, a search
77
+ * term — grew until the process ran out of memory. `0` is an explicit "no
78
+ * ceiling".
30
79
  */
31
80
  readonly #maxItems: number;
81
+ /** Byte bound on all values together; `0` for none. */
82
+ readonly #maxSize: number;
83
+ /** Byte bound on one value; `0` for none. */
84
+ readonly #maxEntrySize: number;
85
+ /** Bytes held, kept in step with every write and removal. */
86
+ #size = 0;
87
+ /**
88
+ * Whether values go in as JSON and come out as a copy.
89
+ *
90
+ * On by default, as upstream serializes its L1 by default: the driver kept
91
+ * the caller's object and returned that same reference, so a request that
92
+ * mutated what it read — a cached permission set, say — changed it for
93
+ * every later reader. JSON is also what the Redis driver stores, so a
94
+ * value reads back the same in development and in production.
95
+ */
96
+ readonly #serialize: boolean;
32
97
 
33
- constructor(sweepIntervalMs = 60_000, maxItems = 0) {
34
- this.#maxItems = maxItems > 0 ? maxItems : 0;
35
- this.#sweepInterval = setInterval(() => this.#sweep(), sweepIntervalMs);
98
+ /**
99
+ * @param options the options, or the sweep interval in milliseconds (the
100
+ * original positional form, kept with `maxItems` beside it).
101
+ */
102
+ constructor(options: MemoryDriverOptions | number = {}, maxItems?: number) {
103
+ const config: MemoryDriverOptions =
104
+ typeof options === "number"
105
+ ? { sweepIntervalMs: options, maxItems }
106
+ : options;
107
+ const ceiling = config.maxItems ?? 1000;
108
+ if (Number.isNaN(ceiling) || ceiling < 0) {
109
+ throw new EchoError(
110
+ "E_ECHO_INVALID_CONFIG",
111
+ `Echo: maxItems must be a count, 0 or Infinity for no ceiling — got ${String(ceiling)}`,
112
+ );
113
+ }
114
+ this.#maxItems = Number.isFinite(ceiling) ? ceiling : 0;
115
+ this.#serialize = config.serialize ?? true;
36
116
  if (
37
- typeof this.#sweepInterval === "object" &&
38
- "unref" in this.#sweepInterval
117
+ !this.#serialize &&
118
+ (config.maxSize !== undefined || config.maxEntrySize !== undefined)
39
119
  ) {
40
- (this.#sweepInterval as { unref(): void }).unref();
120
+ // What it would measure is the JSON, and a driver keeping
121
+ // references has none. Upstream refuses the same combination.
122
+ throw new EchoError(
123
+ "E_ECHO_INVALID_CONFIG",
124
+ "Echo: maxSize and maxEntrySize measure the stored JSON, so they need `serialize` — drop `serialize: false` or the byte bound",
125
+ );
41
126
  }
127
+ this.#maxSize =
128
+ config.maxSize === undefined ? 0 : parseBytes(config.maxSize, "maxSize");
129
+ this.#maxEntrySize =
130
+ config.maxEntrySize === undefined
131
+ ? this.#maxSize
132
+ : parseBytes(config.maxEntrySize, "maxEntrySize");
133
+ this.#sweepInterval = setInterval(
134
+ () => this.#sweep(),
135
+ config.sweepIntervalMs ?? 60_000,
136
+ );
137
+ // The sweep is housekeeping, not a reason for the process to stay up.
138
+ if (hasUnref(this.#sweepInterval)) this.#sweepInterval.unref();
139
+ }
140
+
141
+ #fits(): boolean {
142
+ return (
143
+ (this.#maxItems === 0 || this.#store.size <= this.#maxItems) &&
144
+ (this.#maxSize === 0 || this.#size <= this.#maxSize)
145
+ );
42
146
  }
43
147
 
44
148
  /**
45
- * Drop the oldest entries until the store fits under its ceiling.
149
+ * Drop the least recently used entries until the store fits under its
150
+ * ceilings: the Map's order, since a read moves its key to the end as a
151
+ * write does.
46
152
  *
47
- * Expired ones go first — evicting a live entry while a dead one sits in
48
- * the map would throw away a value someone still wants. Only if that is not
49
- * enough does it take the least recently written.
153
+ * The least recently used, whatever has expired elsewhere in the order.
154
+ * Hunting for expired entries first walked the whole map on every write
155
+ * at the ceiling, a cost proportional to the ceiling a large working set
156
+ * pays on each write; expired entries are the sweep's, and a read drops
157
+ * one it finds. Upstream's LRU evicts the same way.
50
158
  */
51
159
  #enforceCeiling(): void {
52
- if (this.#maxItems === 0 || this.#store.size <= this.#maxItems) return;
53
- const now = Date.now();
54
- for (const [key, entry] of this.#store) {
55
- if (this.#store.size <= this.#maxItems) return;
56
- if (entry.staleUntil > 0 && entry.staleUntil < now) {
57
- this.#evict(key, entry);
58
- }
59
- }
160
+ if (this.#fits()) return;
60
161
  for (const [key, entry] of this.#store) {
61
- if (this.#store.size <= this.#maxItems) return;
162
+ if (this.#fits()) return;
62
163
  this.#evict(key, entry);
63
164
  }
64
165
  }
@@ -113,8 +214,21 @@ export class MemoryDriver implements TaggableDriver {
113
214
  this.#evict(key, entry);
114
215
  return null;
115
216
  }
217
+ // Least recently USED, not written: a read moves the key to the end of
218
+ // the eviction order. Without it the hottest key was the first to go.
219
+ this.#store.delete(key);
220
+ this.#store.set(key, entry);
116
221
  const stale = entry.expiresAt > 0 && entry.expiresAt < now;
117
- return { value: entry.value as T, stale, expiresAt: entry.expiresAt };
222
+ const value =
223
+ this.#serialize && typeof entry.value === "string"
224
+ ? JSON.parse(entry.value)
225
+ : entry.value;
226
+ return {
227
+ value: claimed<T>(value),
228
+ stale,
229
+ expiresAt: entry.expiresAt,
230
+ tags: [...entry.tags],
231
+ };
118
232
  }
119
233
 
120
234
  /**
@@ -124,8 +238,30 @@ export class MemoryDriver implements TaggableDriver {
124
238
  * into a wrong-purge under deleteByTag (audit 2026-06-13).
125
239
  */
126
240
  #evict(key: string, entry: StoredEntry): void {
127
- for (const tag of entry.tags) this.#tagIndex.get(tag)?.delete(key);
241
+ this.#untag(key, entry.tags);
128
242
  this.#store.delete(key);
243
+ this.#size -= entry.size;
244
+ }
245
+
246
+ /**
247
+ * Take `key` out of each tag's set, and drop a set it leaves empty.
248
+ *
249
+ * Emptied sets were kept, so per-user or per-id tags grew the index by one
250
+ * set per entry ever written: a store capped at ten entries held hundreds
251
+ * of megabytes of empty sets.
252
+ */
253
+ #untag(key: string, tags: string[]): void {
254
+ for (const tag of tags) {
255
+ const keys = this.#tagIndex.get(tag);
256
+ if (keys === undefined) continue;
257
+ keys.delete(key);
258
+ if (keys.size === 0) this.#tagIndex.delete(tag);
259
+ }
260
+ }
261
+
262
+ /** How many tags the index holds — what bounds its memory, for diagnostics. */
263
+ tagCount(): number {
264
+ return this.#tagIndex.size;
129
265
  }
130
266
 
131
267
  #write(
@@ -137,21 +273,44 @@ export class MemoryDriver implements TaggableDriver {
137
273
  expiresAtOverride?: number,
138
274
  ): void {
139
275
  if (value === null || value === undefined) {
140
- throw new TypeError(
141
- "Echo: caching null/undefined values is not supported",
142
- );
276
+ throw new UndefinedValueError();
277
+ }
278
+ // Before anything is touched: a value JSON cannot carry must leave the
279
+ // previous entry and its tags exactly as they were.
280
+ const stored = this.#serialize ? toJson(value) : value;
281
+ const size = typeof stored === "string" ? Buffer.byteLength(stored) : 0;
282
+ if (
283
+ (this.#maxEntrySize > 0 && size > this.#maxEntrySize) ||
284
+ (this.#maxSize > 0 && size > this.#maxSize)
285
+ ) {
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. A
288
+ // value over the whole store's bound counts as too big whatever
289
+ // maxEntrySize says: inserted, it evicted every other entry and
290
+ // then itself.
291
+ this.#deleteEntry(key);
292
+ return;
143
293
  }
144
294
  const now = Date.now();
145
- const hasTtl = ttlSeconds != null && ttlSeconds > 0;
295
+ const ttl = ttlSeconds === undefined ? 0 : checkTtlSeconds(ttlSeconds);
296
+ const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
297
+ if (expiresAtOverride === undefined && ttl < 0 && graceMs === 0) {
298
+ // Already expired, and no grace to keep a stale copy for: nothing
299
+ // to store, and the previous value must not survive it.
300
+ this.#deleteEntry(key);
301
+ return;
302
+ }
146
303
  // An absolute `expiresAtOverride` (e.g. `expire()` marking stale-now) wins
147
- // over the ttl-derived expiry; a past value makes the entry immediately stale.
304
+ // over the ttl-derived expiry; a past value makes the entry immediately
305
+ // stale. So does a negative TTL — it never reads as "no expiry".
148
306
  const expiresAt =
149
307
  expiresAtOverride !== undefined
150
308
  ? expiresAtOverride
151
- : hasTtl
152
- ? now + ttlSeconds * 1000
153
- : 0;
154
- const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
309
+ : ttl < 0
310
+ ? now - 1
311
+ : ttl > 0
312
+ ? now + ttl * 1000
313
+ : 0;
155
314
  // A never-expiring entry never goes stale either; otherwise grace extends
156
315
  // physical retention past the logical expiry. Measure grace from the LATER
157
316
  // of the expiry and now, so an already-past expiry still survives its grace.
@@ -160,15 +319,20 @@ export class MemoryDriver implements TaggableDriver {
160
319
  // its old tag-index refs, or a later deleteByTag could purge this fresh
161
320
  // value (audit 2026-05-22 F3).
162
321
  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 });
171
- this.#enforceCeiling();
322
+ if (prev !== undefined) this.#evict(key, prev);
323
+ // Inserted last, so it is the most recently used.
324
+ this.#store.set(key, {
325
+ value: stored,
326
+ expiresAt,
327
+ staleUntil,
328
+ tags,
329
+ size,
330
+ });
331
+ this.#size += size;
332
+ // Indexed BEFORE the ceiling is enforced, so an eviction that takes
333
+ // this very entry untags it. Indexed after, an entry the ceiling had
334
+ // just dropped stayed in its tags' sets, and a later deleteByTag of
335
+ // one of them purged whatever value the key held by then.
172
336
  for (const tag of tags) {
173
337
  let set = this.#tagIndex.get(tag);
174
338
  if (!set) {
@@ -177,6 +341,7 @@ export class MemoryDriver implements TaggableDriver {
177
341
  }
178
342
  set.add(key);
179
343
  }
344
+ this.#enforceCeiling();
180
345
  }
181
346
 
182
347
  async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
@@ -199,30 +364,25 @@ export class MemoryDriver implements TaggableDriver {
199
364
  }
200
365
 
201
366
  async delete(key: string): Promise<boolean> {
367
+ return this.#deleteEntry(key);
368
+ }
369
+
370
+ #deleteEntry(key: string): boolean {
202
371
  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);
372
+ if (entry === undefined) return false;
373
+ this.#evict(key, entry);
374
+ return true;
209
375
  }
210
376
 
211
377
  async flush(prefix?: string): Promise<void> {
212
378
  if (prefix === undefined) {
213
379
  this.#store.clear();
214
380
  this.#tagIndex.clear();
381
+ this.#size = 0;
215
382
  return;
216
383
  }
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);
384
+ for (const [key, entry] of [...this.#store]) {
385
+ if (key.startsWith(prefix)) this.#evict(key, entry);
226
386
  }
227
387
  }
228
388
 
@@ -252,15 +412,7 @@ export class MemoryDriver implements TaggableDriver {
252
412
  for (const key of keys) toDelete.add(key);
253
413
  }
254
414
  }
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
- }
415
+ for (const key of toDelete) this.#deleteEntry(key);
264
416
  for (const tag of tags) this.#tagIndex.delete(tag);
265
417
  }
266
418