Redis

In-memory data store for caching, sessions, and real-time features.

Quick Start

Install:

npm install redis

Connect:

import { createClient } from 'redis';

const redis = createClient({
  url: process.env.REDIS_URL || 'redis://localhost:6379',
});

redis.on('error', (err) => console.error('Redis error:', err));
redis.on('connect', () => console.log('Redis connected'));

await redis.connect();

Basic Operations

Strings

// Set value
await redis.set('key', 'value');

// Set with expiration (seconds)
await redis.setEx('key', 3600, 'value');

// Set with expiration (milliseconds)
await redis.pSetEx('key', 60000, 'value');

// Set if not exists
await redis.setNX('key', 'value');

// Get value
const value = await redis.get('key');

// Get multiple
const values = await redis.mGet(['key1', 'key2', 'key3']);

// Increment
await redis.incr('counter');
await redis.incrBy('counter', 5);
await redis.incrByFloat('counter', 1.5);

// Decrement
await redis.decr('counter');
await redis.decrBy('counter', 5);

// Append
await redis.append('key', ' more text');

// Get length
const length = await redis.strLen('key');

Key Operations

// Check existence
const exists = await redis.exists('key');

// Delete
await redis.del('key');
await redis.del(['key1', 'key2']);

// Set expiration
await redis.expire('key', 3600);        // seconds
await redis.pExpire('key', 60000);      // milliseconds
await redis.expireAt('key', timestamp); // Unix timestamp

// Get TTL
const ttl = await redis.ttl('key');     // seconds
const pttl = await redis.pTtl('key');   // milliseconds

// Remove expiration
await redis.persist('key');

// Rename
await redis.rename('oldKey', 'newKey');

// Find keys (use carefully in production)
const keys = await redis.keys('user:*');

// Scan (safer for production)
for await (const key of redis.scanIterator({ MATCH: 'user:*' })) {
  console.log(key);
}

Hashes

// Set field
await redis.hSet('user:1', 'name', 'John');

// Set multiple fields
await redis.hSet('user:1', {
  name: 'John',
  email: 'john@example.com',
  age: '30',
});

// Get field
const name = await redis.hGet('user:1', 'name');

// Get all fields
const user = await redis.hGetAll('user:1');
// { name: 'John', email: 'john@example.com', age: '30' }

// Get multiple fields
const values = await redis.hmGet('user:1', ['name', 'email']);

// Check field exists
const exists = await redis.hExists('user:1', 'name');

// Increment field
await redis.hIncrBy('user:1', 'age', 1);

// Delete field
await redis.hDel('user:1', 'email');

// Get all field names
const fields = await redis.hKeys('user:1');

// Get all values
const vals = await redis.hVals('user:1');

Lists

// Push to left (prepend)
await redis.lPush('queue', 'item1');
await redis.lPush('queue', ['item2', 'item3']);

// Push to right (append)
await redis.rPush('queue', 'item');

// Pop from left
const item = await redis.lPop('queue');

// Pop from right
const item = await redis.rPop('queue');

// Blocking pop (with timeout)
const result = await redis.blPop('queue', 5);

// Get range
const items = await redis.lRange('queue', 0, -1); // All items
const items = await redis.lRange('queue', 0, 9);  // First 10

// Get length
const length = await redis.lLen('queue');

// Get by index
const item = await redis.lIndex('queue', 0);

// Set by index
await redis.lSet('queue', 0, 'new-value');

// Trim list
await redis.lTrim('queue', 0, 99); // Keep first 100

Sets

// Add members
await redis.sAdd('tags', 'redis');
await redis.sAdd('tags', ['nodejs', 'typescript']);

// Check membership
const isMember = await redis.sIsMember('tags', 'redis');

// Get all members
const members = await redis.sMembers('tags');

// Get random member
const random = await redis.sRandMember('tags');

// Remove member
await redis.sRem('tags', 'nodejs');

// Get count
const count = await redis.sCard('tags');

// Set operations
const union = await redis.sUnion(['set1', 'set2']);
const intersection = await redis.sInter(['set1', 'set2']);
const difference = await redis.sDiff(['set1', 'set2']);

Sorted Sets

// Add with score
await redis.zAdd('leaderboard', { score: 100, value: 'user:1' });
await redis.zAdd('leaderboard', [
  { score: 200, value: 'user:2' },
  { score: 150, value: 'user:3' },
]);

// Get range by rank (ascending)
const top10 = await redis.zRange('leaderboard', 0, 9);

// Get range with scores
const top10 = await redis.zRangeWithScores('leaderboard', 0, 9);
// [{ score: 100, value: 'user:1' }, ...]

// Get range by rank (descending)
const top10 = await redis.zRange('leaderboard', 0, 9, { REV: true });

// Get range by score
const users = await redis.zRangeByScore('leaderboard', 100, 200);

// Get rank
const rank = await redis.zRank('leaderboard', 'user:1');
const revRank = await redis.zRevRank('leaderboard', 'user:1');

// Get score
const score = await redis.zScore('leaderboard', 'user:1');

// Increment score
await redis.zIncrBy('leaderboard', 10, 'user:1');

// Remove member
await redis.zRem('leaderboard', 'user:1');

// Get count
const count = await redis.zCard('leaderboard');

Caching Patterns

Cache-Aside

async function getUser(userId: string): Promise<User> {
  const cacheKey = `user:${userId}`;

  // Try cache first
  const cached = await redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // Fetch from database
  const user = await db.users.findUnique({ where: { id: userId } });

  if (user) {
    // Store in cache
    await redis.setEx(cacheKey, 3600, JSON.stringify(user));
  }

  return user;
}

async function updateUser(userId: string, data: Partial<User>) {
  // Update database
  const user = await db.users.update({
    where: { id: userId },
    data,
  });

  // Invalidate cache
  await redis.del(`user:${userId}`);

  return user;
}

Cache with Wrapper

async function withCache<T>(
  key: string,
  ttl: number,
  fn: () => Promise<T>
): Promise<T> {
  const cached = await redis.get(key);

  if (cached) {
    return JSON.parse(cached);
  }

  const result = await fn();
  await redis.setEx(key, ttl, JSON.stringify(result));

  return result;
}

// Usage
const user = await withCache(
  `user:${userId}`,
  3600,
  () => db.users.findUnique({ where: { id: userId } })
);

Session Storage

Express Session

import session from 'express-session';
import RedisStore from 'connect-redis';

const redisStore = new RedisStore({
  client: redis,
  prefix: 'session:',
});

app.use(
  session({
    store: redisStore,
    secret: process.env.SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
    cookie: {
      secure: process.env.NODE_ENV === 'production',
      httpOnly: true,
      maxAge: 24 * 60 * 60 * 1000, // 24 hours
    },
  })
);

Pub/Sub

Publisher

const publisher = createClient({ url: process.env.REDIS_URL });
await publisher.connect();

// Publish message
await publisher.publish('notifications', JSON.stringify({
  type: 'NEW_MESSAGE',
  userId: '123',
  content: 'Hello!',
}));

Subscriber

const subscriber = createClient({ url: process.env.REDIS_URL });
await subscriber.connect();

// Subscribe to channel
await subscriber.subscribe('notifications', (message) => {
  const data = JSON.parse(message);
  console.log('Received:', data);
});

// Subscribe to pattern
await subscriber.pSubscribe('user:*', (message, channel) => {
  console.log(`${channel}: ${message}`);
});

// Unsubscribe
await subscriber.unsubscribe('notifications');

Rate Limiting

Sliding Window

async function rateLimit(
  key: string,
  limit: number,
  windowMs: number
): Promise<boolean> {
  const now = Date.now();
  const windowStart = now - windowMs;

  // Remove old entries
  await redis.zRemRangeByScore(key, '-inf', windowStart);

  // Count requests in window
  const count = await redis.zCard(key);

  if (count >= limit) {
    return false; // Rate limited
  }

  // Add current request
  await redis.zAdd(key, { score: now, value: `${now}` });
  await redis.pExpire(key, windowMs);

  return true;
}

// Usage in middleware
app.use(async (req, res, next) => {
  const key = `ratelimit:${req.ip}`;
  const allowed = await rateLimit(key, 100, 60000); // 100 req/min

  if (!allowed) {
    return res.status(429).json({ error: 'Too many requests' });
  }

  next();
});

Token Bucket

async function tokenBucket(
  key: string,
  maxTokens: number,
  refillRate: number
): Promise<boolean> {
  const now = Date.now();
  const data = await redis.hGetAll(key);

  let tokens = maxTokens;
  let lastRefill = now;

  if (data.tokens) {
    const elapsed = now - parseInt(data.lastRefill);
    const refill = (elapsed / 1000) * refillRate;
    tokens = Math.min(maxTokens, parseFloat(data.tokens) + refill);
    lastRefill = parseInt(data.lastRefill);
  }

  if (tokens < 1) {
    return false;
  }

  await redis.hSet(key, {
    tokens: String(tokens - 1),
    lastRefill: String(now),
  });
  await redis.expire(key, 3600);

  return true;
}

Distributed Locks

async function acquireLock(
  lockKey: string,
  ttl: number
): Promise<string | null> {
  const lockValue = crypto.randomUUID();

  const acquired = await redis.set(lockKey, lockValue, {
    NX: true,
    PX: ttl,
  });

  return acquired ? lockValue : null;
}

async function releaseLock(lockKey: string, lockValue: string): Promise<void> {
  // Only release if we own the lock
  const script = `
    if redis.call("get", KEYS[1]) == ARGV[1] then
      return redis.call("del", KEYS[1])
    else
      return 0
    end
  `;

  await redis.eval(script, {
    keys: [lockKey],
    arguments: [lockValue],
  });
}

// Usage
const lockValue = await acquireLock('order:123', 5000);
if (lockValue) {
  try {
    await processOrder('123');
  } finally {
    await releaseLock('order:123', lockValue);
  }
}

Best Practices

1. Use connection pooling - Reuse connections
2. Set TTL on keys - Prevent memory leaks
3. Use pipelines for batching - Reduce round trips
4. Use hashes for objects - More efficient than JSON strings
5. Monitor memory usage - Redis is memory-bound

Common Mistakes

Reference Files

• references/patterns.md - Caching patterns
• references/data-structures.md - Data structure usage
• references/cluster.md - Redis cluster setup