@upstash/ratelimit 2.0.6 → 2.0.8

package/dist/index.d.mts

@@ -12,7 +12,7 @@ type EphemeralCache = {
     blockUntil: (identifier: string, reset: number) => void;
     set: (key: string, value: number) => void;
     get: (key: string) => number | null;
-    incr: (key: string) => number;
+    incr: (key: string, incrementAmount?: number) => number;
     pop: (key: string) => void;
     empty: () => void;
     size: () => number;
@@ -20,6 +20,15 @@ type EphemeralCache = {
 type RegionContext = {
     redis: Redis$1;
     cache?: EphemeralCache;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * using MGET before applying the regular limit.
+     */
+    dynamicLimits?: boolean;
+    /**
+     * The prefix used for Redis keys
+     */
+    prefix: string;
 };
 type MultiRegionContext = {
     regionContexts: Omit<RegionContext[], "cache">;
@@ -87,6 +96,7 @@ type Algorithm<TContext> = () => {
     getRemaining: (ctx: TContext, identifier: string) => Promise<{
         remaining: number;
         reset: number;
+        limit: number;
     }>;
     resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
 };
@@ -183,6 +193,16 @@ type RatelimitConfig<TContext> = {
      * @default `@upstash/ratelimit`
      */
     prefix?: string;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * When enabled, adds +1 Redis command (GET) to every limit check.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
     /**
      * If enabled, the ratelimiter will keep a global cache of identifiers, that have
      * exhausted their ratelimit. In serverless environments this is only possible if
@@ -249,6 +269,7 @@ declare abstract class Ratelimit<TContext extends Context> {
     protected readonly analytics?: Analytics;
     protected readonly enableProtection: boolean;
     protected readonly denyListThreshold: number;
+    protected readonly dynamicLimits: boolean;
     constructor(config: RatelimitConfig<TContext>);
     /**
      * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
@@ -315,13 +336,14 @@ declare abstract class Ratelimit<TContext extends Context> {
      * Returns the remaining token count together with a reset timestamps
      *
      * @param identifier identifir to check
-     * @returns object with `remaining` and reset fields. `remaining` denotes
-     *          the remaining tokens and reset denotes the timestamp when the
-     *          tokens reset.
+     * @returns object with `remaining`, `reset`, and `limit` fields. `remaining` denotes
+     *          the remaining tokens, `limit` is the effective limit (considering dynamic
+     *          limits if enabled), and `reset` denotes the timestamp when the tokens reset.
      */
     getRemaining: (identifier: string) => Promise<{
         remaining: number;
         reset: number;
+        limit: number;
     }>;
     /**
      * Checks if the identifier or the values in req are in the deny list cache.
@@ -363,6 +385,46 @@ declare abstract class Ratelimit<TContext extends Context> {
      * @returns list of defined values
      */
     private getDefinedMembers;
+    /**
+     * Set a dynamic rate limit globally.
+     *
+     * When dynamicLimits is enabled, this limit will override the default limit
+     * set in the constructor for all requests.
+     *
+     * @example
+     * ```ts
+     * const ratelimit = new Ratelimit({
+     *   redis: Redis.fromEnv(),
+     *   limiter: Ratelimit.slidingWindow(10, "10 s"),
+     *   dynamicLimits: true
+     * });
+     *
+     * // Set global dynamic limit to 120 requests
+     * await ratelimit.setDynamicLimit({ limit: 120 });
+     *
+     * // Disable dynamic limit (falls back to default)
+     * await ratelimit.setDynamicLimit({ limit: false });
+     * ```
+     *
+     * @param options.limit - The new rate limit to apply globally, or false to disable
+     */
+    setDynamicLimit: (options: {
+        limit: number | false;
+    }) => Promise<void>;
+    /**
+     * Get the current global dynamic rate limit.
+     *
+     * @example
+     * ```ts
+     * const { dynamicLimit } = await ratelimit.getDynamicLimit();
+     * console.log(dynamicLimit); // 120 or null if not set
+     * ```
+     *
+     * @returns Object containing the current global dynamic limit, or null if not set
+     */
+    getDynamicLimit: () => Promise<{
+        dynamicLimit: number | null;
+    }>;
 }
 
 type MultiRegionRatelimitConfig = {
@@ -422,6 +484,17 @@ type MultiRegionRatelimitConfig = {
      * @default true
      */
     cacheScripts?: boolean;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * Note: Dynamic limits are not yet supported for multi-region rate limiters.
+     * This option will be ignored for MultiRegionRatelimit.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -497,7 +570,7 @@ declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
     window: Duration): Algorithm<MultiRegionContext>;
 }
 
-type Redis = Pick<Redis$1, "get" | "set">;
+type Redis = Pick<Redis$1, "evalsha" | "get" | "set">;
 type RegionRatelimitConfig = {
     /**
      * Instance of `@upstash/redis`
@@ -569,6 +642,16 @@ type RegionRatelimitConfig = {
      * @default 6
      */
     denyListThreshold?: number;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * When enabled, adds +1 Redis command (GET) to every limit check.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/dist/index.d.ts

@@ -12,7 +12,7 @@ type EphemeralCache = {
     blockUntil: (identifier: string, reset: number) => void;
     set: (key: string, value: number) => void;
     get: (key: string) => number | null;
-    incr: (key: string) => number;
+    incr: (key: string, incrementAmount?: number) => number;
     pop: (key: string) => void;
     empty: () => void;
     size: () => number;
@@ -20,6 +20,15 @@ type EphemeralCache = {
 type RegionContext = {
     redis: Redis$1;
     cache?: EphemeralCache;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * using MGET before applying the regular limit.
+     */
+    dynamicLimits?: boolean;
+    /**
+     * The prefix used for Redis keys
+     */
+    prefix: string;
 };
 type MultiRegionContext = {
     regionContexts: Omit<RegionContext[], "cache">;
@@ -87,6 +96,7 @@ type Algorithm<TContext> = () => {
     getRemaining: (ctx: TContext, identifier: string) => Promise<{
         remaining: number;
         reset: number;
+        limit: number;
     }>;
     resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
 };
@@ -183,6 +193,16 @@ type RatelimitConfig<TContext> = {
      * @default `@upstash/ratelimit`
      */
     prefix?: string;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * When enabled, adds +1 Redis command (GET) to every limit check.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
     /**
      * If enabled, the ratelimiter will keep a global cache of identifiers, that have
      * exhausted their ratelimit. In serverless environments this is only possible if
@@ -249,6 +269,7 @@ declare abstract class Ratelimit<TContext extends Context> {
     protected readonly analytics?: Analytics;
     protected readonly enableProtection: boolean;
     protected readonly denyListThreshold: number;
+    protected readonly dynamicLimits: boolean;
     constructor(config: RatelimitConfig<TContext>);
     /**
      * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
@@ -315,13 +336,14 @@ declare abstract class Ratelimit<TContext extends Context> {
      * Returns the remaining token count together with a reset timestamps
      *
      * @param identifier identifir to check
-     * @returns object with `remaining` and reset fields. `remaining` denotes
-     *          the remaining tokens and reset denotes the timestamp when the
-     *          tokens reset.
+     * @returns object with `remaining`, `reset`, and `limit` fields. `remaining` denotes
+     *          the remaining tokens, `limit` is the effective limit (considering dynamic
+     *          limits if enabled), and `reset` denotes the timestamp when the tokens reset.
      */
     getRemaining: (identifier: string) => Promise<{
         remaining: number;
         reset: number;
+        limit: number;
     }>;
     /**
      * Checks if the identifier or the values in req are in the deny list cache.
@@ -363,6 +385,46 @@ declare abstract class Ratelimit<TContext extends Context> {
      * @returns list of defined values
      */
     private getDefinedMembers;
+    /**
+     * Set a dynamic rate limit globally.
+     *
+     * When dynamicLimits is enabled, this limit will override the default limit
+     * set in the constructor for all requests.
+     *
+     * @example
+     * ```ts
+     * const ratelimit = new Ratelimit({
+     *   redis: Redis.fromEnv(),
+     *   limiter: Ratelimit.slidingWindow(10, "10 s"),
+     *   dynamicLimits: true
+     * });
+     *
+     * // Set global dynamic limit to 120 requests
+     * await ratelimit.setDynamicLimit({ limit: 120 });
+     *
+     * // Disable dynamic limit (falls back to default)
+     * await ratelimit.setDynamicLimit({ limit: false });
+     * ```
+     *
+     * @param options.limit - The new rate limit to apply globally, or false to disable
+     */
+    setDynamicLimit: (options: {
+        limit: number | false;
+    }) => Promise<void>;
+    /**
+     * Get the current global dynamic rate limit.
+     *
+     * @example
+     * ```ts
+     * const { dynamicLimit } = await ratelimit.getDynamicLimit();
+     * console.log(dynamicLimit); // 120 or null if not set
+     * ```
+     *
+     * @returns Object containing the current global dynamic limit, or null if not set
+     */
+    getDynamicLimit: () => Promise<{
+        dynamicLimit: number | null;
+    }>;
 }
 
 type MultiRegionRatelimitConfig = {
@@ -422,6 +484,17 @@ type MultiRegionRatelimitConfig = {
      * @default true
      */
     cacheScripts?: boolean;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * Note: Dynamic limits are not yet supported for multi-region rate limiters.
+     * This option will be ignored for MultiRegionRatelimit.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -497,7 +570,7 @@ declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
     window: Duration): Algorithm<MultiRegionContext>;
 }
 
-type Redis = Pick<Redis$1, "get" | "set">;
+type Redis = Pick<Redis$1, "evalsha" | "get" | "set">;
 type RegionRatelimitConfig = {
     /**
      * Instance of `@upstash/redis`
@@ -569,6 +642,16 @@ type RegionRatelimitConfig = {
      * @default 6
      */
     denyListThreshold?: number;
+    /**
+     * If enabled, the ratelimiter will check for dynamic limits in Redis
+     * before applying the regular limit. This allows you to change the rate
+     * limit at runtime using setDynamicLimit().
+     *
+     * When enabled, adds +1 Redis command (GET) to every limit check.
+     *
+     * @default false
+     */
+    dynamicLimits?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/