@open-mercato/cache 0.9.1-develop.7575.1.8480826a9b → 0.10.1-develop.7577.1.477f2486e5

package/dist/strategies/sqlite.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/strategies/sqlite.ts"],
-  "sourcesContent": ["import type { CacheStrategy, CacheGetOptions, CacheSetOptions, CacheValue } from '../types'\nimport fs from 'node:fs'\nimport { createRequire } from 'node:module'\nimport path from 'node:path'\nimport { CacheDependencyUnavailableError } from '../errors'\nimport { DEFAULT_SQLITE_CACHE_PATH } from '../defaults'\nimport { matchCacheKeyPattern } from '../patterns'\n\ntype SqliteStatement<TResult = unknown> = {\n  get(...args: unknown[]): TResult | undefined\n  all(...args: unknown[]): TResult[]\n  run(...args: unknown[]): { changes: number }\n}\n\ntype SqliteTransaction<TResult = unknown> = () => TResult\n\ntype SqliteDatabase = {\n  prepare<TResult = unknown>(sql: string): SqliteStatement<TResult>\n  exec(sql: string): unknown\n  transaction<TResult>(fn: () => TResult): SqliteTransaction<TResult>\n  close(): void\n}\n\ntype SqliteConstructor = new (file: string) => SqliteDatabase\ntype SqliteModule = SqliteConstructor | { default: SqliteConstructor }\ntype SqliteStrategyOptions = { defaultTtl?: number; databaseConstructor?: SqliteConstructor }\n\nconst sqliteRequire = createRequire(path.join(process.cwd(), 'package.json'))\n\n/**\n * SQLite cache strategy with tag support\n * Persistent across process restarts, stored in a SQLite database file\n * \n * Uses two tables:\n * - cache_entries: stores cache data\n * - cache_tags: stores tag associations (many-to-many)\n */\nexport function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOptions): CacheStrategy {\n  let db: SqliteDatabase | null = null\n  const defaultTtl = options?.defaultTtl\n  const filePath = dbPath || process.env.CACHE_SQLITE_PATH || DEFAULT_SQLITE_CACHE_PATH\n\n  async function getDb(): Promise<SqliteDatabase> {\n    if (db) return db\n\n    try {\n      const imported = (options?.databaseConstructor ?? sqliteRequire('better-sqlite3')) as SqliteModule\n      const Database = typeof imported === 'function' ? imported : imported.default\n      \n      // Ensure directory exists\n      const dir = path.dirname(filePath)\n      if (!fs.existsSync(dir)) {\n        fs.mkdirSync(dir, { recursive: true })\n      }\n\n      db = new Database(filePath)\n\n      db.exec(`\n        PRAGMA journal_mode = WAL;\n        PRAGMA synchronous = NORMAL;\n        PRAGMA busy_timeout = 5000;\n        PRAGMA foreign_keys = ON;\n      `)\n\n      // Create tables\n      db.exec(`\n        CREATE TABLE IF NOT EXISTS cache_entries (\n          key TEXT PRIMARY KEY,\n          value TEXT NOT NULL,\n          expires_at INTEGER,\n          created_at INTEGER NOT NULL\n        );\n\n        CREATE TABLE IF NOT EXISTS cache_tags (\n          key TEXT NOT NULL,\n          tag TEXT NOT NULL,\n          PRIMARY KEY (key, tag),\n          FOREIGN KEY (key) REFERENCES cache_entries(key) ON DELETE CASCADE\n        );\n\n        CREATE INDEX IF NOT EXISTS idx_cache_tags_tag ON cache_tags(tag);\n        CREATE INDEX IF NOT EXISTS idx_cache_entries_expires_at ON cache_entries(expires_at);\n      `)\n\n      return db\n    } catch (error) {\n      throw new CacheDependencyUnavailableError('sqlite', 'better-sqlite3', error)\n    }\n  }\n\n  function isExpired(expiresAt: number | null): boolean {\n    if (expiresAt === null) return false\n    return Date.now() > expiresAt\n  }\n\n  type EntryRow = { value: string; expires_at: number | null }\n  type ExpiresRow = { expires_at: number | null }\n  type CountRow = { count: number }\n  type KeyRow = { key: string }\n\n  const get = async (key: string, options?: CacheGetOptions): Promise<CacheValue | null> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT value, expires_at FROM cache_entries WHERE key = ?')\n    const row = stmt.get(key) as EntryRow | undefined\n\n    if (!row) return null\n\n    try {\n      const value = JSON.parse(row.value) as CacheValue\n      const expiresAt = row.expires_at\n\n      if (isExpired(expiresAt)) {\n        if (options?.returnExpired) {\n          return value\n        }\n        // Clean up expired entry\n        await deleteKey(key)\n        return null\n      }\n\n      return value\n    } catch {\n      // Invalid JSON, remove it\n      await deleteKey(key)\n      return null\n    }\n  }\n\n  const set = async (key: string, value: CacheValue, options?: CacheSetOptions): Promise<void> => {\n    const database = await getDb()\n    const ttl = options?.ttl ?? defaultTtl\n    const tags = options?.tags || []\n    const expiresAt = ttl ? Date.now() + ttl : null\n    const createdAt = Date.now()\n\n    const serialized = JSON.stringify(value)\n\n    database.transaction(() => {\n      // Delete old tags\n      database.prepare('DELETE FROM cache_tags WHERE key = ?').run(key)\n\n      // Insert or replace cache entry\n      database.prepare(`\n        INSERT OR REPLACE INTO cache_entries (key, value, expires_at, created_at)\n        VALUES (?, ?, ?, ?)\n      `).run(key, serialized, expiresAt, createdAt)\n\n      // Insert new tags\n      if (tags.length > 0) {\n        const insertTag = database.prepare('INSERT INTO cache_tags (key, tag) VALUES (?, ?)')\n        for (const tag of tags) {\n          insertTag.run(key, tag)\n        }\n      }\n    })()\n  }\n\n  const has = async (key: string): Promise<boolean> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT expires_at FROM cache_entries WHERE key = ?')\n    const row = stmt.get(key) as ExpiresRow | undefined\n\n    if (!row) return false\n\n    if (isExpired(row.expires_at)) {\n      await deleteKey(key)\n      return false\n    }\n\n    return true\n  }\n\n  const deleteKey = async (key: string): Promise<boolean> => {\n    const database = await getDb()\n    \n    const result = database.transaction(() => {\n      database.prepare('DELETE FROM cache_tags WHERE key = ?').run(key)\n      const info = database.prepare('DELETE FROM cache_entries WHERE key = ?').run(key)\n      return info.changes > 0\n    })()\n\n    return result\n  }\n\n  const deleteByTags = async (tags: string[]): Promise<number> => {\n    const database = await getDb()\n    \n    // Get all unique keys that have any of the specified tags\n    const placeholders = tags.map(() => '?').join(',')\n    const stmt = database.prepare(`\n      SELECT DISTINCT key FROM cache_tags WHERE tag IN (${placeholders})\n    `)\n    const rows = stmt.all(...tags) as KeyRow[]\n\n    let deleted = 0\n    for (const row of rows) {\n      const success = await deleteKey(row.key)\n      if (success) deleted++\n    }\n\n    return deleted\n  }\n\n  const clear = async (): Promise<number> => {\n    const database = await getDb()\n    \n    const result = database.transaction(() => {\n      const countStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries')\n      const count = (countStmt.get() as CountRow).count\n\n      database.prepare('DELETE FROM cache_tags').run()\n      database.prepare('DELETE FROM cache_entries').run()\n\n      return count\n    })()\n\n    return result\n  }\n\n  const keys = async (pattern?: string): Promise<string[]> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT key FROM cache_entries')\n    const rows = stmt.all() as KeyRow[]\n    \n    const allKeys = rows.map((row) => row.key)\n    \n    if (!pattern) return allKeys\n    \n    return allKeys.filter((key: string) => matchCacheKeyPattern(key, pattern))\n  }\n\n  const stats = async (): Promise<{ size: number; expired: number }> => {\n    const database = await getDb()\n    \n    const sizeStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries')\n    const size = (sizeStmt.get() as CountRow).count\n\n    const now = Date.now()\n    const expiredStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?')\n    const expired = (expiredStmt.get(now) as CountRow).count\n\n    return { size, expired }\n  }\n\n  const cleanup = async (): Promise<number> => {\n    const database = await getDb()\n    const now = Date.now()\n    \n    const result = database.transaction(() => {\n      // Get keys to delete\n      const stmt = database.prepare('SELECT key FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?')\n      const rows = stmt.all(now) as KeyRow[]\n\n      // Delete tags for expired keys\n      for (const row of rows) {\n        database.prepare('DELETE FROM cache_tags WHERE key = ?').run(row.key)\n      }\n\n      // Delete expired entries\n      const info = database.prepare('DELETE FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?').run(now)\n      return info.changes\n    })()\n\n    return result\n  }\n\n  const close = async (): Promise<void> => {\n    if (db) {\n      db.close()\n      db = null\n    }\n  }\n\n  return {\n    get,\n    set,\n    has,\n    delete: deleteKey,\n    deleteByTags,\n    clear,\n    keys,\n    stats,\n    cleanup,\n    close,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { CacheStrategy, CacheGetOptions, CacheSetOptions, CacheValue } from '../types'\nimport fs from 'node:fs'\nimport { createRequire } from 'node:module'\nimport path from 'node:path'\nimport { CacheDependencyUnavailableError } from '../errors'\nimport { DEFAULT_SQLITE_CACHE_PATH } from '../defaults'\nimport { matchCacheKeyPattern } from '../patterns'\nimport { decodeCacheText, encodeCacheText, resolveCacheCodecConfig } from '../codec'\nimport type { CacheCodecOptions } from '../codec'\n\ntype SqliteStatement<TResult = unknown> = {\n  get(...args: unknown[]): TResult | undefined\n  all(...args: unknown[]): TResult[]\n  run(...args: unknown[]): { changes: number }\n}\n\ntype SqliteTransaction<TResult = unknown> = () => TResult\n\ntype SqliteDatabase = {\n  prepare<TResult = unknown>(sql: string): SqliteStatement<TResult>\n  exec(sql: string): unknown\n  transaction<TResult>(fn: () => TResult): SqliteTransaction<TResult>\n  close(): void\n}\n\ntype SqliteConstructor = new (file: string) => SqliteDatabase\ntype SqliteModule = SqliteConstructor | { default: SqliteConstructor }\ntype SqliteStrategyOptions = { defaultTtl?: number; databaseConstructor?: SqliteConstructor } & CacheCodecOptions\n\nconst sqliteRequire = createRequire(path.join(process.cwd(), 'package.json'))\n\n/**\n * SQLite cache strategy with tag support\n * Persistent across process restarts, stored in a SQLite database file\n * \n * Uses two tables:\n * - cache_entries: stores cache data\n * - cache_tags: stores tag associations (many-to-many)\n */\nexport function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOptions): CacheStrategy {\n  let db: SqliteDatabase | null = null\n  const defaultTtl = options?.defaultTtl\n  const codec = resolveCacheCodecConfig(options)\n  const filePath = dbPath || process.env.CACHE_SQLITE_PATH || DEFAULT_SQLITE_CACHE_PATH\n\n  async function getDb(): Promise<SqliteDatabase> {\n    if (db) return db\n\n    try {\n      const imported = (options?.databaseConstructor ?? sqliteRequire('better-sqlite3')) as SqliteModule\n      const Database = typeof imported === 'function' ? imported : imported.default\n      \n      // Ensure directory exists\n      const dir = path.dirname(filePath)\n      if (!fs.existsSync(dir)) {\n        fs.mkdirSync(dir, { recursive: true })\n      }\n\n      db = new Database(filePath)\n\n      db.exec(`\n        PRAGMA journal_mode = WAL;\n        PRAGMA synchronous = NORMAL;\n        PRAGMA busy_timeout = 5000;\n        PRAGMA foreign_keys = ON;\n      `)\n\n      // Create tables\n      db.exec(`\n        CREATE TABLE IF NOT EXISTS cache_entries (\n          key TEXT PRIMARY KEY,\n          value TEXT NOT NULL,\n          expires_at INTEGER,\n          created_at INTEGER NOT NULL\n        );\n\n        CREATE TABLE IF NOT EXISTS cache_tags (\n          key TEXT NOT NULL,\n          tag TEXT NOT NULL,\n          PRIMARY KEY (key, tag),\n          FOREIGN KEY (key) REFERENCES cache_entries(key) ON DELETE CASCADE\n        );\n\n        CREATE INDEX IF NOT EXISTS idx_cache_tags_tag ON cache_tags(tag);\n        CREATE INDEX IF NOT EXISTS idx_cache_entries_expires_at ON cache_entries(expires_at);\n      `)\n\n      return db\n    } catch (error) {\n      throw new CacheDependencyUnavailableError('sqlite', 'better-sqlite3', error)\n    }\n  }\n\n  function isExpired(expiresAt: number | null): boolean {\n    if (expiresAt === null) return false\n    return Date.now() > expiresAt\n  }\n\n  type EntryRow = { value: string | Buffer; expires_at: number | null }\n  type ExpiresRow = { expires_at: number | null }\n  type CountRow = { count: number }\n  type KeyRow = { key: string }\n\n  const get = async (key: string, options?: CacheGetOptions): Promise<CacheValue | null> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT value, expires_at FROM cache_entries WHERE key = ?')\n    const row = stmt.get(key) as EntryRow | undefined\n\n    if (!row) return null\n\n    try {\n      const value = JSON.parse(decodeCacheText(row.value)) as CacheValue\n      const expiresAt = row.expires_at\n\n      if (isExpired(expiresAt)) {\n        if (options?.returnExpired) {\n          return value\n        }\n        // Clean up expired entry\n        await deleteKey(key)\n        return null\n      }\n\n      return value\n    } catch {\n      // Invalid JSON, remove it\n      await deleteKey(key)\n      return null\n    }\n  }\n\n  const set = async (key: string, value: CacheValue, options?: CacheSetOptions): Promise<void> => {\n    const database = await getDb()\n    const ttl = options?.ttl ?? defaultTtl\n    const tags = options?.tags || []\n    const expiresAt = ttl ? Date.now() + ttl : null\n    const createdAt = Date.now()\n\n    const serialized = encodeCacheText(JSON.stringify(value), codec)\n\n    database.transaction(() => {\n      // Delete old tags\n      database.prepare('DELETE FROM cache_tags WHERE key = ?').run(key)\n\n      // Insert or replace cache entry\n      database.prepare(`\n        INSERT OR REPLACE INTO cache_entries (key, value, expires_at, created_at)\n        VALUES (?, ?, ?, ?)\n      `).run(key, serialized, expiresAt, createdAt)\n\n      // Insert new tags\n      if (tags.length > 0) {\n        const insertTag = database.prepare('INSERT INTO cache_tags (key, tag) VALUES (?, ?)')\n        for (const tag of tags) {\n          insertTag.run(key, tag)\n        }\n      }\n    })()\n  }\n\n  const has = async (key: string): Promise<boolean> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT expires_at FROM cache_entries WHERE key = ?')\n    const row = stmt.get(key) as ExpiresRow | undefined\n\n    if (!row) return false\n\n    if (isExpired(row.expires_at)) {\n      await deleteKey(key)\n      return false\n    }\n\n    return true\n  }\n\n  const deleteKey = async (key: string): Promise<boolean> => {\n    const database = await getDb()\n    \n    const result = database.transaction(() => {\n      database.prepare('DELETE FROM cache_tags WHERE key = ?').run(key)\n      const info = database.prepare('DELETE FROM cache_entries WHERE key = ?').run(key)\n      return info.changes > 0\n    })()\n\n    return result\n  }\n\n  const deleteByTags = async (tags: string[]): Promise<number> => {\n    const database = await getDb()\n    \n    // Get all unique keys that have any of the specified tags\n    const placeholders = tags.map(() => '?').join(',')\n    const stmt = database.prepare(`\n      SELECT DISTINCT key FROM cache_tags WHERE tag IN (${placeholders})\n    `)\n    const rows = stmt.all(...tags) as KeyRow[]\n\n    let deleted = 0\n    for (const row of rows) {\n      const success = await deleteKey(row.key)\n      if (success) deleted++\n    }\n\n    return deleted\n  }\n\n  const clear = async (): Promise<number> => {\n    const database = await getDb()\n    \n    const result = database.transaction(() => {\n      const countStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries')\n      const count = (countStmt.get() as CountRow).count\n\n      database.prepare('DELETE FROM cache_tags').run()\n      database.prepare('DELETE FROM cache_entries').run()\n\n      return count\n    })()\n\n    return result\n  }\n\n  const keys = async (pattern?: string): Promise<string[]> => {\n    const database = await getDb()\n    \n    const stmt = database.prepare('SELECT key FROM cache_entries')\n    const rows = stmt.all() as KeyRow[]\n    \n    const allKeys = rows.map((row) => row.key)\n    \n    if (!pattern) return allKeys\n    \n    return allKeys.filter((key: string) => matchCacheKeyPattern(key, pattern))\n  }\n\n  const stats = async (): Promise<{ size: number; expired: number }> => {\n    const database = await getDb()\n    \n    const sizeStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries')\n    const size = (sizeStmt.get() as CountRow).count\n\n    const now = Date.now()\n    const expiredStmt = database.prepare('SELECT COUNT(*) as count FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?')\n    const expired = (expiredStmt.get(now) as CountRow).count\n\n    return { size, expired }\n  }\n\n  const cleanup = async (): Promise<number> => {\n    const database = await getDb()\n    const now = Date.now()\n    \n    const result = database.transaction(() => {\n      // Get keys to delete\n      const stmt = database.prepare('SELECT key FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?')\n      const rows = stmt.all(now) as KeyRow[]\n\n      // Delete tags for expired keys\n      for (const row of rows) {\n        database.prepare('DELETE FROM cache_tags WHERE key = ?').run(row.key)\n      }\n\n      // Delete expired entries\n      const info = database.prepare('DELETE FROM cache_entries WHERE expires_at IS NOT NULL AND expires_at < ?').run(now)\n      return info.changes\n    })()\n\n    return result\n  }\n\n  const close = async (): Promise<void> => {\n    if (db) {\n      db.close()\n      db = null\n    }\n  }\n\n  return {\n    get,\n    set,\n    has,\n    delete: deleteKey,\n    deleteByTags,\n    clear,\n    keys,\n    stats,\n    cleanup,\n    close,\n  }\n}\n"],
+  "mappings": "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",
   "names": ["options"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cache",
-  "version": "0.9.1-develop.7575.1.8480826a9b",
+  "version": "0.10.1-develop.7577.1.477f2486e5",
   "license": "MIT",
   "description": "Multi-strategy cache service with tag-based invalidation support",
   "type": "module",
@@ -72,5 +72,5 @@
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cache"
   },
-  "stableVersion": "0.9.0"
+  "stableVersion": "0.10.0"
 }

package/src/__tests__/codec.test.ts

@@ -0,0 +1,162 @@
+/** @jest-environment node */
+import zlib from 'node:zlib'
+import {
+  DEFAULT_COMPRESSION_MIN_BYTES,
+  MAX_DECOMPRESSED_BYTES,
+  decodeCacheText,
+  encodeCacheText,
+  parseCacheCompression,
+  parseCacheCompressionMinBytes,
+  resolveCacheCodecConfig,
+} from '../codec'
+import type { CacheCodecConfig } from '../codec'
+
+const ZSTD_MAGIC = [0x28, 0xb5, 0x2f, 0xfd]
+const GZIP_MAGIC = [0x1f, 0x8b]
+
+function listPayload(rows: number): string {
+  return JSON.stringify({
+    items: Array.from({ length: rows }, (_, index) => ({
+      id: `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`,
+      displayName: `Contact ${index}`,
+      primaryEmail: `contact.${index}@example.com`,
+      status: index % 2 ? 'active' : 'lead',
+    })),
+    total: rows,
+  })
+}
+
+function startsWith(raw: string | Buffer, magic: number[]): boolean {
+  return Buffer.isBuffer(raw) && magic.every((byte, index) => raw[index] === byte)
+}
+
+describe.each([
+  ['zstd', ZSTD_MAGIC],
+  ['gzip', GZIP_MAGIC],
+] as const)('cache codec (%s)', (compression, magic) => {
+  const config: CacheCodecConfig = { compression, minBytes: DEFAULT_COMPRESSION_MIN_BYTES }
+
+  it('round-trips a large entry through a compressed frame', () => {
+    const json = listPayload(100)
+    const encoded = encodeCacheText(json, config)
+
+    expect(startsWith(encoded, magic)).toBe(true)
+    expect((encoded as Buffer).length).toBeLessThan(Buffer.byteLength(json) / 4)
+    expect(decodeCacheText(encoded)).toBe(json)
+  })
+
+  it('keeps entries below the threshold as plain JSON', () => {
+    const json = listPayload(2)
+    expect(Buffer.byteLength(json)).toBeLessThan(DEFAULT_COMPRESSION_MIN_BYTES)
+
+    expect(encodeCacheText(json, config)).toBe(json)
+  })
+
+  it('stores the JSON when compression would not shrink it', () => {
+    const json = JSON.stringify({ id: 'a1' })
+
+    expect(encodeCacheText(json, { compression, minBytes: 1 })).toBe(json)
+  })
+
+  it('reads entries written by the other codec and by the off setting', () => {
+    const json = listPayload(100)
+    const other: CacheCodecConfig = { compression: compression === 'zstd' ? 'gzip' : 'zstd', minBytes: 1024 }
+
+    expect(decodeCacheText(encodeCacheText(json, other))).toBe(json)
+    expect(decodeCacheText(encodeCacheText(json, { compression: 'off', minBytes: 1024 }))).toBe(json)
+  })
+
+  it('rejects a corrupt frame', () => {
+    const encoded = encodeCacheText(listPayload(100), config) as Buffer
+    const corrupt = Buffer.concat([encoded.subarray(0, magic.length), Buffer.alloc(32, 0xff)])
+
+    expect(() => decodeCacheText(corrupt)).toThrow()
+  })
+})
+
+describe('cache codec format detection', () => {
+  it('reads legacy JSON stored as a string or as UTF-8 bytes', () => {
+    const json = listPayload(100)
+
+    expect(decodeCacheText(json)).toBe(json)
+    expect(decodeCacheText(Buffer.from(json, 'utf8'))).toBe(json)
+  })
+
+  it('never compresses with compression off', () => {
+    const json = listPayload(100)
+    expect(encodeCacheText(json, { compression: 'off', minBytes: 1 })).toBe(json)
+  })
+
+  it('skips compression above the decode cap so a legitimate entry can always be read back', () => {
+    const encodeSpy = jest.spyOn(zlib, 'gzipSync')
+    const json = 'x'.repeat(MAX_DECOMPRESSED_BYTES + 1)
+
+    expect(encodeCacheText(json, { compression: 'gzip', minBytes: 1 })).toBe(json)
+    expect(encodeSpy).not.toHaveBeenCalled()
+    encodeSpy.mockRestore()
+  })
+
+  it('caps the decompressed size of a hostile frame', () => {
+    const bomb = zlib.zstdCompressSync(Buffer.alloc(MAX_DECOMPRESSED_BYTES + 1024, 0x20))
+
+    expect(() => decodeCacheText(bomb)).toThrow()
+  })
+})
+
+describe('cache codec configuration', () => {
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('parses known compression values case-insensitively', () => {
+    expect(parseCacheCompression('zstd')).toBe('zstd')
+    expect(parseCacheCompression(' GZIP ')).toBe('gzip')
+    expect(parseCacheCompression('off')).toBe('off')
+    expect(parseCacheCompression(undefined)).toBe('off')
+    expect(parseCacheCompression('')).toBe('off')
+  })
+
+  it('treats an unknown value as off and warns once', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
+    expect(parseCacheCompression('brotli-codec-test')).toBe('off')
+    expect(parseCacheCompression('brotli-codec-test')).toBe('off')
+
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('accepts only a positive min-bytes value', () => {
+    expect(parseCacheCompressionMinBytes('2048')).toBe(2048)
+    expect(parseCacheCompressionMinBytes('0')).toBeUndefined()
+    expect(parseCacheCompressionMinBytes('-5')).toBeUndefined()
+    expect(parseCacheCompressionMinBytes('abc')).toBeUndefined()
+    expect(parseCacheCompressionMinBytes(undefined)).toBeUndefined()
+  })
+
+  it('defaults to off with a 1 KB threshold', () => {
+    expect(resolveCacheCodecConfig()).toEqual({ compression: 'off', minBytes: DEFAULT_COMPRESSION_MIN_BYTES })
+    expect(resolveCacheCodecConfig({ compression: 'zstd', compressionMinBytes: 0 })).toEqual({
+      compression: 'zstd',
+      minBytes: DEFAULT_COMPRESSION_MIN_BYTES,
+    })
+  })
+
+  it('falls back to gzip when the runtime has no zstd', () => {
+    jest.isolateModules(() => {
+      jest.doMock('node:zlib', () => {
+        const actual = jest.requireActual<typeof import('node:zlib')>('node:zlib')
+        return { ...actual, zstdCompressSync: undefined, zstdDecompressSync: undefined }
+      })
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      const isolated = require('../codec') as typeof import('../codec')
+
+      const config = isolated.resolveCacheCodecConfig({ compression: 'zstd' })
+      const encoded = isolated.encodeCacheText(listPayload(100), config)
+
+      expect(config.compression).toBe('gzip')
+      expect(startsWith(encoded, GZIP_MAGIC)).toBe(true)
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('zstd is not available'))
+    })
+    jest.dontMock('node:zlib')
+  })
+})

package/src/__tests__/redis.compression.live.test.ts

@@ -0,0 +1,41 @@
+/** @jest-environment node */
+import { randomUUID } from 'node:crypto'
+import { createRedisStrategy } from '../strategies/redis'
+
+const redisUrl = process.env.CACHE_REDIS_URL
+const describeWithRedis = redisUrl ? describe : describe.skip
+
+describeWithRedis('redis strategy value compression against a live Redis', () => {
+  const largeValue = {
+    items: Array.from({ length: 100 }, (_, index) => ({ id: `row-${index}`, name: `Contact ${index}`, status: 'active' })),
+  }
+  const runId = randomUUID()
+
+  it.each(['zstd', 'gzip'] as const)('round-trips %s frames and legacy JSON over the binary-safe path', async (compression) => {
+    const legacy = createRedisStrategy(redisUrl, { compression: 'off' })
+    const compressed = createRedisStrategy(redisUrl, { compression })
+    const legacyKey = `compression-live:${runId}:${compression}:legacy`
+    const compressedKey = `compression-live:${runId}:${compression}:compressed`
+    const tag = `compression-live:${runId}:${compression}`
+
+    try {
+      await legacy.set(legacyKey, largeValue, { ttl: 60_000, tags: [tag] })
+      await compressed.set(compressedKey, largeValue, { ttl: 60_000, tags: [tag] })
+
+      expect(await compressed.get(legacyKey)).toEqual(largeValue)
+      expect(await compressed.get(compressedKey)).toEqual(largeValue)
+      expect(await legacy.get(compressedKey)).toEqual(largeValue)
+      expect(await compressed.has(compressedKey)).toBe(true)
+
+      await compressed.set(compressedKey, largeValue, { ttl: 60_000, tags: [`${tag}:next`] })
+      expect(await compressed.deleteByTags([tag])).toBe(1)
+      expect(await compressed.deleteByTags([`${tag}:next`])).toBe(1)
+      expect(await compressed.get(compressedKey)).toBeNull()
+    } finally {
+      await legacy.delete(legacyKey)
+      await compressed.delete(compressedKey)
+      await legacy.close?.()
+      await compressed.close?.()
+    }
+  })
+})

package/src/__tests__/redis.strategy.test.ts

@@ -5,7 +5,7 @@ import { createRedisStrategy } from '../strategies/redis'
 type PipelineOp = () => void
 
 class FakeRedis {
-  values = new Map<string, string>()
+  values = new Map<string, string | Buffer>()
   sets = new Map<string, Set<string>>()
   /** Records the shape of each reap script call so tests can assert its cost. */
   evalCalls: { numKeys: number; memberCount: number }[] = []
@@ -15,15 +15,23 @@ class FakeRedis {
   }
 
   async get(key: string): Promise<string | null> {
-    return this.values.get(key) ?? null
+    const value = this.values.get(key)
+    if (value === undefined) return null
+    return Buffer.isBuffer(value) ? value.toString('utf8') : value
   }
 
-  async set(key: string, value: string): Promise<unknown> {
+  async getBuffer(key: string): Promise<Buffer | null> {
+    const value = this.values.get(key)
+    if (value === undefined) return null
+    return Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8')
+  }
+
+  async set(key: string, value: string | Buffer): Promise<unknown> {
     this.values.set(key, value)
     return 'OK'
   }
 
-  async setex(key: string, _ttlSeconds: number, value: string): Promise<unknown> {
+  async setex(key: string, _ttlSeconds: number, value: string | Buffer): Promise<unknown> {
     this.values.set(key, value)
     return 'OK'
   }
@@ -75,11 +83,11 @@ class FakeRedis {
   pipeline() {
     const ops: PipelineOp[] = []
     const chain = {
-      set: (key: string, value: string) => {
+      set: (key: string, value: string | Buffer) => {
         ops.push(() => void this.values.set(key, value))
         return chain
       },
-      setex: (key: string, _ttlSeconds: number, value: string) => {
+      setex: (key: string, _ttlSeconds: number, value: string | Buffer) => {
         ops.push(() => void this.values.set(key, value))
         return chain
       },
@@ -202,9 +210,9 @@ describe('redis strategy tag index', () => {
     // deleteByTags walks members one round trip at a time, so an entry it read
     // as missing can be rebuilt before the reap runs. Land that write in the
     // window by hooking the GET that reports the key absent.
-    const readValue = currentRedis.get.bind(currentRedis)
+    const readValue = currentRedis.getBuffer.bind(currentRedis)
     let rebuilt = false
-    currentRedis.get = async (key: string) => {
+    currentRedis.getBuffer = async (key: string) => {
       const result = await readValue(key)
       if (!rebuilt && key === 'cache:nav:user-1' && result === null) {
         rebuilt = true
@@ -214,7 +222,7 @@ describe('redis strategy tag index', () => {
     }
 
     await strategy.deleteByTags(['rbac:tenant:t1'])
-    currentRedis.get = readValue
+    currentRedis.getBuffer = readValue
 
     // The rebuilt entry must stay in the index, or it silently outlives every
     // future invalidation of this tag and serves stale data until its TTL.
@@ -276,3 +284,95 @@ describe('redis strategy tag index', () => {
     expect(await currentRedis.smembers('tag:tag-b')).toEqual(['key-1'])
   })
 })
+
+describe('redis strategy value compression', () => {
+  let urlCounter = 0
+  const largeValue = {
+    items: Array.from({ length: 100 }, (_, index) => ({ id: `row-${index}`, name: `Contact ${index}`, status: 'active' })),
+  }
+
+  function createStrategy(compression: 'off' | 'zstd' | 'gzip'): CacheStrategy {
+    urlCounter += 1
+    return createRedisStrategy(`redis://cache-compression-test-${urlCounter}`, { compression })
+  }
+
+  beforeEach(() => {
+    currentRedis = new FakeRedis()
+  })
+
+  it.each([
+    ['zstd', [0x28, 0xb5, 0x2f, 0xfd]],
+    ['gzip', [0x1f, 0x8b]],
+  ] as const)('stores large entries as %s frames and reads them back', async (compression, magic) => {
+    const strategy = createStrategy(compression)
+
+    await strategy.set('list:page:1', largeValue, { ttl: 60_000, tags: ['customers'] })
+
+    const stored = currentRedis.values.get('cache:list:page:1')
+    expect(Buffer.isBuffer(stored)).toBe(true)
+    expect(magic.every((byte, index) => (stored as Buffer)[index] === byte)).toBe(true)
+    expect(await strategy.get('list:page:1')).toEqual(largeValue)
+    expect(await strategy.has('list:page:1')).toBe(true)
+    await strategy.close?.()
+  })
+
+  it('keeps small entries as plain JSON strings', async () => {
+    const strategy = createStrategy('zstd')
+
+    await strategy.set('small', { id: 1 })
+
+    expect(typeof currentRedis.values.get('cache:small')).toBe('string')
+    expect(await strategy.get('small')).toEqual({ id: 1 })
+    await strategy.close?.()
+  })
+
+  it('reads legacy and compressed entries side by side in either direction', async () => {
+    const legacy = createStrategy('off')
+    await legacy.set('legacy', largeValue)
+    const compressed = createStrategy('zstd')
+    await compressed.set('compressed', largeValue)
+
+    expect(typeof currentRedis.values.get('cache:legacy')).toBe('string')
+    expect(await compressed.get('legacy')).toEqual(largeValue)
+    expect(await legacy.get('compressed')).toEqual(largeValue)
+    await legacy.close?.()
+    await compressed.close?.()
+  })
+
+  it('moves tag memberships when a compressed entry is overwritten', async () => {
+    const strategy = createStrategy('zstd')
+
+    await strategy.set('list', largeValue, { tags: ['old-tag'] })
+    await strategy.set('list', largeValue, { tags: ['new-tag'] })
+
+    expect(await currentRedis.smembers('tag:old-tag')).toEqual([])
+    expect(await currentRedis.smembers('tag:new-tag')).toEqual(['list'])
+    expect(await strategy.deleteByTags(['new-tag'])).toBe(1)
+    expect(currentRedis.values.has('cache:list')).toBe(false)
+    expect(await currentRedis.smembers('tag:new-tag')).toEqual([])
+    await strategy.close?.()
+  })
+
+  it('counts and cleans up expired compressed entries', async () => {
+    const strategy = createStrategy('gzip')
+    await strategy.set('fresh', largeValue, { ttl: 60_000, tags: ['t'] })
+    await strategy.set('stale', largeValue, { ttl: 1, tags: ['t'] })
+    await new Promise((resolve) => setTimeout(resolve, 5))
+
+    expect(await strategy.stats()).toEqual({ size: 2, expired: 1 })
+    expect(await strategy.cleanup?.()).toBe(1)
+    expect(currentRedis.values.has('cache:fresh')).toBe(true)
+    expect(currentRedis.values.has('cache:stale')).toBe(false)
+    expect(await currentRedis.smembers('tag:t')).toEqual(['fresh'])
+    await strategy.close?.()
+  })
+
+  it('drops a corrupt frame as a miss', async () => {
+    const strategy = createStrategy('zstd')
+    currentRedis.values.set('cache:broken', Buffer.from([0x28, 0xb5, 0x2f, 0xfd, 0xff, 0xff, 0xff]))
+
+    expect(await strategy.get('broken')).toBeNull()
+    expect(currentRedis.values.has('cache:broken')).toBe(false)
+    await strategy.close?.()
+  })
+})

package/src/__tests__/service.test.ts

@@ -392,3 +392,57 @@ describe('Cache Service stats() counter gating', () => {
     expect(stats.lastSweepReclaimed).toBe(3)
   })
 })
+
+describe('Cache Service compression resolution (CACHE_COMPRESSION)', () => {
+  afterEach(() => {
+    delete process.env.CACHE_COMPRESSION
+    delete process.env.CACHE_COMPRESSION_MIN_BYTES
+    jest.restoreAllMocks()
+  })
+
+  const captureSqliteOptions = () => {
+    const spy = jest.spyOn(sqliteStrategyModule, 'createSqliteStrategy')
+    spy.mockImplementation((_path, options) => {
+      return memoryStrategyModule.createMemoryStrategy({ defaultTtl: options?.defaultTtl })
+    })
+    return spy
+  }
+
+  it('passes the env compression settings to persistent strategies', () => {
+    process.env.CACHE_COMPRESSION = 'zstd'
+    process.env.CACHE_COMPRESSION_MIN_BYTES = '2048'
+    const spy = captureSqliteOptions()
+
+    createCacheService({ strategy: 'sqlite' })
+
+    expect(spy.mock.calls[0][1]).toMatchObject({ compression: 'zstd', compressionMinBytes: 2048 })
+  })
+
+  it('lets explicit options override the env', () => {
+    process.env.CACHE_COMPRESSION = 'zstd'
+    const spy = captureSqliteOptions()
+
+    createCacheService({ strategy: 'sqlite', compression: 'gzip', compressionMinBytes: 512 })
+
+    expect(spy.mock.calls[0][1]).toMatchObject({ compression: 'gzip', compressionMinBytes: 512 })
+  })
+
+  it('keeps compression off for an unknown env value and warns', () => {
+    process.env.CACHE_COMPRESSION = 'lz4-service-test'
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const spy = captureSqliteOptions()
+
+    createCacheService({ strategy: 'sqlite' })
+
+    expect(spy.mock.calls[0][1]).toMatchObject({ compression: 'off' })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('lz4-service-test'))
+  })
+
+  it('defaults to off with no env and no options', () => {
+    const spy = captureSqliteOptions()
+
+    createCacheService({ strategy: 'sqlite' })
+
+    expect(spy.mock.calls[0][1]).toMatchObject({ compression: 'off', compressionMinBytes: undefined })
+  })
+})

package/src/__tests__/sqlite.strategy.test.ts

@@ -3,7 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { createSqliteStrategy } from '../strategies/sqlite'
 
-type CacheEntry = { value: string; expires_at: number | null; created_at: number }
+type CacheEntry = { value: string | Buffer; expires_at: number | null; created_at: number }
 
 class MockSqliteDatabase {
   static instances: MockSqliteDatabase[] = []
@@ -90,7 +90,7 @@ class MockSqliteDatabase {
     if (sql.startsWith('INSERT OR REPLACE INTO cache_entries')) {
       const [key, value, expiresAt, createdAt] = args
       this.entries.set(String(key), {
-        value: String(value),
+        value: Buffer.isBuffer(value) ? value : String(value),
         expires_at: expiresAt === null ? null : Number(expiresAt),
         created_at: Number(createdAt),
       })
@@ -161,3 +161,54 @@ describe('SQLite Cache Strategy', () => {
     await cache.close?.()
   })
 })
+
+describe('SQLite Cache Strategy value compression (better-sqlite3)', () => {
+  const largeValue = {
+    items: Array.from({ length: 100 }, (_, index) => ({ id: `row-${index}`, name: `Contact ${index}`, status: 'active' })),
+  }
+  let tempDir: string
+  let dbPath: string
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'open-mercato-cache-compression-'))
+    dbPath = path.join(tempDir, 'cache.db')
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  function storedTypes(): Record<string, string> {
+    const Database = require('better-sqlite3') as typeof import('better-sqlite3')
+    const db = new Database(dbPath, { readonly: true })
+    try {
+      const rows = db.prepare('SELECT key, typeof(value) AS type FROM cache_entries').all() as { key: string; type: string }[]
+      return Object.fromEntries(rows.map((row) => [row.key, row.type]))
+    } finally {
+      db.close()
+    }
+  }
+
+  it.each(['zstd', 'gzip'] as const)('stores large %s entries as BLOBs next to legacy TEXT rows', async (compression) => {
+    const legacy = createSqliteStrategy(dbPath, { compression: 'off' })
+    await legacy.set('legacy', largeValue, { tags: ['customers'] })
+    await legacy.close?.()
+
+    const cache = createSqliteStrategy(dbPath, { compression })
+    await cache.set('compressed', largeValue, { tags: ['customers'] })
+    await cache.set('small', { id: 1 }, { tags: ['customers'] })
+
+    expect(await cache.get('legacy')).toEqual(largeValue)
+    expect(await cache.get('compressed')).toEqual(largeValue)
+    expect(await cache.get('small')).toEqual({ id: 1 })
+    await cache.close?.()
+
+    expect(storedTypes()).toEqual({ legacy: 'text', compressed: 'blob', small: 'text' })
+
+    const off = createSqliteStrategy(dbPath, { compression: 'off' })
+    expect(await off.get('compressed')).toEqual(largeValue)
+    expect(await off.deleteByTags(['customers'])).toBe(3)
+    expect(await off.get('compressed')).toBeNull()
+    await off.close?.()
+  })
+})