npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

valvejs

v0.6.1

Published

One rate limit for every worker that calls an API.

Readme

valvejs

npm version npm downloads per month

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 valvejs

The 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, IETF RateLimit, and common x-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:dev

The Next.js and Fumadocs MDX documentation site lives in apps/web/. Build it with pnpm docs:build.

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.