valvejs
v0.6.1
Published
One rate limit for every worker that calls an API.
Maintainers
Readme
valvejs
One rate limit for every worker that calls an API.
valve queues outbound API calls under one budget shared by your workers, stored in Redis or Valkey. When the provider asks you to slow down, every worker sharing that budget pauses. A memory store supports single-process use.
Documentation · npm package · Releases
Quickstart
Beta until 1.0. APIs may change between releases. Published versions use plain version numbers and install through npm’s default channel.
npm install valvejsThe npm badge above follows the current release automatically. See the release history for published versions and release notes.
import { createValve } from 'valvejs';
import { redisStore } from 'valvejs/redis';
const api = createValve({
id: 'partner:credential-42',
rate: { limit: 100, interval: '1s' },
store: redisStore({ client: redis }),
});
const limitedFetch = api.wrapFetch();
const response = await limitedFetch('https://api.example.com/contacts');Pass a connected ioredis or node-redis client. valve uses its structural
interface and never owns its connection. Disable command-client offline queues
(enableOfflineQueue: false for ioredis, disableOfflineQueue: true for
node-redis) to reject commands issued while disconnected. Store timeouts do not
cancel commands already sent; see timeouts and reconnection.
Each worker uses the same server, prefix, and id. Immutable workers use the
same complete rules; managed workers use the same structure and stored numeric
values. The library has zero runtime and peer dependencies.
wrapFetch retries rate limit responses for GET, HEAD, OPTIONS, PUT and
DELETE by default. POST and PATCH require retryUnsafeMethods: true after
verifying the provider's idempotency contract. Every response still updates
shared cooldowns; retries: 0 disables automatic retries.
What it does
- Shares a rate budget across processes with atomic Redis/Valkey scripts.
- Queues work with cost, priority, local concurrency, queue bounds, deadlines, and abort signals.
- Reads
Retry-After, IETFRateLimit, and commonx-ratelimit-*headers. - Retries fetch rate limit responses after a shared pause.
- Supports GCRA pacing, explicit fixed windows, and several rules checked together.
- Spends shared and per-recipient or per-tenant budgets atomically; eligible identities proceed while others wait.
- Updates named rule limits at runtime without resetting spent budget.
- Provides ESM and CommonJS entry points with TypeScript declarations.
Choose the right tool
| Need | Tool | | --------------------------------------------------- | ----------------------------------------------------- | | Shared outbound budget, queueing, provider feedback | valve | | Limit parallel work inside one process | p-limit or p-queue | | Accept or reject inbound requests | An inbound rate limiter | | Persist jobs across process restarts | A durable job queue, with valve around outbound calls | | General retries or circuit breaking | Your HTTP client or a retry library |
Guarantees
The default GCRA rule uses burst: 1: at most limit cost units start in any
half-open interval of the configured length, with one unit every
interval / limit milliseconds. With a larger burst, the bound becomes
limit + burst - 1.
Fixed windows admit at most limit units per aligned window. Adjacent windows
can admit 2 * limit units near a boundary. Several rules each hold separately.
All rate calculations use the store clock.
Concurrency and queue order are local to a valve instance. A pause blocks
subsequent grants; already-issued grants can still start. A cancelled job or
timed-out store call can waste its grant. Queued work does not survive process
failure, and onStoreError: 'open' gives up shared rate guarantees while the
store is unavailable. Rate bounds do not survive
loss of Redis state from a flush, eviction, or
failover. Read the full guarantees.
Scoped budgets
A job can spend shared and per-recipient budgets atomically:
const messages = createValve({
id: 'business-42',
rate: [
{ name: 'shared', limit: 80, interval: '1s', burst: 8 },
{ name: 'spacing', scope: 'recipient', limit: 1, interval: '6s' },
],
});
await messages.run(() => sendMessage(), {
scopes: { recipient: 'contact-42' },
});
await messages.close();Blocked recipients let other eligible jobs proceed. Supply opaque application IDs, not phone numbers or secrets. Feedback and pauses remain Valve-wide. See Scoped rate limits for wrappers, store requirements, deployment safety, and limits.
Independent keyed groups
Use a group when tenants, credentials, or models need independent budgets, queues, concurrency, and 429 cooldowns:
import { createValveGroup } from 'valvejs/group';
const tenants = createValveGroup({
id: 'crm:tenants',
maxSize: 500,
resolve: () => ({ rate: { limit: 10, interval: '1s' }, concurrency: 2 }),
});
try {
await tenants.run('tenant-42', () => 'sent');
} finally {
await tenants.close({ drain: true });
}The opt-in valvejs/group entry keeps the core entry small. Members from
get(key) remain safe across idle eviction; store budgets are preserved.
Groups do not enforce a shared parent quota across keys. For a shared hard
parent plus per-key quota, use one valve with atomic scoped rules.
See Independent keyed groups
for tier policies, Redis, managed updates, capacity backpressure, and shutdown.
Compose valves
Use one valve with scoped rules when budgets must be spent together or not at
all. When independent budgets with separate IDs should be admitted in order,
runSequential makes that explicit:
import { runSequential } from 'valvejs';
await runSequential(
[
{ valve: ingress },
{ valve: tenants, options: { scopes: { tenant: 'tenant-1' } } },
],
({ signal }) => callProvider(signal),
{ signal },
);It is not atomic: an earlier admission stays spent if a later stage rejects, and outer jobs keep their concurrency slots and global leases while later stages wait. See Compose valves.
Runtime limit updates
Opt in with named rules and limits: 'managed'. Configured numeric values seed
only a new ID; the store is authoritative afterwards.
const api = createValve({
id: 'partner:credential-42',
limits: 'managed',
rate: { name: 'throughput', limit: 100, interval: '1s', burst: 10 },
store,
});
const current = await api.getLimits();
await api.updateLimits(
{ throughput: { limit: 200, burst: 20 } },
{ expect: { throughput: { limit: current.rules.throughput.limit } } },
);Updates preserve fixed-window counts and GCRA cost-unit debt. Names, scopes,
algorithms, intervals, and global concurrency remain fixed. Drain immutable
workers before the first managed update, and use Redis with
maxmemory-policy noeviction. See
Update limits at runtime.
Documentation and development
pnpm install
pnpm check
pnpm docs:devThe Next.js and Fumadocs MDX documentation site lives in apps/web/. Build it with pnpm docs:build.
- Quickstart
- Share a quota
- Choose provider quota scopes
- Respect Retry-After
- Priorities and shutdown
- Migrate from Bottleneck
- API reference
- Tests and benchmarks
- Contributing
Run pnpm test for unit and property tests, pnpm test:coverage for coverage,
and pnpm test:types for inference checks. With Redis running, use
REDIS_URL=redis://127.0.0.1:6379 pnpm test:integration for real-store tests.
Postgres stores, provider presets, and Bottleneck compatibility are planned for later versions. Shared global concurrency is supported by Redis and Valkey.
License
Apache License 2.0. Copyright 2026 Saurav K.
Rate bounds are measured at atomic store admission. A delayed callback or network write can occur later, so actual HTTP arrival times may bunch together.
Shared concurrency and immediate resume
const subscriber = redis.duplicate(); // Separate ioredis subscription connection
const store = redisStore({ client: redis, subscriber });
const api = createValve({
id: 'partner:credential-42',
concurrency: { limit: 5, scope: 'global', leaseTtl: '30s' },
store,
});
await api.run(({ signal }) => fetch(url, { signal }));The store renews active leases and recovers slots after a worker crashes. Jobs
must honor the signal when ownership is lost. A process stalled past its TTL
can outlive its lease; external fencing is needed for strict partition safety.
Close the valves, then store.close(), then your own subscriber and command
clients. For node-redis, connect the duplicated subscriber before use.
Benchmark tooling lives in the private performance workspace.
Run pnpm perf quick for portable checks or pnpm perf:sylvie for the laptop
comparison preset. Shared-store comparisons use dedicated harness-owned stores;
see the harness documentation for setup, evidence, and workload limitations.
