Redis Store

The Redis store enables distributed rate limiting across multiple server instances. Essential for horizontally scaled applications.

Installation

The Redis store requires ioredis as a peer dependency:

npm install ioredis
# or: pnpm add ioredis
# or: yarn add ioredis

bun add ioredis

Usage

import { hitlimit } from '@joint-ops/hitlimit'
import { redisStore } from '@joint-ops/hitlimit/stores/redis'

app.use(hitlimit({
  limit: 100,
  window: '1m',
  store: redisStore({
    url: 'redis://localhost:6379'
  })
}))

import { hitlimit } from '@joint-ops/hitlimit-bun'
import { redisStore } from '@joint-ops/hitlimit-bun/stores/redis'

const limiter = hitlimit({
  limit: 100,
  window: '1m',
  store: redisStore({
    url: 'redis://localhost:6379'
  })
})

Options

Connection Options

Connect using a URL:

redisStore({
  url: 'redis://:password@hostname:6379/0'
})

Or use an existing client:

import Redis from 'ioredis'

const redis = new Redis({
  host: 'localhost',
  port: 6379,
  password: 'secret',
  db: 0
})

redisStore({ client: redis })

Cluster Support

import Redis from 'ioredis'

const cluster = new Redis.Cluster([
  { host: 'node1', port: 6379 },
  { host: 'node2', port: 6379 },
  { host: 'node3', port: 6379 }
])

redisStore({ client: cluster })

Lua Scripts

As of v1.2.0, the Redis store uses defineCommand() to register Lua scripts with native SHA caching, combining multiple Redis commands into a single call. Instead of issuing separate INCR, PEXPIRE, and PTTL commands (3 round trips), a single Lua script executes all three atomically on the Redis server — reducing round trips from 3 to 1.

This provides two key benefits:

• Lower latency — one network round trip instead of three
• True atomicity — no race conditions between increment and expiry operations

For endpoints with ban detection enabled, the hitWithBan Lua script handles increment, expiry, TTL retrieval, and ban threshold checking in a single atomic call.

Characteristics

• Speed: Network-bound (latency depends on Redis server location and network)
• Persistence: Configurable via Redis persistence settings (RDB/AOF)
• Scalability: Shared across all server instances
• Atomic: Lua scripts ensure race-condition-free increments

When to Use

• Multi-server/container deployments
• Kubernetes or Docker Swarm clusters
• High-traffic applications
• When consistent rate limiting across instances is required