@prisma-next/middleware-cache 0.9.0-dev.6

package/src/cache-store.ts

@@ -0,0 +1,139 @@
+/**
+ * A cached set of rows produced by a single execution.
+ *
+ * - `rows` are stored raw (undecoded). The SQL runtime's `decodeRow` pass
+ *   wraps the orchestrator output, so intercepted rows go through the
+ *   same codec decoding as driver rows on the way to the consumer. The
+ *   cache stores wire-format values; decoding happens once per consumer
+ *   read regardless of where the rows came from.
+ * - `storedAt` is the clock value at the moment the entry was committed
+ *   to the store. It is informational metadata for callers (debugging,
+ *   telemetry) and is **not** used by the in-memory store itself for
+ *   expiry — TTL is driven by the store's own clock plus the `ttlMs`
+ *   passed to `set`. Custom stores may use it differently.
+ */
+export interface CachedEntry {
+  readonly rows: readonly Record<string, unknown>[];
+  readonly storedAt: number;
+}
+
+/**
+ * Pluggable cache backend used by the cache middleware.
+ *
+ * The default implementation is an in-memory LRU with TTL produced by
+ * `createInMemoryCacheStore`. Users can supply Redis, Memcached, or any
+ * other backend by implementing this interface.
+ *
+ * The interface is intentionally minimal:
+ *
+ * - `get` returns the entry if it exists and has not expired, or
+ *   `undefined` otherwise. Implementations that gate on TTL should
+ *   treat an expired entry as absent (return `undefined`) and may
+ *   evict it as a side effect.
+ * - `set` writes the entry under the key with an associated TTL in
+ *   milliseconds. Implementations may evict other entries to make
+ *   room (LRU, LFU, etc.) and may treat the operation as fire-and-
+ *   forget at scale; the cache middleware does not rely on `set`
+ *   completing before subsequent `get`s.
+ *
+ * Both methods are async to leave the door open for I/O-backed stores
+ * (Redis, S3, etc.). The default in-memory store completes
+ * synchronously and wraps the result in `Promise.resolve` for type
+ * conformance.
+ */
+export interface CacheStore {
+  get(key: string): Promise<CachedEntry | undefined>;
+  set(key: string, entry: CachedEntry, ttlMs: number): Promise<void>;
+}
+
+/**
+ * Options accepted by `createInMemoryCacheStore`.
+ *
+ * - `maxEntries` — hard cap on the number of live entries. Once the cap
+ *   is exceeded, the least recently used entry is evicted. Reads and
+ *   writes both count as "uses" for ordering purposes.
+ * - `clock` — injectable time source for TTL math. Defaults to
+ *   `Date.now`. Tests inject a controlled clock to verify expiry without
+ *   real-time waits.
+ */
+export interface InMemoryCacheStoreOptions {
+  readonly maxEntries: number;
+  readonly clock?: () => number;
+}
+
+interface StoredRecord {
+  readonly entry: CachedEntry;
+  readonly expiresAt: number;
+}
+
+/**
+ * Default cache backend. An LRU with per-entry TTL, backed by a `Map`.
+ *
+ * Eviction policy:
+ *
+ * - On `set` of a fresh key whose insertion would push the live count
+ *   above `maxEntries`, the least recently used entry is evicted.
+ *   Setting an existing key updates the entry in place and refreshes its
+ *   recency without changing the live count.
+ * - On `get` of an existing key, recency is bumped (so the entry is no
+ *   longer the LRU candidate).
+ * - On `get` of an expired entry, the entry is removed from the map and
+ *   `undefined` is returned. The slot becomes available for new writes
+ *   without counting against `maxEntries`.
+ *
+ * `Map` insertion order is the LRU order: the first key is the LRU
+ * candidate; the last key is the most recently used. Bumping recency is
+ * a delete-then-set on the underlying map.
+ *
+ * The default store is **not** coherent across processes or replicas —
+ * each process holds its own Map. Users who need a shared cache supply
+ * their own `CacheStore` (Redis, Memcached, etc.).
+ */
+export function createInMemoryCacheStore(options: InMemoryCacheStoreOptions): CacheStore {
+  const maxEntries = options.maxEntries;
+  const clock = options.clock ?? Date.now;
+  const map = new Map<string, StoredRecord>();
+
+  function get(key: string): Promise<CachedEntry | undefined> {
+    const record = map.get(key);
+    if (record === undefined) {
+      return Promise.resolve(undefined);
+    }
+    if (clock() >= record.expiresAt) {
+      map.delete(key);
+      return Promise.resolve(undefined);
+    }
+    // Bump recency: re-insert at the end of the iteration order.
+    map.delete(key);
+    map.set(key, record);
+    return Promise.resolve(record.entry);
+  }
+
+  function set(key: string, entry: CachedEntry, ttlMs: number): Promise<void> {
+    const expiresAt = clock() + ttlMs;
+    // Re-set semantics: if the key is already present, deleting first
+    // ensures the new value lands at the end of the iteration order
+    // (most recently used) rather than retaining the old slot's
+    // position. This matters for LRU correctness when the same key is
+    // re-cached after a refresh.
+    if (map.has(key)) {
+      map.delete(key);
+    }
+    map.set(key, { entry, expiresAt });
+
+    // Evict LRU entries until the live count is within bounds. The
+    // iterator yields keys in insertion order; the first one is the
+    // oldest (LRU).
+    while (map.size > maxEntries) {
+      const oldest = map.keys().next();
+      if (oldest.done) {
+        break;
+      }
+      map.delete(oldest.value);
+    }
+
+    return Promise.resolve();
+  }
+
+  return { get, set };
+}

package/src/exports/index.ts

@@ -0,0 +1,6 @@
+export type { CachePayload } from '../cache-annotation';
+export { cacheAnnotation } from '../cache-annotation';
+export type { CacheMiddlewareOptions } from '../cache-middleware';
+export { createCacheMiddleware } from '../cache-middleware';
+export type { CachedEntry, CacheStore, InMemoryCacheStoreOptions } from '../cache-store';
+export { createInMemoryCacheStore } from '../cache-store';