ioredis

ioredis es el cliente Redis estándar para Node.js: soporte para standalone, Sentinel y Cluster con APIs compatibles con TypeScript.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import Redis from "ioredis";
 
export const redis = new Redis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  lazyConnect: false,
});
 
redis.on("error", (err) => {
  console.error({ msg: "redis_error", err: err.message });
});
 
export async function cacheGet(key: string) {
  return redis.get(key);
}

Cuándo usarlo:

• Caché compartida, almacén de sesiones, límites de tasa o backend de BullMQ
• Necesitas pipelines, scripts Lua o Redis Cluster
• Redis gestionado (ElastiCache, Upstash, Redis Cloud) con URLs TLS

Ejemplo funcional

// src/redis.ts
import Redis from "ioredis";
 
function createRedis() {
  const url = process.env.REDIS_URL!;
  if (process.env.REDIS_CLUSTER === "true") {
    return new Redis.Cluster([{ host: process.env.REDIS_HOST!, port: 6379 }], {
      redisOptions: { password: process.env.REDIS_PASSWORD },
    });
  }
  return new Redis(url, { maxRetriesPerRequest: 3 });
}
 
export const redis = createRedis();
 
// src/cache/batch.ts
export async function mgetJson<T>(keys: string[]): Promise<(T | null)[]> {
  if (keys.length === 0) return [];
  const pipeline = redis.pipeline();
  keys.forEach((k) => pipeline.get(k));
  const results = await pipeline.exec();
  return (results ?? []).map(([err, val]) => {
    if (err || val == null) return null;
    return JSON.parse(val as string) as T;
  });
}
 
// Apagado elegante
process.on("SIGTERM", async () => {
  await redis.quit();
});

Lo que esto demuestra:

• Fábrica para standalone vs Cluster
• Pipeline para multi-get sin N viajes de ida y vuelta
• quit() al apagar para un cierre de conexión limpio

Análisis profundo

Opciones de conexión

Pipelines vs Multi

const pipe = redis.pipeline();
pipe.set("a", "1");
pipe.incr("counter");
await pipe.exec();
 
await redis.mset("a", "1", "b", "2");

• Pipeline: comandos por lotes, un viaje de ida y vuelta de red
• Transacciones MULTI/EXEC: atómicas cuando todas las claves están en la misma ranura (advertencia de Cluster)

Scripts Lua

const script = `
  local current = redis.call('GET', KEYS[1])
  if current == false then
    redis.call('SET', KEYS[1], ARGV[1], 'EX', ARGV[2])
    return 1
  end
  return 0
`;
await redis.eval(script, 1, "lock:job", "token", "30");

• Comparación y establecimiento atómicos para bloqueos y límites de tasa
• Define scripts una vez; usa SHA en producción para mayor eficiencia

Plugin de Fastify

import fp from "fastify-plugin";
import { redis } from "./redis";
 
export const redisPlugin = fp(async (fastify) => {
  fastify.decorate("redis", redis);
  fastify.addHook("onClose", async () => {
    await redis.quit();
  });
});

Nota de BullMQ

• BullMQ usa ioredis internamente
• Los workers a menudo necesitan maxRetriesPerRequest: null en comandos de bloqueo - instancias de cliente separadas para BullMQ vs caché de la aplicación

Errores comunes

• Nuevo Redis por solicitud - agotamiento de sockets. Solución: exportación de singleton.
• Grandes lotes de pipeline - picos de memoria. Solución: dividir pipelines (500-1000 operaciones).
• Multi-clave de clúster entre ranuras - errores CROSSSLOT. Solución: etiquetas hash {tenant}:key o claves separadas.
• Sin manejador de errores - los eventos error no manejados bloquean Node. Solución: redis.on("error", ...).
• Usar Redis como base de datos principal - la persistencia/AOF no es un reemplazo de SQL. Solución: caché + Postgres como fuente de verdad.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de caché - patrones de caché-aside
• Almacenes de sesión - express-session + Redis
• Bloqueos distribuidos - advertencias de Redlock
• BullMQ - backend de cola
• Mejores prácticas de caché - política de invalidación

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.