Benchmarks

Local Memory Strategies

Strategies that fit in process memory. Counter-based strategies run in constant time per check; the sliding window strategy maintains a per-key array of timestamps and runs in $O(N)$ per check.

Local memory is unaffected by the Postgres durability switch. Token Bucket and Individual Fixed Window lead on diverse keys; under extreme spam, every counter-based strategy saturates around 2.3-2.5M ops/sec because the only work is a Map.get and an integer increment. Sliding Window is stable but slow: every check iterates the per-key timestamp array, which is full after 60 s of spam.

Redis Strategies

All numbers below use ioredis and connect to a local Redis 8 container.

The Redis numbers are an order of magnitude below the in-memory numbers because every check is a network round-trip. The p99 latency in the diverse scenario is dominated by the network and serialization, not by the algorithm choice. Under spam, the work shifts to the limiter's Lua script rather than the network, so latency compresses.

PostgreSQL Strategies

Postgres numbers come from a local Postgres 18 container with production-default durability (see Methodology in detail). Throughput is two orders of magnitude below Redis because of the per-query transaction cost.

The diverse scenario is calm: all four strategies sit between 24K and 32K ops/sec. The extreme-spam scenario is where the choice matters:

• Fixed Window, Sliding Window, and Individual Fixed Window stay close to their diverse throughput. They are UPSERT-friendly and tolerate single-key contention. Sliding Window is the slowest of the three under spam but it is no longer the cliff it used to be. The named prepared statement optimisation closed the plan-cache gap that used to dominate.
• Token Bucket collapses to ~1,800 ops/sec with 200+ ms p99. A transaction per check, plus a refill calculation, is too much for a hot Postgres row to absorb.

Logged vs Unlogged tables

On a production-default Postgres, unlogged tables are 20% faster (26,837 vs 22,379 ops/sec) on the diverse scenario. This is the gap that earlier drafts of this page were missing: the bench was running with all durability disabled (synchronous_commit=off, fsync=off, full_page_writes=off), which made WAL effectively free and the gap shrank to noise. With the bench now using production defaults, the gap is real and consistent with the deeper investigation across PG 14, 15, and 18.

A focused investigation across PostgreSQL versions and durability configs is preserved at results/wal-overhead-investigation.md, runnable via packages/bench/src/scripts/investigate-unlogged.ts:

On production-default Postgres, unlogged gives 7-20% higher throughput depending on version. On a tuned synchronous_commit=off deployment, the gain shrinks to 3-4%. Use unlogged for the same reason you would use an in-memory cache: the data is acceptable to lose on crash. If your cluster must survive crashes with no data loss, stay on logged tables.

RateLock vs rate-limiter-flexible

This matrix is the one most likely to be misread, so the methodology matters. Both libraries are configured with points: 1000, duration: 60s (RLF's units) or limit: 1000, windowMs: 60000 (RateLock's). Both run on the same hardware with the same backends. The Redis client is ioredis for both, as discussed in Methodology in detail. The Postgres container uses production-default durability in this matrix. See the note at the top of section 3.

• On local memory, RateLock is 2.8x faster under spam. The single-key hot path benefits from direct Map lookups and the absence of per-call class instantiation.
• On Redis, RateLock is 1.7x faster. Both libraries use Lua scripts for atomic counters, so the gap is the script body and the network framing around it.
• On PostgreSQL, the two libraries are near-identical under spam in this run (1.04x). Both run a single UPSERT per call against the same hot row. RateLock's pgDriver uses named prepared statements (FNV-1a hash of the SQL text), which closed the plan-cache gap that earlier versions of this matrix showed. Treat any claim about a stable Postgres gap as a measurement, not a guarantee. The numbers move with the bench environment.

Resilience Policies (Decorator Overhead)

The decorators (withCache, withCircuitBreaker, withFallback, withRetry) are designed to add value on top of remote backends: withCache absorbs hot-key spam in memory, withCircuitBreaker stops hammering a failing backend, withFallback swaps to a secondary when the primary is down, withRetry masks transient errors. Wrapping a local limiter is structurally pure overhead: there is no network round-trip to absorb, no failure to circuit-break, nothing to retry.

This section is therefore split in two with very different intents:

• 5.1 Decorator on a local Fixed Window (raw overhead reference): how much each decorator costs per call when the underlying limiter is already local. This is a reference for the per-call cost of the decorator machinery, not a recommendation of whether to use it.
• 5.2 Decorator on Redis under extreme spam (the value matrix): the production-realistic case where the decorators earn their keep.

5.1 Raw overhead reference (decorator on local)

All four decorators add overhead on a local limiter; the run-to-run spread is large because the local limiter is fast enough that small differences in JIT optimisation flip the ordering. Read this as the per-call cost of the decorator machinery. On a local limiter, every decorator is pure overhead because there is no remote backend to protect.

Section 5.2 below is the one that actually matters.

5.2 Value under extreme spam (decorator on Redis)

Under extreme spam on a single key, the 1000 req/60s limit is exhausted within the first few milliseconds of the run. After that, every call hits Redis just to learn "denied", and Redis becomes the bottleneck at ~140K ops/sec. The withCache decorator absorbs those denied responses in memory and turns the limiter into a local-memory operation for the rest of the run.

withCache delivers 2.32M ops/sec vs 143K: a 16.2x throughput gain and a 28x latency drop (1.11 ms → 0.04 ms). The cache does this by remembering the last "denied" result for each key for 100 ms; under extreme spam on a single key, every call after the first 1000 is served from memory instead of going through Redis.

withCircuitBreaker and withRetry show no benefit on this matrix because Redis is healthy. Their value lives in the failure case, which is not part of the standard bench. Section 5.3 below injects Redis failures and measures the circuit-breaker / retry / fallback payoff.

5.3 Value under failure (decorator on Redis with fault injection)

Section 5.2 shows what happens on a healthy backend. Production deployments are not healthy. To measure the value of the failure-recovery decorators in realistic conditions, this matrix wraps a real Redis client in a Proxy that injects three kinds of failures before delegating to the real client. The errors are indistinguishable from real Redis failures (same error type, same latency profile), so the limiter and decorators react the same way they would in production.

Three failure profiles, run against the same extreme-spam workload as 5.2.

5.3.1 Transient errors (10% of calls throw)

Each call has a 10% chance of throwing a transient error at the Redis client level, before the limiter logic sees it.

Two results worth flagging:

• withRetry is slower than raw, not faster. Under extreme spam the limiter denies 99.9% of calls within the first few milliseconds. Re-running a denied call does not change the answer; it just adds latency. Retry only helps when the answer would have been different, and a "denied" decision from the rate limiter is final.
• withCircuitBreaker is the worst outcome: 146 allowed (vs 1,000 for raw). The breaker opens after 3 errors and starts fast-failing, which means even requests that the limiter would have allowed are now blocked. The breaker protects the backend, not the user, and 10% transient errors is exactly the regime where it is too aggressive for a limiter that already denies most traffic.

withFallback is the only decorator that hides the errors. It catches the 10% of calls that would have thrown and returns the configured fallback (allowed, with a synthetic remaining/reset). The user sees 10.13% allowed because the fallback bypasses the rate-limit ceiling for failed calls only.

5.3.2 Slow Redis (50 ms per call)

All calls succeed but take 50 ms. This is the latency-spike scenario: a slow backend, not a failing one.

Every decorator converges to the same number: ~1,570 ops/sec, 50.92 ms p99. The throughput is bound by the 50 ms latency per call, and none of the three decorators helps because they are all triggered by errors, not by latency. Retry only re-runs on errors; circuit-breaker only opens on errors; fallback only activates on errors. A slow-but-successful backend looks identical to a healthy one to all three.

Known gap: a future withTimeout(p, { budgetMs: 10 }) decorator would let a caller abort a slow call and treat it as a failure, at which point the existing retry / circuit-breaker / fallback stack would react correctly. The current benchmarks do not include this decorator.

5.3.3 Hard down (100% of calls fail)

Every call throws. This is the worst-case scenario: total Redis outage.

When Redis is hard-down, raw, withRetry, and withCircuitBreaker all serve 0 requests. withFallback serves 727,023 of them at near-baseline throughput (121,419 ops/sec vs 143,059 for raw-on-healthy, a 15% gap that is the cost of the try/catch wrapping). The fallback policy is "allow" with a local synthetic result, so the service keeps accepting traffic and the user-facing system stays up.

withRetry is the worst choice in this scenario: 86% slower than raw, because it tries the failing call 3 times in series (baseDelayMs: 2, maxDelayMs: 10) before giving up. withCircuitBreaker is faster than retry but still serves nothing, because opening the circuit means every subsequent call returns the configured "deny" without consulting the backend. There is no fallback configured for the breaker.

5.3.4 Verdict

The 5.3 matrix inverts the conclusion of 5.2. On a healthy backend, withCache is the only decorator that earns its keep. On a degraded backend, withFallback is the only decorator that earns its keep. The two decorators are complementary: withCache is for the hot-key flood, withFallback is for the backend outage. A production-grade remote limiter should ship with both.

withCircuitBreaker and withRetry still have a place, just not the one this matrix exercises. The circuit-breaker protects a backend from a tight retry loop; retry smooths out one-off blips on a primary before the fallback activates. Both belong in front of the primary when the primary feeds a withFallback. On their own, with a single-tier Redis backend, they cost more than they save.

Redis and Valkey Client Drivers

Both Redis and Valkey are tested with the ioredis and node-redis clients under extreme spam. The numbers in this section come from a freshly-pulled Redis 8.8.0 and Valkey 8.1.8 container, so the comparison is across same-major server versions on both engines.

All four rows sit within a 5% band. ioredis was used for the package-comparison matrix to keep the two libraries on equal footing. The limiter implementation is the dominant cost in this scenario, not the client.

Postgres drivers: pg vs postgres.js

Both drivers ran cleanly on the diverse scenario under production-default durability, with postgres.js ahead on Fixed Window (33,025 vs 22,872 logged / 28,183 unlogged) and on Token Bucket (23,853 vs 19,135). Under extreme Token Bucket spam, the two drivers converge to roughly the same throughput (~1,700 ops/sec, ~213-223 ms p99). The bottleneck is the single hot row, not the driver. The earlier draft of this page reported that postgres.js failed with UNSAFE_TRANSACTION under the default concurrency of 80; the root cause was sql.unsafe() at the top level on a pool with max > 1, which postgres.js v3 disallows. The fix was to use sql.reserve() inside the driver to checkout a dedicated connection per query, allowing the pool to run at full concurrency. As of v0.2, each strategy in @ratelock/postgres ships with two implementations: one using pg's native (sql, params) API with named prepared statements, and one using postgres.js's native tagged templates. Each driver runs on its own optimal path.