@upstash/ratelimit 0.1.2 → 0.1.3-rc.0

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).
@@ -155,15 +155,15 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
-## Globally replicated ratelimiting
+## 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,11 +175,11 @@ 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 */}),
@@ -275,7 +275,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/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}

@@ -5,9 +5,9 @@ import { Ratelimit } from "./ratelimit.js";
  *
  * @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 +15,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.
      */
@@ -108,12 +108,12 @@ export class GlobalRatelimit extends Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
             return {
                 success: remaining > 0,
                 limit: tokens,
                 remaining,
                 reset: (bucket + 1) * windowDuration,
+                pending: sync(),
             };
         };
     }
@@ -216,12 +216,12 @@ export class GlobalRatelimit extends Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
             return {
                 success: remaining > 0,
                 limit: tokens,
                 remaining,
                 reset: (currentWindow + 1) * windowDuration,
+                pending: sync(),
             };
         };
     }

package/esm/ratelimit.js

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

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

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

package/package.json

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

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,6 +1,6 @@
 "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");
 /**
@@ -8,9 +8,9 @@ const ratelimit_js_1 = require("./ratelimit.js");
  *
  * @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 +18,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.
      */
@@ -111,12 +111,12 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
             return {
                 success: remaining > 0,
                 limit: tokens,
                 remaining,
                 reset: (bucket + 1) * windowDuration,
+                pending: sync(),
             };
         };
     }
@@ -219,14 +219,14 @@ class GlobalRatelimit extends ratelimit_js_1.Ratelimit {
             /**
              * Do not await sync. This should not run in the critical path.
              */
-            sync();
             return {
                 success: remaining > 0,
                 limit: tokens,
                 remaining,
                 reset: (currentWindow + 1) * windowDuration,
+                pending: sync(),
             };
         };
     }
 }
-exports.GlobalRatelimit = GlobalRatelimit;
+exports.MultiRegionRatelimit = MultiRegionRatelimit;

package/script/ratelimit.js

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

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

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

package/types/mod.d.ts

@@ -1,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,9 +13,9 @@ 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.
      *
@@ -28,9 +28,9 @@ export declare type GlobalRatelimitConfig = {
  *
  * @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 +38,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 +69,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 +94,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/types.d.ts

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