nano-limit

Tiny concurrency and rate limiter with priorities, AbortSignal, and zero dependencies.

• Zero dependencies
• TypeScript-first with full type inference
• ESM and CommonJS support

The Problem

You need to limit API calls. You reach for p-limit but:

// p-limit: only concurrency, no rate limiting
// p-limit: can't do "max 60 requests per minute"
// p-limit: no priority queue, no AbortSignal

You try bottleneck but:

// bottleneck: complex API with reservoir, highWater, strategy...
// bottleneck: must call disconnect() or memory leaks
// bottleneck: breaks with mock timers in tests
// bottleneck: last major release was 2019

The Fix

import { createLimit } from "@npclfg/nano-limit";

// Concurrency + rate limiting in one
const limit = createLimit({
  concurrency: 5,     // max 5 parallel
  rate: 60,           // max 60 per minute
  interval: 60000,
});

await limit(() => openai.chat.completions.create({ model: "gpt-4", messages }));

// Priority queue: important requests go first
await limit(() => criticalOperation(), { priority: 10 });

// Cancel pending operations
await limit(() => fetch(url), { signal: controller.signal });

That's it. Concurrency limiting, rate limiting, priorities, and cancellation in one tiny package.

Why nano-limit?

| Feature | p-limit | bottleneck | nano-limit | |---------|---------|------------|------------| | Dependencies | 2 | 0 | 0 | | Concurrency limiting | ✅ | ✅ | ✅ | | Rate limiting | ❌ | ✅ | ✅ | | Priority queue | ❌ | ✅ | ✅ | | AbortSignal | ❌ | ❌ | ✅ | | Per-key limiting | ❌ | Manual | ✅ Built-in | | Queue size limit | ❌ | ✅ | ✅ | | onIdle() | ❌ | ✅ | ✅ | | Memory leak risk | Low | disconnect() required | None | | ESM + CJS | ESM-only (v4+) | ✅ | ✅ | | Last updated | Active | 2019 | Active |

Installation

npm install @npclfg/nano-limit

Requirements: Node.js 16+ or modern browsers (ES2020)

Quick Start

import { createLimit } from "@npclfg/nano-limit";

// Concurrency only (like p-limit)
const limit = createLimit({ concurrency: 5 });
await Promise.all(urls.map(url => limit(() => fetch(url))));

// Rate limiting (max 10 per second)
const rateLimited = createLimit({ rate: 10, interval: 1000 });

// Both together
const apiLimit = createLimit({
  concurrency: 5,
  rate: 60,
  interval: 60000,
});

API Reference

createLimit(options?): Limiter

Create a concurrency and/or rate limiter.

const limit = createLimit({
  concurrency: 5,    // max concurrent (default: Infinity)
  rate: 100,         // max per interval
  interval: 1000,    // interval in ms (default: 1000)
  maxQueueSize: 1000 // max queued operations (default: Infinity)
});

const result = await limit(() => fetchData());

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | concurrency | number | Infinity | Maximum concurrent operations | | rate | number | - | Maximum operations per interval | | interval | number | 1000 | Interval in ms for rate limiting | | maxQueueSize | number | Infinity | Max queued operations (throws QueueFullError) |

Limiter Properties

| Property | Type | Description | |----------|------|-------------| | activeCount | number | Currently running operations | | pendingCount | number | Operations waiting in queue | | clearQueue(reject?) | function | Clear pending operations | | onIdle() | Promise<void> | Resolves when queue is empty and all done |

Operation Options

await limit(() => fn(), {
  priority: 10,              // higher = sooner (default: 0)
  signal: controller.signal  // AbortSignal for cancellation
});

createKeyedLimit(options?): KeyedLimiter

Per-key rate limiting for multi-tenant systems.

const userLimit = createKeyedLimit({
  concurrency: 2,
  rate: 10,
  interval: 1000
});

// Each user gets their own limit
await userLimit("user-123", () => fetchUserData("123"));
await userLimit("user-456", () => fetchUserData("456"));

// Manage keys
userLimit.get("user-123");     // Get limiter for key
userLimit.delete("user-123");  // Remove key
userLimit.clear();             // Remove all keys
userLimit.size;                // Number of active keys

limited(fn, options?): WrappedFunction

Create a pre-configured limited function.

const fetchWithLimit = limited(
  (url: string) => fetch(url),
  { concurrency: 5, rate: 10, interval: 1000 }
);

await fetchWithLimit("/api/data");

Error Types

import { AbortError, QueueClearedError, QueueFullError } from "nano-limit";

try {
  await limit(() => fn(), { signal });
} catch (error) {
  if (error instanceof AbortError) {
    // Operation was aborted
  }
  if (error instanceof QueueClearedError) {
    // clearQueue() was called
  }
  if (error instanceof QueueFullError) {
    // maxQueueSize exceeded
  }
}

Patterns & Recipes

OpenAI/Anthropic Rate Limiting

const aiLimit = createLimit({
  concurrency: 5,      // parallel requests
  rate: 60,            // 60 RPM
  interval: 60000,
});

const response = await aiLimit(() =>
  openai.chat.completions.create({
    model: "gpt-4",
    messages,
  })
);

Priority Queue

const limit = createLimit({ concurrency: 1 });

// High priority runs first
limit(() => lowPriorityTask());
limit(() => criticalTask(), { priority: 10 });  // Runs first

Graceful Shutdown

const limit = createLimit({ concurrency: 10 });

// On shutdown
process.on("SIGTERM", async () => {
  limit.clearQueue();     // Cancel pending
  await limit.onIdle();   // Wait for active to finish
  process.exit(0);
});

With Timeout

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  await limit(() => slowOperation(), { signal: controller.signal });
} catch (error) {
  if (error instanceof AbortError) {
    console.log("Timed out");
  }
}

Backpressure / Queue Overflow

const limit = createLimit({
  concurrency: 5,
  maxQueueSize: 100,  // Reject if queue grows too large
});

try {
  await limit(() => processRequest());
} catch (error) {
  if (error instanceof QueueFullError) {
    // Return 503 Service Unavailable
  }
}

Multi-Tenant API

const userLimit = createKeyedLimit({
  concurrency: 2,
  rate: 100,
  interval: 60000,
});

app.use(async (req, res, next) => {
  try {
    await userLimit(req.user.id, () => next());
  } catch (error) {
    if (error instanceof QueueFullError) {
      res.status(429).send("Too Many Requests");
    }
  }
});

TypeScript Usage

Full type inference is supported:

import { createLimit, LimitOptions, Limiter } from "nano-limit";

interface ApiResponse {
  data: string[];
}

// Return type is inferred as Promise<ApiResponse>
const result = await limit(async (): Promise<ApiResponse> => {
  const res = await fetch("/api");
  return res.json();
});

License

MIT