Runtimes
Compatibility matrix for the JavaScript runtimes RateLock supports.
RateLock targets JavaScript runtimes, not a single host. The storage adapter determines whether state is local to an isolate or shared through a remote backend.
Supported
| Runtime | Versions | Status |
|---|---|---|
| Node.js | 22, 24 | Primary. Mock tests run on every PR; Redis, PostgreSQL, and local HTTP integration suites run through package-specific commands. |
| Bun | 1.1+ | Tested. Mock tests run on every PR. The benchmarks page includes Node vs Bun numbers from the same harness. |
| Edge / serverless | Provider-specific | @ratelock/upstash is designed for fetch-based handlers such as Cloudflare Workers and Vercel Edge. |
The Edge row applies to the HTTP adapter. A connection-oriented Redis or PostgreSQL driver is not automatically Edge-compatible just because the limiter API itself uses standard promises and objects.
Per-package status
| Package | Node.js | Bun | Edge / serverless |
|---|---|---|---|
@ratelock/core | yes | yes | yes, web-compatible primitives |
@ratelock/local | yes | yes | yes, but state is isolate-local |
@ratelock/redis | yes | yes | no, its supported clients use TCP connections |
@ratelock/upstash | yes | yes | yes, through the Upstash REST API |
@ratelock/postgres | yes | yes | not currently supported as a package/runtime combination |
@ratelock/local can execute in an Edge isolate, but its Map is not shared
between isolates or regions. Use @ratelock/upstash when the limit must be
consistent across instances.
Client libraries
@ratelock/redis, @ratelock/postgres, and @ratelock/upstash declare their
drivers as peer dependencies. The drivers themselves determine the runtime
boundary:
| Client | Versions | Runtime support |
|---|---|---|
ioredis | 5.x | Node.js, Bun |
redis (node-redis) | 4.x, 5.x | Node.js, Bun |
Bun native (RedisClient) | Bun >= 1.4 | Bun only |
pg (node-postgres) | 8.x | Node.js, Bun |
postgres (porsager/postgres) | 3.x | Node.js, Bun |
@upstash/redis | >= 1.34 | Node.js, Bun, supported fetch-based runtimes |
The Bun native Redis client is supported as a first-class driver by
@ratelock/redis: Lua scripts run through the client's raw command API, with
automatic pipelining batching concurrent commands. It is auto-detected when
passed as client, or can be forced with driver: 'bun' using a connection
URL.
PostgreSQL has no Bun-specific driver: Bun.SQL is a unified multi-database
API that RateLock deliberately avoids for @ratelock/postgres (dialect-specific
performance and semantics come first).
Implementation notes
The core, local, and Upstash adapter sources do not import Node.js built-ins.
@ratelock/upstash delegates HTTP transport to the official @upstash/redis
client and does not create or close a TCP socket. The published adapter bundle
contains the shared Lua strategy code, so it does not require the private
workspace package at runtime.
The PostgreSQL engine runs periodic cleanup timers. Its Node and Bun support is tested, but it is not currently part of the Edge support matrix.
When to pick a runtime
- Node.js is the reference when you have an existing server, an LTS constraint, or a connection-oriented backend.
- Bun provides the same API and is useful for Bun-native applications and local development.
- Edge/serverless is the right fit when you use
@ratelock/upstashand want shared state without a TCP connection. Keep credentials in the provider's secret bindings.
If you target both Node.js and Bun, the same mock suite covers both. CI runs the fast tests on every PR; the backend integration commands remain explicit because they need Docker or external service credentials.
How is this guide?
Last updated on