@open-mercato/cache 0.3.2

package/ENV.md

@@ -0,0 +1,173 @@
+# Cache Environment Variables
+
+This document describes the environment variables used to configure the cache service.
+
+## Configuration Variables
+
+### `CACHE_STRATEGY`
+
+**Description:** Specifies which cache storage strategy to use.
+
+**Values:** `memory` | `redis` | `sqlite` | `jsonfile`
+
+**Default:** `memory`
+
+**Example:**
+```bash
+CACHE_STRATEGY=redis
+```
+
+### `CACHE_TTL`
+
+**Description:** Default Time To Live (TTL) for cache entries in milliseconds. If not set, cache entries don't expire by default unless specified per-operation.
+
+**Type:** Number (milliseconds)
+
+**Optional:** Yes
+
+**Example:**
+```bash
+CACHE_TTL=300000  # 5 minutes
+```
+
+### `CACHE_REDIS_URL`
+
+**Description:** Redis connection URL. Required when using `redis` strategy. Falls back to `REDIS_URL` if not set.
+
+**Type:** String (URL)
+
+**Required:** Only for `redis` strategy
+
+**Example:**
+```bash
+CACHE_REDIS_URL=redis://localhost:6379
+# or
+REDIS_URL=redis://localhost:6379
+```
+
+### `CACHE_SQLITE_PATH`
+
+**Description:** Path to the SQLite database file. Required when using `sqlite` strategy.
+
+**Type:** String (file path)
+
+**Default:** `.cache.db`
+
+**Required:** Only for `sqlite` strategy
+
+**Example:**
+```bash
+CACHE_SQLITE_PATH=./data/.cache.db
+```
+
+### `CACHE_JSON_FILE_PATH`
+
+**Description:** Path to the JSON cache file. Required when using `jsonfile` strategy.
+
+**Type:** String (file path)
+
+**Default:** `.cache.json`
+
+**Required:** Only for `jsonfile` strategy
+
+**Example:**
+```bash
+CACHE_JSON_FILE_PATH=./data/.cache.json
+```
+
+## Example Configurations
+
+### Development (In-Memory)
+
+Fast, not shared across instances, data lost on restart.
+
+```bash
+CACHE_STRATEGY=memory
+CACHE_TTL=300000
+```
+
+### Production (Redis)
+
+Shared across instances, persistent, requires Redis server.
+
+```bash
+CACHE_STRATEGY=redis
+CACHE_REDIS_URL=redis://localhost:6379
+CACHE_TTL=600000
+```
+
+### Production (SQLite)
+
+Persistent, file-based, good for single instance deployments.
+
+```bash
+CACHE_STRATEGY=sqlite
+CACHE_SQLITE_PATH=./data/.cache.db
+CACHE_TTL=3600000
+```
+
+### Development/Testing (JSON File)
+
+Persistent, human-readable, slow, good for debugging.
+
+```bash
+CACHE_STRATEGY=jsonfile
+CACHE_JSON_FILE_PATH=./data/.cache.json
+CACHE_TTL=600000
+```
+
+## Strategy Comparison
+
+| Strategy   | Speed      | Persistent | Shared | Dependencies     | Use Case                        |
+|------------|------------|------------|--------|------------------|---------------------------------|
+| `memory`   | Fastest    | No         | No     | None             | Development, single instance    |
+| `redis`    | Fast       | Yes        | Yes    | ioredis          | Production, multi-instance      |
+| `sqlite`   | Medium     | Yes        | No*    | better-sqlite3   | Production, single instance     |
+| `jsonfile` | Slowest    | Yes        | No     | None             | Development, debugging          |
+
+*Not recommended for concurrent access from multiple processes
+
+## TTL Values Reference
+
+Common TTL values in milliseconds:
+
+```bash
+# 1 minute
+CACHE_TTL=60000
+
+# 5 minutes
+CACHE_TTL=300000
+
+# 10 minutes
+CACHE_TTL=600000
+
+# 30 minutes
+CACHE_TTL=1800000
+
+# 1 hour
+CACHE_TTL=3600000
+
+# 24 hours
+CACHE_TTL=86400000
+```
+
+## Installation Requirements
+
+Depending on your chosen strategy, you may need to install additional dependencies:
+
+### Redis Strategy
+
+```bash
+yarn add ioredis
+```
+
+### SQLite Strategy
+
+```bash
+yarn add better-sqlite3
+```
+
+### Memory and JSON File Strategies
+
+No additional dependencies required.
+

package/README.md

@@ -0,0 +1,177 @@
+# @open-mercato/cache
+
+> Tag-aware, strategy-pluggable cache service extracted from the Open Mercato platform—now packaged for general-purpose Node.js apps.
+
+- 🔁 **Swappable storage engines**: in-memory, Redis, SQLite, or JSON-file without touching your call-sites.
+- 🏷️ **Tag-based invalidation**: expire related keys with one operation (`deleteByTags`).
+- ⏱️ **TTL + stats tooling**: per-entry TTLs, wildcard key lookups, stats, and cleanup helpers.
+- 🧩 **DI friendly**: use the functional factory or the `CacheService` class.
+- 🧾 **Pure TypeScript**: strict typings + generated declaration files (emitted to `dist/`).
+- 🪶 **Zero hard deps**: optional peers (`ioredis`, `better-sqlite3`) only when you activate those strategies.
+
+---
+
+## Installation
+
+```bash
+yarn add @open-mercato/cache
+
+# add peers when needed
+yarn add ioredis           # for the Redis strategy
+yarn add better-sqlite3    # for the SQLite strategy
+```
+
+> Runtime: Node 18+. The library is compiled with the repo’s root `tsconfig` and ships JS + d.ts files in `dist/`.
+
+---
+
+## Quick start
+
+```ts
+import { createCacheService } from '@open-mercato/cache'
+
+const cache = createCacheService({
+  strategy: process.env.CACHE_STRATEGY || 'memory',
+  redisUrl: process.env.CACHE_REDIS_URL,
+  sqlitePath: './data/cache.db',
+  jsonFilePath: './data/cache.json',
+  defaultTtl: 5 * 60_000,
+})
+
+await cache.set('user:123', { name: 'Ada' }, { ttl: 10 * 60_000, tags: ['users', 'user:123'] })
+
+const result = await cache.get('user:123')
+await cache.deleteByTags(['users']) // bust related entries
+await cache.cleanup()               // sweep expired rows (mainly for sqlite/json)
+await cache.close()                 // dispose connections on shutdown
+```
+
+---
+
+## Strategy matrix
+
+| Strategy   | Persistence | Concurrency | Extra deps       | Typical use case                               |
+|------------|-------------|-------------|------------------|------------------------------------------------|
+| `memory`   | ❌ process   | single node | –                | Unit tests, light CLIs, temporary caches       |
+| `redis`    | ✅ external  | multi-node  | `ioredis`        | Horizontal APIs, queues, distributed workers   |
+| `sqlite`   | ✅ local     | single node | `better-sqlite3` | Edge workers, self-hosted admin tooling        |
+| `jsonfile` | ✅ local     | single node | –                | Debugging snapshots, very small deployments    |
+
+Switch the strategy via:
+
+- `CACHE_STRATEGY` env var (`memory` default), or
+- Passing `strategy`, `redisUrl`, `sqlitePath`, `jsonFilePath` to `createCacheService`.
+
+---
+
+## Configuration
+
+### Environment variables
+
+```bash
+CACHE_STRATEGY=memory|redis|sqlite|jsonfile
+CACHE_TTL=300000
+CACHE_REDIS_URL=redis://localhost:6379
+CACHE_SQLITE_PATH=.cache/cache.db
+CACHE_JSON_FILE_PATH=.cache/cache.json
+```
+
+### Programmatic
+
+```ts
+const sqliteCache = createCacheService({
+  strategy: 'sqlite',
+  sqlitePath: './data/cache.db',
+  defaultTtl: 30 * 60_000,
+})
+```
+
+---
+
+## API reference (all strategies implement these)
+
+| Method | Description |
+|--------|-------------|
+| `get(key, { returnExpired? })` | Retrieves a value, optionally returning expired records for debugging. |
+| `set(key, value, { ttl?, tags? })` | Stores a value with a TTL and tag metadata. |
+| `has(key)` | Boolean existence check (ignores expired rows). |
+| `delete(key)` | Removes a single key. |
+| `deleteByTags(tags[])` | Removes every entry that matches _any_ of the provided tags. |
+| `clear()` | Clears the current scope (all tenant-prefixed entries when used inside Open Mercato). |
+| `keys(pattern?)` | Lists logical keys using glob syntax (`*`, `?`). |
+| `stats()` | Returns `{ size, expired }` counters. |
+| `cleanup()` | Sweeps expired entries (primarily for sqlite/json backends). |
+| `close()` | Disposes the underlying client (important for Redis). |
+
+Prefer the functional factory (`createCacheService`) for most cases. If you need to integrate with Awilix or another DI container, use the `CacheService` class wrapper—its public methods mirror the table above.
+
+---
+
+## Advanced usage
+
+### Tag-based invalidation
+
+```ts
+await cache.set(`product:${id}`, payload, {
+  tags: ['products', `catalog:${catalogId}`, `product:${id}`],
+})
+
+// Later…
+await cache.deleteByTags([`catalog:${catalogId}`]) // bust only that catalog
+```
+
+Tags behave like sets. A single delete request can invalidate thousands of keys without scanning the entire store, which keeps admin actions and background jobs snappy.
+
+### Pattern matching & diagnostics
+
+```ts
+const staleKeys = await cache.keys('report:*:2024-*')
+const stats = await cache.stats()
+
+console.log(`Cache size: ${stats.size}, expired entries waiting: ${stats.expired}`)
+```
+
+The glob-matching happens on logical keys, so you can keep friendly names for troubleshooting while the implementation hashes/filters keys under the hood.
+
+---
+
+## Building & publishing
+
+This package lives inside the monorepo but publishes independently. The emitted JS and declaration files live in `dist/` (ignored by git).
+
+```bash
+# Install dependencies at the repo root
+yarn install
+
+# Build the cache package
+npx tsc -p packages/cache/tsconfig.build.json
+
+# Run the targeted test suite (optional)
+npm run test -- --runTestsByPath packages/cache/src/__tests__/service.test.ts
+
+# Inspect the tarball before publishing
+cd packages/cache
+npm pack
+
+# Publish
+npm publish --access public
+```
+
+The `package.json` already points `main`/`types` at `dist/index.*`, so consumers always receive compiled artifacts.
+
+---
+
+## Contributing
+
+1. Edit the TypeScript sources in `packages/cache/src`.
+2. Run the focused Jest suite (`npm run test -- --runTestsByPath packages/cache/src/__tests__/service.test.ts`).
+3. Rebuild (`npx tsc -p packages/cache/tsconfig.build.json`) to refresh `dist/`.
+4. Open a PR and describe the strategy/feature you touched.
+
+Bug reports & feature requests: open an issue in the main Open Mercato repository and tag it with `cache`.
+
+---
+
+## License
+
+MIT © Open Mercato

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class CacheDependencyUnavailableError extends Error {
+    readonly strategy: string;
+    readonly dependency: string;
+    readonly originalError?: unknown;
+    constructor(strategy: string, dependency: string, originalError?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAgB,QAAQ,EAAE,MAAM,CAAA;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAA;IAClC,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAA;gBAE3B,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAO1E"}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export class CacheDependencyUnavailableError extends Error {
+    constructor(strategy, dependency, originalError) {
+        super(`Cache strategy "${strategy}" requires dependency "${dependency}" which is not available`);
+        this.name = 'CacheDependencyUnavailableError';
+        this.strategy = strategy;
+        this.dependency = dependency;
+        this.originalError = originalError;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -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/dist/service.d.ts

@@ -0,0 +1,40 @@
+import type { CacheStrategy, CacheServiceOptions, CacheGetOptions, CacheSetOptions, CacheValue } from './types';
+/**
+ * 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 declare function createCacheService(options?: CacheServiceOptions): CacheStrategy;
+/**
+ * CacheService class wrapper for DI integration
+ * Provides the same interface as the functional API but as a class
+ */
+export declare class CacheService implements CacheStrategy {
+    private strategy;
+    constructor(options?: CacheServiceOptions);
+    get(key: string, options?: CacheGetOptions): Promise<CacheValue | null>;
+    set(key: string, value: CacheValue, options?: CacheSetOptions): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    deleteByTags(tags: string[]): Promise<number>;
+    clear(): Promise<number>;
+    keys(pattern?: string): Promise<string[]>;
+    stats(): Promise<{
+        size: number;
+        expired: number;
+    }>;
+    cleanup(): Promise<number>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AA6M/G;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAc/E;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAe;gBAEnB,OAAO,CAAC,EAAE,mBAAmB;IAInC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxB,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIzC,KAAK,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAInD,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAO1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}