@upstash/ratelimit 0.1.3-rc.0 → 0.1.4-rc.1

package/.releaserc

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

package/README.md

@@ -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,6 +177,36 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
+### 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
@@ -181,9 +233,15 @@ 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 */}),
+    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

package/esm/cache.js

@@ -0,0 +1,28 @@
+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 };
+        }
+        return { blocked: true, reset: reset };
+    }
+    blockUntil(identifier, reset) {
+        this.cache.set(identifier, reset);
+    }
+}

package/esm/multi.js

@@ -1,5 +1,6 @@
 import { ms } from "./duration.js";
 import { Ratelimit } from "./ratelimit.js";
+import { Cache } from "./cache.js";
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
  *
@@ -23,7 +24,10 @@ export class MultiRegionRatelimit 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 MultiRegionRatelimit 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,11 +124,16 @@ export class MultiRegionRatelimit extends Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
+            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 MultiRegionRatelimit 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,14 +246,16 @@ export class MultiRegionRatelimit extends Ratelimit {
                     await db.redis.sadd(currentKey, ...allIDs);
                 }
             }
-            /**
-             * Do not await sync. This should not run in the critical path.
-             */
+            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/
  *
@@ -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/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,29 @@ 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(),
             };
         };
@@ -142,12 +162,29 @@ 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(),
             };
         };
@@ -225,11 +262,27 @@ 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]));
+            const success = remaining > 0;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: maxTokens,
                 remaining,
                 reset,

package/package.json

@@ -3,7 +3,7 @@
   "main": "./script/mod.js",
   "types": "./types/mod.d.ts",
   "name": "@upstash/ratelimit",
-  "version": "v0.1.3-rc.0",
+  "version": "v0.1.4-rc.1",
   "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,32 @@
+"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 };
+        }
+        return { blocked: true, reset: reset };
+    }
+    blockUntil(identifier, reset) {
+        this.cache.set(identifier, reset);
+    }
+}
+exports.Cache = Cache;

package/script/multi.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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/
  *
@@ -26,7 +27,10 @@ class MultiRegionRatelimit 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 MultiRegionRatelimit 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,11 +127,16 @@ class MultiRegionRatelimit extends ratelimit_js_1.Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
+            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 MultiRegionRatelimit 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,14 +249,16 @@ class MultiRegionRatelimit extends ratelimit_js_1.Ratelimit {
                     await db.redis.sadd(currentKey, ...allIDs);
                 }
             }
-            /**
-             * Do not await sync. This should not run in the critical path.
-             */
+            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/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/
  *
@@ -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/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,29 @@ 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(),
             };
         };
@@ -145,12 +165,29 @@ 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(),
             };
         };
@@ -228,11 +265,27 @@ 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]));
+            const success = remaining > 0;
+            if (ctx.cache && !success) {
+                ctx.cache.blockUntil(identifier, reset);
+            }
             return {
-                success: remaining > 0,
+                success,
                 limit: maxTokens,
                 remaining,
                 reset,

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/multi.d.ts

@@ -22,6 +22,23 @@ export declare type MultiRegionRatelimitConfig = {
      * @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/

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/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,11 +2,23 @@ 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 MultiRegionContext = {
     redis: Redis[];
+    cache?: EphermeralCache;
 };
 export declare type Context = RegionContext | MultiRegionContext;
 export declare type RatelimitResponse = {
@@ -50,4 +62,6 @@ export declare type RatelimitResponse = {
      */
     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>;