@sunacchi/cache-kit-redis

Redis cache adapter for @sunacchi/cache-kit. Uses ioredis under the hood.

Part of the Cache Kit monorepo.

Install

npm install @sunacchi/cache-kit @sunacchi/cache-kit-redis ioredis

Usage

import { Cache } from '@sunacchi/cache-kit';
import { RedisAdapter } from '@sunacchi/cache-kit-redis';

const cache = new Cache<string>({
  adapter: new RedisAdapter(),
  defaultTtl: 300_000, // 5 minutes
});

await cache.set('session:abc', JSON.stringify({ userId: 42 }));
const session = await cache.get('session:abc');

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | client | Redis | — | An existing ioredis client instance. Takes precedence over other connection options. | | url | string | — | Redis connection URL (e.g. redis://localhost:6379). Ignored if client is provided. | | host | string | '127.0.0.1' | Redis host. Ignored if client or url is provided. | | port | number | 6379 | Redis port. Ignored if client or url is provided. | | prefix | string | 'cache:' | Key prefix applied to all operations. |

// Using an existing client
import Redis from 'ioredis';

const redis = new Redis('redis://my-redis:6379');
const adapter = new RedisAdapter({ client: redis });

// Using a URL
const adapter = new RedisAdapter({ url: 'redis://my-redis:6379' });

// Custom prefix
const adapter = new RedisAdapter({ prefix: 'myapp:cache:' });

How It Works

• Uses ioredis for all Redis communication
• Keys are prefixed with prefix (default cache:) to avoid collisions
• clear(), keys(), and size() use SCAN for safe iteration over large keyspaces
• Connections use lazyConnect — the first operation triggers the connection
• Bring your own client or let the adapter create one

Cleanup

Call disconnect() or quit() when done. These only act if the adapter owns the client (i.e., you didn't pass an external client).

const adapter = new RedisAdapter();
const cache = new Cache({ adapter });

// When shutting down:
await adapter.quit();       // graceful shutdown
// or
adapter.disconnect();       // immediate disconnect

Example

import { Cache } from '@sunacchi/cache-kit';
import { RedisAdapter } from '@sunacchi/cache-kit-redis';

const adapter = new RedisAdapter({ url: 'redis://localhost:6379' });

const cache = new Cache<Record<string, unknown>>({
  adapter,
  defaultTtl: 60_000,
  maxSize: 10_000,
  eviction: 'lru',
  namespace: 'api',
});

const user = await cache.getOrCreate('user:42', async () => {
  return await db.users.findById(42);
}, { ttl: 30_000 });

// On shutdown
await adapter.quit();

Exports

export { RedisAdapter } from './redis-adapter.js';
export type { RedisAdapterOptions } from './redis-adapter.js';

License

MIT