@upstash/ratelimit 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,10 @@
-# Upstash Redis
+# Upstash Ratelimit
 
 An HTTP/REST based Redis client built on top of Upstash REST API.
 [Upstash REST API](https://docs.upstash.com/features/restapi).
 
 [![Tests](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml)
 ![npm (scoped)](https://img.shields.io/npm/v/@upstash/ratelimit)
-![npm bundle size](https://img.shields.io/bundlephobia/minzip/@upstash/ratelimit)
 
 It is the only connectionless (HTTP based) ratelimiter and designed for:
 
@@ -17,6 +16,38 @@ It is the only connectionless (HTTP based) ratelimiter and designed for:
 - WebAssembly
 - and other environments where HTTP is preferred over TCP.
 
+<!-- toc -->
+
+- [Quick Start](#quick-start)
+  - [Install](#install)
+    - [npm](#npm)
+    - [Deno](#deno)
+  - [Create database](#create-database)
+  - [Use it](#use-it)
+  - [Block until ready](#block-until-ready)
+- [Globally replicated ratelimiting](#globally-replicated-ratelimiting)
+  - [Usage](#usage)
+  - [Example](#example)
+- [Ratelimiting algorithms](#ratelimiting-algorithms)
+  - [Fixed Window](#fixed-window)
+    - [Pros:](#pros)
+    - [Cons:](#cons)
+    - [Usage:](#usage)
+  - [Sliding Window](#sliding-window)
+    - [Pros:](#pros-1)
+    - [Cons:](#cons-1)
+    - [Usage:](#usage-1)
+  - [Token Bucket](#token-bucket)
+    - [Pros:](#pros-2)
+    - [Cons:](#cons-2)
+    - [Usage:](#usage-2)
+- [Contributing](#contributing)
+  - [Install Deno](#install-deno)
+  - [Database](#database)
+  - [Running tests](#running-tests)
+
+<!-- tocstop -->
+
 ## Quick Start
 
 ### Install
@@ -30,7 +61,7 @@ npm install @upstash/ratelimit
 #### Deno
 
 ```ts
-import { Redis } from "https://deno.land/x/upstash_ratelimit/mod.ts";
+import { Ratelimit } from "https://deno.land/x/upstash_ratelimit/mod.ts";
 ```
 
 ### Create database
@@ -68,29 +99,50 @@ return "Here you go!";
 
 The `limit` method returns some more metadata that might be useful to you:
 
-```ts
+````ts
 export type RatelimitResponse = {
   /**
    * Whether the request may pass(true) or exceeded the limit(false)
    */
   success: boolean;
-
   /**
    * Maximum number of requests allowed within a window.
    */
   limit: number;
-
   /**
    * How many requests the user has left within the current window.
    */
   remaining: number;
-
   /**
    * Unix timestamp in milliseconds when the limits are reset.
    */
   reset: number;
+
+  /**
+   * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
+   * In most case you can simply ignore this.
+   *
+   * On Vercel Edge or Cloudflare workers, you need to explicitely handle the pending Promise like this:
+   *
+   * **Vercel Edge:**
+   * https://nextjs.org/docs/api-reference/next/server#nextfetchevent
+   *
+   * ```ts
+   * const { pending } = await ratelimit.limit("id")
+   * event.waitUntil(pending)
+   * ```
+   *
+   * **Cloudflare Worker:**
+   * https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker
+   *
+   * ```ts
+   * const { pending } = await ratelimit.limit("id")
+   * context.waitUntil(pending)
+   * ```
+   */
+  pending: Promise<unknown>;
 };
-```
+````
 
 ### Block until ready
 
@@ -124,6 +176,80 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
+## MultiRegionly replicated ratelimiting
+
+Using a single redis instance has the downside of providing low latencies to the
+part of your userbase closest to the deployed db. That's why we also built
+`MultiRegionRatelimit` which replicates the state across multiple redis
+databases as well as offering lower latencies to more of your users.
+
+`MultiRegionRatelimit` does this by checking the current limit in the closest db
+and returning immediately. Only afterwards will the state be asynchronously
+replicated to the other datbases leveraging
+[CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type). Due
+to the nature of distributed systems, there is no way to guarantee the set
+ratelimit is not exceeded by a small margin. This is the tradeoff for reduced
+global latency.
+
+### Usage
+
+The api is the same, except for asking for multiple redis instances:
+
+```ts
+import { MultiRegionRatelimit } from "@upstash/ratelimit"; // for deno: see above
+import { Redis } from "@upstash/redis";
+
+// Create a new ratelimiter, that allows 10 requests per 10 seconds
+const ratelimit = new MultiRegionRatelimit({
+  redis: [
+    new Redis({
+      /* auth */
+    }),
+    new Redis({
+      /* auth */
+    }),
+    new Redis({
+      /* auth */
+    }),
+  ],
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+});
+
+// Use a constant string to limit all requests with a single ratelimit
+// Or use a userID, apiKey or ip address for individual limits.
+const identifier = "api";
+const { success } = await ratelimit.limit(identifier);
+```
+
+### Asynchronous synchronization between databases
+
+The MultiRegion setup will do some synchronization between databases after
+returning the current limit. This can lead to problems on Cloudflare Workers and
+therefore Vercel Edge functions, because dangling promises must be taken care
+of:
+
+**Vercel Edge:**
+[docs](https://nextjs.org/docs/api-reference/next/server#nextfetchevent)
+
+```ts
+const { pending } = await ratelimit.limit("id");
+event.waitUntil(pending);
+```
+
+**Cloudflare Worker:**
+[docs](https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker)
+
+```ts
+const { pending } = await ratelimit.limit("id");
+context.waitUntil(pending);
+```
+
+### Example
+
+Let's assume you have customers in the US and Europe. In this case you can
+create 2 regional redis databases on [Upastash](https://console.upstash.com) and
+your users will enjoy the latency of whichever db is closest to them.
+
 ## Ratelimiting algorithms
 
 We provide different algorithms to use out of the box. Each has pros and cons.
@@ -199,6 +325,8 @@ const ratelimit = new Ratelimit({
 
 ### Token Bucket
 
+_Not yet supported for `MultiRegionRatelimit`_
+
 Consider a bucket filled with `{maxTokens}` tokens that refills constantly at
 `{refillRate}` per `{interval}`. Every request will remove one token from the
 bucket and if there is no token to take, the request is rejected.

package/esm/mod.js

@@ -1 +1,2 @@
-export { RegionRatelimit as Ratelimit } from "./region.js";
+export { RegionRatelimit as Ratelimit } from "./single.js";
+export { MultiRegionRatelimit } from "./multi.js";

package/esm/multi.js

@@ -0,0 +1,228 @@
+import { ms } from "./duration.js";
+import { Ratelimit } from "./ratelimit.js";
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new MultiRegionRatelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: MultiRegionRatelimit.fixedWindow(
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+export class MultiRegionRatelimit extends Ratelimit {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config) {
+        super({
+            prefix: config.prefix,
+            limiter: config.limiter,
+            ctx: { redis: config.redis },
+        });
+    }
+    /**
+     * Each requests inside a fixed time increases a counter.
+     * Once the counter reaches a maxmimum allowed number, all further requests are
+     * rejected.
+     *
+     * **Pro:**
+     *
+     * - Newer requests are not starved by old ones.
+     * - Low storage cost.
+     *
+     * **Con:**
+     *
+     * A burst of requests near the boundary of a window can result in a very
+     * high request rate because two windows will be filled with requests quickly.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - A fixed timeframe
+     */
+    static fixedWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowDuration = ms(window);
+        const script = `
+    local key     = KEYS[1]
+    local id      = ARGV[1]
+    local window  = ARGV[2]
+    
+    redis.call("SADD", key, id)
+    local members = redis.call("SMEMBERS", key)
+    if #members == 1 then
+    -- The first time this key is set, the value will be 1.
+    -- So we only need the expire command once
+      redis.call("PEXPIRE", key, window)
+    end
+    
+    return members
+`;
+        return async function (ctx, identifier) {
+            const requestID = crypto.randomUUID();
+            const bucket = Math.floor(Date.now() / windowDuration);
+            const key = [identifier, bucket].join(":");
+            const dbs = ctx.redis.map((redis) => ({
+                redis,
+                request: redis.eval(script, [key], [requestID, windowDuration]),
+            }));
+            const firstResponse = await Promise.any(dbs.map((s) => s.request));
+            const usedTokens = firstResponse.length;
+            const remaining = tokens - usedTokens - 1;
+            /**
+             * If the length between two databases does not match, we sync the two databases
+             */
+            async function sync() {
+                const individualIDs = await Promise.all(dbs.map((s) => s.request));
+                const allIDs = Array.from(new Set(individualIDs.flatMap((_) => _)).values());
+                for (const db of dbs) {
+                    const ids = await db.request;
+                    /**
+                     * If the bucket in this db is already full, it doesn't matter which ids it contains.
+                     * So we do not have to sync.
+                     */
+                    if (ids.length >= tokens) {
+                        continue;
+                    }
+                    const diff = allIDs.filter((id) => !ids.includes(id));
+                    /**
+                     * Don't waste a request if there is nothing to send
+                     */
+                    if (diff.length === 0) {
+                        continue;
+                    }
+                    await db.redis.sadd(key, ...allIDs);
+                }
+            }
+            /**
+             * Do not await sync. This should not run in the critical path.
+             */
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (bucket + 1) * windowDuration,
+                pending: sync(),
+            };
+        };
+    }
+    /**
+     * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+     * costs than `slidingLogs` and improved boundary behavior by calcualting a
+     * weighted score between two windows.
+     *
+     * **Pro:**
+     *
+     * Good performance allows this to scale to very high loads.
+     *
+     * **Con:**
+     *
+     * Nothing major.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - The duration in which the user can max X requests.
+     */
+    static slidingWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowSize = ms(window);
+        const script = `
+      local currentKey  = KEYS[1]           -- identifier including prefixes
+      local previousKey = KEYS[2]           -- key of the previous bucket
+      local tokens      = tonumber(ARGV[1]) -- tokens per window
+      local now         = ARGV[2]           -- current timestamp in milliseconds
+      local window      = ARGV[3]           -- interval in milliseconds
+      local requestID   = ARGV[4]           -- uuid for this request
+
+
+      local currentMembers = redis.call("SMEMBERS", currentKey)
+      local requestsInCurrentWindow = #currentMembers
+      local previousMembers = redis.call("SMEMBERS", previousKey)
+      local requestsInPreviousWindow = #previousMembers
+
+      local percentageInCurrent = ( now % window) / window
+      if requestsInPreviousWindow * ( 1 - percentageInCurrent ) + requestsInCurrentWindow >= tokens then
+        return {currentMembers, previousMembers}
+      end
+
+      redis.call("SADD", currentKey, requestID)
+      table.insert(currentMembers, requestID)
+      if requestsInCurrentWindow == 0 then 
+        -- The first time this key is set, the value will be 1.
+        -- So we only need the expire command once
+        redis.call("PEXPIRE", currentKey, window * 2 + 1000) -- Enough time to overlap with a new window + 1 second
+      end
+      return {currentMembers, previousMembers}
+      `;
+        const windowDuration = ms(window);
+        return async function (ctx, identifier) {
+            const requestID = crypto.randomUUID();
+            const now = Date.now();
+            const currentWindow = Math.floor(now / windowSize);
+            const currentKey = [identifier, currentWindow].join(":");
+            const previousWindow = currentWindow - windowSize;
+            const previousKey = [identifier, previousWindow].join(":");
+            const dbs = ctx.redis.map((redis) => ({
+                redis,
+                request: redis.eval(script, [currentKey, previousKey], [tokens, now, windowDuration, requestID]),
+            }));
+            const percentageInCurrent = (now % windowDuration) / windowDuration;
+            const [current, previous] = await Promise.any(dbs.map((s) => s.request));
+            const usedTokens = previous.length * (1 - percentageInCurrent) +
+                current.length;
+            const remaining = tokens - usedTokens;
+            /**
+             * If a database differs from the consensus, we sync it
+             */
+            async function sync() {
+                const [individualIDs] = await Promise.all(dbs.map((s) => s.request));
+                const allIDs = Array.from(new Set(individualIDs.flatMap((_) => _)).values());
+                for (const db of dbs) {
+                    const [ids] = await db.request;
+                    /**
+                     * If the bucket in this db is already full, it doesn't matter which ids it contains.
+                     * So we do not have to sync.
+                     */
+                    if (ids.length >= tokens) {
+                        continue;
+                    }
+                    const diff = allIDs.filter((id) => !ids.includes(id));
+                    /**
+                     * Don't waste a request if there is nothing to send
+                     */
+                    if (diff.length === 0) {
+                        continue;
+                    }
+                    await db.redis.sadd(currentKey, ...allIDs);
+                }
+            }
+            /**
+             * Do not await sync. This should not run in the critical path.
+             */
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (currentWindow + 1) * windowDuration,
+                pending: sync(),
+            };
+        };
+    }
+}

package/esm/ratelimit.js

@@ -92,7 +92,7 @@ export class Ratelimit {
              * An identifier per user or api.
              * Choose a userID, or api token, or ip address.
              *
-             * If you want to globally limit your api, you can set a constant string.
+             * If you want to limit your api across all users, you can set a constant string.
              */
             identifier, 
             /**

package/esm/{region.js → single.js}

@@ -76,6 +76,7 @@ export class RegionRatelimit extends Ratelimit {
                 limit: tokens,
                 remaining: tokens - usedTokensAfterUpdate,
                 reset: (bucket + 1) * windowDuration,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -147,6 +148,7 @@ export class RegionRatelimit extends Ratelimit {
                 limit: tokens,
                 remaining,
                 reset: (currentWindow + 1) * windowSize,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -226,7 +228,13 @@ export class RegionRatelimit extends Ratelimit {
             const now = Date.now();
             const key = [identifier, Math.floor(now / intervalDuration)].join(":");
             const [remaining, reset] = (await ctx.redis.eval(script, [key], [maxTokens, intervalDuration, refillRate, now]));
-            return { success: remaining > 0, limit: maxTokens, remaining, reset };
+            return {
+                success: remaining > 0,
+                limit: maxTokens,
+                remaining,
+                reset,
+                pending: Promise.resolve(),
+            };
         };
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "main": "./script/mod.js",
   "types": "./types/mod.d.ts",
   "name": "@upstash/ratelimit",
-  "version": "v0.1.1",
+  "version": "v0.1.3",
   "description": "A serverless ratelimiter built on top of Upstash REST API.",
   "repository": {
     "type": "git",

package/script/mod.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Ratelimit = void 0;
-var region_js_1 = require("./region.js");
-Object.defineProperty(exports, "Ratelimit", { enumerable: true, get: function () { return region_js_1.RegionRatelimit; } });
+exports.MultiRegionRatelimit = exports.Ratelimit = void 0;
+var single_js_1 = require("./single.js");
+Object.defineProperty(exports, "Ratelimit", { enumerable: true, get: function () { return single_js_1.RegionRatelimit; } });
+var multi_js_1 = require("./multi.js");
+Object.defineProperty(exports, "MultiRegionRatelimit", { enumerable: true, get: function () { return multi_js_1.MultiRegionRatelimit; } });

package/script/multi.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiRegionRatelimit = void 0;
+const duration_js_1 = require("./duration.js");
+const ratelimit_js_1 = require("./ratelimit.js");
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new MultiRegionRatelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: MultiRegionRatelimit.fixedWindow(
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+class MultiRegionRatelimit extends ratelimit_js_1.Ratelimit {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config) {
+        super({
+            prefix: config.prefix,
+            limiter: config.limiter,
+            ctx: { redis: config.redis },
+        });
+    }
+    /**
+     * Each requests inside a fixed time increases a counter.
+     * Once the counter reaches a maxmimum allowed number, all further requests are
+     * rejected.
+     *
+     * **Pro:**
+     *
+     * - Newer requests are not starved by old ones.
+     * - Low storage cost.
+     *
+     * **Con:**
+     *
+     * A burst of requests near the boundary of a window can result in a very
+     * high request rate because two windows will be filled with requests quickly.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - A fixed timeframe
+     */
+    static fixedWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowDuration = (0, duration_js_1.ms)(window);
+        const script = `
+    local key     = KEYS[1]
+    local id      = ARGV[1]
+    local window  = ARGV[2]
+    
+    redis.call("SADD", key, id)
+    local members = redis.call("SMEMBERS", key)
+    if #members == 1 then
+    -- The first time this key is set, the value will be 1.
+    -- So we only need the expire command once
+      redis.call("PEXPIRE", key, window)
+    end
+    
+    return members
+`;
+        return async function (ctx, identifier) {
+            const requestID = crypto.randomUUID();
+            const bucket = Math.floor(Date.now() / windowDuration);
+            const key = [identifier, bucket].join(":");
+            const dbs = ctx.redis.map((redis) => ({
+                redis,
+                request: redis.eval(script, [key], [requestID, windowDuration]),
+            }));
+            const firstResponse = await Promise.any(dbs.map((s) => s.request));
+            const usedTokens = firstResponse.length;
+            const remaining = tokens - usedTokens - 1;
+            /**
+             * If the length between two databases does not match, we sync the two databases
+             */
+            async function sync() {
+                const individualIDs = await Promise.all(dbs.map((s) => s.request));
+                const allIDs = Array.from(new Set(individualIDs.flatMap((_) => _)).values());
+                for (const db of dbs) {
+                    const ids = await db.request;
+                    /**
+                     * If the bucket in this db is already full, it doesn't matter which ids it contains.
+                     * So we do not have to sync.
+                     */
+                    if (ids.length >= tokens) {
+                        continue;
+                    }
+                    const diff = allIDs.filter((id) => !ids.includes(id));
+                    /**
+                     * Don't waste a request if there is nothing to send
+                     */
+                    if (diff.length === 0) {
+                        continue;
+                    }
+                    await db.redis.sadd(key, ...allIDs);
+                }
+            }
+            /**
+             * Do not await sync. This should not run in the critical path.
+             */
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (bucket + 1) * windowDuration,
+                pending: sync(),
+            };
+        };
+    }
+    /**
+     * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+     * costs than `slidingLogs` and improved boundary behavior by calcualting a
+     * weighted score between two windows.
+     *
+     * **Pro:**
+     *
+     * Good performance allows this to scale to very high loads.
+     *
+     * **Con:**
+     *
+     * Nothing major.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - The duration in which the user can max X requests.
+     */
+    static slidingWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowSize = (0, duration_js_1.ms)(window);
+        const script = `
+      local currentKey  = KEYS[1]           -- identifier including prefixes
+      local previousKey = KEYS[2]           -- key of the previous bucket
+      local tokens      = tonumber(ARGV[1]) -- tokens per window
+      local now         = ARGV[2]           -- current timestamp in milliseconds
+      local window      = ARGV[3]           -- interval in milliseconds
+      local requestID   = ARGV[4]           -- uuid for this request
+
+
+      local currentMembers = redis.call("SMEMBERS", currentKey)
+      local requestsInCurrentWindow = #currentMembers
+      local previousMembers = redis.call("SMEMBERS", previousKey)
+      local requestsInPreviousWindow = #previousMembers
+
+      local percentageInCurrent = ( now % window) / window
+      if requestsInPreviousWindow * ( 1 - percentageInCurrent ) + requestsInCurrentWindow >= tokens then
+        return {currentMembers, previousMembers}
+      end
+
+      redis.call("SADD", currentKey, requestID)
+      table.insert(currentMembers, requestID)
+      if requestsInCurrentWindow == 0 then 
+        -- The first time this key is set, the value will be 1.
+        -- So we only need the expire command once
+        redis.call("PEXPIRE", currentKey, window * 2 + 1000) -- Enough time to overlap with a new window + 1 second
+      end
+      return {currentMembers, previousMembers}
+      `;
+        const windowDuration = (0, duration_js_1.ms)(window);
+        return async function (ctx, identifier) {
+            const requestID = crypto.randomUUID();
+            const now = Date.now();
+            const currentWindow = Math.floor(now / windowSize);
+            const currentKey = [identifier, currentWindow].join(":");
+            const previousWindow = currentWindow - windowSize;
+            const previousKey = [identifier, previousWindow].join(":");
+            const dbs = ctx.redis.map((redis) => ({
+                redis,
+                request: redis.eval(script, [currentKey, previousKey], [tokens, now, windowDuration, requestID]),
+            }));
+            const percentageInCurrent = (now % windowDuration) / windowDuration;
+            const [current, previous] = await Promise.any(dbs.map((s) => s.request));
+            const usedTokens = previous.length * (1 - percentageInCurrent) +
+                current.length;
+            const remaining = tokens - usedTokens;
+            /**
+             * If a database differs from the consensus, we sync it
+             */
+            async function sync() {
+                const [individualIDs] = await Promise.all(dbs.map((s) => s.request));
+                const allIDs = Array.from(new Set(individualIDs.flatMap((_) => _)).values());
+                for (const db of dbs) {
+                    const [ids] = await db.request;
+                    /**
+                     * If the bucket in this db is already full, it doesn't matter which ids it contains.
+                     * So we do not have to sync.
+                     */
+                    if (ids.length >= tokens) {
+                        continue;
+                    }
+                    const diff = allIDs.filter((id) => !ids.includes(id));
+                    /**
+                     * Don't waste a request if there is nothing to send
+                     */
+                    if (diff.length === 0) {
+                        continue;
+                    }
+                    await db.redis.sadd(currentKey, ...allIDs);
+                }
+            }
+            /**
+             * Do not await sync. This should not run in the critical path.
+             */
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (currentWindow + 1) * windowDuration,
+                pending: sync(),
+            };
+        };
+    }
+}
+exports.MultiRegionRatelimit = MultiRegionRatelimit;

package/script/ratelimit.js

@@ -95,7 +95,7 @@ class Ratelimit {
              * An identifier per user or api.
              * Choose a userID, or api token, or ip address.
              *
-             * If you want to globally limit your api, you can set a constant string.
+             * If you want to limit your api across all users, you can set a constant string.
              */
             identifier, 
             /**

package/script/{region.js → single.js}

@@ -79,6 +79,7 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
                 limit: tokens,
                 remaining: tokens - usedTokensAfterUpdate,
                 reset: (bucket + 1) * windowDuration,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -150,6 +151,7 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
                 limit: tokens,
                 remaining,
                 reset: (currentWindow + 1) * windowSize,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -229,7 +231,13 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
             const now = Date.now();
             const key = [identifier, Math.floor(now / intervalDuration)].join(":");
             const [remaining, reset] = (await ctx.redis.eval(script, [key], [maxTokens, intervalDuration, refillRate, now]));
-            return { success: remaining > 0, limit: maxTokens, remaining, reset };
+            return {
+                success: remaining > 0,
+                limit: maxTokens,
+                remaining,
+                reset,
+                pending: Promise.resolve(),
+            };
         };
     }
 }

package/types/mod.d.ts

@@ -1,3 +1,5 @@
-export { RegionRatelimit as Ratelimit } from "./region.js";
-export type { RegionRatelimitConfig as RatelimitConfig } from "./region.js";
+export { RegionRatelimit as Ratelimit } from "./single.js";
+export type { RegionRatelimitConfig as RatelimitConfig } from "./single.js";
+export { MultiRegionRatelimit } from "./multi.js";
+export type { MultiRegionRatelimitConfig } from "./multi.js";
 export type { Algorithm } from "./types.js";

package/types/multi.d.ts

@@ -0,0 +1,98 @@
+import type { Duration } from "./duration.js";
+import type { Algorithm, MultiRegionContext } from "./types.js";
+import { Ratelimit } from "./ratelimit.js";
+import type { Redis } from "./types.js";
+export declare type MultiRegionRatelimitConfig = {
+    /**
+     * Instances of `@upstash/redis`
+     * @see https://github.com/upstash/upstash-redis#quick-start
+     */
+    redis: Redis[];
+    /**
+     * The ratelimiter function to use.
+     *
+     * Choose one of the predefined ones or implement your own.
+     * Available algorithms are exposed via static methods:
+     * - MultiRegionRatelimit.fixedWindow
+     */
+    limiter: Algorithm<MultiRegionContext>;
+    /**
+     * All keys in redis are prefixed with this.
+     *
+     * @default `@upstash/ratelimit`
+     */
+    prefix?: string;
+};
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new MultiRegionRatelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: MultiRegionRatelimit.fixedWindow(
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+export declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config: MultiRegionRatelimitConfig);
+    /**
+     * Each requests inside a fixed time increases a counter.
+     * Once the counter reaches a maxmimum allowed number, all further requests are
+     * rejected.
+     *
+     * **Pro:**
+     *
+     * - Newer requests are not starved by old ones.
+     * - Low storage cost.
+     *
+     * **Con:**
+     *
+     * A burst of requests near the boundary of a window can result in a very
+     * high request rate because two windows will be filled with requests quickly.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - A fixed timeframe
+     */
+    static fixedWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens: number, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window: Duration): Algorithm<MultiRegionContext>;
+    /**
+     * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+     * costs than `slidingLogs` and improved boundary behavior by calcualting a
+     * weighted score between two windows.
+     *
+     * **Pro:**
+     *
+     * Good performance allows this to scale to very high loads.
+     *
+     * **Con:**
+     *
+     * Nothing major.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - The duration in which the user can max X requests.
+     */
+    static slidingWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens: number, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window: Duration): Algorithm<MultiRegionContext>;
+}

package/types/types.d.ts

@@ -5,10 +5,10 @@ export interface Redis {
 export declare type RegionContext = {
     redis: Redis;
 };
-export declare type GlobalContext = {
+export declare type MultiRegionContext = {
     redis: Redis[];
 };
-export declare type Context = RegionContext | GlobalContext;
+export declare type Context = RegionContext | MultiRegionContext;
 export declare type RatelimitResponse = {
     /**
      * Whether the request may pass(true) or exceeded the limit(false)
@@ -26,5 +26,28 @@ export declare type RatelimitResponse = {
      * Unix timestamp in milliseconds when the limits are reset.
      */
     reset: number;
+    /**
+     * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
+     * In most case you can simply ignore this.
+     *
+     * On Vercel Edge or Cloudflare workers, you need to explicitely handle the pending Promise like this:
+     *
+     * **Vercel Edge:**
+     * https://nextjs.org/docs/api-reference/next/server#nextfetchevent
+     *
+     * ```ts
+     * const { pending } = await ratelimit.limit("id")
+     * event.waitUntil(pending)
+     * ```
+     *
+     * **Cloudflare Worker:**
+     * https://developers.cloudflare.com/workers/runtime-apis/fetch-event/#syntax-module-worker
+     *
+     * ```ts
+     * const { pending } = await ratelimit.limit("id")
+     * context.waitUntil(pending)
+     * ```
+     */
+    pending: Promise<unknown>;
 };
 export declare type Algorithm<TContext> = (ctx: TContext, identifier: string) => Promise<RatelimitResponse>;