@upstash/ratelimit 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "module": "./esm/mod.js",
+  "main": "./script/mod.js",
+  "types": "./types/mod.d.ts",
+  "name": "@upstash/ratelimit",
+  "version": "v0.1.0-alpha.0",
+  "description": "A serverless ratelimiter built on top of Upstash REST API.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/upstash/ratelimiter.git"
+  },
+  "keywords": [
+    "rate",
+    "limit",
+    "redis",
+    "serverless",
+    "edge",
+    "upstash"
+  ],
+  "author": "Andreas Thomas <andreas.thomas@chronark.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/upstash/ratelimiter/issues"
+  },
+  "homepage": "https://github.com/upstash/ratelimiter#readme",
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "latest",
+    "@upstash/redis": "1.3.3-alpha.1",
+    "size-limit": "latest"
+  },
+  "peerDependencies": {
+    "@upstash/redis": "1.3.3-alpha.1"
+  },
+  "size-limit": [
+    {
+      "path": "esm/mod.js",
+      "limit": "2 KB"
+    },
+    {
+      "path": "script/mod.js",
+      "limit": "52 KB"
+    }
+  ],
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js",
+      "types": "./types/mod.d.ts"
+    }
+  }
+}

package/script/duration.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ms = void 0;
+/**
+ * Convert a human readable duration to milliseconds
+ */
+function ms(d) {
+    const [timeString, duration] = d.split(" ");
+    const time = parseFloat(timeString);
+    switch (duration) {
+        case "ms":
+            return time;
+        case "s":
+            return time * 1000;
+        case "m":
+            return time * 1000 * 60;
+        case "h":
+            return time * 1000 * 60 * 60;
+        case "d":
+            return time * 1000 * 60 * 60 * 24;
+        default:
+            throw new Error(`Unable to parse window size: ${d}`);
+    }
+}
+exports.ms = ms;

package/script/mod.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ratelimiter.js"), exports);
+__exportStar(require("./types.js"), exports);

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/ratelimiter.js

@@ -0,0 +1,388 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ratelimit = void 0;
+const duration_js_1 = require("./duration.js");
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new Ratelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: Ratelimit.slidingWindow(
+ *      "30 m", // interval of 30 minutes
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+class Ratelimit {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config) {
+        Object.defineProperty(this, "redis", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "limiter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "prefix", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
+         *
+         * Use this if you want to reject all requests that you can not handle right now.
+         *
+         * @example
+         * ```ts
+         *  const ratelimit = new Ratelimit({
+         *    redis: Redis.fromEnv(),
+         *    limiter: Ratelimit.slidingWindow(10, "10 s")
+         *  })
+         *
+         *  const { success } = await ratelimit.limit(id)
+         *  if (!success){
+         *    return "Nope"
+         *  }
+         *  return "Yes"
+         * ```
+         */
+        Object.defineProperty(this, "limit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (identifier) => {
+                const key = [this.prefix, identifier].join(":");
+                return await this.limiter({ redis: this.redis }, key);
+            }
+        });
+        /**
+         * Block until the request may pass or timeout is reached.
+         *
+         * This method returns a promsie that resolves as soon as the request may be processed
+         * or after the timeoue has been reached.
+         *
+         * Use this if you want to delay the request until it is ready to get processed.
+         *
+         * @example
+         * ```ts
+         *  const ratelimit = new Ratelimit({
+         *    redis: Redis.fromEnv(),
+         *    limiter: Ratelimit.slidingWindow(10, "10 s")
+         *  })
+         *
+         *  const { success } = await ratelimit.blockUntilReady(id, 60_000)
+         *  if (!success){
+         *    return "Nope"
+         *  }
+         *  return "Yes"
+         * ```
+         */
+        Object.defineProperty(this, "blockUntilReady", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (
+            /**
+             * 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.
+             */
+            identifier, 
+            /**
+             * Maximum duration to wait in milliseconds.
+             * After this time the request will be denied.
+             */
+            timeout) => {
+                if (timeout <= 0) {
+                    throw new Error("timeout must be positive");
+                }
+                let res;
+                const deadline = Date.now() + timeout;
+                while (true) {
+                    res = await this.limit(identifier);
+                    if (res.success) {
+                        break;
+                    }
+                    if (res.reset === 0) {
+                        throw new Error("This should not happen");
+                    }
+                    const wait = Math.min(res.reset, deadline) - Date.now();
+                    await new Promise((r) => setTimeout(r, wait));
+                    if (Date.now() > deadline) {
+                        break;
+                    }
+                }
+                return res;
+            }
+        });
+        this.redis = config.redis;
+        this.limiter = config.limiter;
+        this.prefix = config.prefix ?? "@upstash/ratelimit";
+    }
+    /**
+     * Each requests inside a fixed time increases a counter.
+     * Once the counter reaches a maxmimum allowed number, all further requests are
+     * rejected.
+     *
+     * **Pro:**
+     *
+     * - Newer requests are not starved by old ones.
+     * - Low storage cost.
+     *
+     * **Con:**
+     *
+     * A burst of requests near the boundary of a window can result in a very
+     * high request rate because two windows will be filled with requests quickly.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - A fixed timeframe
+     */
+    static fixedWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowDuration = (0, duration_js_1.ms)(window);
+        const script = `
+    local key     = KEYS[1]
+    local window  = ARGV[1]
+    
+    local r = redis.call("INCR", key)
+    if r == 1 then 
+    -- The first time this key is set, the value will be 1.
+    -- So we only need the expire command once
+    redis.call("PEXPIRE", key, window)
+    end
+    
+    return r
+    `;
+        return async function (ctx, identifier) {
+            const bucket = Math.floor(Date.now() / windowDuration);
+            const key = [identifier, bucket].join(":");
+            const usedTokensAfterUpdate = (await ctx.redis.eval(script, [key], [windowDuration]));
+            return {
+                success: usedTokensAfterUpdate <= tokens,
+                limit: tokens,
+                remaining: tokens - usedTokensAfterUpdate,
+                reset: (bucket + 1) * windowDuration,
+            };
+        };
+    }
+    // /**
+    //  * For each request all past requests in the last `{window}` are summed up and
+    //  * if they exceed `{tokens}`, the request will be rejected.
+    //  *
+    //  * **Pro:**
+    //  *
+    //  * Does not have the problem of `fixedWindow` at the window boundaries.
+    //  *
+    //  * **Con:**
+    //  *
+    //  * More expensive to store and compute, which makes this unsuitable for apis
+    //  * with very high traffic.
+    //  *
+    //  * @param window - The duration in which the user can max X requests.
+    //  * @param tokens - How many requests a user can make in each time window.
+    //  */
+    // static slidingLogs(window: Duration, tokens: number): Ratelimiter {
+    //   const script = `
+    //   local key         = KEYS[1] -- identifier including prefixes
+    //   local windowStart = ARGV[1] -- timestamp of window start
+    //   local windowEnd   = ARGV[2] -- timestamp of window end
+    //   local tokens      = ARGV[3] -- tokens per window
+    //   local now         = ARGV[4] -- current timestamp
+    //   local count = redis.call("ZCOUNT", key, windowStart, windowEnd)
+    //   if count < tonumber(tokens) then
+    //     -- Log the current request
+    //     redis.call("ZADD", key, now, now)
+    //     -- Remove all previous requests that are outside the window
+    //     redis.call("ZREMRANGEBYSCORE", key, "-inf", windowStart - 1)
+    //   end
+    //   return count
+    //   `;
+    //   return async function (ctx: Context, identifier: string) {
+    //     const windowEnd = Date.now();
+    //     const windowStart = windowEnd - ms(window);
+    //     const count = (await ctx.redis.eval(
+    //       script,
+    //       [identifier],
+    //       [windowStart, windowEnd, tokens, Date.now()]
+    //     )) as number;
+    //     return {
+    //       success: count < tokens,
+    //       limit: tokens,
+    //       remaining: Math.max(0, tokens - count - 1),
+    //       reset: windowEnd,
+    //     };
+    //   };
+    // }
+    /**
+     * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+     * costs than `slidingLogs` and improved boundary behavior by calcualting a
+     * weighted score between two windows.
+     *
+     * **Pro:**
+     *
+     * Good performance allows this to scale to very high loads.
+     *
+     * **Con:**
+     *
+     * Nothing major.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - The duration in which the user can max X requests.
+     */
+    static slidingWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const script = `
+      local currentKey  = KEYS[1]           -- identifier including prefixes
+      local previousKey = KEYS[2]           -- key of the previous bucket
+      local tokens      = tonumber(ARGV[1]) -- tokens per window
+      local now         = ARGV[2]           -- current timestamp in milliseconds
+      local window      = ARGV[3]           -- interval in milliseconds
+
+      local requestsInCurrentWindow = redis.call("GET", currentKey)
+      if requestsInCurrentWindow == false then
+        requestsInCurrentWindow = 0
+      end
+
+
+      local requestsInPreviousWindow = redis.call("GET", previousKey)
+      if requestsInPreviousWindow == false then
+        requestsInPreviousWindow = 0
+      end
+      local percentageInCurrent = ( now % window) / window
+      if requestsInPreviousWindow * ( 1 - percentageInCurrent ) + requestsInCurrentWindow >= tokens then
+        return 0
+      end
+
+      local newValue = redis.call("INCR", currentKey)
+      if newValue == 1 then 
+        -- The first time this key is set, the value will be 1.
+        -- So we only need the expire command once
+        redis.call("PEXPIRE", currentKey, window * 2 + 1000) -- Enough time to overlap with a new window + 1 second
+      end
+      return tokens - newValue
+      `;
+        const windowSize = (0, duration_js_1.ms)(window);
+        return async function (ctx, identifier) {
+            const now = Date.now();
+            const currentWindow = Math.floor(now / windowSize);
+            const currentKey = [identifier, currentWindow].join(":");
+            const previousWindow = currentWindow - windowSize;
+            const previousKey = [identifier, previousWindow].join(":");
+            const remaining = (await ctx.redis.eval(script, [currentKey, previousKey], [tokens, now, windowSize]));
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (currentWindow + 1) * windowSize,
+            };
+        };
+    }
+    /**
+     * You have a bucket filled with `{maxTokens}` tokens that refills constantly
+     * at `{refillRate}` per `{interval}`.
+     * Every request will remove one token from the bucket and if there is no
+     * token to take, the request is rejected.
+     *
+     * **Pro:**
+     *
+     * - Bursts of requests are smoothed out and you can process them at a constant
+     * rate.
+     * - Allows to set a higher initial burst limit by setting `maxTokens` higher
+     * than `refillRate`
+     *
+     * **Usage of Upstash Redis requests:**
+     */
+    static tokenBucket(
+    /**
+     * How many tokens are refilled per `interval`
+     *
+     * An interval of `10s` and refillRate of 5 will cause a new token to be added every 2 seconds.
+     */
+    refillRate, 
+    /**
+     * The interval for the `refillRate`
+     */
+    interval, 
+    /**
+     * Maximum number of tokens.
+     * A newly created bucket starts with this many tokens.
+     * Useful to allow higher burst limits.
+     */
+    maxTokens) {
+        const script = `
+        local key         = KEYS[1]           -- identifier including prefixes
+        local maxTokens   = tonumber(ARGV[1]) -- maximum number of tokens
+        local interval    = tonumber(ARGV[2]) -- size of the window in milliseconds
+        local refillRate  = tonumber(ARGV[3]) -- how many tokens are refilled after each interval
+        local now         = tonumber(ARGV[4]) -- current timestamp in milliseconds
+        local remaining   = 0
+        
+        local bucket = redis.call("HMGET", key, "updatedAt", "tokens")
+        
+        if bucket[1] == false then
+          -- The bucket does not exist yet, so we create it and add a ttl.
+          remaining = maxTokens - 1
+          
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+          redis.call("PEXPIRE", key, interval)
+  
+          return {remaining, now + interval}
+        end
+
+        -- The bucket does exist
+  
+        local updatedAt = tonumber(bucket[1])
+        local tokens = tonumber(bucket[2])
+  
+        if now >= updatedAt + interval then
+          remaining = math.min(maxTokens, tokens + refillRate) - 1
+          
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+          return {remaining, now + interval}
+        end
+  
+        if tokens > 0 then
+          remaining = tokens - 1
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+        end
+  
+        return {remaining, updatedAt + interval}
+       `;
+        const intervalDuration = (0, duration_js_1.ms)(interval);
+        return async function (ctx, identifier) {
+            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 };
+        };
+    }
+}
+exports.Ratelimit = Ratelimit;

package/script/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/duration.d.ts

@@ -0,0 +1,7 @@
+declare type Unit = "ms" | "s" | "m" | "h" | "d";
+export declare type Duration = `${number} ${Unit}`;
+/**
+ * Convert a human readable duration to milliseconds
+ */
+export declare function ms(d: Duration): number;
+export {};

package/types/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./ratelimiter.js";
+export * from "./types.js";

package/types/ratelimiter.d.ts

@@ -0,0 +1,177 @@
+import type { Duration } from "./duration.js";
+import type { Ratelimiter, RatelimitResponse, Redis } from "./types.js";
+export declare type RatelimitConfig = {
+    /**
+     * Instance of `@upstash/redis`
+     * @see https://github.com/upstash/upstash-redis#quick-start
+     */
+    redis: Redis;
+    /**
+     * The ratelimiter function to use.
+     *
+     * Choose one of the predefined ones or implement your own.
+     * Available algorithms are exposed via static methods:
+     * - Ratelimiter.fixedWindow
+     * - Ratelimiter.slidingLogs
+     * - Ratelimiter.slidingWindow
+     * - Ratelimiter.tokenBucket
+     */
+    limiter: Ratelimiter;
+    /**
+     * All keys in redis are prefixed with this.
+     *
+     * @default `@upstash/ratelimit`
+     */
+    prefix?: string;
+};
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new Ratelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: Ratelimit.slidingWindow(
+ *      "30 m", // interval of 30 minutes
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+export declare class Ratelimit {
+    private readonly redis;
+    private readonly limiter;
+    private readonly prefix;
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config: RatelimitConfig);
+    /**
+     * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
+     *
+     * Use this if you want to reject all requests that you can not handle right now.
+     *
+     * @example
+     * ```ts
+     *  const ratelimit = new Ratelimit({
+     *    redis: Redis.fromEnv(),
+     *    limiter: Ratelimit.slidingWindow(10, "10 s")
+     *  })
+     *
+     *  const { success } = await ratelimit.limit(id)
+     *  if (!success){
+     *    return "Nope"
+     *  }
+     *  return "Yes"
+     * ```
+     */
+    limit: (identifier: string) => Promise<RatelimitResponse>;
+    /**
+     * Block until the request may pass or timeout is reached.
+     *
+     * This method returns a promsie that resolves as soon as the request may be processed
+     * or after the timeoue has been reached.
+     *
+     * Use this if you want to delay the request until it is ready to get processed.
+     *
+     * @example
+     * ```ts
+     *  const ratelimit = new Ratelimit({
+     *    redis: Redis.fromEnv(),
+     *    limiter: Ratelimit.slidingWindow(10, "10 s")
+     *  })
+     *
+     *  const { success } = await ratelimit.blockUntilReady(id, 60_000)
+     *  if (!success){
+     *    return "Nope"
+     *  }
+     *  return "Yes"
+     * ```
+     */
+    blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
+    /**
+     * Each requests inside a fixed time increases a counter.
+     * Once the counter reaches a maxmimum allowed number, all further requests are
+     * rejected.
+     *
+     * **Pro:**
+     *
+     * - Newer requests are not starved by old ones.
+     * - Low storage cost.
+     *
+     * **Con:**
+     *
+     * A burst of requests near the boundary of a window can result in a very
+     * high request rate because two windows will be filled with requests quickly.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - A fixed timeframe
+     */
+    static fixedWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens: number, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window: Duration): Ratelimiter;
+    /**
+     * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+     * costs than `slidingLogs` and improved boundary behavior by calcualting a
+     * weighted score between two windows.
+     *
+     * **Pro:**
+     *
+     * Good performance allows this to scale to very high loads.
+     *
+     * **Con:**
+     *
+     * Nothing major.
+     *
+     * @param tokens - How many requests a user can make in each time window.
+     * @param window - The duration in which the user can max X requests.
+     */
+    static slidingWindow(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens: number, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window: Duration): Ratelimiter;
+    /**
+     * You have a bucket filled with `{maxTokens}` tokens that refills constantly
+     * at `{refillRate}` per `{interval}`.
+     * Every request will remove one token from the bucket and if there is no
+     * token to take, the request is rejected.
+     *
+     * **Pro:**
+     *
+     * - Bursts of requests are smoothed out and you can process them at a constant
+     * rate.
+     * - Allows to set a higher initial burst limit by setting `maxTokens` higher
+     * than `refillRate`
+     *
+     * **Usage of Upstash Redis requests:**
+     */
+    static tokenBucket(
+    /**
+     * How many tokens are refilled per `interval`
+     *
+     * An interval of `10s` and refillRate of 5 will cause a new token to be added every 2 seconds.
+     */
+    refillRate: number, 
+    /**
+     * The interval for the `refillRate`
+     */
+    interval: Duration, 
+    /**
+     * Maximum number of tokens.
+     * A newly created bucket starts with this many tokens.
+     * Useful to allow higher burst limits.
+     */
+    maxTokens: number): Ratelimiter;
+}