@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/cache/stores/memory.ts

@@ -0,0 +1,125 @@
+/**
+ * In-memory CacheStore — local consistency only.
+ *
+ * LRU eviction by entry count and optional byte budget. The TagAwareCacheHandler
+ * uses the Set-based strategy here (we implement sadd/smembers/srem/sdel with
+ * plain Maps — atomic within a single process).
+ *
+ * Tag sets may accumulate stale memberships when data entries expire via TTL or
+ * LRU eviction (the store layer cannot know which sets reference a given key).
+ * This is harmless: TagAwareCacheHandler's eager invalidation path reads each
+ * member before deleting and prunes stale entries. The cost is proportional to
+ * set size on invalidation, not to memory — stale memberships are just strings.
+ */
+
+import type { CacheStore } from '../store';
+import { estimateByteSize } from '../sizeof.js';
+
+export interface MemoryStoreOptions {
+  maxEntries?: number;
+  maxBytes?: number;
+  maxEntryBytes?: number;
+}
+
+export class MemoryCacheStore implements CacheStore {
+  private store = new Map<string, { value: string; expiresAt: number; byteSize: number }>();
+  private sets = new Map<string, Set<string>>();
+  private maxEntries: number;
+  private maxBytes: number | undefined;
+  private maxEntryBytes: number | undefined;
+  private currentBytes = 0;
+  private readonly trackBytes: boolean;
+  readonly consistency = 'local' as const;
+
+  constructor(opts?: MemoryStoreOptions) {
+    this.maxEntries = Math.max(opts?.maxEntries ?? 1000, 1);
+    this.maxBytes = opts?.maxBytes;
+    this.maxEntryBytes = opts?.maxEntryBytes;
+    this.trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.removeEntry(key);
+      return null;
+    }
+    // LRU: move to end
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    const byteSize = this.trackBytes ? estimateByteSize(value) : 0;
+
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) return;
+
+    if (this.store.has(key)) this.removeEntry(key);
+
+    while (this.store.size >= this.maxEntries) this.evictOldest();
+
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      if (this.currentBytes + byteSize > this.maxBytes) return;
+    }
+
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000, byteSize });
+    this.currentBytes += byteSize;
+  }
+
+  async del(key: string): Promise<void> {
+    this.removeEntry(key);
+  }
+
+  // Set operations — trivial in-process implementations.
+
+  async sadd(key: string, members: string[], _ttlSeconds: number): Promise<void> {
+    let set = this.sets.get(key);
+    if (!set) {
+      set = new Set();
+      this.sets.set(key, set);
+    }
+    for (const m of members) set.add(m);
+  }
+
+  async srem(key: string, members: string[]): Promise<void> {
+    const set = this.sets.get(key);
+    if (!set) return;
+    for (const m of members) set.delete(m);
+    if (set.size === 0) this.sets.delete(key);
+  }
+
+  async smembers(key: string): Promise<string[]> {
+    const set = this.sets.get(key);
+    return set ? [...set] : [];
+  }
+
+  async sdel(key: string): Promise<void> {
+    this.sets.delete(key);
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  get bytes(): number {
+    return this.currentBytes;
+  }
+
+  private removeEntry(key: string): void {
+    const entry = this.store.get(key);
+    if (entry) {
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(key);
+    }
+  }
+
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) this.removeEntry(oldest);
+  }
+}

package/src/cache/stores/redis.ts

@@ -0,0 +1,97 @@
+/**
+ * Redis CacheStore — strongly-consistent, supports native Set operations.
+ *
+ * The TagAwareCacheHandler will use the Set-based strategy automatically
+ * because this store provides sadd/smembers/srem/sdel.
+ */
+
+import type { CacheStore } from '../store';
+
+/**
+ * Minimal Redis client contract. Same philosophy as the old RedisClient
+ * interface — deliberately NOT the native shape of any library. TTL is a
+ * required positional argument so no adapter can forget it.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }).then(() => {}),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ */
+export interface RedisStoreClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  smembers(key: string): Promise<string[]>;
+  /** `EXPIRE key seconds NX` — set TTL only if the key has no existing expiry (Redis 7.0+). */
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  /** `EXPIRE key seconds GT` — extend TTL only if new value is greater (Redis 7.0+). */
+  expireGT(key: string, seconds: number): Promise<unknown>;
+}
+
+export class RedisCacheStore implements CacheStore {
+  private client: RedisStoreClient;
+  readonly consistency = 'strong' as const;
+
+  constructor(client: RedisStoreClient) {
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.client.get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    await this.client.set(key, value, ttlSeconds);
+  }
+
+  async del(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+
+  async sadd(key: string, members: string[], ttlSeconds: number): Promise<void> {
+    await this.client.sadd(key, ...members);
+    await this.client.expireNX(key, ttlSeconds);
+    await this.client.expireGT(key, ttlSeconds);
+  }
+
+  async srem(key: string, members: string[]): Promise<void> {
+    await this.client.srem(key, ...members);
+  }
+
+  async smembers(key: string): Promise<string[]> {
+    return this.client.smembers(key);
+  }
+
+  async sdel(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+}

package/src/cache/stores/vercel.ts

@@ -0,0 +1,59 @@
+/**
+ * Vercel Runtime Cache CacheStore — native tag support.
+ *
+ * Delegates tag operations to Vercel's infrastructure via their Runtime Cache
+ * API (getCache/expireTag). The TagAwareCacheHandler detects setWithTags +
+ * invalidateTag and delegates entirely — no inverted index, no version stamps.
+ *
+ * Vercel handles tag purging across CDN, Runtime Cache, and Data Cache layers
+ * simultaneously. Available on all plans.
+ */
+
+import type { CacheStore } from '../store';
+
+/**
+ * Vercel Runtime Cache contract — the subset we depend on.
+ * Resolved from `@vercel/functions` at runtime.
+ */
+export interface VercelCache {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, options: { ttl: number; tags?: string[] }): Promise<void>;
+  delete(key: string): Promise<void>;
+  expireTag(tag: string): Promise<void>;
+}
+
+export class VercelCacheStore implements CacheStore {
+  private cache: VercelCache | (() => VercelCache);
+  readonly consistency = 'strong' as const;
+
+  constructor(cache: VercelCache | (() => VercelCache)) {
+    this.cache = cache;
+  }
+
+  private getCache(): VercelCache {
+    return typeof this.cache === 'function' ? this.cache() : this.cache;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const result = await this.getCache().get(key);
+    return result ?? null;
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    await this.getCache().set(key, value, { ttl: ttlSeconds });
+  }
+
+  async del(key: string): Promise<void> {
+    await this.getCache().delete(key);
+  }
+
+  // --- Native tag support ---
+
+  async setWithTags(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void> {
+    await this.getCache().set(key, value, { ttl: ttlSeconds, tags });
+  }
+
+  async invalidateTag(tag: string): Promise<void> {
+    await this.getCache().expireTag(tag);
+  }
+}

package/src/cache/tag-aware-handler.ts

@@ -0,0 +1,237 @@
+/**
+ * TagAwareCacheHandler — wraps any CacheStore and adds tag-based invalidation.
+ *
+ * Three strategies, selected by store capabilities (best available wins):
+ *
+ * 1. **Native** (store has setWithTags + invalidateTag): Delegates entirely.
+ *    The store owns tag indexing. Used for Vercel Runtime Cache, DO-backed
+ *    stores, or any platform with first-class tag support.
+ *
+ * 2. **Eager** (store has sadd/smembers/srem/sdel): Maintains an inverted
+ *    index via atomic set operations. Invalidation enumerates the set and
+ *    deletes entries. Used for Redis.
+ *
+ * 3. **Lazy** (bare get/set/del only): Version-stamps entries with tag
+ *    counters. Invalidation bumps a counter (O(1)). Reads validate stored
+ *    versions against current. Race-free, correct under eventual consistency.
+ *    Used for Cloudflare KV.
+ *
+ * Implements the CacheHandler interface consumed by timber-cache.ts.
+ */
+
+import type { CacheHandler } from './index';
+import type { CacheStore } from './store';
+
+const DATA_PREFIX = 'd:';
+const TAG_SET_PREFIX = 'ts:';
+const TAG_VERSION_PREFIX = 'tv:';
+
+type Strategy = 'native' | 'eager' | 'lazy';
+
+/** Stored entry format for eager strategy. */
+interface EagerEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+}
+
+/** Stored entry format for lazy (version-stamp) strategy. */
+interface LazyEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+  tagVersions: Record<string, number>;
+}
+
+function detectStrategy(store: CacheStore): Strategy {
+  if (store.setWithTags && store.invalidateTag) return 'native';
+  if (store.sadd && store.smembers && store.srem && store.sdel) return 'eager';
+  return 'lazy';
+}
+
+export class TagAwareCacheHandler implements CacheHandler {
+  private store: CacheStore;
+  private prefix: string;
+  private strategy: Strategy;
+
+  constructor(store: CacheStore, opts?: { prefix?: string }) {
+    this.store = store;
+    this.prefix = opts?.prefix ?? 'timber:';
+    this.strategy = detectStrategy(store);
+  }
+
+  get consistency(): 'strong' | 'eventual' | 'local' {
+    return this.store.consistency;
+  }
+
+  private dataKey(key: string): string {
+    return `${this.prefix}${DATA_PREFIX}${key}`;
+  }
+
+  /** Namespace tags for native stores so prefix isolates shared stores. */
+  private prefixTags(tags: string[]): string[] {
+    return tags.map((t) => `${this.prefix}${t}`);
+  }
+
+  private tagSetKey(tag: string): string {
+    return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
+  }
+
+  private tagVersionKey(tag: string): string {
+    return `${this.prefix}${TAG_VERSION_PREFIX}${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const raw = await this.store.get(this.dataKey(key));
+    if (raw === null) return null;
+
+    if (this.strategy === 'native' || this.strategy === 'eager') {
+      const entry = JSON.parse(raw) as EagerEntry;
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    }
+
+    // Lazy: validate tag versions before returning
+    const entry = JSON.parse(raw) as LazyEntry;
+    if (entry.tags.length > 0) {
+      const currentVersions = await this.getTagVersions(entry.tags);
+      for (const tag of entry.tags) {
+        const stored = entry.tagVersions[tag] ?? 0;
+        const current = currentVersions[tag] ?? 0;
+        if (current > stored) return null;
+      }
+    }
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
+    const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
+
+    if (this.strategy === 'native') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      const payload = JSON.stringify(entry);
+      if (opts.tags.length > 0) {
+        await this.store.setWithTags!(
+          this.dataKey(key),
+          payload,
+          physicalTtl,
+          this.prefixTags(opts.tags)
+        );
+      } else {
+        await this.store.set(this.dataKey(key), payload, physicalTtl);
+      }
+      return;
+    }
+
+    if (this.strategy === 'eager') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+      if (opts.tags.length > 0) {
+        await Promise.all(
+          opts.tags.map((tag) => this.store.sadd!(this.tagSetKey(tag), [key], physicalTtl))
+        );
+      }
+      return;
+    }
+
+    // Lazy: snapshot current tag versions into the entry
+    const tagVersions = opts.tags.length > 0 ? await this.getTagVersions(opts.tags) : {};
+    const entry: LazyEntry = {
+      value,
+      expiresAt: Date.now() + opts.ttl * 1000,
+      tags: opts.tags,
+      tagVersions,
+    };
+    await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    if (opts.key) {
+      if (this.strategy === 'eager') {
+        const raw = await this.store.get(this.dataKey(opts.key));
+        if (raw !== null) {
+          const entry = JSON.parse(raw) as EagerEntry;
+          if (entry.tags.length > 0) {
+            await Promise.all(
+              entry.tags.map((tag) => this.store.srem!(this.tagSetKey(tag), [opts.key!]))
+            );
+          }
+        }
+      }
+      await this.store.del(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const tag = opts.tag;
+      if (this.strategy === 'native') {
+        await this.store.invalidateTag!(`${this.prefix}${tag}`);
+      } else if (this.strategy === 'eager') {
+        const members = await this.store.smembers!(this.tagSetKey(tag));
+        // Verify each member still carries the tag before deleting — the set
+        // can contain stale memberships from overwritten entries or LRU eviction.
+        // Remove only the snapshot members (via srem, not sdel) so concurrent
+        // writes that add new members between smembers() and cleanup are preserved.
+        await Promise.all(
+          members.map(async (k) => {
+            const raw = await this.store.get(this.dataKey(k));
+            if (raw === null) {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+              return;
+            }
+            const entry = JSON.parse(raw) as EagerEntry;
+            if (entry.tags.includes(tag)) {
+              await this.store.del(this.dataKey(k));
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            } else {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            }
+          })
+        );
+      } else {
+        await this.bumpTagVersion(opts.tag);
+      }
+    }
+  }
+
+  // --- Lazy strategy helpers ---
+
+  private async getTagVersions(tags: string[]): Promise<Record<string, number>> {
+    const versions: Record<string, number> = {};
+    await Promise.all(
+      tags.map(async (tag) => {
+        const raw = await this.store.get(this.tagVersionKey(tag));
+        versions[tag] = raw !== null ? parseInt(raw, 10) : 0;
+      })
+    );
+    return versions;
+  }
+
+  private async bumpTagVersion(tag: string): Promise<void> {
+    const key = this.tagVersionKey(tag);
+    const raw = await this.store.get(key);
+    const stored = raw !== null ? parseInt(raw, 10) : 0;
+    // max(stored, now) + 1: strictly advancing even within the same
+    // millisecond (two bumps in 1ms produce N, N+1 not N, N). On
+    // eventually-consistent stores the read can be stale, but Date.now()
+    // provides a floor — regression only if BOTH the read is stale AND the
+    // clock is behind, bounded by the store's propagation window (~60s).
+    const version = Math.max(stored, Date.now()) + 1;
+    // Version keys must outlive all data entries stamped with them. Data
+    // entries use physical TTL of max(ttl*2+60, 120); 365 days exceeds any
+    // practical cache lifetime.
+    await this.store.set(key, String(version), 365 * 86400);
+  }
+}