rate-limit-valkey

A Valkey store for the express-rate-limit middleware — so rate-limit counters are shared across all your server instances instead of living in each process's memory.

It works with any Valkey client that can send raw commands, such as iovalkey. The store never imports a client itself — you pass in a sendCommand function, so it stays client-agnostic.

Installation

npm install rate-limit-valkey iovalkey express-rate-limit

Usage

import rateLimit from "express-rate-limit";
import { ValkeyStore } from "rate-limit-valkey";
import Valkey from "iovalkey";

const client = new Valkey({ host: "localhost", port: 6379 });

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                 // limit each IP to 100 requests per window
  store: new ValkeyStore({
    sendCommand: (...args) => client.call(...args),
  }),
});

app.use(limiter);

Cluster

For a Valkey Cluster, pass sendCommandCluster instead — it receives routing details:

new ValkeyStore({
  sendCommandCluster: ({ command }) => cluster.call(...command),
});

Options

Option	Description	Default
sendCommand	Function that sends a raw command to Valkey and returns the reply.	—
sendCommandCluster	Cluster alternative that receives { key, isReadOnly, command }.	—
prefix	Text prepended to every key stored in Valkey.	rl:

Provide either sendCommand or sendCommandCluster, not both.

How it works

The store keeps each client's hit count in a single Valkey key with a TTL equal to the rate-limit window. Increment and get run as Lua scripts (loaded once with SCRIPT LOAD, executed with EVALSHA) so the count-and-expiry logic happens atomically on the server, avoiding race conditions across instances. If the server reports NOSCRIPT, the script is reloaded and the operation is safely replayed.

License

MIT