@playstack/rate-limit-redis

@playstack/rate-limit-redis implements the atomic RateLimitStore contract with one Redis Lua invocation.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/rate-limit-redis@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose the store

import { RedisRateLimitStore } from '@playstack/rate-limit-redis'

const store = new RedisRateLimitStore(redis)
const limiter = createRateLimiter({ definitions, store, clock, keyHasher, environment })

Client bridge

The client needs only the Node Redis-compatible structural surface:

interface RedisEvalClient {
  eval(
    script: string,
    options: { keys: readonly string[]; arguments: readonly string[] },
  ): Promise<unknown>
}

store.client exposes that exact injected instance for lifecycle and diagnostics.

Atomic behavior

The production Lua script reads, refills, decides, and updates every bucket in one call. It uses Redis server time rather than the application timestamp, retains refill state without spending any bucket on denial, and derives key expiry from twice the time required to refill capacity with a one-minute minimum.

Core has already HMAC-protected every key; this adapter does not log or reinterpret subject identifiers. Redis errors and malformed decisions become RateLimitUnavailableError for the core policy’s explicit failure mode.

Boundary

The application owns Redis topology, authentication, connection creation and shutdown, clustering policy, observability, and deployment. Policy definition and subject resolution remain in @playstack/rate-limit.

API entry points and requirements

Reference snapshot: @playstack/rate-limit-redis@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.