@upstash/ratelimit 0.1.2 → 0.1.4-rc.0

package/.releaserc

@@ -0,0 +1,14 @@
+{
+  "branches": [
+    {
+      "name": "release"
+    },
+    {
+      "name": "main",
+      "channel": "next",
+      "prerelease": "next"
+    }
+  ],
+  "dryRun": false,
+  "ci": true
+}

package/README.md

@@ -1,4 +1,4 @@
-# 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).
@@ -25,8 +25,9 @@ It is the only connectionless (HTTP based) ratelimiter and designed for:
   - [Create database](#create-database)
   - [Use it](#use-it)
   - [Block until ready](#block-until-ready)
-- [Globally replicated ratelimiting](#globally-replicated-ratelimiting)
+- [MultiRegionly replicated ratelimiting](#multiregionly-replicated-ratelimiting)
   - [Usage](#usage)
+  - [Asynchronous synchronization between databases](#asynchronous-synchronization-between-databases)
   - [Example](#example)
 - [Ratelimiting algorithms](#ratelimiting-algorithms)
   - [Fixed Window](#fixed-window)
@@ -99,29 +100,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
 
@@ -155,15 +177,45 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
-## Globally replicated ratelimiting
+### Ephemeral Cache
+
+For extreme load or denial of service attacks, it might be too expensive to call
+redis for every incoming request, just to find out the request should be blocked
+because they have exceeded the limit.
+
+You can use an ephemeral in memory cache by passing the `ephemeralCache`
+options:
+
+```ts
+const cache = new Map(); // must be outside of your serverless function handler
+
+// ...
+
+const ratelimit = new Ratelimit({
+  // ...
+  ephemeralCache: cache,
+});
+```
+
+If enabled, the ratelimiter will keep a global cache of identifiers and a reset
+timestamp, that have exhausted their ratelimit. In serverless environments this
+is only possible if you create the ratelimiter instance outside of your handler
+function. While the function is still hot, the ratelimiter can block requests
+without having to request data from redis, thus saving time and money.
+
+Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+internal list together with its reset timestamp. If the same identifier makes a
+new request before it is reset, we can immediately reject it.
+
+## 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
-`GlobalRatelimit` which replicates the state across multiple redis databases as
-well as offering lower latencies to more of your users.
+`MultiRegionRatelimit` which replicates the state across multiple redis
+databases as well as offering lower latencies to more of your users.
 
-`GlobalRatelimit` does this by checking the current limit in the closest db and
-returning immediately. Only afterwards will the state be asynchronously
+`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
@@ -175,15 +227,21 @@ global latency.
 The api is the same, except for asking for multiple redis instances:
 
 ```ts
-import { GlobalRatelimit } from "@upstash/ratelimit"; // for deno: see above
+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 GlobalRatelimit({
+const ratelimit = new MultiRegionRatelimit({
   redis: [
-    new Redis({/* auth */}),
-    new Redis({/* auth */}),
-    new Redis({/* auth */}),
+    new Redis({
+      /* auth */
+    }),
+    new Redis({
+      /* auth */
+    }),
+    new Redis({
+      /* auth */
+    }),
   ],
   limiter: Ratelimit.slidingWindow(10, "10 s"),
 });
@@ -194,6 +252,29 @@ 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
@@ -275,7 +356,7 @@ const ratelimit = new Ratelimit({
 
 ### Token Bucket
 
-_Not yet supported for `GlobalRatelimit`_
+_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

package/esm/cache.js

@@ -0,0 +1,29 @@
+export class Cache {
+    constructor(cache) {
+        /**
+         * Stores identifier -> reset (in milliseconds)
+         */
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cache = cache;
+    }
+    isBlocked(identifier) {
+        if (!this.cache.has(identifier)) {
+            return { blocked: false, reset: 0 };
+        }
+        const reset = this.cache.get(identifier);
+        if (reset < Date.now()) {
+            this.cache.delete(identifier);
+            return { blocked: false, reset: 0 };
+        }
+        console.log(`[CACHE] isBlocked(${identifier}) -> true`);
+        return { blocked: true, reset: reset };
+    }
+    blockUntil(identifier, reset) {
+        this.cache.set(identifier, reset);
+    }
+}

package/esm/mod.js

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

package/esm/{global.js → multi.js}

@@ -1,13 +1,14 @@
 import { ms } from "./duration.js";
 import { Ratelimit } from "./ratelimit.js";
+import { Cache } from "./cache.js";
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
  * @example
  * ```ts
- * const { limit } = new GlobalRatelimit({
+ * const { limit } = new MultiRegionRatelimit({
  *    redis: Redis.fromEnv(),
- *    limiter: GlobalRatelimit.fixedWindow(
+ *    limiter: MultiRegionRatelimit.fixedWindow(
  *      10,     // Allow 10 requests per window of 30 minutes
  *      "30 m", // interval of 30 minutes
  *    )
@@ -15,7 +16,7 @@ import { Ratelimit } from "./ratelimit.js";
  *
  * ```
  */
-export class GlobalRatelimit extends Ratelimit {
+export class MultiRegionRatelimit extends Ratelimit {
     /**
      * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
      */
@@ -23,7 +24,10 @@ export class GlobalRatelimit extends Ratelimit {
         super({
             prefix: config.prefix,
             limiter: config.limiter,
-            ctx: { redis: config.redis },
+            ctx: {
+                redis: config.redis,
+                cache: config.ephermeralCache ? new Cache() : undefined,
+            },
         });
     }
     /**
@@ -70,6 +74,18 @@ export class GlobalRatelimit extends Ratelimit {
     return members
 `;
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const requestID = crypto.randomUUID();
             const bucket = Math.floor(Date.now() / windowDuration);
             const key = [identifier, bucket].join(":");
@@ -108,12 +124,17 @@ export class GlobalRatelimit extends Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
+            const success = remaining > 0;
+            const reset = (bucket + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (bucket + 1) * windowDuration,
+                reset,
+                pending: sync(),
             };
         };
     }
@@ -173,6 +194,18 @@ export class GlobalRatelimit extends Ratelimit {
       `;
         const windowDuration = ms(window);
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const requestID = crypto.randomUUID();
             const now = Date.now();
             const currentWindow = Math.floor(now / windowSize);
@@ -213,15 +246,17 @@ export class GlobalRatelimit extends Ratelimit {
                     await db.redis.sadd(currentKey, ...allIDs);
                 }
             }
-            /**
-             * Do not await sync. This should not run in the critical path.
-             */
-            sync();
+            const success = remaining > 0;
+            const reset = (currentWindow + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (currentWindow + 1) * windowDuration,
+                reset,
+                pending: sync(),
             };
         };
     }

package/esm/ratelimit.js

@@ -1,3 +1,4 @@
+import { Cache } from "./cache.js";
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
@@ -92,7 +93,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, 
             /**
@@ -125,5 +126,11 @@ export class Ratelimit {
         this.ctx = config.ctx;
         this.limiter = config.limiter;
         this.prefix = config.prefix ?? "@upstash/ratelimit";
+        if (config.ephermeralCache instanceof Map) {
+            this.ctx.cache = new Cache(config.ephermeralCache);
+        }
+        else if (typeof config.ephermeralCache === "undefined") {
+            this.ctx.cache = new Cache(new Map());
+        }
     }
 }

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

@@ -23,7 +23,10 @@ export class RegionRatelimit extends Ratelimit {
         super({
             prefix: config.prefix,
             limiter: config.limiter,
-            ctx: { redis: config.redis },
+            ctx: {
+                redis: config.redis,
+            },
+            ephermeralCache: config.ephermeralCache,
         });
     }
     /**
@@ -70,12 +73,30 @@ export class RegionRatelimit extends Ratelimit {
         return async function (ctx, identifier) {
             const bucket = Math.floor(Date.now() / windowDuration);
             const key = [identifier, bucket].join(":");
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const usedTokensAfterUpdate = (await ctx.redis.eval(script, [key], [windowDuration]));
+            const success = usedTokensAfterUpdate <= tokens;
+            const reset = (bucket + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: usedTokensAfterUpdate <= tokens,
+                success,
                 limit: tokens,
                 remaining: tokens - usedTokensAfterUpdate,
-                reset: (bucket + 1) * windowDuration,
+                reset,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -141,12 +162,30 @@ export class RegionRatelimit extends Ratelimit {
             const currentKey = [identifier, currentWindow].join(":");
             const previousWindow = currentWindow - windowSize;
             const previousKey = [identifier, previousWindow].join(":");
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const remaining = (await ctx.redis.eval(script, [currentKey, previousKey], [tokens, now, windowSize]));
+            const success = remaining > 0;
+            const reset = (currentWindow + 1) * windowSize;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (currentWindow + 1) * windowSize,
+                reset,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -223,10 +262,32 @@ export class RegionRatelimit extends Ratelimit {
        `;
         const intervalDuration = ms(interval);
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: maxTokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             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 };
+            const success = remaining > 0;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
+            return {
+                success,
+                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.2",
+  "version": "v0.1.4-rc.0",
   "description": "A serverless ratelimiter built on top of Upstash REST API.",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
     "size-limit": "latest"
   },
   "peerDependencies": {
-    "@upstash/redis": "^1.3.4"
+    "@upstash/redis": "^1.4.0"
   },
   "size-limit": [
     {

package/script/cache.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+class Cache {
+    constructor(cache) {
+        /**
+         * Stores identifier -> reset (in milliseconds)
+         */
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cache = cache;
+    }
+    isBlocked(identifier) {
+        if (!this.cache.has(identifier)) {
+            return { blocked: false, reset: 0 };
+        }
+        const reset = this.cache.get(identifier);
+        if (reset < Date.now()) {
+            this.cache.delete(identifier);
+            return { blocked: false, reset: 0 };
+        }
+        console.log(`[CACHE] isBlocked(${identifier}) -> true`);
+        return { blocked: true, reset: reset };
+    }
+    blockUntil(identifier, reset) {
+        this.cache.set(identifier, reset);
+    }
+}
+exports.Cache = Cache;

package/script/mod.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GlobalRatelimit = exports.Ratelimit = void 0;
-var region_js_1 = require("./region.js");
-Object.defineProperty(exports, "Ratelimit", { enumerable: true, get: function () { return region_js_1.RegionRatelimit; } });
-var global_js_1 = require("./global.js");
-Object.defineProperty(exports, "GlobalRatelimit", { enumerable: true, get: function () { return global_js_1.GlobalRatelimit; } });
+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/{global.js → multi.js}

@@ -1,16 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GlobalRatelimit = void 0;
+exports.MultiRegionRatelimit = void 0;
 const duration_js_1 = require("./duration.js");
 const ratelimit_js_1 = require("./ratelimit.js");
+const cache_js_1 = require("./cache.js");
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
  * @example
  * ```ts
- * const { limit } = new GlobalRatelimit({
+ * const { limit } = new MultiRegionRatelimit({
  *    redis: Redis.fromEnv(),
- *    limiter: GlobalRatelimit.fixedWindow(
+ *    limiter: MultiRegionRatelimit.fixedWindow(
  *      10,     // Allow 10 requests per window of 30 minutes
  *      "30 m", // interval of 30 minutes
  *    )
@@ -18,7 +19,7 @@ const ratelimit_js_1 = require("./ratelimit.js");
  *
  * ```
  */
-class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
+class MultiRegionRatelimit extends ratelimit_js_1.Ratelimit {
     /**
      * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
      */
@@ -26,7 +27,10 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
         super({
             prefix: config.prefix,
             limiter: config.limiter,
-            ctx: { redis: config.redis },
+            ctx: {
+                redis: config.redis,
+                cache: config.ephermeralCache ? new cache_js_1.Cache() : undefined,
+            },
         });
     }
     /**
@@ -73,6 +77,18 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
     return members
 `;
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const requestID = crypto.randomUUID();
             const bucket = Math.floor(Date.now() / windowDuration);
             const key = [identifier, bucket].join(":");
@@ -111,12 +127,17 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
+            const success = remaining > 0;
+            const reset = (bucket + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (bucket + 1) * windowDuration,
+                reset,
+                pending: sync(),
             };
         };
     }
@@ -176,6 +197,18 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
       `;
         const windowDuration = (0, duration_js_1.ms)(window);
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const requestID = crypto.randomUUID();
             const now = Date.now();
             const currentWindow = Math.floor(now / windowSize);
@@ -216,17 +249,19 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
                     await db.redis.sadd(currentKey, ...allIDs);
                 }
             }
-            /**
-             * Do not await sync. This should not run in the critical path.
-             */
-            sync();
+            const success = remaining > 0;
+            const reset = (currentWindow + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (currentWindow + 1) * windowDuration,
+                reset,
+                pending: sync(),
             };
         };
     }
 }
-exports.GlobalRatelimit = GlobalRatelimit;
+exports.MultiRegionRatelimit = MultiRegionRatelimit;

package/script/ratelimit.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Ratelimit = void 0;
+const cache_js_1 = require("./cache.js");
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
@@ -95,7 +96,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, 
             /**
@@ -128,6 +129,12 @@ class Ratelimit {
         this.ctx = config.ctx;
         this.limiter = config.limiter;
         this.prefix = config.prefix ?? "@upstash/ratelimit";
+        if (config.ephermeralCache instanceof Map) {
+            this.ctx.cache = new cache_js_1.Cache(config.ephermeralCache);
+        }
+        else if (typeof config.ephermeralCache === "undefined") {
+            this.ctx.cache = new cache_js_1.Cache(new Map());
+        }
     }
 }
 exports.Ratelimit = Ratelimit;

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

@@ -26,7 +26,10 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
         super({
             prefix: config.prefix,
             limiter: config.limiter,
-            ctx: { redis: config.redis },
+            ctx: {
+                redis: config.redis,
+            },
+            ephermeralCache: config.ephermeralCache,
         });
     }
     /**
@@ -73,12 +76,30 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
         return async function (ctx, identifier) {
             const bucket = Math.floor(Date.now() / windowDuration);
             const key = [identifier, bucket].join(":");
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const usedTokensAfterUpdate = (await ctx.redis.eval(script, [key], [windowDuration]));
+            const success = usedTokensAfterUpdate <= tokens;
+            const reset = (bucket + 1) * windowDuration;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: usedTokensAfterUpdate <= tokens,
+                success,
                 limit: tokens,
                 remaining: tokens - usedTokensAfterUpdate,
-                reset: (bucket + 1) * windowDuration,
+                reset,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -144,12 +165,30 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
             const currentKey = [identifier, currentWindow].join(":");
             const previousWindow = currentWindow - windowSize;
             const previousKey = [identifier, previousWindow].join(":");
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: tokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             const remaining = (await ctx.redis.eval(script, [currentKey, previousKey], [tokens, now, windowSize]));
+            const success = remaining > 0;
+            const reset = (currentWindow + 1) * windowSize;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: tokens,
                 remaining,
-                reset: (currentWindow + 1) * windowSize,
+                reset,
+                pending: Promise.resolve(),
             };
         };
     }
@@ -226,10 +265,32 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
        `;
         const intervalDuration = (0, duration_js_1.ms)(interval);
         return async function (ctx, identifier) {
+            if (ctx.cache) {
+                const { blocked, reset } = ctx.cache.isBlocked(identifier);
+                if (blocked) {
+                    return {
+                        success: false,
+                        limit: maxTokens,
+                        remaining: 0,
+                        reset: reset,
+                        pending: Promise.resolve(),
+                    };
+                }
+            }
             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 };
+            const success = remaining > 0;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
+            return {
+                success,
+                limit: maxTokens,
+                remaining,
+                reset,
+                pending: Promise.resolve(),
+            };
         };
     }
 }

package/types/cache.d.ts

@@ -0,0 +1,13 @@
+import { EphermeralCache } from "./types.js";
+export declare class Cache implements EphermeralCache {
+    /**
+     * Stores identifier -> reset (in milliseconds)
+     */
+    private readonly cache;
+    constructor(cache: Map<string, number>);
+    isBlocked(identifier: string): {
+        blocked: boolean;
+        reset: number;
+    };
+    blockUntil(identifier: string, reset: number): void;
+}

package/types/mod.d.ts

@@ -1,5 +1,5 @@
-export { RegionRatelimit as Ratelimit } from "./region.js";
-export type { RegionRatelimitConfig as RatelimitConfig } from "./region.js";
-export { GlobalRatelimit } from "./global.js";
-export type { GlobalRatelimitConfig } from "./global.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/{global.d.ts → multi.d.ts}

@@ -1,8 +1,8 @@
 import type { Duration } from "./duration.js";
-import type { Algorithm, GlobalContext } from "./types.js";
+import type { Algorithm, MultiRegionContext } from "./types.js";
 import { Ratelimit } from "./ratelimit.js";
 import type { Redis } from "./types.js";
-export declare type GlobalRatelimitConfig = {
+export declare type MultiRegionRatelimitConfig = {
     /**
      * Instances of `@upstash/redis`
      * @see https://github.com/upstash/upstash-redis#quick-start
@@ -13,24 +13,41 @@ export declare type GlobalRatelimitConfig = {
      *
      * Choose one of the predefined ones or implement your own.
      * Available algorithms are exposed via static methods:
-     * - GlobalRatelimit.fixedWindow
+     * - MultiRegionRatelimit.fixedWindow
      */
-    limiter: Algorithm<GlobalContext>;
+    limiter: Algorithm<MultiRegionContext>;
     /**
      * All keys in redis are prefixed with this.
      *
      * @default `@upstash/ratelimit`
      */
     prefix?: string;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter instance outside of your handler function. While the
+     * function is still hot, the ratelimiter can block requests without having to
+     * request data from redis, thus saving time and money.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * Set to `false` to disable.
+     *
+     * If left undefined, a map is created automatically, but it can only work
+     * if the map or th ratelimit instance is created outside your serverless function handler.
+     */
+    ephermeralCache?: Map<string, number> | false;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
  * @example
  * ```ts
- * const { limit } = new GlobalRatelimit({
+ * const { limit } = new MultiRegionRatelimit({
  *    redis: Redis.fromEnv(),
- *    limiter: GlobalRatelimit.fixedWindow(
+ *    limiter: MultiRegionRatelimit.fixedWindow(
  *      10,     // Allow 10 requests per window of 30 minutes
  *      "30 m", // interval of 30 minutes
  *    )
@@ -38,11 +55,11 @@ export declare type GlobalRatelimitConfig = {
  *
  * ```
  */
-export declare class GlobalRatelimit extends Ratelimit<GlobalContext> {
+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: GlobalRatelimitConfig);
+    constructor(config: MultiRegionRatelimitConfig);
     /**
      * Each requests inside a fixed time increases a counter.
      * Once the counter reaches a maxmimum allowed number, all further requests are
@@ -69,7 +86,7 @@ export declare class GlobalRatelimit extends Ratelimit<GlobalContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<GlobalContext>;
+    window: Duration): Algorithm<MultiRegionContext>;
     /**
      * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
      * costs than `slidingLogs` and improved boundary behavior by calcualting a
@@ -94,5 +111,5 @@ export declare class GlobalRatelimit extends Ratelimit<GlobalContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<GlobalContext>;
+    window: Duration): Algorithm<MultiRegionContext>;
 }

package/types/ratelimit.d.ts

@@ -18,6 +18,23 @@ export declare type RatelimitConfig<TContext> = {
      * @default `@upstash/ratelimit`
      */
     prefix?: string;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter instance outside of your handler function. While the
+     * function is still hot, the ratelimiter can block requests without having to
+     * request data from redis, thus saving time and money.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * Set to `false` to disable.
+     *
+     * If left undefined, a map is created automatically, but it can only work
+     * if the map or the  ratelimit instance is created outside your serverless function handler.
+     */
+    ephermeralCache?: Map<string, number> | false;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/types/{region.d.ts → single.d.ts}

@@ -25,6 +25,23 @@ export declare type RegionRatelimitConfig = {
      * @default `@upstash/ratelimit`
      */
     prefix?: string;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter instance outside of your handler function. While the
+     * function is still hot, the ratelimiter can block requests without having to
+     * request data from redis, thus saving time and money.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * Set to `false` to disable.
+     *
+     * If left undefined, a map is created automatically, but it can only work
+     * if the map or the ratelimit instance is created outside your serverless function handler.
+     */
+    ephermeralCache?: Map<string, number> | false;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/types/types.d.ts

@@ -2,13 +2,25 @@ export interface Redis {
     eval: (script: string, keys: string[], values: unknown[]) => Promise<unknown>;
     sadd: (key: string, ...members: string[]) => Promise<number>;
 }
+/**
+ * EphermeralCache is used to block certain identifiers right away in case they have already exceedd the ratelimit.
+ */
+export interface EphermeralCache {
+    isBlocked: (identifier: string) => {
+        blocked: boolean;
+        reset: number;
+    };
+    blockUntil: (identifier: string, reset: number) => void;
+}
 export declare type RegionContext = {
     redis: Redis;
+    cache?: EphermeralCache;
 };
-export declare type GlobalContext = {
+export declare type MultiRegionContext = {
     redis: Redis[];
+    cache?: EphermeralCache;
 };
-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 +38,30 @@ 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>;
+export declare type Algorithm<TContext> = (ctx: TContext, identifier: string, opts?: {
+    cache?: EphermeralCache;
+}) => Promise<RatelimitResponse>;