Valkey Store

The Valkey store enables distributed rate limiting using Valkey — the Linux Foundation's open-source fork of Redis 7.2, backed by AWS, Google, and Oracle. It's a drop-in replacement for the Redis store with identical performance, using the same ioredis client and atomic Lua scripts.

What is Valkey?

After Redis changed its license from BSD to SSPL + RSALv2 in March 2024, the Linux Foundation forked Redis 7.2 as Valkey under the BSD-3-Clause license. It maintains full wire compatibility with Redis — same protocol (RESP2/RESP3), same commands, same Lua scripting. Major cloud providers (AWS ElastiCache, Google Cloud Memorystore) now offer managed Valkey services.

Installation

The Valkey store requires ioredis as a peer dependency (same as Redis store):

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

bun add ioredis

Usage

import { hitlimit } from '@joint-ops/hitlimit'
import { valkeyStore } from '@joint-ops/hitlimit/stores/valkey'

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

import { hitlimit } from '@joint-ops/hitlimit-bun'
import { valkeyStore } from '@joint-ops/hitlimit-bun/stores/valkey'

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

Options

Migration from Redis

Migrating from redisStore to valkeyStore requires changing two lines:

// Before (Redis)
import { redisStore } from '@joint-ops/hitlimit/stores/redis'
const store = redisStore({ url: 'redis://localhost:6379' })

// After (Valkey) — same URL scheme, same port, same options
import { valkeyStore } from '@joint-ops/hitlimit/stores/valkey'
const store = valkeyStore({ url: 'redis://localhost:6379' })

The connection URL uses the same redis:// scheme. ioredis connects identically to both Redis and Valkey servers.

Lua Scripts

The Valkey store uses the same atomic Lua scripts as the Redis store via defineCommand() with native SHA caching. Valkey maintains full Lua scripting compatibility including the redis.call() global object (also aliased as server.call()).

Characteristics

• Speed: Same as Redis store (network-bound)
• License: BSD-3-Clause (fully open source, no relicensing risk)
• Persistence: Configurable via Valkey persistence settings (RDB/AOF)
• Scalability: Shared across all server instances
• Atomic: Lua scripts ensure race-condition-free increments
• Cloud: AWS ElastiCache for Valkey, Google Memorystore for Valkey

When to Use

• You want distributed rate limiting with a fully open-source backend
• Your organization has concerns about Redis's SSPL license
• You're using AWS ElastiCache for Valkey or Google Memorystore
• Migrating from Redis — zero code changes beyond import path