@open-mercato/cache 0.3.2

package/src/__tests__/service.test.ts

@@ -0,0 +1,189 @@
+import { createCacheService, CacheService } from '../service'
+
+describe('Cache Service', () => {
+  describe('Strategy selection', () => {
+    it('should default to memory strategy', async () => {
+      const cache = createCacheService()
+      await cache.set('test', 'value')
+      const value = await cache.get('test')
+      expect(value).toBe('value')
+    })
+
+    it('should use memory strategy when specified', async () => {
+      const cache = createCacheService({ strategy: 'memory' })
+      await cache.set('test', 'value')
+      const value = await cache.get('test')
+      expect(value).toBe('value')
+    })
+
+    it('should use jsonfile strategy when specified', async () => {
+      const cache = createCacheService({ 
+        strategy: 'jsonfile',
+        jsonFilePath: '.test-cache.json'
+      })
+      
+      await cache.set('test', 'value')
+      const value = await cache.get('test')
+      expect(value).toBe('value')
+      
+      await cache.clear()
+    })
+
+    it('should respect defaultTtl option', async () => {
+      const cache = createCacheService({ 
+        strategy: 'memory',
+        defaultTtl: 100
+      })
+      
+      await cache.set('test', 'value') // Should use default TTL
+      expect(await cache.get('test')).toBe('value')
+      
+      await new Promise((resolve) => setTimeout(resolve, 150))
+      expect(await cache.get('test')).toBeNull()
+    })
+  })
+
+  describe('CacheService class', () => {
+    let cache: CacheService
+
+    beforeEach(() => {
+      cache = new CacheService({ strategy: 'memory' })
+    })
+
+    it('should set and get values', async () => {
+      await cache.set('key', 'value')
+      const value = await cache.get('key')
+      expect(value).toBe('value')
+    })
+
+    it('should support tags', async () => {
+      await cache.set('user:1', { name: 'John' }, { tags: ['users'] })
+      await cache.set('user:2', { name: 'Jane' }, { tags: ['users'] })
+      
+      const deleted = await cache.deleteByTags(['users'])
+      expect(deleted).toBe(2)
+    })
+
+    it('should support all cache operations', async () => {
+      await cache.set('key1', 'value1')
+      await cache.set('key2', 'value2')
+      
+      expect(await cache.has('key1')).toBe(true)
+      expect(await cache.has('nonexistent')).toBe(false)
+      
+      const keys = await cache.keys()
+      expect(keys).toHaveLength(2)
+      
+      const stats = await cache.stats()
+      expect(stats.size).toBe(2)
+      
+      const deleted = await cache.delete('key1')
+      expect(deleted).toBe(true)
+      
+      const cleared = await cache.clear()
+      expect(cleared).toBe(1)
+    })
+
+    it('should support cleanup', async () => {
+      await cache.set('key1', 'value1', { ttl: 50 })
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      
+      const removed = await cache.cleanup()
+      expect(removed).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should support close', async () => {
+      await cache.close()
+      // Should not throw
+    })
+  })
+
+  describe('Complex scenarios', () => {
+    it('should handle concurrent operations', async () => {
+      const cache = createCacheService()
+      
+      const promises = []
+      for (let i = 0; i < 100; i++) {
+        promises.push(cache.set(`key${i}`, `value${i}`))
+      }
+      await Promise.all(promises)
+      
+      const stats = await cache.stats()
+      expect(stats.size).toBe(100)
+      
+      const getPromises = []
+      for (let i = 0; i < 100; i++) {
+        getPromises.push(cache.get(`key${i}`))
+      }
+      const values = await Promise.all(getPromises)
+      
+      values.forEach((value, i) => {
+        expect(value).toBe(`value${i}`)
+      })
+    })
+
+    it('should handle tag-based invalidation with complex tag structure', async () => {
+      const cache = createCacheService()
+      
+      // User cache entries with multiple tags
+      await cache.set('user:1:profile', { name: 'John' }, { 
+        tags: ['users', 'user:1', 'profiles', 'org:1'] 
+      })
+      await cache.set('user:1:settings', { theme: 'dark' }, { 
+        tags: ['users', 'user:1', 'settings', 'org:1'] 
+      })
+      await cache.set('user:2:profile', { name: 'Jane' }, { 
+        tags: ['users', 'user:2', 'profiles', 'org:1'] 
+      })
+      await cache.set('user:3:profile', { name: 'Bob' }, { 
+        tags: ['users', 'user:3', 'profiles', 'org:2'] 
+      })
+      
+      // Invalidate all user:1 cache
+      const deleted = await cache.deleteByTags(['user:1'])
+      expect(deleted).toBe(2)
+      expect(await cache.get('user:1:profile')).toBeNull()
+      expect(await cache.get('user:1:settings')).toBeNull()
+      expect(await cache.get('user:2:profile')).not.toBeNull()
+      
+      // Invalidate all org:1 cache
+      const deleted2 = await cache.deleteByTags(['org:1'])
+      expect(deleted2).toBe(1) // Only user:2:profile remains
+      expect(await cache.get('user:2:profile')).toBeNull()
+      expect(await cache.get('user:3:profile')).not.toBeNull()
+    })
+
+    it('should handle rapid TTL expirations', async () => {
+      const cache = createCacheService()
+      
+      // Create many entries with short TTL
+      for (let i = 0; i < 50; i++) {
+        await cache.set(`temp:${i}`, `value${i}`, { ttl: 50 })
+      }
+      
+      // Create some permanent entries
+      for (let i = 0; i < 10; i++) {
+        await cache.set(`perm:${i}`, `value${i}`)
+      }
+      
+      let stats = await cache.stats()
+      expect(stats.size).toBe(60)
+      
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      
+      stats = await cache.stats()
+      expect(stats.expired).toBe(50)
+      
+      // Cleanup should remove expired entries
+      if (!cache.cleanup) {
+        throw new Error('Expected cache strategy to support cleanup in tests')
+      }
+      const removed = await cache.cleanup()
+      expect(removed).toBe(50)
+      
+      stats = await cache.stats()
+      expect(stats.size).toBe(10)
+      expect(stats.expired).toBe(0)
+    })
+  })
+})

package/src/errors.ts

@@ -0,0 +1,14 @@
+export class CacheDependencyUnavailableError extends Error {
+  public readonly strategy: string
+  public readonly dependency: string
+  public readonly originalError?: unknown
+
+  constructor(strategy: string, dependency: string, originalError?: unknown) {
+    super(`Cache strategy "${strategy}" requires dependency "${dependency}" which is not available`)
+    this.name = 'CacheDependencyUnavailableError'
+    this.strategy = strategy
+    this.dependency = dependency
+    this.originalError = originalError
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './types'
+export * from './service'
+export { createMemoryStrategy } from './strategies/memory'
+export { createRedisStrategy } from './strategies/redis'
+export { createSqliteStrategy } from './strategies/sqlite'
+export { createJsonFileStrategy } from './strategies/jsonfile'
+export { runWithCacheTenant, getCurrentCacheTenant } from './tenantContext'

package/src/service.ts

@@ -0,0 +1,367 @@
+import type { CacheStrategy, CacheServiceOptions, CacheGetOptions, CacheSetOptions, CacheValue } from './types'
+import { createMemoryStrategy } from './strategies/memory'
+import { createRedisStrategy } from './strategies/redis'
+import { createSqliteStrategy } from './strategies/sqlite'
+import { createJsonFileStrategy } from './strategies/jsonfile'
+import { getCurrentCacheTenant } from './tenantContext'
+import { createHash } from 'node:crypto'
+import { CacheDependencyUnavailableError } from './errors'
+
+function normalizeTenantKey(raw: string | null | undefined): string {
+  const value = typeof raw === 'string' ? raw.trim() : ''
+  if (!value) return 'global'
+  return value.replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+type TenantPrefixes = {
+  keyPrefix: string
+  tagPrefix: string
+  scopeTag: string
+}
+
+type CacheMetadata = {
+  key: string
+  expiresAt: number | null
+}
+
+function isCacheMetadata(value: CacheValue | null): value is CacheMetadata {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const record = value as Record<string, unknown>
+  const hasValidKey = typeof record.key === 'string'
+  const hasValidExpiresAt =
+    !('expiresAt' in record)
+    || record.expiresAt === null
+    || typeof record.expiresAt === 'number'
+
+  return hasValidKey && hasValidExpiresAt
+}
+
+type CacheStrategyName = NonNullable<CacheServiceOptions['strategy']>
+const KNOWN_STRATEGIES: CacheStrategyName[] = ['memory', 'redis', 'sqlite', 'jsonfile']
+
+function isCacheStrategyName(value: string | undefined): value is CacheStrategyName {
+  if (!value) return false
+  return KNOWN_STRATEGIES.includes(value as CacheStrategyName)
+}
+
+function resolveTenantPrefixes(): TenantPrefixes {
+  const tenant = normalizeTenantKey(getCurrentCacheTenant())
+  const base = `tenant:${tenant}:`
+  return {
+    keyPrefix: `${base}key:`,
+    tagPrefix: `${base}tag:`,
+    scopeTag: `${base}tag:__scope__`,
+  }
+}
+
+function hashIdentifier(input: string): string {
+  return createHash('sha1').update(input).digest('hex')
+}
+
+function storageKey(originalKey: string, prefixes: TenantPrefixes): string {
+  return `${prefixes.keyPrefix}k:${hashIdentifier(originalKey)}`
+}
+
+function metaKey(originalKey: string, prefixes: TenantPrefixes): string {
+  return `${prefixes.keyPrefix}meta:${hashIdentifier(originalKey)}`
+}
+
+function hashedTag(tag: string, prefixes: TenantPrefixes): string {
+  return `${prefixes.tagPrefix}t:${hashIdentifier(tag)}`
+}
+
+function buildTagSet(tags: string[] | undefined, prefixes: TenantPrefixes, includeScope: boolean): string[] {
+  const scoped = new Set<string>()
+  if (includeScope) scoped.add(prefixes.scopeTag)
+  if (Array.isArray(tags)) {
+    for (const tag of tags) {
+      if (typeof tag === 'string' && tag.length > 0) scoped.add(hashedTag(tag, prefixes))
+    }
+  }
+  return Array.from(scoped)
+}
+
+function matchPattern(value: string, pattern: string): boolean {
+  const regexPattern = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  const regex = new RegExp(`^${regexPattern}$`)
+  return regex.test(value)
+}
+
+function createTenantAwareWrapper(base: CacheStrategy): CacheStrategy {
+  function normalizeDeletionCount(raw: number): number {
+    if (!raw) return raw
+    if (!Number.isFinite(raw)) return raw
+    return Math.ceil(raw / 2)
+  }
+
+  const get = async (key: string, options?: CacheGetOptions) => {
+    const prefixes = resolveTenantPrefixes()
+    return base.get(storageKey(key, prefixes), options)
+  }
+
+  const set = async (key: string, value: CacheValue, options?: CacheSetOptions) => {
+    const prefixes = resolveTenantPrefixes()
+    const hashedTags = buildTagSet(options?.tags, prefixes, true)
+    const ttl = options?.ttl ?? undefined
+    const nextOptions: CacheSetOptions | undefined = options
+      ? { ...options, tags: hashedTags }
+      : { tags: hashedTags }
+    await base.set(storageKey(key, prefixes), value, nextOptions)
+    const metaPayload: CacheMetadata = { key, expiresAt: ttl ? Date.now() + ttl : null }
+    await base.set(metaKey(key, prefixes), metaPayload, {
+      ttl,
+      tags: hashedTags,
+    })
+  }
+
+  const has = async (key: string) => {
+    const prefixes = resolveTenantPrefixes()
+    return base.has(storageKey(key, prefixes))
+  }
+
+  const del = async (key: string) => {
+    const prefixes = resolveTenantPrefixes()
+    const primary = await base.delete(storageKey(key, prefixes))
+    await base.delete(metaKey(key, prefixes))
+    return primary
+  }
+
+  const deleteByTags = async (tags: string[]) => {
+    const prefixes = resolveTenantPrefixes()
+    const scopedTags = buildTagSet(tags, prefixes, false)
+    if (!scopedTags.length) return 0
+    const removed = await base.deleteByTags(scopedTags)
+    return normalizeDeletionCount(removed)
+  }
+
+  const clear = async () => {
+    const prefixes = resolveTenantPrefixes()
+    const removed = await base.deleteByTags([prefixes.scopeTag])
+    return normalizeDeletionCount(removed)
+  }
+
+  const keys = async (pattern?: string) => {
+    const prefixes = resolveTenantPrefixes()
+    const metaPattern = `${prefixes.keyPrefix}meta:*`
+    const metaKeys = await base.keys(metaPattern)
+    const originals: string[] = []
+    for (const metaKey of metaKeys) {
+      const metaValue = await base.get(metaKey, { returnExpired: true })
+      if (!metaValue) continue
+      const metadata = typeof metaValue === 'string' ? null : (isCacheMetadata(metaValue) ? metaValue : null)
+      const original = typeof metaValue === 'string' ? metaValue : metadata?.key
+      if (!original) continue
+      if (pattern && !matchPattern(original, pattern)) continue
+      originals.push(original)
+    }
+    return originals
+  }
+
+  const stats = async () => {
+    const prefixes = resolveTenantPrefixes()
+    const metaKeys = await base.keys(`${prefixes.keyPrefix}meta:*`)
+    let size = 0
+    let expired = 0
+    const now = Date.now()
+    for (const metaKey of metaKeys) {
+      const metaValue = await base.get(metaKey, { returnExpired: true })
+      if (!metaValue) continue
+      const metadata = typeof metaValue === 'string' ? null : (isCacheMetadata(metaValue) ? metaValue : null)
+      const original = typeof metaValue === 'string' ? metaValue : metadata?.key
+      if (!original) continue
+      size++
+      const expiresAt = metadata?.expiresAt ?? null
+      if (expiresAt !== null && expiresAt <= now) expired++
+    }
+    return { size, expired }
+  }
+
+  const cleanup = base.cleanup
+    ? async () => normalizeDeletionCount(await base.cleanup!())
+    : undefined
+
+  const close = base.close
+    ? async () => base.close!()
+    : undefined
+
+  return {
+    get,
+    set,
+    has,
+    delete: del,
+    deleteByTags,
+    clear,
+    keys,
+    stats,
+    cleanup,
+    close,
+  }
+}
+
+/**
+ * Cache service that provides a unified interface to different cache strategies
+ * 
+ * Configuration via environment variables:
+ * - CACHE_STRATEGY: 'memory' | 'redis' | 'sqlite' | 'jsonfile' (default: 'memory')
+ * - CACHE_TTL: Default TTL in milliseconds (optional)
+ * - CACHE_REDIS_URL: Redis connection URL (for redis strategy)
+ * - CACHE_SQLITE_PATH: SQLite database file path (for sqlite strategy)
+ * - CACHE_JSON_FILE_PATH: JSON file path (for jsonfile strategy)
+ * 
+ * @example
+ * const cache = createCacheService({ strategy: 'memory', defaultTtl: 60000 })
+ * await cache.set('user:123', { name: 'John' }, { tags: ['users', 'user:123'] })
+ * const user = await cache.get('user:123')
+ * await cache.deleteByTags(['users']) // Invalidate all user-related cache
+ */
+export function createCacheService(options?: CacheServiceOptions): CacheStrategy {
+  const envStrategy = isCacheStrategyName(process.env.CACHE_STRATEGY)
+    ? process.env.CACHE_STRATEGY
+    : undefined
+  const strategyType: CacheStrategyName = options?.strategy ?? envStrategy ?? 'memory'
+
+  const envTtl = process.env.CACHE_TTL
+  const parsedEnvTtl = envTtl ? Number.parseInt(envTtl, 10) : undefined
+  const defaultTtl = options?.defaultTtl ?? (typeof parsedEnvTtl === 'number' && Number.isFinite(parsedEnvTtl) ? parsedEnvTtl : undefined)
+
+  const baseStrategy = createStrategyForType(strategyType, options, defaultTtl)
+  const resilientStrategy = withDependencyFallback(baseStrategy, strategyType, defaultTtl)
+
+  return createTenantAwareWrapper(resilientStrategy)
+}
+
+/**
+ * CacheService class wrapper for DI integration
+ * Provides the same interface as the functional API but as a class
+ */
+export class CacheService implements CacheStrategy {
+  private strategy: CacheStrategy
+
+  constructor(options?: CacheServiceOptions) {
+    this.strategy = createCacheService(options)
+  }
+
+  async get(key: string, options?: CacheGetOptions): Promise<CacheValue | null> {
+    return this.strategy.get(key, options)
+  }
+
+  async set(key: string, value: CacheValue, options?: CacheSetOptions): Promise<void> {
+    return this.strategy.set(key, value, options)
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.strategy.has(key)
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.strategy.delete(key)
+  }
+
+  async deleteByTags(tags: string[]): Promise<number> {
+    return this.strategy.deleteByTags(tags)
+  }
+
+  async clear(): Promise<number> {
+    return this.strategy.clear()
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    return this.strategy.keys(pattern)
+  }
+
+  async stats(): Promise<{ size: number; expired: number }> {
+    return this.strategy.stats()
+  }
+
+  async cleanup(): Promise<number> {
+    if (this.strategy.cleanup) {
+      return this.strategy.cleanup()
+    }
+    return 0
+  }
+
+  async close(): Promise<void> {
+    if (this.strategy.close) {
+      return this.strategy.close()
+    }
+  }
+}
+
+function createStrategyForType(strategyType: CacheStrategyName, options?: CacheServiceOptions, defaultTtl?: number): CacheStrategy {
+  switch (strategyType) {
+    case 'redis':
+      return createRedisStrategy(options?.redisUrl, { defaultTtl })
+    case 'sqlite':
+      return createSqliteStrategy(options?.sqlitePath, { defaultTtl })
+    case 'jsonfile':
+      return createJsonFileStrategy(options?.jsonFilePath, { defaultTtl })
+    case 'memory':
+    default:
+      return createMemoryStrategy({ defaultTtl })
+  }
+}
+
+function withDependencyFallback(strategy: CacheStrategy, strategyType: CacheStrategyName, defaultTtl?: number): CacheStrategy {
+  if (strategyType === 'memory') return strategy
+
+  let activeStrategy = strategy
+  let fallbackStrategy: CacheStrategy | null = null
+  let warned = false
+
+  const ensureFallback = (error: CacheDependencyUnavailableError) => {
+    if (!fallbackStrategy) {
+      fallbackStrategy = createMemoryStrategy({ defaultTtl })
+    }
+    if (!warned) {
+      const dependencyMessage = error.dependency
+        ? ` (missing dependency: ${error.dependency})`
+        : ''
+      console.warn(`[cache] ${error.strategy} strategy unavailable${dependencyMessage}. Falling back to memory strategy.`)
+      warned = true
+    }
+    activeStrategy = fallbackStrategy
+  }
+
+  const wrapMethod = <K extends keyof CacheStrategy>(method: K): CacheStrategy[K] => {
+    const handler = async (...args: Parameters<NonNullable<CacheStrategy[K]>>) => {
+      const fn = activeStrategy[method] as ((...methodArgs: Parameters<NonNullable<CacheStrategy[K]>>) => ReturnType<NonNullable<CacheStrategy[K]>>) | undefined
+      if (!fn) {
+        return undefined as Awaited<ReturnType<NonNullable<CacheStrategy[K]>>>
+      }
+
+      try {
+        return await fn(...args)
+      } catch (error) {
+        if (error instanceof CacheDependencyUnavailableError) {
+          ensureFallback(error)
+          const fallbackFn = activeStrategy[method] as ((...methodArgs: Parameters<NonNullable<CacheStrategy[K]>>) => ReturnType<NonNullable<CacheStrategy[K]>>) | undefined
+          if (!fallbackFn) {
+            return undefined as Awaited<ReturnType<NonNullable<CacheStrategy[K]>>>
+          }
+          return fallbackFn(...args)
+        }
+        throw error
+      }
+    }
+
+    return handler as CacheStrategy[K]
+  }
+
+  return {
+    get: wrapMethod('get'),
+    set: wrapMethod('set'),
+    has: wrapMethod('has'),
+    delete: wrapMethod('delete'),
+    deleteByTags: wrapMethod('deleteByTags'),
+    clear: wrapMethod('clear'),
+    keys: wrapMethod('keys'),
+    stats: wrapMethod('stats'),
+    cleanup: typeof strategy.cleanup === 'function' ? wrapMethod('cleanup') : undefined,
+    close: typeof strategy.close === 'function' ? wrapMethod('close') : undefined,
+  }
+}