@upstash/ratelimit 0.2.0 → 0.3.0-canary.0

package/script/single.js

@@ -1,379 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RegionRatelimit = void 0;
-const duration_js_1 = require("./duration.js");
-const ratelimit_js_1 = require("./ratelimit.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 RegionRatelimit extends ratelimit_js_1.Ratelimit {
-    /**
-     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
-     */
-    constructor(config) {
-        super({
-            prefix: config.prefix,
-            limiter: config.limiter,
-            timeout: config.timeout,
-            ctx: {
-                redis: config.redis,
-            },
-            ephemeralCache: config.ephemeralCache,
-        });
-    }
-    /**
-     * 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(":");
-            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,
-                limit: tokens,
-                remaining: tokens - usedTokensAfterUpdate,
-                reset,
-                pending: Promise.resolve(),
-            };
-        };
-    }
-    /**
-     * 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(":");
-            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,
-                limit: tokens,
-                remaining,
-                reset,
-                pending: Promise.resolve(),
-            };
-        };
-    }
-    /**
-     * 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`
-     */
-    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) {
-            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,
-                limit: maxTokens,
-                remaining,
-                reset,
-                pending: Promise.resolve(),
-            };
-        };
-    }
-    /**
-     * cachedFixedWindow first uses the local cache to decide if a request may pass and then updates
-     * it asynchronously.
-     * This is experimental and not yet recommended for production use.
-     *
-     * @experimental
-     *
-     * 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 cachedFixedWindow(
-    /**
-     * 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) {
-            if (!ctx.cache) {
-                throw new Error("This algorithm requires a cache");
-            }
-            const bucket = Math.floor(Date.now() / windowDuration);
-            const key = [identifier, bucket].join(":");
-            const reset = (bucket + 1) * windowDuration;
-            const hit = typeof ctx.cache.get(key) === "number";
-            if (hit) {
-                const cachedTokensAfterUpdate = ctx.cache.incr(key);
-                const success = cachedTokensAfterUpdate < tokens;
-                const pending = success
-                    ? ctx.redis.eval(script, [key], [windowDuration]).then((t) => {
-                        ctx.cache.set(key, t);
-                    })
-                    : Promise.resolve();
-                return {
-                    success,
-                    limit: tokens,
-                    remaining: tokens - cachedTokensAfterUpdate,
-                    reset: reset,
-                    pending,
-                };
-            }
-            const usedTokensAfterUpdate = (await ctx.redis.eval(script, [key], [windowDuration]));
-            ctx.cache.set(key, usedTokensAfterUpdate);
-            const remaining = tokens - usedTokensAfterUpdate;
-            return {
-                success: remaining >= 0,
-                limit: tokens,
-                remaining,
-                reset: reset,
-                pending: Promise.resolve(),
-            };
-        };
-    }
-}
-exports.RegionRatelimit = RegionRatelimit;

package/script/types.js

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

package/types/_dnt.shims.d.ts

@@ -1,5 +0,0 @@
-export { crypto, type Crypto, type SubtleCrypto, type AlgorithmIdentifier, type Algorithm, type RsaOaepParams, type BufferSource, type AesCtrParams, type AesCbcParams, type AesGcmParams, type CryptoKey, type KeyAlgorithm, type KeyType, type KeyUsage, type EcdhKeyDeriveParams, type HkdfParams, type HashAlgorithmIdentifier, type Pbkdf2Params, type AesDerivedKeyParams, type HmacImportParams, type JsonWebKey, type RsaOtherPrimesInfo, type KeyFormat, type RsaHashedKeyGenParams, type RsaKeyGenParams, type BigInteger, type EcKeyGenParams, type NamedCurve, type CryptoKeyPair, type AesKeyGenParams, type HmacKeyGenParams, type RsaHashedImportParams, type EcKeyImportParams, type AesKeyAlgorithm, type RsaPssParams, type EcdsaParams } from "@deno/shim-crypto";
-export {} from "@types/node";
-export declare const dntGlobalThis: Omit<typeof globalThis, "crypto"> & {
-    crypto: import("@deno/shim-crypto").Crypto;
-};

package/types/cache.d.ts

@@ -1,16 +0,0 @@
-import { EphemeralCache } from "./types.js";
-export declare class Cache implements EphemeralCache {
-    /**
-     * 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;
-    set(key: string, value: number): void;
-    get(key: string): number | null;
-    incr(key: string): number;
-}

package/types/duration.d.ts

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

package/types/mod.d.ts

@@ -1,5 +0,0 @@
-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/multi.d.ts

@@ -1,121 +0,0 @@
-import type { Duration } from "./duration.js";
-import type { Algorithm, MultiRegionContext } from "./types.js";
-import { Ratelimit } from "./ratelimit.js";
-import type { Redis } from "./types.js";
-export type MultiRegionRatelimitConfig = {
-    /**
-     * Instances 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:
-     * - MultiRegionRatelimit.fixedWindow
-     */
-    limiter: Algorithm<MultiRegionContext>;
-    /**
-     * All keys in redis are prefixed with this.
-     *
-     * @default `@upstash/ratelimit`
-     */
-    prefix?: string;
-    /**
-     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
-     * exhausted their ratelimit. In serverless environments this is only possible if
-     * you create the ratelimiter instance outside of your handler function. While the
-     * function is still hot, the ratelimiter can block requests without having to
-     * request data from redis, thus saving time and money.
-     *
-     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
-     * internal list together with its reset timestamp. If the same identifier makes a
-     * new request before it is reset, we can immediately reject it.
-     *
-     * Set to `false` to disable.
-     *
-     * If left undefined, a map is created automatically, but it can only work
-     * if the map or th ratelimit instance is created outside your serverless function handler.
-     */
-    ephemeralCache?: Map<string, number> | false;
-    /**
-     * If set, the ratelimiter will allow requests to pass after this many milliseconds.
-     *
-     * Use this if you want to allow requests in case of network problems
-     */
-    timeout?: number;
-};
-/**
- * Ratelimiter using serverless redis from https://upstash.com/
- *
- * @example
- * ```ts
- * const { limit } = new MultiRegionRatelimit({
- *    redis: Redis.fromEnv(),
- *    limiter: MultiRegionRatelimit.fixedWindow(
- *      10,     // Allow 10 requests per window of 30 minutes
- *      "30 m", // interval of 30 minutes
- *    )
- * })
- *
- * ```
- */
-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: MultiRegionRatelimitConfig);
-    /**
-     * 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): Algorithm<MultiRegionContext>;
-    /**
-     * 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): Algorithm<MultiRegionContext>;
-}

package/types/ratelimit.d.ts

@@ -1,112 +0,0 @@
-import type { Algorithm, Context, RatelimitResponse } from "./types.js";
-export declare class TimeoutError extends Error {
-    constructor();
-}
-export type RatelimitConfig<TContext> = {
-    /**
-     * 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: Algorithm<TContext>;
-    ctx: TContext;
-    /**
-     * All keys in redis are prefixed with this.
-     *
-     * @default `@upstash/ratelimit`
-     */
-    prefix?: string;
-    /**
-     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
-     * exhausted their ratelimit. In serverless environments this is only possible if
-     * you create the ratelimiter instance outside of your handler function. While the
-     * function is still hot, the ratelimiter can block requests without having to
-     * request data from redis, thus saving time and money.
-     *
-     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
-     * internal list together with its reset timestamp. If the same identifier makes a
-     * new request before it is reset, we can immediately reject it.
-     *
-     * Set to `false` to disable.
-     *
-     * If left undefined, a map is created automatically, but it can only work
-     * if the map or the  ratelimit instance is created outside your serverless function handler.
-     */
-    ephemeralCache?: Map<string, number> | false;
-    /**
-     * If set, the ratelimiter will allow requests to pass after this many milliseconds.
-     *
-     * Use this if you want to allow requests in case of network problems
-     */
-    timeout?: number;
-};
-/**
- * Ratelimiter using serverless redis from https://upstash.com/
- *
- * @example
- * ```ts
- * const { limit } = new Ratelimit({
- *    redis: Redis.fromEnv(),
- *    limiter: Ratelimit.slidingWindow(
- *      10,     // Allow 10 requests per window of 30 minutes
- *      "30 m", // interval of 30 minutes
- *    ),
- * })
- *
- * ```
- */
-export declare abstract class Ratelimit<TContext extends Context> {
-    protected readonly limiter: Algorithm<TContext>;
-    protected readonly ctx: TContext;
-    protected readonly prefix: string;
-    protected readonly timeout?: number;
-    constructor(config: RatelimitConfig<TContext>);
-    /**
-     * 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>;
-}