@upstash/ratelimit 1.2.1 → 2.0.0

package/README.md

@@ -3,7 +3,8 @@
 [![npm (scoped)](https://img.shields.io/npm/v/@upstash/ratelimit)](https://www.npmjs.com/package/@upstash/ratelimit)
 [![Tests](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml)
 
-> [!NOTE] > **This project is in GA Stage.**
+> [!NOTE]
+>  **This project is in GA Stage.**
 > The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes. The Upstash team is committed to maintaining and improving its functionality.
 
 It is the only connectionless (HTTP based) rate limiting library and designed

package/dist/index.d.mts

@@ -90,7 +90,10 @@ type Algorithm<TContext> = () => {
     limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
         cache?: EphemeralCache;
     }) => Promise<RatelimitResponse>;
-    getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
+    getRemaining: (ctx: TContext, identifier: string) => Promise<{
+        remaining: number;
+        reset: number;
+    }>;
     resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
 };
 type IsDenied = 0 | 1;
@@ -328,7 +331,18 @@ declare abstract class Ratelimit<TContext extends Context> {
      */
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
     resetUsedTokens: (identifier: string) => Promise<void>;
-    getRemaining: (identifier: string) => Promise<number>;
+    /**
+     * 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.
+     */
+    getRemaining: (identifier: string) => Promise<{
+        remaining: number;
+        reset: number;
+    }>;
     /**
      * Checks if the identifier or the values in req are in the deny list cache.
      * If so, returns the default denied response.

package/dist/index.d.ts

@@ -90,7 +90,10 @@ type Algorithm<TContext> = () => {
     limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
         cache?: EphemeralCache;
     }) => Promise<RatelimitResponse>;
-    getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
+    getRemaining: (ctx: TContext, identifier: string) => Promise<{
+        remaining: number;
+        reset: number;
+    }>;
     resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
 };
 type IsDenied = 0 | 1;
@@ -328,7 +331,18 @@ declare abstract class Ratelimit<TContext extends Context> {
      */
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
     resetUsedTokens: (identifier: string) => Promise<void>;
-    getRemaining: (identifier: string) => Promise<number>;
+    /**
+     * 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.
+     */
+    getRemaining: (identifier: string) => Promise<{
+        remaining: number;
+        reset: number;
+    }>;
     /**
      * Checks if the identifier or the values in req are in the deny list cache.
      * If so, returns the default denied response.

package/dist/index.js

@@ -583,6 +583,14 @@ var Ratelimit = class {
     const pattern = [this.prefix, identifier].join(":");
     await this.limiter().resetTokens(this.ctx, pattern);
   };
+  /**
+   * 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.
+   */
   getRemaining = async (identifier) => {
     const pattern = [this.prefix, identifier].join(":");
     return await this.limiter().getRemaining(this.ctx, pattern);
@@ -867,7 +875,10 @@ var MultiRegionRatelimit = class extends Ratelimit {
           }
           return accTokens + parsedToken;
         }, 0);
-        return Math.max(0, tokens - usedTokens);
+        return {
+          remaining: Math.max(0, tokens - usedTokens),
+          reset: (bucket + 1) * windowDuration
+        };
       },
       async resetTokens(ctx, identifier) {
         const pattern = [identifier, "*"].join(":");
@@ -1029,7 +1040,10 @@ var MultiRegionRatelimit = class extends Ratelimit {
           )
         }));
         const usedTokens = await Promise.any(dbs.map((s) => s.request));
-        return Math.max(0, tokens - usedTokens);
+        return {
+          remaining: Math.max(0, tokens - usedTokens),
+          reset: (currentWindow + 1) * windowSize
+        };
       },
       async resetTokens(ctx, identifier) {
         const pattern = [identifier, "*"].join(":");
@@ -1168,17 +1182,18 @@ var tokenBucketLimitScript = `
   redis.call("PEXPIRE", key, expireAt)
   return {remaining, refilledAt + interval}
 `;
+var tokenBucketIdentifierNotFound = -1;
 var tokenBucketRemainingTokensScript = `
   local key         = KEYS[1]
   local maxTokens   = tonumber(ARGV[1])
         
-  local bucket = redis.call("HMGET", key, "tokens")
+  local bucket = redis.call("HMGET", key, "refilledAt", "tokens")
 
   if bucket[1] == false then
-    return maxTokens
+    return {maxTokens, ${tokenBucketIdentifierNotFound}}
   end
         
-  return tonumber(bucket[1])
+  return {tonumber(bucket[2]), tonumber(bucket[1])}
 `;
 var cachedFixedWindowLimitScript = `
   local key     = KEYS[1]
@@ -1295,7 +1310,10 @@ var RegionRatelimit = class extends Ratelimit {
           [key],
           [null]
         );
-        return Math.max(0, tokens - usedTokens);
+        return {
+          remaining: Math.max(0, tokens - usedTokens),
+          reset: (bucket + 1) * windowDuration
+        };
       },
       async resetTokens(ctx, identifier) {
         const pattern = [identifier, "*"].join(":");
@@ -1384,7 +1402,10 @@ var RegionRatelimit = class extends Ratelimit {
           [currentKey, previousKey],
           [now, windowSize]
         );
-        return Math.max(0, tokens - usedTokens);
+        return {
+          remaining: Math.max(0, tokens - usedTokens),
+          reset: (currentWindow + 1) * windowSize
+        };
       },
       async resetTokens(ctx, identifier) {
         const pattern = [identifier, "*"].join(":");
@@ -1453,14 +1474,19 @@ var RegionRatelimit = class extends Ratelimit {
         };
       },
       async getRemaining(ctx, identifier) {
-        const remainingTokens = await safeEval(
+        const [remainingTokens, refilledAt] = await safeEval(
           ctx,
           tokenBucketRemainingTokensScript,
           "getRemainingHash",
           [identifier],
           [maxTokens]
         );
-        return remainingTokens;
+        const freshRefillAt = Date.now() + intervalDuration;
+        const identifierRefillsAt = refilledAt + intervalDuration;
+        return {
+          remaining: remainingTokens,
+          reset: refilledAt === tokenBucketIdentifierNotFound ? freshRefillAt : identifierRefillsAt
+        };
       },
       async resetTokens(ctx, identifier) {
         const pattern = identifier;
@@ -1557,7 +1583,10 @@ var RegionRatelimit = class extends Ratelimit {
         const hit = typeof ctx.cache.get(key) === "number";
         if (hit) {
           const cachedUsedTokens = ctx.cache.get(key) ?? 0;
-          return Math.max(0, tokens - cachedUsedTokens);
+          return {
+            remaining: Math.max(0, tokens - cachedUsedTokens),
+            reset: (bucket + 1) * windowDuration
+          };
         }
         const usedTokens = await safeEval(
           ctx,
@@ -1566,7 +1595,10 @@ var RegionRatelimit = class extends Ratelimit {
           [key],
           [null]
         );
-        return Math.max(0, tokens - usedTokens);
+        return {
+          remaining: Math.max(0, tokens - usedTokens),
+          reset: (bucket + 1) * windowDuration
+        };
       },
       async resetTokens(ctx, identifier) {
         if (!ctx.cache) {