@maestro-js/cache 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,392 @@
+# @maestro-js/cache
+
+Key-value caching with optional TTL, stale-while-revalidate (SWR), distributed locking, and
+cache-aside (`remember`) pattern. This is the canonical example of the Maestro Provider pattern.
+
+## Quick Setup
+
+```ts
+import { Cache } from '@maestro-js/cache'
+
+// Create and register a cache instance
+const cacheService = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379 })
+})
+Cache.Provider.register('default', cacheService)
+
+// Use directly via the facade
+await Cache.set('user:123', { name: 'Alice' }, 3600)
+const user = await Cache.get<User>('user:123')
+```
+
+## Provider Pattern
+
+Cache follows the standard Maestro Provider pattern built on `@maestro-js/service-registry`:
+
+1. **`Cache.Provider.create(config)`** -- factory that instantiates a cache service with a driver
+2. **`Cache.Provider.register(name, service)`** -- register the instance in a named registry
+3. **`Cache.provider(key)`** -- resolve a named instance (deferred via Proxy)
+4. **Facade** -- `Cache.get()`, `Cache.set()`, etc. spread from `provider('default')`
+5. **`Cache.drivers`** -- factory functions for pluggable backends (`redis`, `mockRedis`)
+
+Extend provider keys via declaration merging:
+
+```ts
+declare module '@maestro-js/cache' {
+  namespace Cache.Provider {
+    interface Keys {
+      default: unknown
+      sessions: unknown
+    }
+  }
+}
+```
+
+Source: `packages/cache/src/index.ts`
+
+## Drivers
+
+### Redis
+
+Production driver backed by ioredis. Pass connection details and optional tuning:
+
+```ts
+Cache.drivers.redis({
+  url: 'redis-host',
+  port: 6379,
+  operationTimeout: 5000,   // ms, default 5000
+  connectTimeout: 10000,    // ms, default 10000
+  keyPrefix: 'myapp:',      // optional prefix for all keys
+  logger: customLogger       // optional Log.LogFunctions
+})
+```
+
+The returned driver exposes a `connection` property (the raw ioredis `Redis` instance) for
+advanced use cases.
+
+Config interface:
+
+| Field              | Type              | Default | Description                   |
+|--------------------|-------------------|---------|-------------------------------|
+| `url`              | `string`          | --      | Redis host                    |
+| `port`             | `number`          | --      | Redis port                    |
+| `operationTimeout` | `number`          | `5000`  | Per-operation timeout (ms)    |
+| `connectTimeout`   | `number`          | `10000` | Connection timeout (ms)       |
+| `keyPrefix`        | `string`          | `''`    | Prefix applied to all keys    |
+| `logger`           | `Log.LogFunctions`| --      | Optional structured logger    |
+
+Source: `packages/cache/src/redis-cache-driver.ts`
+
+### MockRedis
+
+In-memory driver using `ioredis-mock` for testing. Same interface as Redis:
+
+```ts
+Cache.drivers.mockRedis({
+  keyPrefix: 'test:',   // optional
+  logger: customLogger  // optional
+})
+```
+
+Source: `packages/cache/src/mock-redis-cache-driver.ts`
+
+## API Reference
+
+All values must be JSON-serializable. TTL is always in seconds; pass `null` to persist forever.
+
+### Core Methods
+
+```ts
+Cache.has(key: string): Promise<boolean>
+```
+Return `true` if the key exists in the cache.
+
+```ts
+Cache.get<T>(key: string): Promise<T | null>
+```
+Retrieve a value. Return `null` on miss.
+
+```ts
+Cache.set(key: string, value: any, ttlSeconds: number | null): Promise<void>
+```
+Store a value with TTL in seconds. Pass `null` for no expiration.
+
+```ts
+Cache.del(key: string): Promise<void>
+```
+Remove a key from the cache.
+
+```ts
+Cache.flush(): Promise<void>
+```
+Remove all entries. Ignores key prefix -- affects the entire store.
+
+### Atomic Operations
+
+```ts
+Cache.add(key: string, value: any, ttlSeconds: number): Promise<boolean>
+```
+Store a value only if the key does not already exist. Returns `true` if added, `false` if the key
+was already present. The value is JSON-serialized (compatible with `get`).
+
+```ts
+Cache.increment(key: string, value?: number): Promise<number>
+```
+Atomically increment a numeric value by `value` (default `1`). Returns the new value.
+
+```ts
+Cache.decrement(key: string, value?: number): Promise<number>
+```
+Atomically decrement a numeric value by `value` (default `1`). Returns the new value.
+
+> **Warning:** `increment` and `decrement` use Redis `INCRBY`/`DECRBY` on raw integers, not
+> JSON-serialized values. Values stored with `set` (which JSON-serializes) cannot be incremented.
+> Conversely, values created by `increment`/`decrement` are raw numbers and will come back as plain
+> numbers from `get`, not wrapped in JSON.
+
+```ts
+// Rate-limit counter
+await Cache.increment('rate:user:42')
+const count = await Cache.increment('rate:user:42')
+if (count > 100) throw new Error('Rate limit exceeded')
+
+// Add-if-absent: claim a one-time token
+const claimed = await Cache.add('token:abc123', { userId: 42 }, 300)
+if (!claimed) throw new Error('Token already used')
+```
+
+### remember (Cache-Aside)
+
+```ts
+Cache.remember<T>(key: string, options: RememberOptions, fn: () => Promise<T>): Promise<T>
+```
+
+Retrieve `key` from cache. On miss, call `fn`, cache the result, and return it.
+
+**RememberOptions** accepts:
+- `number` -- TTL in seconds
+- `null` -- persist forever
+- `DurationString` -- e.g. `'5 minutes'`, `'1 hour'`, `'30 seconds'`, `'2 days'`
+- `{ ttl: number | DurationString | null, swr: number | DurationString }` -- TTL with
+  stale-while-revalidate window
+
+```ts
+// Simple TTL
+await Cache.remember('user:1', 60, async () => fetchUser(1))
+
+// Duration string
+await Cache.remember('config', '5 minutes', async () => loadConfig())
+
+// Forever
+await Cache.remember('constants', null, async () => getConstants())
+
+// Stale-while-revalidate
+await Cache.remember('feed', { ttl: 60, swr: 30 }, async () => buildFeed())
+await Cache.remember('feed', { ttl: '1 minute', swr: '30 seconds' }, async () => buildFeed())
+```
+
+SWR behavior: when the TTL expires but the entry is within the SWR window, the stale value is
+returned immediately and `fn` runs in the background to refresh the cache. Background refresh
+errors are silently swallowed (the stale value remains). Only one background refresh per key runs
+at a time.
+
+Do not mix `Cache.set()` and `Cache.remember()` on the same key -- `remember` wraps values in an
+internal envelope (`__remember` marker) and throws if it encounters a raw value.
+
+### item (Typed Key Handle)
+
+```ts
+Cache.item<T>(key: string)
+```
+
+Return a typed handle scoped to a single key:
+
+```ts
+const user = Cache.item<User>('user:456')
+await user.set({ name: 'Bob' }, 7200)
+await user.exists()                        // true
+await user.get()                           // { name: 'Bob' }
+await user.del()
+await user.remember(60, async () => fetchUser(456))
+await user.remember('5 minutes', async () => fetchUser(456))
+await user.remember({ ttl: 1, swr: 10 }, async () => fetchUser(456))
+```
+
+### lock (Distributed Locking)
+
+```ts
+Cache.lock(name: string, ttlSeconds: number | null): Cache.Lock
+```
+
+Create a distributed lock backed by Redis `SET NX`. Lock methods:
+
+```ts
+const lock = Cache.lock('process-orders', 30)
+
+await lock.get()           // true if acquired, false if held by another
+await lock.isAvailable()   // true if no one holds the lock
+await lock.release()       // release if owned by this caller (atomic Lua script)
+await lock.forceRelease()  // release regardless of owner
+await lock.block(5)        // retry acquiring for up to 5 seconds, throw on timeout
+```
+
+Pass `null` for TTL to create a lock with no automatic expiration.
+
+`block()` polls every 250ms and also listens for Redis pub/sub release events for faster
+acquisition. Throws `Error('Could not acquire lock: <name>')` on timeout.
+
+## Common Patterns
+
+### Cache-aside with TTL
+
+```ts
+const user = await Cache.remember('user:123', 3600, async () => {
+  return await db.query('SELECT * FROM users WHERE id = 123')
+})
+```
+
+### Stale-while-revalidate
+
+Serve stale data instantly while refreshing in the background:
+
+```ts
+const dashboard = await Cache.remember(
+  'dashboard:stats',
+  { ttl: '5 minutes', swr: '1 minute' },
+  async () => computeExpensiveStats()
+)
+```
+
+### Distributed mutex
+
+Ensure only one process runs a task at a time:
+
+```ts
+const lock = Cache.lock('import-job', 60)
+const acquired = await lock.get()
+if (acquired) {
+  try {
+    await runImport()
+  } finally {
+    await lock.release()
+  }
+}
+```
+
+### Blocking lock with timeout
+
+Wait for availability:
+
+```ts
+const lock = Cache.lock('critical-section', 30)
+await lock.block(10) // wait up to 10 seconds
+try {
+  await doCriticalWork()
+} finally {
+  await lock.release()
+}
+```
+
+### Named provider instances
+
+```ts
+const sessions = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379, keyPrefix: 'sess:' })
+})
+Cache.Provider.register('sessions', sessions)
+
+// Resolve by name
+const sessCache = Cache.provider('sessions')
+await sessCache.set('abc', { userId: 1 }, 1800)
+```
+
+## Testing
+
+Use MockRedis driver in tests. Flush before each test to ensure isolation:
+
+```ts
+import { Cache } from '@maestro-js/cache'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+const cache = Cache.Provider.create({ driver: Cache.drivers.mockRedis({}) })
+
+test.beforeEach(async () => {
+  await cache.flush()
+})
+
+test('cache stores and retrieves values', async () => {
+  await cache.set('key', { a: 1 }, null)
+  expect(await cache.has('key')).toBeTruthy()
+  expect(await cache.get('key')).toEqual({ a: 1 })
+})
+
+test('remember caches on miss', async () => {
+  const result = await cache.remember('user:1', 60, async () => ({ name: 'Alice' }))
+  expect(result).toEqual({ name: 'Alice' })
+
+  let called = false
+  const cached = await cache.remember('user:1', 60, async () => {
+    called = true
+    return { name: 'Bob' }
+  })
+  expect(cached).toEqual({ name: 'Alice' })
+  expect(called).toBe(false)
+})
+
+test('locks acquire and release', async () => {
+  const lock = cache.lock('test-lock', null)
+  expect(await lock.isAvailable()).toBe(true)
+  await lock.get()
+  expect(await lock.isAvailable()).toBe(false)
+  await lock.release()
+  expect(await lock.isAvailable()).toBe(true)
+})
+```
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/cache test          # all cache tests
+cd packages/cache && npx beartest ./tests/cache.test.ts  # single file
+```
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation),
+  `@maestro-js/log` (structured logging in drivers)
+- **Used by**: `@maestro-js/cache-control` (HTTP cache-control headers backed by cache)
+- **Complements**: `@maestro-js/context` (per-request via AsyncLocalStorage; cache is
+  cross-request shared state)
+
+## Driver Interface
+
+Implement `Cache.Driver` to create a custom backend:
+
+```ts
+interface CacheDriver {
+  has(key: string): Promise<boolean>
+  get(key: string): Promise<any | null>
+  set(key: string, value: any, ttlSeconds: number): Promise<unknown>
+  add(key: string, value: any, ttlSeconds: number): Promise<boolean>
+  setForever(key: string, value: any): Promise<unknown>
+  del(key: string): Promise<unknown>
+  increment(key: string, value: number): Promise<number>
+  decrement(key: string, value: number): Promise<number>
+  flush(): Promise<unknown>
+  getPrefix(): string
+  lock(name: string, ttlSeconds: number | null): Cache.Lock
+}
+```
+
+Source: `packages/cache/src/cache-types.ts`
+
+## Key Source Files
+
+- `packages/cache/src/index.ts` -- main export, Provider pattern, `create()`, `remember()` logic
+- `packages/cache/src/cache-types.ts` -- `CacheDriver` and `CacheLock` interfaces
+- `packages/cache/src/redis-cache-driver.ts` -- production Redis driver
+- `packages/cache/src/mock-redis-cache-driver.ts` -- in-memory mock driver for tests
+- `packages/cache/src/duration.ts` -- `DurationString` type and parser
+- `packages/cache/tests/cache.test.ts` -- core cache and remember/SWR tests
+- `packages/cache/tests/cache-locks.test.ts` -- distributed lock tests

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import { Log } from '@maestro-js/log';
+import Redis$1, { Redis } from 'ioredis';
+
+type DurationString = `${number} ${'day' | 'days' | 'hour' | 'hours' | 'minute' | 'minutes' | 'second' | 'seconds'}`;
+
+/** Contract that every cache backend (Redis, MockRedis, etc.) must implement */
+interface CacheDriver {
+    /** Checks whether `key` exists in the store */
+    has(key: string): Promise<boolean>;
+    /** Retrieves the value for `key`, or `null` if absent */
+    get(key: string): Promise<any | null>;
+    /** Stores `value` at `key` with a TTL in seconds */
+    set(key: string, value: any, ttlSeconds: number): Promise<unknown>;
+    /** only add the item to the cache if it does not already exist in the cache store */
+    add(key: string, value: any, ttlSeconds: number): Promise<boolean>;
+    /** Stores `value` at `key` with no expiration */
+    setForever(key: string, value: any): Promise<unknown>;
+    /** Removes `key` from the store */
+    del(key: string): Promise<unknown>;
+    /** Adjust the value of an integer item in the cache */
+    increment(key: string, value: number): Promise<number>;
+    /** Adjust the value of an integer item in the cache */
+    decrement(key: string, value: number): Promise<number>;
+    /** Removes all entries from the store */
+    flush(): Promise<unknown>;
+    /** Returns the key prefix applied to all operations */
+    getPrefix(): string;
+    /** Creates a distributed lock with the given name and optional TTL */
+    lock(name: string, ttlSeconds: number | null): CacheLock;
+}
+/** Distributed lock for coordinating exclusive access across processes */
+type CacheLock = {
+    /** Attempts to acquire the lock — resolves to `true` if acquired, `false` if already held */
+    get: () => Promise<boolean>;
+    /** Releases the lock if held by this caller */
+    release: () => Promise<void>;
+    /** Releases the lock regardless of who holds it */
+    forceRelease: () => Promise<void>;
+    /** Checks whether the lock is currently available (not held) */
+    isAvailable: () => Promise<boolean>;
+    /** Retries acquiring the lock for up to `seconds`, resolving to `true` if acquired */
+    block: (seconds: number) => Promise<void>;
+};
+
+interface MockRedisDriverConfig {
+    keyPrefix?: string;
+    logger?: Log.LogFunctions;
+}
+declare function mockRedisCacheDriver({ logger: loggerInput, keyPrefix }: MockRedisDriverConfig): CacheDriver & {
+    connection: Redis;
+};
+
+interface RedisDriverConfig {
+    url: string;
+    port: number;
+    operationTimeout?: number;
+    connectTimeout?: number;
+    keyPrefix?: string;
+    logger?: Log.LogFunctions;
+}
+declare function redisCacheDriver({ url, port, operationTimeout, connectTimeout, keyPrefix, logger: loggerInput }: RedisDriverConfig): CacheDriver & {
+    connection: Redis$1;
+};
+
+/**
+ * Creates a new Cache service instance with the provided driver configuration.
+ */
+declare function create(config: Cache.Provider.CacheServiceConfig): Cache.CacheService;
+declare function provider(key: Cache.Provider.Key): {
+    has: (key: string) => Promise<boolean>;
+    get: <T = any>(key: string) => Promise<T | null>;
+    set: (key: string, value: any, ttlSeconds: number | null) => Promise<void>;
+    add: (key: string, value: any, ttlSeconds: number) => Promise<boolean>;
+    increment: (key: string, value?: number) => Promise<number>;
+    decrement: (key: string, value?: number) => Promise<number>;
+    del: (key: string) => Promise<void>;
+    flush: () => Promise<void>;
+    remember: <T>(key: string, options: Cache.RememberOptions, fn: () => Promise<T>) => Promise<T>;
+    item: <T>(key: string) => {
+        /** Checks whether this key exists in the cache */
+        exists: () => Promise<boolean>;
+        /** Retrieves the value, or `null` if absent */
+        get: () => Promise<T | null>;
+        /** Stores a value with an optional TTL in seconds — pass `null` to persist forever */
+        set: (value: T, ttlSeconds: number | null) => Promise<void>;
+        /** Removes this key and its value from the cache */
+        del: () => Promise<void>;
+        /** Retrieves the cached value; on miss calls `fn`, caches the result, and returns it */
+        remember: (options: Cache.RememberOptions, fn: () => Promise<T>) => Promise<T>;
+    };
+    lock: (name: string, ttlSeconds: number | null) => Cache.Lock;
+};
+type KeysWithFallback = keyof Cache.Provider.Keys extends never ? {
+    default: unknown;
+} : Cache.Provider.Keys;
+/**
+ * Key-value caching with optional TTL and distributed locking.
+ * Call methods directly on the default instance, or use `Cache.Provider.create()` for named instances.
+ */
+declare const Cache: {
+    provider: typeof provider;
+    drivers: {
+        redis: typeof redisCacheDriver;
+        mockRedis: typeof mockRedisCacheDriver;
+    };
+    has: (key: string) => Promise<boolean>;
+    get: <T = any>(key: string) => Promise<T | null>;
+    set: (key: string, value: any, ttlSeconds: number | null) => Promise<void>;
+    add: (key: string, value: any, ttlSeconds: number) => Promise<boolean>;
+    increment: (key: string, value?: number) => Promise<number>;
+    decrement: (key: string, value?: number) => Promise<number>;
+    del: (key: string) => Promise<void>;
+    flush: () => Promise<void>;
+    remember: <T>(key: string, options: Cache.RememberOptions, fn: () => Promise<T>) => Promise<T>;
+    item: <T>(key: string) => {
+        /** Checks whether this key exists in the cache */
+        exists: () => Promise<boolean>;
+        /** Retrieves the value, or `null` if absent */
+        get: () => Promise<T | null>;
+        /** Stores a value with an optional TTL in seconds — pass `null` to persist forever */
+        set: (value: T, ttlSeconds: number | null) => Promise<void>;
+        /** Removes this key and its value from the cache */
+        del: () => Promise<void>;
+        /** Retrieves the cached value; on miss calls `fn`, caches the result, and returns it */
+        remember: (options: Cache.RememberOptions, fn: () => Promise<T>) => Promise<T>;
+    };
+    lock: (name: string, ttlSeconds: number | null) => Cache.Lock;
+    Provider: {
+        create: typeof create;
+        register: (name: Cache.Provider.Key, item: Cache.CacheService) => void;
+    };
+};
+/**
+ * Key-value caching with optional TTL and distributed locking.
+ *
+ * All values must be JSON-serializable. Keys can be set with a time-to-live
+ * (in seconds) or persisted indefinitely by passing `null`. Use {@link item}
+ * for a typed handle scoped to a single key, or {@link lock} for distributed
+ * coordination across processes.
+ *
+ * @example
+ * ```ts
+ * await Cache.set('user:123', { name: 'Alice' }, 3600)
+ * await Cache.get<User>('user:123')   // { name: 'Alice' }
+ * await Cache.has('user:123')         // true
+ * await Cache.del('user:123')
+ *
+ * // Atomic increment (rate-limit counter)
+ * const count = await Cache.increment('rate:user:42')
+ *
+ * // Add only if absent (claim a one-time token)
+ * const claimed = await Cache.add('token:abc', { userId: 42 }, 300)
+ *
+ * // Typed handle for a single key
+ * const user = Cache.item<User>('user:456')
+ * await user.set({ name: 'Bob' }, 7200)
+ * await user.get()                    // { name: 'Bob' }
+ * ```
+ */
+declare namespace Cache {
+    /** Distributed lock for coordinating exclusive access across processes */
+    type Lock = CacheLock;
+    /** Pluggable backend implementation — see `Cache.drivers` for built-in options */
+    type Driver = CacheDriver;
+    /** Duration string like `'5 minutes'` or `'1 hour'` */
+    type DurationString = DurationString;
+    /** TTL options for `remember` — a number (seconds), `null` (forever), a duration string, or an object with `ttl` and `swr` */
+    type RememberOptions = number | null | DurationString | {
+        ttl: number | DurationString | null;
+        swr: number | DurationString;
+    };
+    /**
+     * Core cache operations for storing and retrieving JSON-serializable values.
+     *
+     * - **TTL** – pass a number of seconds to {@link set}, or `null` to persist forever.
+     * - **Item handles** – {@link item} returns a typed wrapper scoped to a single key.
+     * - **Locking** – {@link lock} creates a distributed lock backed by the cache driver.
+     *
+     * Returned by `Cache.Provider.create()` or resolved via `Cache.provider()`.
+     *
+     * @example
+     * ```ts
+     * await Cache.set('config', { apiKey: 'abc' }, 600)
+     * const cfg = await Cache.get<Config>('config') // { apiKey: 'abc' }
+     * await Cache.del('config')
+     * ```
+     */
+    interface CacheService {
+        /** Checks whether the key exists in the cache */
+        has: (key: string) => Promise<boolean>;
+        /** Retrieves the value for `key`, or `null` if absent */
+        get: <T = any>(key: string) => Promise<T | null>;
+        /** Stores a value at `key` with an optional TTL in seconds — pass `null` to persist forever */
+        set: (key: string, value: any, ttlSeconds: number | null) => Promise<void>;
+        /** Stores a value at `key` only if the key does not already exist — returns `true` if added, `false` if the key was already present */
+        add: (key: string, value: any, ttlSeconds: number) => Promise<boolean>;
+        /** Increments the numeric value at `key` by `value` */
+        increment: (key: string, value?: number) => Promise<number>;
+        /** Decrements the numeric value at `key` by `value` */
+        decrement: (key: string, value?: number) => Promise<number>;
+        /** Removes the key and its value from the cache */
+        del: (key: string) => Promise<void>;
+        /** Clears all entries from the cache — ignores key prefix, affects the entire store */
+        flush: () => Promise<void>;
+        /** Retrieves `key` from cache; on miss calls `fn`, caches the result, and returns it */
+        remember: <T>(key: string, options: RememberOptions, fn: () => Promise<T>) => Promise<T>;
+        /** Returns a typed handle scoped to a single key with {@link CacheService.has exists}, get, set, del, and remember methods */
+        item: <T>(key: string) => {
+            /** Checks whether this key exists in the cache */
+            exists: () => Promise<boolean>;
+            /** Retrieves the value, or `null` if absent */
+            get: () => Promise<T | null>;
+            /** Stores a value with an optional TTL in seconds — pass `null` to persist forever */
+            set: (value: T, ttlSeconds: number | null) => Promise<void>;
+            /** Removes this key and its value from the cache */
+            del: () => Promise<void>;
+            /** Retrieves the cached value; on miss calls `fn`, caches the result, and returns it */
+            remember: (options: RememberOptions, fn: () => Promise<T>) => Promise<T>;
+        };
+        /** Creates a distributed lock with the given name and optional TTL */
+        lock: (name: string, ttlSeconds: number | null) => Cache.Lock;
+    }
+    namespace Provider {
+        interface CacheServiceConfig {
+            driver: CacheDriver;
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { Cache };

package/dist/index.js

@@ -0,0 +1,530 @@
+// src/index.ts
+import assert from "assert";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/mock-redis-cache-driver.ts
+import EventEmitter from "events";
+import { randomUUID } from "crypto";
+import { Log } from "@maestro-js/log";
+import MockRedis from "ioredis-mock";
+import "ioredis";
+function mockRedisCacheDriver({
+  logger: loggerInput,
+  keyPrefix = ""
+}) {
+  const logger = loggerInput ?? Log.create();
+  const redis = new MockRedis();
+  const lockEmitter = new EventEmitter();
+  const channelPrefix = [keyPrefix, "maestro.events."].join("");
+  const cacheLockChannelName = `${channelPrefix}cache-locks`;
+  redis.on("error", (error) => {
+    logger.error(error);
+  });
+  redis.on("message", (channel, message) => {
+    if (channel === cacheLockChannelName) {
+      lockEmitter.emit(message);
+    }
+  });
+  return {
+    async has(key) {
+      const res = await redis.exists(key);
+      return res > 0;
+    },
+    async get(key) {
+      const res = await redis.get(key);
+      if (res) {
+        if (typeof res === "string") {
+          try {
+            return JSON.parse(res);
+          } catch (e) {
+            throw new Error(`Could not JSON.parse data for key ${key}`, { cause: e });
+          }
+        } else if (Array.isArray(res)) {
+          return res.map((r) => {
+            try {
+              return JSON.parse(r);
+            } catch (e) {
+              throw new Error(`Could not JSON.parse data for key ${key}`, { cause: e });
+            }
+          });
+        } else {
+          throw new Error(`Unrecognized value for key ${key}`);
+        }
+      } else {
+        return res;
+      }
+    },
+    async set(key, value, ttlSeconds) {
+      await redis.set(key, JSON.stringify(value), "EX", ttlSeconds);
+    },
+    async add(key, value, ttlSeconds) {
+      const result = await redis.set(key, JSON.stringify(value), "EX", ttlSeconds, "NX");
+      return result !== null;
+    },
+    async increment(key, value) {
+      return redis.incrby(key, value);
+    },
+    async decrement(key, value) {
+      return redis.decrby(key, value);
+    },
+    async setForever(key, value) {
+      await redis.set(key, JSON.stringify(value));
+    },
+    async del(key) {
+      await redis.del(key);
+    },
+    async flush() {
+      await redis.flushdb();
+    },
+    getPrefix() {
+      return keyPrefix;
+    },
+    connection: redis,
+    lock(name, ttlSeconds) {
+      const id = `lock-${name}`;
+      const callId = randomUUID();
+      async function tryLock() {
+        if (ttlSeconds !== null) {
+          const isSet = await redis.set(id, callId, "EX", ttlSeconds, "NX");
+          return isSet === "OK";
+        } else {
+          const isSet = await redis.set(id, callId, "NX");
+          return isSet === "OK";
+        }
+      }
+      async function get() {
+        const locked = await tryLock();
+        return locked;
+      }
+      async function block(seconds) {
+        const locked = await tryLock();
+        if (locked) return;
+        return new Promise((resolve, reject) => {
+          let settled = false;
+          let acquiring = false;
+          let waitingForAcquire = false;
+          const cleanup = () => {
+            settled = true;
+            lockEmitter.off(id, onRelease);
+            clearInterval(fallbackPoll);
+          };
+          const timeout = setTimeout(() => {
+            if (acquiring) {
+              waitingForAcquire = true;
+              return;
+            }
+            cleanup();
+            reject(new Error(`Could not acquire lock: ${name}`));
+          }, seconds * 1e3);
+          const onRelease = async () => {
+            if (settled) return;
+            acquiring = true;
+            const acquired = await tryLock();
+            acquiring = false;
+            if (acquired) {
+              clearTimeout(timeout);
+              cleanup();
+              resolve();
+              return;
+            }
+            if (waitingForAcquire) {
+              cleanup();
+              reject(new Error(`Could not acquire lock: ${name}`));
+            }
+          };
+          lockEmitter.on(id, onRelease);
+          const fallbackPoll = setInterval(onRelease, 250);
+          onRelease();
+        });
+      }
+      async function isAvailable() {
+        const value = await redis.get(id);
+        return !value;
+      }
+      async function release() {
+        const released = await redis.eval(
+          'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) end return 0',
+          1,
+          id,
+          callId
+        );
+        if (released === 1) {
+          lockEmitter.emit(id);
+          await redis.publish(cacheLockChannelName, id);
+        }
+      }
+      async function forceRelease() {
+        await redis.del(id);
+        lockEmitter.emit(id);
+        await redis.publish(cacheLockChannelName, id);
+      }
+      return { get, release, forceRelease, isAvailable, block };
+    }
+  };
+}
+
+// src/redis-cache-driver.ts
+import EventEmitter2 from "events";
+import { randomUUID as randomUUID2 } from "crypto";
+import Redis2 from "ioredis";
+import RedisTimeout from "ioredis-timeout";
+import { Log as Log2 } from "@maestro-js/log";
+function redisCacheDriver({
+  url,
+  port,
+  operationTimeout = 5e3,
+  connectTimeout = 1e4,
+  keyPrefix = "",
+  logger: loggerInput
+}) {
+  const logger = loggerInput ?? Log2.create();
+  const redis = new Redis2(port, url, {
+    connectTimeout,
+    keyPrefix
+  });
+  const lockEmitter = new EventEmitter2();
+  const channelPrefix = [keyPrefix, "maestro.events."].join("");
+  const cacheLockChannelName = `${channelPrefix}cache-locks`;
+  redis.on("connect", () => {
+    logger.info("connected!");
+    RedisTimeout.timeout("set", operationTimeout, redis);
+    RedisTimeout.timeout("get", operationTimeout, redis);
+    RedisTimeout.timeout("exists", operationTimeout, redis);
+    RedisTimeout.timeout("del", operationTimeout, redis);
+    RedisTimeout.timeout("publish", operationTimeout, redis);
+  });
+  redis.on("error", (error) => {
+    logger.error(error);
+  });
+  redis.on("message", (channel, message) => {
+    if (channel === cacheLockChannelName) {
+      lockEmitter.emit(message);
+    }
+  });
+  return {
+    async has(key) {
+      const res = await redis.exists(key);
+      return res > 0;
+    },
+    async get(key) {
+      const res = await redis.get(key);
+      if (res) {
+        if (typeof res === "string") {
+          try {
+            return JSON.parse(res);
+          } catch (e) {
+            throw new Error(`Could not JSON.parse data for key ${key}`, { cause: e });
+          }
+        } else if (Array.isArray(res)) {
+          return res.map((r) => {
+            try {
+              return JSON.parse(r);
+            } catch (e) {
+              throw new Error(`Could not JSON.parse data for key ${key}`, { cause: e });
+            }
+          });
+        } else {
+          throw new Error(`Unrecognized value for key ${key}`);
+        }
+      } else {
+        return res;
+      }
+    },
+    async set(key, value, ttlSeconds) {
+      await redis.set(key, JSON.stringify(value), "EX", ttlSeconds);
+    },
+    async add(key, value, ttlSeconds) {
+      const result = await redis.set(key, JSON.stringify(value), "EX", ttlSeconds, "NX");
+      return result !== null;
+    },
+    async increment(key, value) {
+      return redis.incrby(key, value);
+    },
+    async decrement(key, value) {
+      return redis.decrby(key, value);
+    },
+    async setForever(key, value) {
+      await redis.set(key, JSON.stringify(value));
+    },
+    async del(key) {
+      await redis.del(key);
+    },
+    async flush() {
+      await redis.flushdb();
+    },
+    getPrefix() {
+      return keyPrefix;
+    },
+    connection: redis,
+    lock(name, ttlSeconds) {
+      const id = `lock-${name}`;
+      const callId = randomUUID2();
+      async function tryLock() {
+        if (ttlSeconds !== null) {
+          const isSet = await redis.set(id, callId, "EX", ttlSeconds, "NX");
+          return isSet === "OK";
+        } else {
+          const isSet = await redis.set(id, callId, "NX");
+          return isSet === "OK";
+        }
+      }
+      async function get() {
+        const locked = await tryLock();
+        return locked;
+      }
+      async function block(seconds) {
+        const locked = await tryLock();
+        if (locked) return;
+        return new Promise((resolve, reject) => {
+          let settled = false;
+          let acquiring = false;
+          let waitingForAcquire = false;
+          const cleanup = () => {
+            settled = true;
+            lockEmitter.off(id, onRelease);
+            clearInterval(fallbackPoll);
+          };
+          const timeout = setTimeout(() => {
+            if (acquiring) {
+              waitingForAcquire = true;
+              return;
+            }
+            cleanup();
+            reject(new Error(`Could not acquire lock: ${name}`));
+          }, seconds * 1e3);
+          const onRelease = async () => {
+            if (settled) return;
+            acquiring = true;
+            const acquired = await tryLock();
+            acquiring = false;
+            if (acquired) {
+              clearTimeout(timeout);
+              cleanup();
+              resolve();
+              return;
+            }
+            if (waitingForAcquire) {
+              cleanup();
+              reject(new Error(`Could not acquire lock: ${name}`));
+            }
+          };
+          lockEmitter.on(id, onRelease);
+          const fallbackPoll = setInterval(onRelease, 250);
+          onRelease();
+        });
+      }
+      async function isAvailable() {
+        const value = await redis.get(id);
+        return !value;
+      }
+      async function release() {
+        const released = await redis.eval(
+          'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) end return 0',
+          1,
+          id,
+          callId
+        );
+        if (released === 1) {
+          lockEmitter.emit(id);
+          await redis.publish(cacheLockChannelName, id);
+        }
+      }
+      async function forceRelease() {
+        await redis.del(id);
+        lockEmitter.emit(id);
+        await redis.publish(cacheLockChannelName, id);
+      }
+      return { get, release, forceRelease, isAvailable, block };
+    }
+  };
+}
+
+// src/duration.ts
+function parseDurationToSeconds(duration) {
+  const [numberStr, unit] = duration.split(" ");
+  const n = Number(numberStr);
+  if (Number.isNaN(n)) {
+    throw new Error(`${numberStr} not recognized as a number`);
+  }
+  if (unit === "day" || unit === "days") {
+    return n * 60 * 60 * 24;
+  } else if (unit === "hour" || unit === "hours") {
+    return n * 60 * 60;
+  } else if (unit === "minute" || unit === "minutes") {
+    return n * 60;
+  } else if (unit === "second" || unit === "seconds") {
+    return n;
+  } else {
+    throw new Error(`Unrecognized unit ${unit}`);
+  }
+}
+
+// src/index.ts
+function create(config) {
+  const driver = config.driver;
+  const pendingRefreshes = /* @__PURE__ */ new Map();
+  async function has(key) {
+    return driver.has(key);
+  }
+  async function get(key) {
+    assert.ok(key);
+    return driver.get(key);
+  }
+  async function set(key, value, ttlSeconds) {
+    if (ttlSeconds !== null) {
+      await driver.set(key, value, ttlSeconds);
+    } else {
+      await driver.setForever(key, value);
+    }
+  }
+  async function add(key, value, ttlSeconds) {
+    return driver.add(key, value, ttlSeconds);
+  }
+  async function increment(key, value = 1) {
+    return driver.increment(key, value);
+  }
+  async function decrement(key, value = 1) {
+    return driver.decrement(key, value);
+  }
+  async function del(key) {
+    await driver.del(key);
+  }
+  async function flush() {
+    await driver.flush();
+  }
+  async function remember(key, options, fn) {
+    assert.ok(key);
+    const { ttlSeconds, swrSeconds } = resolveRememberOptions(options);
+    const cached = await driver.get(key);
+    if (cached !== null) {
+      if (!isRememberEntry(cached)) {
+        throw new Error(
+          `Cache key "${key}" was not stored by remember(). Do not mix cache.set() and cache.remember() on the same key.`
+        );
+      }
+      const ageSeconds = (Date.now() - cached.createdTime) / 1e3;
+      const isFresh = ttlSeconds === null || ageSeconds < ttlSeconds;
+      const isWithinSwrWindow = swrSeconds > 0 && (ttlSeconds === null || ageSeconds < ttlSeconds + swrSeconds);
+      if (isFresh) {
+        return cached.value;
+      }
+      if (isWithinSwrWindow) {
+        if (!pendingRefreshes.has(key)) {
+          const refreshPromise = fn().then(async (value2) => {
+            await storeEntry(key, value2, ttlSeconds, swrSeconds);
+          }).catch(() => {
+          }).finally(() => {
+            pendingRefreshes.delete(key);
+          });
+          pendingRefreshes.set(key, refreshPromise);
+        }
+        return cached.value;
+      }
+    }
+    const value = await fn();
+    await storeEntry(key, value, ttlSeconds, swrSeconds);
+    return value;
+  }
+  async function storeEntry(key, value, ttlSeconds, swrSeconds) {
+    const entry = { __remember: true, createdTime: Date.now(), value };
+    const totalTtl = ttlSeconds !== null ? ttlSeconds + swrSeconds : null;
+    if (totalTtl !== null) {
+      await driver.set(key, entry, totalTtl);
+    } else {
+      await driver.setForever(key, entry);
+    }
+  }
+  function item(key) {
+    async function exists() {
+      return await driver.has(key);
+    }
+    async function get2() {
+      assert.ok(key);
+      const res = await driver.get(key);
+      return res;
+    }
+    async function set2(value, ttlSeconds) {
+      if (ttlSeconds !== null) {
+        await driver.set(key, value, ttlSeconds);
+      } else {
+        await driver.setForever(key, value);
+      }
+    }
+    async function del2() {
+      await driver.del(key);
+    }
+    async function itemRemember(options, fn) {
+      return remember(key, options, fn);
+    }
+    return { exists, get: get2, set: set2, del: del2, remember: itemRemember };
+  }
+  function lock(name, ttlSeconds) {
+    return driver.lock(name, ttlSeconds);
+  }
+  return {
+    has,
+    get,
+    set,
+    increment,
+    decrement,
+    add,
+    del,
+    flush,
+    remember,
+    item,
+    lock
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    has: service.has,
+    get: service.get,
+    set: service.set,
+    add: service.add,
+    increment: service.increment,
+    decrement: service.decrement,
+    del: service.del,
+    flush: service.flush,
+    remember: service.remember,
+    item: service.item,
+    lock: service.lock
+  };
+}
+var Cache = {
+  Provider,
+  ...provider("default"),
+  provider,
+  drivers: {
+    redis: redisCacheDriver,
+    mockRedis: mockRedisCacheDriver
+  }
+};
+function isSwrOptions(opts) {
+  return typeof opts === "object" && opts !== null && "swr" in opts;
+}
+function resolveDuration(d) {
+  return typeof d === "string" ? parseDurationToSeconds(d) : d;
+}
+function resolveRememberOptions(opts) {
+  if (isSwrOptions(opts)) {
+    const ttlSeconds = opts.ttl === null ? null : resolveDuration(opts.ttl);
+    const swrSeconds = resolveDuration(opts.swr);
+    return { ttlSeconds, swrSeconds };
+  }
+  if (opts === null) return { ttlSeconds: null, swrSeconds: 0 };
+  return { ttlSeconds: resolveDuration(opts), swrSeconds: 0 };
+}
+function isRememberEntry(value) {
+  return typeof value === "object" && value !== null && value.__remember === true;
+}
+export {
+  Cache
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@maestro-js/cache",
+  "description": "Key-value caching with TTL, stale-while-revalidate, distributed locking, cache-aside pattern, atomic increment/decrement, and set-if-not-exists (add) for @maestro-js/cache. Use when working with @maestro-js/cache, adding caching to services, implementing distributed locks, using the remember/SWR pattern, incrementing or decrementing counters, adding values only if absent, configuring Redis or MockRedis drivers, or following the canonical Provider pattern from service-registry.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ioredis": "^5.4.1",
+    "ioredis-timeout": "^1.5.0",
+    "@maestro-js/log": "1.0.0-alpha.0",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/ioredis-mock": "^8.2.6",
+    "@types/node": "^22.19.11",
+    "ioredis-mock": "^8.2.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}