release: WRNexusJS 0.8.0

packages/cache/src/memory.ts

@@ -19,35 +19,66 @@ export interface TagCacheOptions {
   staleWhileRevalidateMs?: number;
   maxEntries?: number;
   clock?: () => number;
+  onEvent?: (event: CacheEvent) => void;
+}
+
+export interface CacheEvent {
+  operation: "hit" | "stale" | "miss" | "set" | "delete" | "invalidate" | "clear" | "load";
+  key?: string;
+  tags?: string[];
+  at: number;
+}
+
+export interface CacheSnapshotEntry {
+  key: string;
+  state: "fresh" | "stale";
+  createdAt: number;
+  expiresAt: number;
+  staleUntil: number;
+  tags: string[];
 }
 
 export class TagCache<V = unknown> {
   private entries = new Map<string, CacheEntry<V>>();
   private tagIndex = new Map<string, Set<string>>();
   private pending = new Map<string, Promise<V>>();
+  private locks = new Map<string, Promise<void>>();
+  private revisions = new Map<string, number>();
   private readonly ttlMs: number;
   private readonly staleMs: number;
   private readonly maxEntries: number;
   private readonly clock: () => number;
+  private readonly onEvent?: (event: CacheEvent) => void;
 
   constructor(options: TagCacheOptions = {}) {
     this.ttlMs = options.ttlMs ?? 60_000;
     this.staleMs = options.staleWhileRevalidateMs ?? 0;
     this.maxEntries = Math.max(1, options.maxEntries ?? 10_000);
     this.clock = options.clock ?? Date.now;
+    this.onEvent = options.onEvent;
+  }
+
+  private emit(event: Omit<CacheEvent, "at">): void {
+    this.onEvent?.({ ...event, at: this.clock() });
   }
 
   lookup(key: string): CacheLookup<V> {
     const entry = this.entries.get(key);
-    if (!entry) return { state: "miss" };
+    if (!entry) {
+      this.emit({ operation: "miss", key });
+      return { state: "miss" };
+    }
     const now = this.clock();
     if (entry.staleUntil <= now) {
       this.delete(key);
+      this.emit({ operation: "miss", key });
       return { state: "miss" };
     }
     this.entries.delete(key);
     this.entries.set(key, entry);
-    return { state: entry.expiresAt > now ? "fresh" : "stale", entry };
+    const state = entry.expiresAt > now ? "fresh" : "stale";
+    this.emit({ operation: state === "fresh" ? "hit" : "stale", key, tags: entry.tags });
+    return { state, entry };
   }
 
   get(key: string): V | undefined {
@@ -56,7 +87,12 @@ export class TagCache<V = unknown> {
   }
 
   set(key: string, value: V, options: CacheSetOptions = {}): void {
-    this.delete(key);
+    this.bump(key);
+    this.store(key, value, options);
+  }
+
+  private store(key: string, value: V, options: CacheSetOptions): void {
+    this.removeEntry(key);
     const now = this.clock();
     const ttlMs = Math.max(0, options.ttlMs ?? this.ttlMs);
     const staleMs = Math.max(0, options.staleWhileRevalidateMs ?? this.staleMs);
@@ -69,6 +105,7 @@ export class TagCache<V = unknown> {
       tags,
     };
     this.entries.set(key, entry);
+    this.emit({ operation: "set", key, tags });
     for (const tag of tags) {
       const keys = this.tagIndex.get(tag) ?? new Set<string>();
       keys.add(key);
@@ -90,10 +127,12 @@ export class TagCache<V = unknown> {
     if (hit.state === "fresh") return hit.entry.value;
     if (hit.state === "stale") {
       if (!this.pending.has(key)) {
+        const revision = this.revision(key);
+        this.emit({ operation: "load", key, tags: options.tags });
         const refresh = Promise.resolve()
           .then(loader)
           .then((value) => {
-            this.set(key, value, options);
+            if (this.revision(key) === revision) this.store(key, value, options);
             return value;
           })
           .finally(() => this.pending.delete(key));
@@ -103,10 +142,12 @@ export class TagCache<V = unknown> {
     }
     const existing = this.pending.get(key);
     if (existing) return existing;
+    const revision = this.revision(key);
+    this.emit({ operation: "load", key, tags: options.tags });
     const pending = Promise.resolve()
       .then(loader)
       .then((value) => {
-        this.set(key, value, options);
+        if (this.revision(key) === revision) this.store(key, value, options);
         return value;
       })
       .finally(() => this.pending.delete(key));
@@ -114,7 +155,30 @@ export class TagCache<V = unknown> {
     return pending;
   }
 
+  /** Serialize arbitrary cache-adjacent work for a key without storing its result. */
+  async withLock<T>(key: string, task: () => T | Promise<T>): Promise<T> {
+    const previous = this.locks.get(key) ?? Promise.resolve();
+    let release!: () => void;
+    const current = new Promise<void>((resolve) => (release = resolve));
+    const queued = previous.then(() => current);
+    this.locks.set(key, queued);
+    await previous;
+    try {
+      return await task();
+    } finally {
+      release();
+      if (this.locks.get(key) === queued) this.locks.delete(key);
+    }
+  }
+
   delete(key: string): boolean {
+    const removed = this.removeEntry(key);
+    if (removed || this.pending.has(key)) this.bump(key);
+    if (removed) this.emit({ operation: "delete", key });
+    return removed;
+  }
+
+  private removeEntry(key: string): boolean {
     const entry = this.entries.get(key);
     if (!entry) return false;
     this.entries.delete(key);
@@ -129,23 +193,47 @@ export class TagCache<V = unknown> {
   invalidateTag(tag: string): number {
     const keys = [...(this.tagIndex.get(tag) ?? [])];
     for (const key of keys) this.delete(key);
+    this.emit({ operation: "invalidate", tags: [tag] });
     return keys.length;
   }
 
   invalidateTags(tags: Iterable<string>): number {
+    const requested = [...tags];
     const keys = new Set<string>();
-    for (const tag of tags) for (const key of this.tagIndex.get(tag) ?? []) keys.add(key);
+    for (const tag of requested) for (const key of this.tagIndex.get(tag) ?? []) keys.add(key);
     for (const key of keys) this.delete(key);
+    this.emit({ operation: "invalidate", tags: requested });
     return keys.size;
   }
 
   clear(): void {
+    for (const key of new Set([...this.entries.keys(), ...this.pending.keys()])) this.bump(key);
     this.entries.clear();
     this.tagIndex.clear();
-    this.pending.clear();
+    this.emit({ operation: "clear" });
   }
 
   get size(): number {
     return this.entries.size;
   }
+
+  snapshot(): CacheSnapshotEntry[] {
+    const now = this.clock();
+    return [...this.entries.entries()].map(([key, entry]) => ({
+      key,
+      state: entry.expiresAt > now ? "fresh" : "stale",
+      createdAt: entry.createdAt,
+      expiresAt: entry.expiresAt,
+      staleUntil: entry.staleUntil,
+      tags: [...entry.tags],
+    }));
+  }
+
+  private revision(key: string): number {
+    return this.revisions.get(key) ?? 0;
+  }
+
+  private bump(key: string): void {
+    this.revisions.set(key, this.revision(key) + 1);
+  }
 }