@trieb.work/nextjs-turbo-redis-cache 1.16.0 → 1.16.1

package/src/CacheComponentsHandler.ts

@@ -530,5 +530,38 @@ export function getRedisCacheComponentsHandler(
   return singletonHandler;
 }
 
-export const redisCacheHandler: CacheComponentsHandler =
-  getRedisCacheComponentsHandler();
+// Lazily resolve the default Cache Components handler.
+//
+// Constructing a RedisCacheComponentsHandler opens a Redis connection in its
+// constructor. Building the singleton at module-eval time therefore means that simply
+// *importing this package* — e.g. only for `RedisStringsHandler` (the legacy
+// `cacheHandler`), with Cache Components never enabled — eagerly connects to Redis,
+// defaulting to `redis://localhost:6379` when neither `REDIS_URL` nor `REDISHOST` is
+// set. In a deployment whose Redis is not on localhost that yields a non-stop
+// `RedisCacheComponentsHandler client error ECONNREFUSED 127.0.0.1:6379` reconnect
+// loop, and it also makes a consumer's later `getRedisCacheComponentsHandler(options)`
+// a no-op, because the singleton was already built with defaults (see #84).
+//
+// Defer construction to first use via a Proxy: importing the package never connects, a
+// consumer that configures the handler via `getRedisCacheComponentsHandler(options)`
+// before it is first used has that configuration honored, and a consumer that never
+// touches Cache Components never opens a Redis connection at all.
+let resolvedHandler: CacheComponentsHandler | undefined;
+
+export const redisCacheHandler: CacheComponentsHandler = new Proxy(
+  {} as CacheComponentsHandler,
+  {
+    get(_target, prop) {
+      if (!resolvedHandler) {
+        resolvedHandler = getRedisCacheComponentsHandler();
+      }
+      const value = resolvedHandler[prop as keyof CacheComponentsHandler];
+      return typeof value === 'function'
+        ? (value as (...args: unknown[]) => unknown).bind(resolvedHandler)
+        : value;
+    },
+    has(_target, prop) {
+      return prop in RedisCacheComponentsHandler.prototype;
+    },
+  },
+);

package/test/vitest/integration/cache-components/redis-kill-reconnect.test.ts

@@ -50,6 +50,12 @@ describe('redis kill/reconnect end-to-end (both handlers)', () => {
 
       const res = await runNode(script, 180_000);
 
+      if (res.code !== 0) {
+        console.error('Script exited with code', res.code);
+        console.error('stdout:', res.stdout);
+        console.error('stderr:', res.stderr);
+      }
+
       expect(res.code).toBe(0);
       expect(res.stdout).toContain('OK');
       expect(res.stderr).not.toContain('Socket already opened');

package/test/vitest/integration/cache-components/scripts/redis-kill-reconnect.ts

@@ -92,8 +92,9 @@ async function main() {
     if (r.code !== 0) throw new Error(`podman run failed: ${r.stderr}`);
   }
 
-  // IMPORTANT: importing from "src" will eagerly instantiate the singleton via `redisCacheHandler`.
-  // So we must set env BEFORE importing.
+  // Set env BEFORE importing in case any module-level code reads REDIS_URL.
+  // (With lazy init the singleton is no longer created at import time, but
+  //  setting env first is still good practice.)
   process.env.REDIS_URL = `redis://127.0.0.1:${port}`;
   process.env.VERCEL_URL = `e2e-${name}-`;
 
@@ -112,9 +113,6 @@ async function main() {
       // allow redis client to reconnect; this scenario is about stability under restart
       reconnectStrategy: (retries) => Math.min(50 + retries * 50, 500),
     },
-    clientOptions: {
-      disableOfflineQueue: true,
-    } as any,
   });
 
   const cacheComponentsClient = (cacheComponentsHandler as any).client as {

package/test/vitest/unit/index.test.ts

@@ -4,7 +4,7 @@ import type { CreateRedisStringsHandlerOptions } from '../../../src/index';
 import RedisStringsHandler from '../../../src/RedisStringsHandler';
 
 vi.mock('redis', () => {
-  const createClient = () => {
+  const createClient = vi.fn(() => {
     return {
       isReady: true,
       on: vi.fn(),
@@ -31,7 +31,7 @@ vi.mock('redis', () => {
       unlink: vi.fn(async () => 1),
       set: vi.fn(async () => 'OK'),
     };
-  };
+  });
   return {
     createClient,
     commandOptions: vi.fn((opts) => opts),
@@ -96,3 +96,50 @@ describe('Public exports', () => {
     expect(_typeCheck.keyPrefix).toBe('test');
   });
 });
+
+describe('redisCacheHandler lazy proxy', () => {
+  it('does not construct a Redis connection on import', async () => {
+    vi.resetModules();
+    const { createClient } = await import('redis');
+    vi.mocked(createClient).mockClear();
+
+    // Importing the module should NOT trigger a Redis connection
+    await import('../../../src');
+
+    expect(vi.mocked(createClient)).not.toHaveBeenCalled();
+  });
+
+  it('has trap returns true for known methods without constructing the handler', async () => {
+    vi.resetModules();
+    const { createClient } = await import('redis');
+    vi.mocked(createClient).mockClear();
+
+    const { redisCacheHandler } = await import('../../../src');
+
+    expect('getExpiration' in redisCacheHandler).toBe(true);
+    expect('get' in redisCacheHandler).toBe(true);
+    expect('set' in redisCacheHandler).toBe(true);
+    expect('refreshTags' in redisCacheHandler).toBe(true);
+    expect('updateTags' in redisCacheHandler).toBe(true);
+
+    expect(vi.mocked(createClient)).not.toHaveBeenCalled();
+  });
+
+  it('method call delegates to the singleton and binds correctly', async () => {
+    vi.resetModules();
+    const { createClient } = await import('redis');
+    vi.mocked(createClient).mockClear();
+
+    const { redisCacheHandler } = await import('../../../src');
+
+    // Accessing a method triggers construction and delegates to the real handler
+    const getFn = redisCacheHandler.get;
+    expect(typeof getFn).toBe('function');
+    expect(vi.mocked(createClient)).toHaveBeenCalledTimes(1);
+
+    // Subsequent accesses reuse the same singleton (no extra construction)
+    const getFn2 = redisCacheHandler.get;
+    expect(vi.mocked(createClient)).toHaveBeenCalledTimes(1);
+    expect(typeof getFn2).toBe('function');
+  });
+});

package/test/vitest/unit/reconnect-socket-already-opened.test.ts

@@ -1,5 +1,58 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 
+vi.mock('redis', () => ({
+  createClient: vi.fn(() => {
+    const listeners = new Map<string, Function[]>();
+    const client = {
+      isOpen: false,
+      isReady: false,
+      on: vi.fn((event: string, cb: Function) => {
+        if (!listeners.has(event)) listeners.set(event, []);
+        listeners.get(event)!.push(cb);
+      }),
+      emit: vi.fn((event: string, ...args: unknown[]) => {
+        (listeners.get(event) ?? []).forEach((cb) => cb(...args));
+      }),
+      connect: vi.fn(async () => undefined),
+      disconnect: vi.fn(),
+      quit: vi.fn(async () => undefined),
+      duplicate: vi.fn(() => ({
+        connect: vi.fn(async () => undefined),
+        subscribe: vi.fn(async () => undefined),
+        on: vi.fn(),
+        quit: vi.fn(async () => undefined),
+        configGet: vi.fn(async () => ({ 'notify-keyspace-events': 'Exe' })),
+      })),
+      get: vi.fn(async () => null),
+      hScan: vi.fn(async () => ({ cursor: 0, tuples: [] })),
+      scan: vi.fn(async () => ({ cursor: 0, keys: [] })),
+      hSet: vi.fn(async () => 1),
+      hDel: vi.fn(async () => 1),
+      publish: vi.fn(async () => 1),
+      unlink: vi.fn(async () => 1),
+      set: vi.fn(async () => 'OK'),
+    };
+    return client;
+  }),
+  commandOptions: vi.fn((opts) => opts),
+}));
+
+vi.mock('../../../src/SyncedMap', () => {
+  class SyncedMap {
+    waitUntilReady = vi.fn(async () => undefined);
+    get = vi.fn(() => undefined);
+    set = vi.fn(async () => undefined);
+    delete = vi.fn(async () => undefined);
+    entries = vi.fn(function* () {
+      return;
+    });
+
+    constructor() {}
+  }
+
+  return { SyncedMap };
+});
+
 /**
  * Deterministic regression test for:
  *   "Failed to reconnect RedisCacheComponentsHandler client after connection loss: Error: Socket already opened"
@@ -34,6 +87,9 @@ describe('RedisCacheComponentsHandler reconnect logic', () => {
 
     const client = (handler as any).client;
 
+    // Clear the initial connect() call from the constructor.
+    vi.mocked(client.connect).mockClear();
+
     // Simulate a connection-loss situation where the socket is still open.
     Object.defineProperty(client, 'isOpen', { value: true });
     Object.defineProperty(client, 'isReady', { value: false });