@upstash/ratelimit 0.1.3 → 0.1.4

package/.releaserc

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

package/README.md

@@ -1,12 +1,10 @@
-# Upstash Ratelimit
-
-An HTTP/REST based Redis client built on top of Upstash REST API.
-[Upstash REST API](https://docs.upstash.com/features/restapi).
+# Upstash RateLimit
 
 [![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)
 
-It is the only connectionless (HTTP based) ratelimiter and designed for:
+It is the only connectionless (HTTP based) rate limiting library and designed
+for:
 
 - Serverless functions (AWS Lambda ...)
 - Cloudflare Workers
@@ -18,6 +16,7 @@ It is the only connectionless (HTTP based) ratelimiter and designed for:
 
 <!-- toc -->
 
+- [Docs](#docs)
 - [Quick Start](#quick-start)
   - [Install](#install)
     - [npm](#npm)
@@ -25,8 +24,10 @@ 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)
+  - [Ephemeral Cache](#ephemeral-cache)
+- [MultiRegion replicated ratelimiting](#multiregion-replicated-ratelimiting)
   - [Usage](#usage)
+  - [Asynchronous synchronization between databases](#asynchronous-synchronization-between-databases)
   - [Example](#example)
 - [Ratelimiting algorithms](#ratelimiting-algorithms)
   - [Fixed Window](#fixed-window)
@@ -48,6 +49,10 @@ It is the only connectionless (HTTP based) ratelimiter and designed for:
 
 <!-- tocstop -->
 
+## Docs
+
+[doc.deno.land](https://doc.deno.land/https://deno.land/x/upstash_ratelimit/src/mod.ts)
+
 ## Quick Start
 
 ### Install
@@ -176,11 +181,37 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
-## MultiRegionly 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 it should be blocked because
+they have exceeded the limit.
+
+You can use an ephemeral in memory cache by passing the `ephemeralCache` option:
+
+```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 their
+reset timestamps, that have exhausted their ratelimit. In serverless
+environments this is only possible if you create the cache or 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.
+
+## MultiRegion 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
+Using a single redis instance has the downside of providing low latencies only
+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
@@ -247,7 +278,7 @@ 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
+create 2 regional redis databases on [Upstash](https://console.upstash.com) and
 your users will enjoy the latency of whichever db is closest to them.
 
 ## Ratelimiting algorithms

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,12 @@ 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(config.ephermeralCache)
+                    : undefined,
+            },
         });
     }
     /**
@@ -70,6 +76,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 +126,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 +196,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 +248,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(),
             };
         };
@@ -164,8 +201,6 @@ export class RegionRatelimit extends Ratelimit {
      * rate.
      * - Allows to set a higher initial burst limit by setting `maxTokens` higher
      * than `refillRate`
-     *
-     * **Usage of Upstash Redis requests:**
      */
     static tokenBucket(
     /**
@@ -225,11 +260,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",
+  "version": "v0.1.4",
   "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,12 @@ 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(config.ephermeralCache)
+                    : undefined,
+            },
         });
     }
     /**
@@ -73,6 +79,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 +129,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 +199,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 +251,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(),
             };
         };
@@ -167,8 +204,6 @@ class RegionRatelimit extends ratelimit_js_1.Ratelimit {
      * rate.
      * - Allows to set a higher initial burst limit by setting `maxTokens` higher
      * than `refillRate`
-     *
-     * **Usage of Upstash Redis requests:**
      */
     static tokenBucket(
     /**
@@ -228,11 +263,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/
@@ -110,8 +127,6 @@ export declare class RegionRatelimit extends Ratelimit<RegionContext> {
      * rate.
      * - Allows to set a higher initial burst limit by setting `maxTokens` higher
      * than `refillRate`
-     *
-     * **Usage of Upstash Redis requests:**
      */
     static tokenBucket(
     /**

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>;