@upstash/ratelimit 1.0.3 → 1.1.0

package/README.md

@@ -1,10 +1,9 @@
 # Upstash Rate Limit
 
 [![Tests](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml)
-![npm (scoped)](https://img.shields.io/npm/v/@upstash/ratelimit)
+[![npm (scoped)](https://img.shields.io/npm/v/@upstash/ratelimit)](https://www.npmjs.com/package/ratelimit)
 
-> [!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
@@ -32,7 +31,7 @@ npm install @upstash/ratelimit
 #### Deno
 
 ```ts
-import { Ratelimit } from "https://cdn.skypack.dev/@upstash/ratelimit@latest"
+import { Ratelimit } from "https://cdn.skypack.dev/@upstash/ratelimit@latest";
 ```
 
 ### Create database
@@ -105,31 +104,50 @@ export type RatelimitResponse = {
 
   /**
    * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
+   * Or when analytics is enabled, we send the analytics asynchronously after returning the 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
+   * On Vercel Edge or Cloudflare workers, you need to explicitly handle the pending Promise like this:
    *
    * ```ts
    * const { pending } = await ratelimit.limit("id")
-   * event.waitUntil(pending)
+   * context.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)
+   * See `waitUntil` documentation in
+   * [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)
+   * and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)
+   * for more details.
    * ```
    */
   pending: Promise<unknown>;
 };
 ````
 
+### Using with CloudFlare Workers and Vercel Edge
+
+When we use CloudFlare Workers and Vercel Edge, we need to be careful about
+making sure that the rate limiting operations complete correctly before the runtime ends
+after returning the response.
+
+This is important in two cases where we do some operations in the backgroung asynchronously after `limit` is called:
+
+1. Using MultiRegion: synchronize Redis instances in different regions
+2. Enabling analytics: send analytics to Redis
+
+In these cases, we need to wait for these operations to finish before sending the response to the user. Otherwise, the runtime will end and we won't be able to complete our chores.
+
+In order to wait for these operations to finish, use the `pending` promise:
+
+```ts
+const { pending } = await ratelimit.limit("id");
+context.waitUntil(pending);
+```
+
+See `waitUntil` documentation in [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil) for more details.
+
 ### Docs
+
 See [the documentation](https://upstash.com/docs/oss/sdks/ts/ratelimit/overview) for details.
 
 ## Contributing

package/dist/index.d.mts

@@ -10,6 +10,7 @@ interface EphemeralCache {
     set: (key: string, value: number) => void;
     get: (key: string) => number | null;
     incr: (key: string) => number;
+    empty: () => void;
 }
 type RegionContext = {
     redis: Redis;
@@ -39,31 +40,31 @@ type RatelimitResponse = {
     reset: number;
     /**
      * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
+     * Or when analytics is enabled, we send the analytics asynchronously after returning the limit.
      * In most case you can simply ignore this.
      *
      * On Vercel Edge or Cloudflare workers, you need to explicitly 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)
+     * context.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)
+     * See `waitUntil` documentation in
+     * [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)
+     * and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)
+     * for more details.
      * ```
      */
     pending: Promise<unknown>;
 };
-type Algorithm<TContext> = (ctx: TContext, identifier: string, rate?: number, opts?: {
-    cache?: EphemeralCache;
-}) => Promise<RatelimitResponse>;
+type Algorithm<TContext> = () => {
+    limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
+        cache?: EphemeralCache;
+    }) => Promise<RatelimitResponse>;
+    getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
+    resetTokens: (ctx: TContext, identifier: string) => void;
+};
 /**
  * This is all we need from the redis sdk.
  */
@@ -257,6 +258,8 @@ declare abstract class Ratelimit<TContext extends Context> {
      * ```
      */
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
+    resetUsedTokens: (identifier: string) => Promise<void>;
+    getRemaining: (identifier: string) => Promise<number>;
 }
 
 type MultiRegionRatelimitConfig = {

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface EphemeralCache {
     set: (key: string, value: number) => void;
     get: (key: string) => number | null;
     incr: (key: string) => number;
+    empty: () => void;
 }
 type RegionContext = {
     redis: Redis;
@@ -39,31 +40,31 @@ type RatelimitResponse = {
     reset: number;
     /**
      * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
+     * Or when analytics is enabled, we send the analytics asynchronously after returning the limit.
      * In most case you can simply ignore this.
      *
      * On Vercel Edge or Cloudflare workers, you need to explicitly 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)
+     * context.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)
+     * See `waitUntil` documentation in
+     * [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)
+     * and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)
+     * for more details.
      * ```
      */
     pending: Promise<unknown>;
 };
-type Algorithm<TContext> = (ctx: TContext, identifier: string, rate?: number, opts?: {
-    cache?: EphemeralCache;
-}) => Promise<RatelimitResponse>;
+type Algorithm<TContext> = () => {
+    limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
+        cache?: EphemeralCache;
+    }) => Promise<RatelimitResponse>;
+    getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
+    resetTokens: (ctx: TContext, identifier: string) => void;
+};
 /**
  * This is all we need from the redis sdk.
  */
@@ -257,6 +258,8 @@ declare abstract class Ratelimit<TContext extends Context> {
      * ```
      */
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
+    resetUsedTokens: (identifier: string) => Promise<void>;
+    getRemaining: (identifier: string) => Promise<number>;
 }
 
 type MultiRegionRatelimitConfig = {