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

apiguardlimitjs

v0.1.0

Published

Sub-millisecond rate limiter with local token leasing, distributed Redis sync, and pluggable risk scoring

Readme

apiguardjs

Sub-millisecond rate limiter with local token leasing, distributed Redis sync, and a pluggable risk-scoring pipeline.


Architecture

                        ┌─────────────────────────────────────┐
  Request               │              Guard.check()           │
  ──────►  Middleware   │                                      │
           (Express /   │  1. Denylist?  ──yes──► 429         │
            Fastify /   │       │                              │
            Hono)       │       no                             │
                        │       ▼                              │
                        │  2. Risk pipeline (optional)         │
                        │     velocity · failed-auth           │
                        │     ip-rep · geo-jump · ua           │
                        │       │                              │
                        │    block ──────────────► 429         │
                        │    challenge ──► pass + flag         │
                        │    allow ──────────────► ▼           │
                        │                          │           │
                        │  3. Rate-limit check     │           │
                        │     (synchronous,        │           │
                        │      zero network I/O)   │           │
                        │       │                  │           │
                        │    denied ─────────────► 429         │
                        │    allowed ────────────► next()      │
                        └─────────────────────────────────────┘
                                        │
                              background│lease refill
                                        ▼
                                  ┌──────────┐
                                  │  Redis   │  ← Lua atomic lease grant
                                  │  pub/sub │  ← denylist propagation
                                  └──────────┘
                               (only in distributed mode)

Install

npm install apiguardjs
# peer deps — install only what you use
npm install express        # Express adapter
npm install fastify        # Fastify adapter
npm install hono           # Hono adapter
npm install ioredis        # distributed mode

Quick start

Single-node (Express)

import express from "express";
import { createGuard, expressMiddleware } from "apiguardjs";

const guard = createGuard({
  limits: {
    default:          { rate: 100,  per: "1m", by: "ip" },
    "POST /login":    { rate: 5,    per: "1m", by: "ip", algorithm: "sliding-window" },
    "POST /register": { rate: 3,    per: "1h", by: "ip" },
  },
});

app.use(expressMiddleware(guard, {
  limits: {
    default:          { by: "ip" },
    "POST /login":    { by: "ip" },
  },
}));

Distributed mode (Redis)

import Redis from "ioredis";
import { createGuard } from "apiguardjs";

const guard = createGuard({
  limits: { default: { rate: 1000, per: "1m" } },
  redis: {
    client: new Redis(process.env.REDIS_URL),
    leaseSize: 50,        // tokens requested per lease
    lowWatermark: 0.2,    // refill when budget drops to 20% of leaseSize
    denylist: true,       // cross-node pub/sub denylist
  },
  onError: (err) => console.error("Redis error", err),
});

Risk scoring

import {
  createGuard,
  velocitySignal,
  failedAuthSignal,
  ipReputationSignal,
  geoJumpSignal,
  suspiciousUaSignal,
  ReputationList,
} from "apiguardjs";

const rep = new ReputationList();
rep.loadText(await fs.readFile("blocklist.txt", "utf8"));

const guard = createGuard({
  limits: { default: { rate: 100, per: "1m" } },
  risk: {
    signals: [
      velocitySignal(50, 100),
      failedAuthSignal(3, 8),
      ipReputationSignal((ip) => rep.contains(ip)),
      geoJumpSignal(),
      suspiciousUaSignal(),
    ],
    challengeThreshold: 0.5,   // → result.risk.decision === "challenge"
    blockThreshold: 0.8,       // → result.allowed === false
  },
});

// Pass riskCtx to check() to activate the pipeline
const result = guard.check(ip, "POST /login", 1, {
  ip,
  requestVelocity: 12,
  failedAuthStreak: 2,
  userAgent: req.headers["user-agent"],
  country: geoLookup(ip),
  previousCountry: session.lastCountry,
});

if (result.risk?.decision === "challenge") {
  // serve CAPTCHA or step-up auth
}

Custom signal

const mySignal = {
  name: "vpn-detected",
  weight: 2,
  score: (ctx) => isVpn(ctx.ip) ? 1 : 0,
};

API

createGuard(config: GuardConfig): Guard

| Field | Type | Default | Description | |---|---|---|---| | limits | Record<string, LimitConfig> | required | Must include "default" | | onFailure | "fail-open" \| "fail-closed" | "fail-open" | Behavior when store throws | | evictionIntervalMs | number | 60_000 | How often to sweep expired keys | | redis | RedisConfig | — | Enables distributed mode | | risk | RiskConfig | — | Enables risk pipeline | | onError | (err) => void | — | Redis error callback |

LimitConfig

| Field | Type | Default | Description | |---|---|---|---| | rate | number | required | Max requests per window | | per | "1s" / "30m" / "2h" | required | Window size | | by | "ip" \| "user" \| "ip+user" \| fn | "ip" | Key extractor | | algorithm | "token-bucket" \| "sliding-window" | "token-bucket" | Algorithm |

guard.check(identifier, route, cost?, riskCtx?): CheckResult

| Field | Description | |---|---| | allowed | true if the request should proceed | | matchedRule | Which config key was matched | | denylisted | true if blocked by the denylist | | risk | RiskResult — only present when riskCtx is passed |

RiskResult

| Field | Description | |---|---| | decision | "allow" \| "challenge" \| "block" | | score | Weighted score 0-1 | | breakdown | Per-signal scores Record<string, number> |

Built-in signals

| Signal | Factory | Description | |---|---|---| | Velocity | velocitySignal(warnAt, blockAt) | Request rate per window | | Failed auth | failedAuthSignal(warnAt, blockAt) | Consecutive auth failures | | IP reputation | ipReputationSignal(lookup) | Blocklist / MaxMind | | Geo jump | geoJumpSignal() | Country changed since last request | | Suspicious UA | suspiciousUaSignal(patterns?) | curl, scrapy, headless browsers |


Benchmarks

Measured on Apple M2, Node 20, connections=10, duration=5s.

┌─────────────────────────────────────┬──────────────┬────────────┐
│ Scenario                            │ Requests/sec │ Latency p99│
├─────────────────────────────────────┼──────────────┼────────────┤
│ Baseline (no guard)                 │  ~85,000     │  < 1ms     │
│ Guard — token-bucket                │  ~78,000     │  < 1ms     │
│ Guard — token-bucket + 5 signals    │  ~71,000     │  < 1ms     │
│ rate-limiter-flexible (comparison)  │  ~55,000     │  1-2ms     │
└─────────────────────────────────────┴──────────────┴────────────┘

Overhead vs baseline:  ~8% (guard only)  |  ~16% (guard + risk)

Run yourself:

npm run bench

Distributed accuracy

Nodes: 5  |  Global limit: 1000  |  Lease size: 50

Total allowed : 1000-1049  (typical)
Overshoot     : 0-4.9%
Undershoot    : 0%

The overshoot is bounded by (nodes × leaseSize) - 1. With 5 nodes and leaseSize=50 the worst-case overshoot is 249 requests (24.9%). In practice it is far lower because nodes exhaust their leases before the window closes. Reduce leaseSize to tighten accuracy at the cost of more Redis round-trips.

Run yourself:

npm run bench:accuracy

Docker Compose (3-node cluster)

docker compose up

Starts Redis + 3 app nodes on ports 3001-3003. All nodes share the same Redis instance and denylist channel.


E-commerce Example (single backend container + pm2)

A realistic setup for an e-commerce backend deployed in a single Docker container behind a VPC. No Redis needed at this scale — single-node mode is enough. Add redis: only when you scale to multiple backend containers.

VPC
├── Container 1: Frontend (Next.js / nginx)
└── Container 2: Backend (Express + pm2)   ← guard lives here only
         │
         └── DB, payment gateway, email service
// backend/src/middleware/rateLimit.ts
import { createGuard, expressMiddleware, velocitySignal, failedAuthSignal, suspiciousUaSignal } from "apiguardjs";

export const guard = createGuard({
  limits: {
    // generous default for browsing
    default:                      { rate: 200, per: "1m",  by: "ip" },

    // auth — tightest limits, sliding-window prevents boundary bursts
    "POST /auth/login":           { rate: 5,   per: "1m",  by: "ip",   algorithm: "sliding-window" },
    "POST /auth/register":        { rate: 3,   per: "1h",  by: "ip",   algorithm: "sliding-window" },
    "POST /auth/forgot-password": { rate: 3,   per: "1h",  by: "ip",   algorithm: "sliding-window" },

    // checkout keyed by user, not IP (shared office/NAT IPs would false-positive)
    "POST /checkout":             { rate: 10,  per: "1h",  by: "user" },

    // coupon abuse — common in e-commerce
    "POST /apply-coupon":         { rate: 5,   per: "1h",  by: "user" },

    // search can be expensive (full DB query)
    "GET /products/search":       { rate: 30,  per: "1m",  by: "ip" },

    // password change requires auth, key by user
    "POST /account/password":     { rate: 3,   per: "1h",  by: "user" },
  },

  risk: {
    signals: [
      velocitySignal(100, 200),   // flag IPs hammering the API
      failedAuthSignal(3, 8),     // flag repeated login failures
      suspiciousUaSignal(),       // flag bots, curl, scrapy, headless browsers
    ],
    challengeThreshold: 0.5,
    blockThreshold: 0.8,
  },

  // if guard itself throws, don't take down the store
  onFailure: "fail-open",
  evictionIntervalMs: 60_000,
});

export const guardMiddleware = expressMiddleware(guard, {
  limits: {
    default:                      { by: "ip" },
    "POST /auth/login":           { by: "ip" },
    "POST /checkout":             { by: "user" },
    "POST /apply-coupon":         { by: "user" },
    "POST /account/password":     { by: "user" },
  },
  risk: true,
});
// backend/src/index.ts
import { guardMiddleware } from "./middleware/rateLimit";

app.use(guardMiddleware); // one line, covers all routes

What each rule prevents

| Route | Threat | Without guard | With guard | |---|---|---|---| | POST /auth/login | Credential stuffing | 10k attempts in seconds | 5/min per IP → 33 hours | | POST /auth/register | Fake account creation for coupon abuse | Unlimited | 3/hour per IP | | POST /auth/forgot-password | Email cost attack (SES/SendGrid) | 50k emails, bill spikes | 3/hour per IP | | POST /checkout | Stolen card probing (you pay gateway fees) | 1k card tests | 10/hour per user | | POST /apply-coupon | Promo budget drain | Drained in minutes | 5/hour per user | | GET /products/search | Competitor scraping | Full catalog in minutes | 30/min per IP | | suspiciousUaSignal | Bot traffic (curl, scrapy, headless) | Unrestricted | Blocked at risk score |

Overhead at this scale

Hot path cost per request:  ~350ns  (Map lookup + algorithm + 3 risk signals)

At 1,000 req/s  →  0.35ms CPU/s   negligible
At 5,000 req/s  →  1.75ms CPU/s   negligible

A typical e-commerce backend on a $20-50/month container will not feel this.

When to add Redis

You don't need Redis with a single backend container. Add it only when you scale to multiple containers behind a load balancer — otherwise each container tracks limits independently and the effective limit becomes rate × number of containers.

// Add this to your existing config when you scale out:
redis: {
  client: new Redis(process.env.REDIS_URL),
  leaseSize: 50,
  lowWatermark: 0.2,
  denylist: true,
},

Everything else — limits, risk config, middleware — stays exactly the same.


IP reputation with MaxMind GeoLite2

import { ReputationList } from "apiguardjs";
import { createReadStream } from "fs";
import readline from "readline";

const rep = new ReputationList();
const rl = readline.createInterface({ input: createReadStream("GeoLite2-Anonymous-IP-Blocks.csv") });
rl.on("line", (line) => {
  const cidr = line.split(",")[0];
  if (cidr && !cidr.startsWith("network")) rep.add(cidr);
});
await new Promise((r) => rl.on("close", r));

const guard = createGuard({
  limits: { default: { rate: 100, per: "1m" } },
  risk: {
    signals: [ipReputationSignal((ip) => rep.contains(ip))],
    blockThreshold: 0.8,
  },
});

Known trade-offs

| Trade-off | Detail | |---|---| | Distributed overshoot | Up to nodes × leaseSize extra requests near the limit. Tune leaseSize down to reduce. | | First-request optimism | A new key always passes on the first request while the first lease is fetched. | | Clock sensitivity | Uses Date.now(). NTP jumps can cause a free burst (token-bucket) or missed window rollover (sliding-window). Use a monotonic clock wrapper if this matters. | | X-Forwarded-For spoofing | Set Express trust proxy correctly. Guard reads the header as-is; spoofed IPs bypass per-IP limits. | | In-memory only | No persistence across restarts in single-node mode. Distributed mode survives restarts via Redis. |