Quick Start

Default fail behavior

By default, if the Borrow API is unreachable or returns an error (e.g. due to a network failure or quota issue), the limiter resolves with success: true and allows the request through. This is controlled by the failBehavior option, which defaults to "bypass". If your use case requires that requests are blocked whenever the limiter cannot be verified, set failBehavior to "fail": Note that INVALID_PARAMETERS errors always result in success: false regardless of this setting.

Authentication

Follow these steps to get your API key and start using Borrow Limiter:

Create a Borrow account.
Create a new project.
Inside your project, go to the Settings tab.
In the Authentication section, click Show API Key.
Wait for the API key to be decrypted and copy it.
Set the BORROW_API_KEY environment variable in your application to the copied API key.

Installation

Install the Borrow Node.js package using your preferred package manager:

npm install @borrowdev/limiter

Usage

Limiting with the fixed window algorithm

Let's use the fixed window algorithm to rate limit our login endpoint to 10 requests per minute.

import { limiter } from "@borrowdev/limiter";
async function callLimiter() {
  const { success, timeLeft } = await limiter(
    { key: "my-limiter-id", userId: "current-user-id" },
    {
      limiters: [
        {
          maxRequests: 10,
          interval: "minute",
          type: "fixed",
        },
      ],
    },
  );
  if (!success) {
    return {
      message:
        "Rate limit exceeded." +
        (timeLeft !== null ? ` You can try again in ${timeLeft} seconds.` : ""),
    };
  }
}
// ... Your expensive business logic

Rate limiting with the sliding window algorithm

Let's use the sliding window algorithm to rate limit our login endpoint to 10 requests per minute.

import { limiter } from "@borrowdev/limiter";
async function callLimiter() {
  const { success, timeLeft } = await limiter(
    { key: "my-limiter-id", userId: "current-user-id" },
    {
      limiters: [
        {
          maxRequests: 10,
          interval: "minute",
          type: "sliding",
        },
      ],
    },
  );
  if (!success) {
    return {
      message:
        "Rate limit exceeded." +
        (timeLeft !== null ? ` You can try again in ${timeLeft} seconds.` : ""),
    };
  }
  // ... Your expensive business logic
}

Rate limiting with the token bucket algorithm

Let's use the token bucket algorithm to rate limit requests to 10 tokens per minute, with a maximum of 20 tokens.

import { limiter } from "@borrowdev/limiter";
async function callLimiter() {
  const { success, timeLeft } = await limiter(
    { key: "my-limiter-id", userId: "current-user-id" },
    {
      limiters: [
        {
          maxTokens: 20,
          tokensCost: 5,
          tokensPerReplenish: 10,
          interval: "minute",
          type: "token",
        },
      ],
    },
  );
  if (!success) {
    return {
      message:
        "Rate limit exceeded." +
        (timeLeft !== null ? ` You can try again in ${timeLeft} seconds.` : ""),
    };
  }
  // Optionally, you can also manually refill tokens!
  await limiter.tokens.refill({
    key: "my-limiter-id",
    userId: "current-user-id",
  });
  // ... Your expensive business logic
}

Limiting with the borrow algorithm

Let's use the borrow algorithm to rate limit requests to one request at a time.

import { limiter } from "@borrowdev/limiter";
async function callLimiter() {
  const { success, timeLeft } = await limiter(
    { key: "my-limiter-id", userId: "current-user-id" },
    {
      limiters: [
        {
          borrowAction: "start",
          type: "borrow",
          timeout: 10,
        },
      ],
    },
  );
  if (!success) {
    return {
      message:
        "Rate limit exceeded." +
        (timeLeft !== null ? ` You can try again in ${timeLeft} seconds.` : ""),
    };
  }
  // ... Your expensive business logic
  const { success: endSuccess } = await limiter(
    { key: "my-limiter-id", userId: "current-user-id" },
    {
      limiters: [
        {
          borrowAction: "end",
          type: "borrow",
          timeout: 10,
        },
      ],
    },
  );
  if (!endSuccess) {
    return { message: "Failed to end borrow." };
  }
}

Conclusion

In this Quick Start guide, we've barely scratched the surface of what Borrow Limiter can do. You can do so much more such as customizing the unexpected fail behavior and creating different limiter combinations with up to 4 limiters of unique types.

If you want to learn more, the best way to do so is to just install Borrow and read the in-editor comments (JSDoc for TS/JS).

Quick Start

On this page