@happyvertical/cache 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/cache
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Standardized caching interface supporting Memory, File, and Redis backends
+
+## Package Map
+- Package: `@happyvertical/cache`
+- Hierarchy path: `@happyvertical/sdk > packages > cache`
+- Workspace position: `5 of 30` local packages
+- Internal dependencies: `@happyvertical/utils`
+- Internal dependents: `@happyvertical/geo`, `@happyvertical/translator`
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/cache build
+pnpm --filter @happyvertical/cache test
+pnpm --filter @happyvertical/cache clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/cache build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/cache clean` followed by `pnpm --filter @happyvertical/cache build` and `pnpm --filter @happyvertical/cache test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Standardized caching interface supporting Memory, File, and Redis backends
+- Implements: none
+- Requires: @happyvertical/utils, @aws-sdk/client-s3, @aws-sdk/credential-providers, redis
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @happyvertical/cache
+
+Unified caching interface supporting Memory, File, Redis, and S3 backends with TTL, eviction policies, batch operations, and compression. All providers implement the same `CacheProvider` interface, so you can swap backends without changing application code.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/cache
+# Requires @happyvertical/utils as a peer
+# redis and @aws-sdk/client-s3 are bundled
+```
+
+## Quick Start
+
+```typescript
+import { getCache } from '@happyvertical/cache';
+
+const cache = await getCache({
+  provider: 'memory',
+  maxSize: 100 * 1024 * 1024,
+  evictionPolicy: 'lru',
+});
+
+await cache.set('user:123', { name: 'Alice' }, 3600); // TTL in seconds
+const user = await cache.get('user:123');
+await cache.delete('user:123');
+await cache.close();
+```
+
+## Providers
+
+### Memory
+
+In-process `Map`-based cache. No external dependencies. Data lost on restart.
+
+```typescript
+const cache = await getCache({
+  provider: 'memory',
+  namespace: 'app',
+  defaultTTL: 3600,          // seconds
+  maxSize: 100 * 1024 * 1024, // bytes (default 100MB)
+  maxEntries: 10000,          // default 10k
+  evictionPolicy: 'lru',      // 'lru' | 'lfu' | 'fifo'
+  checkPeriod: 60000,          // expiration sweep interval in ms
+});
+```
+
+### File
+
+Stores entries as files on disk with optional gzip compression. Persists across restarts.
+
+```typescript
+const cache = await getCache({
+  provider: 'file',
+  cacheDir: './cache',         // required
+  compression: true,           // gzip (default false)
+  maxSize: 500 * 1024 * 1024,  // bytes (default 500MB)
+  fileExtension: '.cache',
+  checkPeriod: 300000,         // cleanup interval in ms
+});
+```
+
+### Redis
+
+Distributed cache using the `redis` npm client. Supports optional gzip compression for large values.
+
+```typescript
+const cache = await getCache({
+  provider: 'redis',
+  host: 'localhost',
+  port: 6379,
+  password: 'secret',
+  db: 0,
+  namespace: 'app',
+  enableCompression: true,
+  compressionThreshold: 1024, // bytes — only compress values larger than this
+  connectTimeout: 5000,       // ms
+});
+```
+
+### S3
+
+Stores entries as S3 objects. Useful for CI caches that must persist between runs. Compression enabled by default to reduce egress costs.
+
+```typescript
+const cache = await getCache({
+  provider: 's3',
+  bucket: 'my-cache-bucket',
+  prefix: 'cache/',
+  region: 'us-east-1',
+  compression: true,           // default true
+  compressionThreshold: 1024,  // bytes
+});
+```
+
+## API
+
+All providers implement `CacheProvider`:
+
+```typescript
+interface CacheProvider {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+  has(key: string): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  clear(namespace?: string): Promise<void>;
+  keys(pattern?: string): Promise<string[]>;
+  getMany<T>(keys: string[]): Promise<Map<string, T>>;
+  setMany<T>(entries: Array<{ key: string; value: T; ttl?: number }>): Promise<void>;
+  deleteMany(keys: string[]): Promise<number>;
+  touch(key: string, ttl: number): Promise<boolean>;
+  getStats(): Promise<CacheStats>;
+  close(): Promise<void>;
+}
+```
+
+- **TTL** is always in seconds. Omit for no expiration.
+- **`keys()`** accepts glob patterns (`user:*`, `report:2024*`).
+- **`touch()`** updates TTL without modifying the value. Returns `false` if the key doesn't exist.
+- **Batch ops** (`getMany`, `setMany`, `deleteMany`) reduce round-trips, especially for Redis.
+
+## Environment Variables
+
+Configuration can be loaded from `HAVE_CACHE_*` environment variables via `@happyvertical/utils/loadEnvConfig`. Programmatic options always take precedence.
+
+| Variable | Maps to | Notes |
+|----------|---------|-------|
+| `HAVE_CACHE_PROVIDER` | `provider` | `memory`, `file`, `redis`, `s3` |
+| `HAVE_CACHE_NAMESPACE` | `namespace` | |
+| `HAVE_CACHE_DEFAULT_TTL` | `defaultTTL` | seconds |
+| `HAVE_CACHE_MAX_SIZE` | `maxSize` | bytes (memory/file) |
+| `HAVE_CACHE_MAX_ENTRIES` | `maxEntries` | memory only |
+| `HAVE_CACHE_EVICTION_POLICY` | `evictionPolicy` | memory only |
+| `HAVE_CACHE_CACHE_DIR` | `cacheDir` | file only |
+| `HAVE_CACHE_COMPRESSION` | `compression` | file/s3 |
+| `HAVE_CACHE_HOST` | `host` | redis only |
+| `HAVE_CACHE_PORT` | `port` | redis only |
+| `HAVE_CACHE_PASSWORD` | `password` | redis only |
+| `HAVE_CACHE_BUCKET` | `bucket` | s3 only |
+| `HAVE_CACHE_PREFIX` | `prefix` | s3 only |
+| `HAVE_CACHE_REGION` | `region` | s3 only |
+
+## Error Classes
+
+All errors extend `CacheError(message, code, provider)`:
+
+- `CacheKeyError` — invalid key (empty or >250 chars)
+- `CacheConnectionError` — backend unreachable (Redis)
+- `CacheSizeError` — entry would exceed `maxSize`
+- `CacheSerializationError` — JSON serialize/deserialize failure
+
+## Exported Utilities
+
+Low-level helpers re-exported from `shared/utils`:
+
+- `isValidKey(key)` — check key length constraints
+- `calculateSize(value)` — approximate JSON byte size
+- `matchesPattern(pattern, str)` — glob matching
+- `formatKey(namespace, key)` / `extractKey(namespace, fullKey)` — namespace prefixing
+- `isExpired(expiresAt)` / `calculateExpiration(ttl)` — TTL math
+- `serialize(value)` / `deserialize(json)` — JSON wrappers

package/dist/chunks/file-DyC_7WDS.js

@@ -0,0 +1,450 @@
+import { readFile, rm, stat, mkdir, readdir, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { promisify } from "node:util";
+import { gunzip, gzip } from "node:zlib";
+import { isValidKey, CacheKeyError, formatKey, deserialize, isExpired, CacheError, calculateExpiration, calculateSize, extractKey, matchesPattern, serialize, CacheSerializationError, CacheSizeError } from "../index.js";
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+class FileProvider {
+  cacheDir;
+  namespace;
+  defaultTTL;
+  maxSize;
+  compression;
+  fileExtension;
+  checkPeriod;
+  checkInterval;
+  stats;
+  constructor(options) {
+    this.cacheDir = resolve(options.cacheDir);
+    this.namespace = options.namespace;
+    this.defaultTTL = options.defaultTTL;
+    this.maxSize = options.maxSize || 500 * 1024 * 1024;
+    this.compression = options.compression ?? false;
+    this.fileExtension = options.fileExtension || ".cache";
+    this.checkPeriod = options.checkPeriod || 3e5;
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0
+    };
+    this.ensureCacheDir();
+    this.startCleanup();
+  }
+  async get(key) {
+    if (!isValidKey(key)) {
+      throw new CacheKeyError(key, "file");
+    }
+    const fullKey = formatKey(this.namespace, key);
+    const filePath = this.getFilePath(fullKey);
+    try {
+      const fileContent = await readFile(filePath);
+      let data;
+      if (this.compression) {
+        data = await gunzipAsync(fileContent);
+      } else {
+        data = fileContent;
+      }
+      const entry = deserialize(data.toString("utf-8"));
+      if (isExpired(entry.expiresAt)) {
+        await rm(filePath, { force: true });
+        this.stats.misses++;
+        return void 0;
+      }
+      entry.hits++;
+      this.stats.hits++;
+      await this.writeEntry(filePath, entry);
+      return entry.value;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        this.stats.misses++;
+        return void 0;
+      }
+      throw new CacheError(
+        `Failed to read cache entry: ${error.message}`,
+        "READ_ERROR",
+        "file"
+      );
+    }
+  }
+  async set(key, value, ttl) {
+    if (!isValidKey(key)) {
+      throw new CacheKeyError(key, "file");
+    }
+    const fullKey = formatKey(this.namespace, key);
+    const filePath = this.getFilePath(fullKey);
+    const expiresAt = calculateExpiration(ttl ?? this.defaultTTL);
+    const entry = {
+      value,
+      createdAt: Date.now(),
+      expiresAt,
+      size: calculateSize(value),
+      hits: 0,
+      metadata: {
+        compressed: this.compression,
+        namespace: this.namespace
+      }
+    };
+    await this.evictIfNeeded(entry.size);
+    await this.writeEntry(filePath, entry);
+  }
+  async has(key) {
+    if (!isValidKey(key)) {
+      throw new CacheKeyError(key, "file");
+    }
+    const fullKey = formatKey(this.namespace, key);
+    const filePath = this.getFilePath(fullKey);
+    try {
+      const fileContent = await readFile(filePath);
+      let data;
+      if (this.compression) {
+        data = await gunzipAsync(fileContent);
+      } else {
+        data = fileContent;
+      }
+      const entry = deserialize(data.toString("utf-8"));
+      if (isExpired(entry.expiresAt)) {
+        await rm(filePath, { force: true });
+        return false;
+      }
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw new CacheError(
+        `Failed to check cache entry: ${error.message}`,
+        "CHECK_ERROR",
+        "file"
+      );
+    }
+  }
+  async delete(key) {
+    if (!isValidKey(key)) {
+      throw new CacheKeyError(key, "file");
+    }
+    const fullKey = formatKey(this.namespace, key);
+    const filePath = this.getFilePath(fullKey);
+    try {
+      await rm(filePath);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw new CacheError(
+        `Failed to delete cache entry: ${error.message}`,
+        "DELETE_ERROR",
+        "file"
+      );
+    }
+  }
+  async clear(namespace) {
+    if (namespace) {
+      const prefix = this.sanitizeKey(`${namespace}:`);
+      const files = await this.getAllFiles();
+      for (const file of files) {
+        if (file.startsWith(prefix)) {
+          await rm(join(this.cacheDir, file), { force: true });
+        }
+      }
+    } else {
+      try {
+        await rm(this.cacheDir, { recursive: true, force: true });
+        await this.ensureCacheDir();
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.evictions = 0;
+      } catch (error) {
+        throw new CacheError(
+          `Failed to clear cache: ${error.message}`,
+          "CLEAR_ERROR",
+          "file"
+        );
+      }
+    }
+  }
+  async keys(pattern) {
+    const files = await this.getAllFiles();
+    const keys = [];
+    for (const file of files) {
+      const key = file.replace(this.fileExtension, "");
+      const filePath = join(this.cacheDir, file);
+      try {
+        const fileContent = await readFile(filePath);
+        let data;
+        if (this.compression) {
+          data = await gunzipAsync(fileContent);
+        } else {
+          data = fileContent;
+        }
+        const entry = deserialize(data.toString("utf-8"));
+        if (!isExpired(entry.expiresAt)) {
+          const desanitized = this.desanitizeKey(key);
+          keys.push(extractKey(this.namespace, desanitized));
+        }
+      } catch {
+      }
+    }
+    if (pattern) {
+      return keys.filter((key) => matchesPattern(pattern, key));
+    }
+    return keys;
+  }
+  async getMany(keys) {
+    const result = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      const value = await this.get(key);
+      if (value !== void 0) {
+        result.set(key, value);
+      }
+    }
+    return result;
+  }
+  async setMany(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.ttl);
+    }
+  }
+  async deleteMany(keys) {
+    let deleted = 0;
+    for (const key of keys) {
+      const wasDeleted = await this.delete(key);
+      if (wasDeleted) {
+        deleted++;
+      }
+    }
+    return deleted;
+  }
+  async getStats() {
+    const files = await this.getAllFiles();
+    let totalSize = 0;
+    let entries = 0;
+    for (const file of files) {
+      const filePath = join(this.cacheDir, file);
+      try {
+        const stats = await stat(filePath);
+        totalSize += stats.size;
+        const fileContent = await readFile(filePath);
+        let data;
+        if (this.compression) {
+          data = await gunzipAsync(fileContent);
+        } else {
+          data = fileContent;
+        }
+        const entry = deserialize(data.toString("utf-8"));
+        if (!isExpired(entry.expiresAt)) {
+          entries++;
+        }
+      } catch {
+      }
+    }
+    const totalAccesses = this.stats.hits + this.stats.misses;
+    const hitRate = totalAccesses > 0 ? this.stats.hits / totalAccesses : 0;
+    return {
+      entries,
+      totalSize,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      hitRate,
+      evictions: this.stats.evictions,
+      backend: {
+        type: "file",
+        cacheDir: this.cacheDir,
+        compression: this.compression,
+        maxSize: this.maxSize
+      }
+    };
+  }
+  async touch(key, ttl) {
+    if (!isValidKey(key)) {
+      throw new CacheKeyError(key, "file");
+    }
+    const fullKey = formatKey(this.namespace, key);
+    const filePath = this.getFilePath(fullKey);
+    try {
+      const fileContent = await readFile(filePath);
+      let data;
+      if (this.compression) {
+        data = await gunzipAsync(fileContent);
+      } else {
+        data = fileContent;
+      }
+      const entry = deserialize(data.toString("utf-8"));
+      if (isExpired(entry.expiresAt)) {
+        return false;
+      }
+      entry.expiresAt = calculateExpiration(ttl);
+      await this.writeEntry(filePath, entry);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw new CacheError(
+        `Failed to touch cache entry: ${error.message}`,
+        "TOUCH_ERROR",
+        "file"
+      );
+    }
+  }
+  async close() {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = void 0;
+    }
+  }
+  /**
+   * Ensures cache directory exists
+   */
+  async ensureCacheDir() {
+    try {
+      await mkdir(this.cacheDir, { recursive: true });
+    } catch (error) {
+      throw new CacheError(
+        `Failed to create cache directory: ${error.message}`,
+        "INIT_ERROR",
+        "file"
+      );
+    }
+  }
+  /**
+   * Gets the file path for a cache key
+   */
+  getFilePath(key) {
+    const sanitizedKey = this.sanitizeKey(key);
+    return join(this.cacheDir, `${sanitizedKey}${this.fileExtension}`);
+  }
+  /**
+   * Sanitizes a key for use as a filename
+   */
+  sanitizeKey(key) {
+    return key.replace(/[^a-zA-Z0-9_:-]/g, "_");
+  }
+  /**
+   * Desanitizes a filename back to the original key
+   */
+  desanitizeKey(sanitized) {
+    return sanitized;
+  }
+  /**
+   * Gets all cache file names
+   */
+  async getAllFiles() {
+    try {
+      const files = await readdir(this.cacheDir);
+      return files.filter((file) => file.endsWith(this.fileExtension));
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw new CacheError(
+        `Failed to list cache files: ${error.message}`,
+        "LIST_ERROR",
+        "file"
+      );
+    }
+  }
+  /**
+   * Writes an entry to a file
+   */
+  async writeEntry(filePath, entry) {
+    try {
+      let data;
+      const json = serialize(entry);
+      data = Buffer.from(json, "utf-8");
+      if (this.compression) {
+        data = await gzipAsync(data);
+      }
+      await writeFile(filePath, data);
+    } catch (error) {
+      throw new CacheSerializationError(
+        `Failed to write cache entry: ${error.message}`,
+        "file"
+      );
+    }
+  }
+  /**
+   * Evicts files if size limit is exceeded
+   */
+  async evictIfNeeded(newEntrySize) {
+    const stats = await this.getStats();
+    if (stats.totalSize + newEntrySize > this.maxSize) {
+      await this.evict();
+      const updatedStats = await this.getStats();
+      if (updatedStats.totalSize + newEntrySize > this.maxSize) {
+        throw new CacheSizeError(
+          `Cannot cache entry: would exceed max size of ${this.maxSize} bytes`,
+          "file"
+        );
+      }
+    }
+  }
+  /**
+   * Evicts oldest files based on creation time
+   */
+  async evict() {
+    const files = await this.getAllFiles();
+    const filesWithStats = [];
+    for (const file of files) {
+      const filePath = join(this.cacheDir, file);
+      try {
+        const fileContent = await readFile(filePath);
+        let data;
+        if (this.compression) {
+          data = await gunzipAsync(fileContent);
+        } else {
+          data = fileContent;
+        }
+        const entry = deserialize(data.toString("utf-8"));
+        filesWithStats.push({ file, createdAt: entry.createdAt });
+      } catch {
+      }
+    }
+    filesWithStats.sort((a, b) => a.createdAt - b.createdAt);
+    const toRemove = Math.max(1, Math.floor(filesWithStats.length * 0.1));
+    for (let i = 0; i < toRemove; i++) {
+      const filePath = join(this.cacheDir, filesWithStats[i].file);
+      await rm(filePath, { force: true });
+      this.stats.evictions++;
+    }
+  }
+  /**
+   * Starts background cleanup of expired files
+   */
+  startCleanup() {
+    this.checkInterval = setInterval(() => {
+      this.removeExpiredFiles();
+    }, this.checkPeriod);
+    if (this.checkInterval.unref) {
+      this.checkInterval.unref();
+    }
+  }
+  /**
+   * Removes expired files
+   */
+  async removeExpiredFiles() {
+    const files = await this.getAllFiles();
+    for (const file of files) {
+      const filePath = join(this.cacheDir, file);
+      try {
+        const fileContent = await readFile(filePath);
+        let data;
+        if (this.compression) {
+          data = await gunzipAsync(fileContent);
+        } else {
+          data = fileContent;
+        }
+        const entry = deserialize(data.toString("utf-8"));
+        if (isExpired(entry.expiresAt)) {
+          await rm(filePath, { force: true });
+        }
+      } catch {
+      }
+    }
+  }
+}
+export {
+  FileProvider
+};
+//# sourceMappingURL=file-DyC_7WDS.js.map