@bhooai/nexus-cache 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @bhooai/nexus-cache
+
+Redis wrapper, cache-aside, pub/sub, and the Redis-backed rate-limit backend.
+
+## Exports
+
+- **Cache** — `new Cache({ url, keyPrefix })`. `get/set/del/incr` with TTL,
+  cache-aside helpers, graceful no-op when Redis is unavailable.
+- **RateLimiter** — `new RateLimiter({ windowMs, max })` (Redis-backed;
+  in-memory fallback in `nexus-auth`).
+- **PubSub** — publish/subscribe for WS fanout and inter-process events.
+
+## Usage
+
+```ts
+import { Cache } from '@bhooai/nexus-cache';
+const cache = new Cache({ url: 'redis://localhost:6379', keyPrefix: 'app' });
+await cache.set('k', 'v', { ttl: 60 });
+const v = await cache.get('k');
+await cache.close();
+```
+
+Redis is **optional**: if the URL is unreachable the cache degrades to misses and
+the server keeps running. Tests use a real Redis via `.env` (`NEXUS_REDIS_URL`).

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@bhooai/nexus-cache",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "redis": "^4.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/Cache.ts

@@ -0,0 +1,155 @@
+import { createClient, type RedisClientType } from 'redis';
+import type { CacheOptions } from './types.js';
+
+/**
+ * Redis-backed cache wrapper. Lazily creates and connects a `node-redis`
+ * client on first use. All keys pass through {@link Cache.key} to apply an
+ * optional namespace/prefix.
+ */
+export class Cache {
+  private client: RedisClientType;
+  private connectPromise: Promise<void> | null = null;
+  private readonly keyPrefix: string;
+  protected readonly url?: string;
+  protected readonly connectTimeout?: number;
+
+  constructor(opts: CacheOptions = {}) {
+    this.url = opts.url;
+    this.connectTimeout = opts.connectTimeout;
+    this.keyPrefix = opts.keyPrefix ?? (opts.namespace ? `${opts.namespace}:` : '');
+    // `redis` v4 createClient returns a client in a closed state; we connect
+    // lazily on first use via ensureConnected().
+    this.client = createClient({
+      ...(this.url ? { url: this.url } : {}),
+      ...(this.connectTimeout != null ? { socket: { connectTimeout: this.connectTimeout } } : {}),
+    });
+  }
+
+  /** Connect the underlying client if not already connected. Idempotent. */
+  async ensureConnected(): Promise<void> {
+    if (this.client.isOpen) return;
+    if (!this.connectPromise) {
+      this.connectPromise = this.client.connect().then(() => {
+        // connected
+      });
+    }
+    try {
+      await this.connectPromise;
+    } catch (err) {
+      // Reset so a later retry can attempt reconnection.
+      this.connectPromise = null;
+      throw err;
+    }
+  }
+
+  /** Build the fully-prefixed redis key for a logical name. */
+  key(name: string): string {
+    return `${this.keyPrefix}${name}`;
+  }
+
+  /** The underlying redis client (connected after `ensureConnected`). */
+  protected getClient(): RedisClientType {
+    return this.client;
+  }
+
+  /** Get a JSON-decoded value, or undefined on miss/null. */
+  async get<T>(name: string): Promise<T | undefined> {
+    await this.ensureConnected();
+    const raw = await this.client.get(this.key(name));
+    if (raw == null) return undefined;
+    return JSON.parse(raw) as T;
+  }
+
+  /** Set a JSON-encoded value, optionally with a TTL in seconds. */
+  async set<T>(name: string, value: T, ttlSeconds?: number): Promise<void> {
+    await this.ensureConnected();
+    const encoded = JSON.stringify(value);
+    if (ttlSeconds != null) {
+      await this.client.set(this.key(name), encoded, { EX: ttlSeconds });
+    } else {
+      await this.client.set(this.key(name), encoded);
+    }
+  }
+
+  /** Delete a key. */
+  async del(name: string): Promise<void> {
+    await this.ensureConnected();
+    await this.client.del(this.key(name));
+  }
+
+  /**
+   * INCR a key. When `ttlSeconds` is supplied and the result becomes 1 (first
+   * hit in a fresh window) the key is expired after `ttlSeconds` seconds.
+   * Returns the post-increment integer value.
+   */
+  async incr(name: string, ttlSeconds?: number): Promise<number> {
+    await this.ensureConnected();
+    const key = this.key(name);
+    const count = await this.client.incr(key);
+    if (ttlSeconds != null && count === 1) {
+      await this.client.expire(key, ttlSeconds);
+    }
+    return count;
+  }
+
+  /** Whether a key exists. */
+  async exists(name: string): Promise<boolean> {
+    await this.ensureConnected();
+    const n = await this.client.exists(this.key(name));
+    return n > 0;
+  }
+
+  /** Set an expiry (seconds) on an existing key. */
+  async expire(name: string, ttlSeconds: number): Promise<void> {
+    await this.ensureConnected();
+    await this.client.expire(this.key(name), ttlSeconds);
+  }
+
+  /** Remaining TTL in seconds (-1 no expiry, -2 missing key). */
+  async ttl(name: string): Promise<number> {
+    await this.ensureConnected();
+    return this.client.ttl(this.key(name));
+  }
+
+  /**
+   * Delete all keys matching a glob pattern using non-blocking SCAN + DEL.
+   * Returns the number of keys removed.
+   */
+  async flushPattern(pattern: string): Promise<number> {
+    await this.ensureConnected();
+    const fullPattern = `${this.keyPrefix}${pattern}`;
+    let cursor = 0;
+    let removed = 0;
+    do {
+      const reply = await this.client.scan(cursor, { MATCH: fullPattern, COUNT: 100 });
+      cursor = Number(reply.cursor);
+      const keys = reply.keys;
+      if (keys.length > 0) {
+        await this.client.del(keys);
+        removed += keys.length;
+      }
+    } while (cursor !== 0);
+    return removed;
+  }
+
+  /**
+   * Cache-aside helper: return the cached value if present, otherwise invoke
+   * `loader`, store its result with `ttlSeconds`, and return it. No negative
+   * caching in v1 — loader errors propagate to the caller.
+   */
+  async cacheAside<T>(name: string, ttlSeconds: number, loader: () => Promise<T>): Promise<T> {
+    const cached = await this.get<T>(name);
+    if (cached !== undefined) return cached;
+    const fresh = await loader();
+    await this.set(name, fresh, ttlSeconds);
+    return fresh;
+  }
+
+  /** Disconnect the underlying client. */
+  async close(): Promise<void> {
+    if (this.client.isOpen) {
+      await this.client.quit();
+    }
+    this.connectPromise = null;
+  }
+}

package/src/PubSub.ts

@@ -0,0 +1,98 @@
+import { createClient, type RedisClientType } from 'redis';
+import type { Cache } from './Cache.js';
+
+type Handler = (msg: unknown) => void;
+
+/**
+ * Redis pub/sub helper. Uses the {@link Cache} client for publishing and a
+ * separate, dedicated subscriber client (required by `redis` v4) for
+ * subscriptions. Both clients are connected lazily.
+ */
+export class PubSub {
+  private subscriber: RedisClientType;
+  private subscriberConnectPromise: Promise<void> | null = null;
+  private handlers = new Map<string, Set<Handler>>();
+
+  constructor(private cache: Cache) {
+    // Reuse the same URL/connection options as the cache's publisher client.
+    // The cache exposes its url/connectTimeout via protected fields; here we
+    // reconstruct from the cache's key prefix-agnostic config by reading the
+    // same options the cache used. We mirror the cache's createClient call.
+    const url = (cache as unknown as { url?: string }).url;
+    const connectTimeout = (cache as unknown as { connectTimeout?: number }).connectTimeout;
+    this.subscriber = createClient({
+      ...(url ? { url } : {}),
+      ...(connectTimeout != null ? { socket: { connectTimeout } } : {}),
+    });
+  }
+
+  private async ensureSubscriberConnected(): Promise<void> {
+    if (this.subscriber.isOpen) return;
+    if (!this.subscriberConnectPromise) {
+      this.subscriberConnectPromise = this.subscriber.connect().then(() => undefined);
+    }
+    try {
+      await this.subscriberConnectPromise;
+    } catch (err) {
+      this.subscriberConnectPromise = null;
+      throw err;
+    }
+  }
+
+  /** Publish a JSON-encoded message to `channel`. */
+  async publish(channel: string, message: unknown): Promise<void> {
+    // Ensure the cache (publisher) client is connected.
+    await this.cache.ensureConnected();
+    const publisher = (this.cache as unknown as { getClient: () => RedisClientType }).getClient();
+    await publisher.publish(channel, JSON.stringify(message));
+  }
+
+  /**
+   * Subscribe to `channel`; `handler` is invoked with the JSON-parsed payload.
+   * Returns an unsubscribe function that removes the handler and, when no
+   * handlers remain for the channel, unsubscribes from Redis.
+   */
+  async subscribe(channel: string, handler: Handler): Promise<() => Promise<void>> {
+    await this.ensureSubscriberConnected();
+    let set = this.handlers.get(channel);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(channel, set);
+      // `redis` v4 subscribe(channel, callback) registers a per-channel
+      // listener that receives the message string.
+      await this.subscriber.subscribe(channel, (message) => {
+        const handlers = this.handlers.get(channel);
+        if (!handlers) return;
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(message);
+        } catch {
+          parsed = message;
+        }
+        for (const h of handlers) h(parsed);
+      });
+    }
+    set.add(handler);
+    return async () => {
+      const current = this.handlers.get(channel);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) {
+        this.handlers.delete(channel);
+        try {
+          await this.subscriber.unsubscribe(channel);
+        } catch {
+          /* ignore — client may be closing */
+        }
+      }
+    };
+  }
+
+  /** Close the dedicated subscriber client. */
+  async close(): Promise<void> {
+    if (this.subscriber.isOpen) {
+      await this.subscriber.quit();
+    }
+    this.subscriberConnectPromise = null;
+  }
+}

package/src/RateLimiter.ts

@@ -0,0 +1,43 @@
+import type { Cache } from './Cache.js';
+import type { RateLimitResult, RateLimitRule } from './types.js';
+
+/**
+ * Fixed-window counter rate limiter backed by Redis INCR via a {@link Cache}.
+ * Each call to {@link RateLimiter.check} atomically increments a per-key
+ * counter and, on the first hit of a window, sets the window expiry.
+ */
+export class RateLimiter {
+  constructor(private cache: Cache) {}
+
+  /**
+   * Check (and consume) one unit against the rule for `key`. Redis INCR both
+   * increments and returns the count, so the counter is consumed regardless of
+   * whether the request is allowed — matching the in-memory store semantics.
+   */
+  async check(key: string, rule: RateLimitRule): Promise<RateLimitResult> {
+    const redisKey = `${key}:rate`;
+    const count = await this.cache.incr(redisKey, rule.windowSeconds);
+    const limit = rule.max;
+    const allowed = count <= limit;
+    const remaining = Math.max(0, limit - count);
+    // Use the live TTL to compute resetAt; falls back to now + window.
+    let ttl = await this.cache.ttl(redisKey);
+    if (ttl < 0) ttl = rule.windowSeconds;
+    const resetAt = Date.now() + ttl * 1000;
+    const result: RateLimitResult = {
+      allowed,
+      limit,
+      remaining,
+      resetAt,
+    };
+    if (!allowed) {
+      result.retryAfter = rule.windowSeconds;
+    }
+    return result;
+  }
+
+  /** Alias of {@link check}; the counter is already consumed by INCR. */
+  async consume(key: string, rule: RateLimitRule): Promise<RateLimitResult> {
+    return this.check(key, rule);
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { Cache } from './Cache.js';
+export { RateLimiter } from './RateLimiter.js';
+export { PubSub } from './PubSub.js';
+export type {
+  CacheOptions,
+  CacheEntry,
+  RateLimitResult,
+  RateLimitRule,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Options for constructing a {@link Cache} instance.
+ */
+export interface CacheOptions {
+  /** Redis connection URL (e.g. `redis://localhost:6379`). */
+  url?: string;
+  /** Logical namespace applied to all keys as `${namespace}:` prefix. */
+  namespace?: string;
+  /** Explicit key prefix (overrides namespace prefix when provided). */
+  keyPrefix?: string;
+  /** Connection timeout in milliseconds passed to the redis client. */
+  connectTimeout?: number;
+}
+
+/**
+ * A cached value entry (kept for symmetry; values are JSON-stringified as-is).
+ */
+export interface CacheEntry<T> {
+  value: T;
+  expiresAt?: number;
+}
+
+/**
+ * Result of a rate-limit check.
+ */
+export interface RateLimitResult {
+  /** Whether the request is allowed under the current window. */
+  allowed: boolean;
+  /** Maximum requests permitted in the window. */
+  limit: number;
+  /** Remaining requests in the current window (>= 0). */
+  remaining: number;
+  /** Epoch ms when the current window resets. */
+  resetAt: number;
+  /** Seconds until the next request would be allowed (present when denied). */
+  retryAfter?: number;
+}
+
+/**
+ * Fixed-window rate-limit rule.
+ */
+export interface RateLimitRule {
+  /** Window length in seconds. */
+  windowSeconds: number;
+  /** Maximum requests permitted per window. */
+  max: number;
+}

package/tests/cache.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, afterAll, afterEach } from 'vitest';
+import { Cache, RateLimiter, PubSub } from '../src/index.js';
+import type { Cache as CacheType } from '../src/index.js';
+
+const REDIS_URL = process.env.REDIS_URL ?? 'redis://localhost:6379';
+
+async function connectOrSkip(): Promise<CacheType | null> {
+  const c = new Cache({ url: REDIS_URL, connectTimeout: 2000, namespace: 'nexus-cache-test' });
+  try {
+    await c.ensureConnected();
+    return c;
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.warn('[nexus-cache tests] Redis unavailable, skipping live tests:', (e as Error).message);
+    return null;
+  }
+}
+
+// Top-level await so `cache` is populated before describe bodies register tests.
+const cache = await connectOrSkip();
+
+afterEach(async () => {
+  if (cache) {
+    // Clean all test keys between tests.
+    try {
+      await cache.flushPattern('*');
+    } catch {
+      /* ignore */
+    }
+  }
+});
+
+afterAll(async () => {
+  if (cache) {
+    try {
+      await cache.flushPattern('*');
+    } catch {
+      /* ignore */
+    }
+    await cache.close();
+  }
+});
+
+/** Helper: run `fn` only when redis is available, else skip. */
+function itif(name: string, fn: () => Promise<void>): void {
+  if (cache) {
+    it(name, fn);
+  } else {
+    it.skip(name, fn);
+  }
+}
+
+describe('Cache: get / set / del', () => {
+  itif('set/get round-trip of a JSON object', async () => {
+    const c = cache!;
+    await c.set('obj', { a: 1, b: ['x', 'y'] });
+    const got = await c.get<{ a: number; b: string[] }>('obj');
+    expect(got).toEqual({ a: 1, b: ['x', 'y'] });
+  });
+
+  itif('get miss returns undefined', async () => {
+    const c = cache!;
+    const got = await c.get<{ x: number }>('does-not-exist');
+    expect(got).toBeUndefined();
+  });
+
+  itif('del removes the key', async () => {
+    const c = cache!;
+    await c.set('todelete', { v: 1 });
+    expect(await c.get('todelete')).toEqual({ v: 1 });
+    await c.del('todelete');
+    expect(await c.get('todelete')).toBeUndefined();
+  });
+});
+
+describe('Cache: TTL', () => {
+  itif('set with ttl=1s expires after 1100ms', async () => {
+    const c = cache!;
+    await c.set('temp', { n: 42 }, 1);
+    expect(await c.get('temp')).toEqual({ n: 42 });
+    await new Promise((r) => setTimeout(r, 1100));
+    expect(await c.get('temp')).toBeUndefined();
+  });
+});
+
+describe('Cache: incr', () => {
+  itif('starts at 1, increments, sets ttl on first hit, restarts after window', async () => {
+    const c = cache!;
+    const first = await c.incr('counter', 2);
+    expect(first).toBe(1);
+    const second = await c.incr('counter', 2);
+    expect(second).toBe(2);
+    // After window expiry the key should be gone and INCR restarts at 1.
+    await new Promise((r) => setTimeout(r, 2200));
+    const restarted = await c.incr('counter', 2);
+    expect(restarted).toBe(1);
+  });
+});
+
+describe('Cache: cacheAside', () => {
+  itif('miss calls loader and caches; second call does not call loader', async () => {
+    const c = cache!;
+    let calls = 0;
+    const loader = async () => {
+      calls++;
+      return { hello: 'world' };
+    };
+    const r1 = await c.cacheAside('aside', 10, loader);
+    expect(r1).toEqual({ hello: 'world' });
+    expect(calls).toBe(1);
+    const r2 = await c.cacheAside('aside', 10, loader);
+    expect(r2).toEqual({ hello: 'world' });
+    expect(calls).toBe(1);
+  });
+});
+
+describe('RateLimiter.check', () => {
+  itif('allows up to max then denies; allows again after window', async () => {
+    const c = cache!;
+    const limiter = new RateLimiter(c);
+    const rule = { windowSeconds: 2, max: 3 };
+    const r1 = await limiter.check('ip', rule);
+    expect(r1.allowed).toBe(true);
+    expect(r1.remaining).toBe(2);
+    const r2 = await limiter.check('ip', rule);
+    expect(r2.allowed).toBe(true);
+    expect(r2.remaining).toBe(1);
+    const r3 = await limiter.check('ip', rule);
+    expect(r3.allowed).toBe(true);
+    expect(r3.remaining).toBe(0);
+    const r4 = await limiter.check('ip', rule);
+    expect(r4.allowed).toBe(false);
+    expect(r4.remaining).toBe(0);
+    expect(r4.retryAfter).toBeDefined();
+    // After window expires the counter resets and a request is allowed again.
+    await new Promise((r) => setTimeout(r, 2200));
+    const r5 = await limiter.check('ip', rule);
+    expect(r5.allowed).toBe(true);
+    expect(r5.remaining).toBe(2);
+  });
+});
+
+describe('PubSub', () => {
+  itif('publish reaches a subscribed handler with parsed payload', async () => {
+    const c = cache!;
+    const pubsub = new PubSub(c);
+    const received = new Promise<unknown>((resolve) => {
+      void pubsub.subscribe('test', (msg) => resolve(msg));
+    });
+    // Give the subscription a moment to register.
+    await new Promise((r) => setTimeout(r, 50));
+    await pubsub.publish('test', { hello: 'pubsub' });
+    const msg = await received;
+    expect(msg).toEqual({ hello: 'pubsub' });
+    await pubsub.close();
+  });
+});
+
+describe('Cache: flushPattern', () => {
+  itif('removes matching keys and leaves others', async () => {
+    const c = cache!;
+    // Use namespaced names so the prefix is applied.
+    await c.set('ns:a', 1);
+    await c.set('ns:b', 2);
+    await c.set('other', 3);
+    const removed = await c.flushPattern('ns:*');
+    expect(removed).toBeGreaterThanOrEqual(2);
+    expect(await c.get('ns:a')).toBeUndefined();
+    expect(await c.get('ns:b')).toBeUndefined();
+    expect(await c.get('other')).toEqual(3);
+  });
+});
+
+describe('Cache: exists / expire / ttl', () => {
+  itif('exists reports presence, expire sets ttl, ttl reports remaining', async () => {
+    const c = cache!;
+    await c.set('k', 'v');
+    expect(await c.exists('k')).toBe(true);
+    expect(await c.exists('missing')).toBe(false);
+    await c.expire('k', 5);
+    const t = await c.ttl('k');
+    expect(t).toBeGreaterThan(0);
+    expect(t).toBeLessThanOrEqual(5);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../nexus-core" }
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+    testTimeout: 15_000,
+  },
+});