@open-mercato/cache 0.9.1-develop.7517.1.3d0995a8ca → 0.9.1-develop.7518.1.343d9198f1

package/src/codec.ts

@@ -0,0 +1,94 @@
+import zlib from 'node:zlib'
+
+export type CacheCompression = 'off' | 'zstd' | 'gzip'
+
+export type CacheCodecConfig = {
+  compression: CacheCompression
+  minBytes: number
+}
+
+export type CacheCodecOptions = {
+  compression?: CacheCompression
+  compressionMinBytes?: number
+}
+
+export const DEFAULT_COMPRESSION_MIN_BYTES = 1024
+
+/** Upper bound for one decompressed entry; larger JSON is never compressed, so no legitimate entry can hit it. */
+export const MAX_DECOMPRESSED_BYTES = 64 * 1024 * 1024
+
+const ZSTD_LEVEL = 1
+const COMPRESSIONS: CacheCompression[] = ['off', 'zstd', 'gzip']
+
+const warnedMessages = new Set<string>()
+
+function warnOnce(message: string): void {
+  if (warnedMessages.has(message)) return
+  warnedMessages.add(message)
+  console.warn(message)
+}
+
+export function isZstdAvailable(): boolean {
+  return typeof zlib.zstdCompressSync === 'function' && typeof zlib.zstdDecompressSync === 'function'
+}
+
+export function parseCacheCompression(raw: string | undefined): CacheCompression {
+  const value = raw?.trim().toLowerCase()
+  if (!value) return 'off'
+  if (COMPRESSIONS.includes(value as CacheCompression)) return value as CacheCompression
+  warnOnce(`[cache] Unknown CACHE_COMPRESSION value "${raw}". Compression stays off.`)
+  return 'off'
+}
+
+export function parseCacheCompressionMinBytes(raw: string | undefined): number | undefined {
+  if (!raw) return undefined
+  const parsed = Number.parseInt(raw, 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+export function resolveCacheCodecConfig(options?: CacheCodecOptions): CacheCodecConfig {
+  const minBytes = options?.compressionMinBytes && options.compressionMinBytes > 0
+    ? options.compressionMinBytes
+    : DEFAULT_COMPRESSION_MIN_BYTES
+  let compression = options?.compression ?? 'off'
+  if (compression === 'zstd' && !isZstdAvailable()) {
+    warnOnce('[cache] zstd is not available in this Node.js runtime. Falling back to gzip cache compression.')
+    compression = 'gzip'
+  }
+  return { compression, minBytes }
+}
+
+function compress(input: Buffer, compression: Exclude<CacheCompression, 'off'>): Buffer {
+  if (compression === 'zstd') {
+    return zlib.zstdCompressSync(input, { params: { [zlib.constants.ZSTD_c_compressionLevel]: ZSTD_LEVEL } })
+  }
+  return zlib.gzipSync(input)
+}
+
+export function encodeCacheText(json: string, config: CacheCodecConfig): string | Buffer {
+  if (config.compression === 'off') return json
+  const size = Buffer.byteLength(json)
+  if (size < config.minBytes || size > MAX_DECOMPRESSED_BYTES) return json
+  const compressed = compress(Buffer.from(json, 'utf8'), config.compression)
+  return compressed.length < size ? compressed : json
+}
+
+function isZstdFrame(raw: Buffer): boolean {
+  return raw.length >= 4 && raw[0] === 0x28 && raw[1] === 0xb5 && raw[2] === 0x2f && raw[3] === 0xfd
+}
+
+function isGzipStream(raw: Buffer): boolean {
+  return raw.length >= 2 && raw[0] === 0x1f && raw[1] === 0x8b
+}
+
+/** Detects the format from the stored bytes, so entries stay readable whatever CACHE_COMPRESSION is set to now. */
+export function decodeCacheText(raw: string | Buffer): string {
+  if (typeof raw === 'string') return raw
+  if (isZstdFrame(raw)) {
+    return zlib.zstdDecompressSync(raw, { maxOutputLength: MAX_DECOMPRESSED_BYTES }).toString('utf8')
+  }
+  if (isGzipStream(raw)) {
+    return zlib.gunzipSync(raw, { maxOutputLength: MAX_DECOMPRESSED_BYTES }).toString('utf8')
+  }
+  return raw.toString('utf8')
+}

package/src/service.ts

@@ -7,6 +7,8 @@ import { getCurrentCacheTenant } from './tenantContext'
 import { createHash } from 'node:crypto'
 import { CacheDependencyUnavailableError } from './errors'
 import { matchCacheKeyPattern } from './patterns'
+import { parseCacheCompression, parseCacheCompressionMinBytes } from './codec'
+import type { CacheCodecOptions } from './codec'
 
 function normalizeTenantKey(raw: string | null | undefined): string {
   const value = typeof raw === 'string' ? raw.trim() : ''
@@ -260,7 +262,12 @@ function createConfiguredTenantAwareStrategy(options?: CacheServiceOptions): Ten
   const parsedEnvMaxEntries = envMaxEntries ? Number.parseInt(envMaxEntries, 10) : undefined
   const maxEntries = options?.maxEntries ?? (typeof parsedEnvMaxEntries === 'number' && Number.isFinite(parsedEnvMaxEntries) ? parsedEnvMaxEntries : undefined)
 
-  const baseStrategy = createStrategyForType(strategyType, options, defaultTtl, maxEntries)
+  const codecOptions: CacheCodecOptions = {
+    compression: options?.compression ?? parseCacheCompression(process.env.CACHE_COMPRESSION),
+    compressionMinBytes: options?.compressionMinBytes ?? parseCacheCompressionMinBytes(process.env.CACHE_COMPRESSION_MIN_BYTES),
+  }
+
+  const baseStrategy = createStrategyForType(strategyType, options, defaultTtl, maxEntries, codecOptions)
   const resilientStrategy = withDependencyFallback(baseStrategy, strategyType, defaultTtl, maxEntries)
   const reportsBoundedCounters = strategyType === 'memory'
 
@@ -276,6 +283,8 @@ function createConfiguredTenantAwareStrategy(options?: CacheServiceOptions): Ten
  * - 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)
+ * - CACHE_COMPRESSION: 'off' | 'zstd' | 'gzip' value compression for redis/sqlite (default: 'off')
+ * - CACHE_COMPRESSION_MIN_BYTES: smallest serialized entry that gets compressed (default: 1024)
  *
  * @example
  * const cache = createCacheService({ strategy: 'memory', defaultTtl: 60000 })
@@ -373,12 +382,12 @@ export class CacheService implements CacheStrategy {
   }
 }
 
-function createStrategyForType(strategyType: CacheStrategyName, options?: CacheServiceOptions, defaultTtl?: number, maxEntries?: number): CacheStrategy {
+function createStrategyForType(strategyType: CacheStrategyName, options?: CacheServiceOptions, defaultTtl?: number, maxEntries?: number, codecOptions?: CacheCodecOptions): CacheStrategy {
   switch (strategyType) {
     case 'redis':
-      return createRedisStrategy(options?.redisUrl, { defaultTtl })
+      return createRedisStrategy(options?.redisUrl, { defaultTtl, ...codecOptions })
     case 'sqlite':
-      return createSqliteStrategy(options?.sqlitePath, { defaultTtl })
+      return createSqliteStrategy(options?.sqlitePath, { defaultTtl, ...codecOptions })
     case 'jsonfile':
       return createJsonFileStrategy(options?.jsonFilePath, { defaultTtl })
     case 'memory':

package/src/strategies/redis.ts

@@ -3,10 +3,12 @@ import { CacheDependencyUnavailableError } from '../errors'
 import { getRedisUrlOrThrow, REDIS_WIRE_PROTOCOL } from '@open-mercato/shared/lib/redis/connection'
 import type { RedisProtocolVersion } from '@open-mercato/shared/lib/redis/connection'
 import { matchCacheKeyPattern } from '../patterns'
+import { decodeCacheText, encodeCacheText, resolveCacheCodecConfig } from '../codec'
+import type { CacheCodecOptions } from '../codec'
 
 type RedisPipeline = {
-  set(key: string, value: string): RedisPipeline
-  setex(key: string, ttlSeconds: number, value: string): RedisPipeline
+  set(key: string, value: string | Buffer): RedisPipeline
+  setex(key: string, ttlSeconds: number, value: string | Buffer): RedisPipeline
   sadd(key: string, value: string): RedisPipeline
   srem(key: string, member: string): RedisPipeline
   del(key: string): RedisPipeline
@@ -17,8 +19,9 @@ type RedisPipeline = {
 type RedisClient = {
   ping(): Promise<string>
   get(key: string): Promise<string | null>
-  set(key: string, value: string): Promise<unknown>
-  setex(key: string, ttlSeconds: number, value: string): Promise<unknown>
+  getBuffer(key: string): Promise<Buffer | null>
+  set(key: string, value: string | Buffer): Promise<unknown>
+  setex(key: string, ttlSeconds: number, value: string | Buffer): Promise<unknown>
   del(key: string): Promise<unknown>
   exists(key: string): Promise<number>
   keys(pattern: string): Promise<string[]>
@@ -186,8 +189,9 @@ async function releaseRedisEntry(key: string, entry: RedisRegistryEntry): Promis
   }
 }
 
-export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?: number }): CacheStrategy {
+export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?: number } & CacheCodecOptions): CacheStrategy {
   const defaultTtl = options?.defaultTtl
+  const codec = resolveCacheCodecConfig(options)
   const keyPrefix = 'cache:'
   const tagPrefix = 'tag:'
   const connectionUrl = redisUrl || getRedisUrlOrThrow('CACHE')
@@ -217,12 +221,12 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
   const get = async (key: string, options?: CacheGetOptions): Promise<CacheValue | null> => {
     const client = await getRedisClient()
     const cacheKey = getCacheKey(key)
-    const data = await client.get(cacheKey)
+    const data = await client.getBuffer(cacheKey)
 
     if (!data) return null
 
     try {
-      const entry: CacheEntry = JSON.parse(data)
+      const entry: CacheEntry = JSON.parse(decodeCacheText(data))
 
       if (isExpired(entry)) {
         if (options?.returnExpired) {
@@ -246,10 +250,10 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     const cacheKey = getCacheKey(key)
 
     // Remove old entry from tag index if it exists
-    const oldData = await client.get(cacheKey)
+    const oldData = await client.getBuffer(cacheKey)
     if (oldData) {
       try {
-        const oldEntry: CacheEntry = JSON.parse(oldData)
+        const oldEntry: CacheEntry = JSON.parse(decodeCacheText(oldData))
         // Remove from old tags
         const pipeline = client.pipeline()
         for (const tag of oldEntry.tags) {
@@ -276,7 +280,7 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     const pipeline = client.pipeline()
 
     // Store the entry
-    const serialized = JSON.stringify(entry)
+    const serialized = encodeCacheText(JSON.stringify(entry), codec)
     if (ttl) {
       pipeline.setex(cacheKey, Math.ceil(ttl / 1000), serialized)
     } else {
@@ -299,11 +303,11 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     if (!exists) return false
 
     // Check if expired
-    const data = await client.get(cacheKey)
+    const data = await client.getBuffer(cacheKey)
     if (!data) return false
 
     try {
-      const entry: CacheEntry = JSON.parse(data)
+      const entry: CacheEntry = JSON.parse(decodeCacheText(data))
       if (isExpired(entry)) {
         await deleteKey(key)
         return false
@@ -319,11 +323,11 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     const cacheKey = getCacheKey(key)
 
     // Get entry to remove from tag index
-    const data = await client.get(cacheKey)
+    const data = await client.getBuffer(cacheKey)
     if (!data) return false
 
     try {
-      const entry: CacheEntry = JSON.parse(data)
+      const entry: CacheEntry = JSON.parse(decodeCacheText(data))
       const pipeline = client.pipeline()
 
       // Remove from tag index
@@ -447,10 +451,10 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     
     let expired = 0
     for (const cacheKey of cacheKeys) {
-      const data = await client.get(cacheKey)
+      const data = await client.getBuffer(cacheKey)
       if (data) {
         try {
-          const entry: CacheEntry = JSON.parse(data)
+          const entry: CacheEntry = JSON.parse(decodeCacheText(data))
           if (isExpired(entry)) {
             expired++
           }
@@ -469,10 +473,10 @@ export function createRedisStrategy(redisUrl?: string, options?: { defaultTtl?:
     
     let removed = 0
     for (const cacheKey of cacheKeys) {
-      const data = await client.get(cacheKey)
+      const data = await client.getBuffer(cacheKey)
       if (data) {
         try {
-          const entry: CacheEntry = JSON.parse(data)
+          const entry: CacheEntry = JSON.parse(decodeCacheText(data))
           if (isExpired(entry)) {
             const key = cacheKey.substring(keyPrefix.length)
             await deleteKey(key)

package/src/strategies/sqlite.ts

@@ -5,6 +5,8 @@ import path from 'node:path'
 import { CacheDependencyUnavailableError } from '../errors'
 import { DEFAULT_SQLITE_CACHE_PATH } from '../defaults'
 import { matchCacheKeyPattern } from '../patterns'
+import { decodeCacheText, encodeCacheText, resolveCacheCodecConfig } from '../codec'
+import type { CacheCodecOptions } from '../codec'
 
 type SqliteStatement<TResult = unknown> = {
   get(...args: unknown[]): TResult | undefined
@@ -23,7 +25,7 @@ type SqliteDatabase = {
 
 type SqliteConstructor = new (file: string) => SqliteDatabase
 type SqliteModule = SqliteConstructor | { default: SqliteConstructor }
-type SqliteStrategyOptions = { defaultTtl?: number; databaseConstructor?: SqliteConstructor }
+type SqliteStrategyOptions = { defaultTtl?: number; databaseConstructor?: SqliteConstructor } & CacheCodecOptions
 
 const sqliteRequire = createRequire(path.join(process.cwd(), 'package.json'))
 
@@ -38,6 +40,7 @@ const sqliteRequire = createRequire(path.join(process.cwd(), 'package.json'))
 export function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOptions): CacheStrategy {
   let db: SqliteDatabase | null = null
   const defaultTtl = options?.defaultTtl
+  const codec = resolveCacheCodecConfig(options)
   const filePath = dbPath || process.env.CACHE_SQLITE_PATH || DEFAULT_SQLITE_CACHE_PATH
 
   async function getDb(): Promise<SqliteDatabase> {
@@ -93,7 +96,7 @@ export function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOp
     return Date.now() > expiresAt
   }
 
-  type EntryRow = { value: string; expires_at: number | null }
+  type EntryRow = { value: string | Buffer; expires_at: number | null }
   type ExpiresRow = { expires_at: number | null }
   type CountRow = { count: number }
   type KeyRow = { key: string }
@@ -107,7 +110,7 @@ export function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOp
     if (!row) return null
 
     try {
-      const value = JSON.parse(row.value) as CacheValue
+      const value = JSON.parse(decodeCacheText(row.value)) as CacheValue
       const expiresAt = row.expires_at
 
       if (isExpired(expiresAt)) {
@@ -134,7 +137,7 @@ export function createSqliteStrategy(dbPath?: string, options?: SqliteStrategyOp
     const expiresAt = ttl ? Date.now() + ttl : null
     const createdAt = Date.now()
 
-    const serialized = JSON.stringify(value)
+    const serialized = encodeCacheText(JSON.stringify(value), codec)
 
     database.transaction(() => {
       // Delete old tags

package/src/types.ts

@@ -120,4 +120,15 @@ export type CacheServiceOptions = {
    * disables the cap.
    */
   maxEntries?: number
+  /**
+   * Value compression for the redis and sqlite strategies. Falls back to
+   * `CACHE_COMPRESSION`, then `off`. Reads detect the stored format, so
+   * entries written under any setting stay readable.
+   */
+  compression?: 'off' | 'zstd' | 'gzip'
+  /**
+   * Smallest serialized entry, in bytes, that gets compressed. Falls back to
+   * `CACHE_COMPRESSION_MIN_BYTES`, then 1024.
+   */
+  compressionMinBytes?: number
 }