@upstash/ratelimit 0.4.1 → 0.4.3-canary.0

package/README.md

@@ -1,4 +1,4 @@
-# Upstash RateLimit
+# 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)
@@ -86,7 +86,13 @@ import { Redis } from "@upstash/redis";
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.slidingWindow(10, "10 s"),
-  analytics: true
+  analytics: true,
+  /**
+   * Optional prefix for the keys used in redis. This is useful if you want to share a redis
+   * instance with other applications and want to avoid key collisions. The default prefix is
+   * "@upstash/ratelimit"
+   */ 
+  prefix: "@upstash/ratelimit",
 });
 
 // Use a constant string to limit all requests with a single ratelimit
@@ -224,6 +230,41 @@ 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.
 
+
+## Using multiple limits
+
+Sometimes you might want to apply different limits to different users. For example you might want to allow 10 requests per 10 seconds for free users, but 60 requests per 10 seconds for paid users.
+
+Here's how you could do that:
+
+```ts
+import { Redis } from "@upstash/redis"
+import { Ratelimit from "@upstash/ratelimit"
+
+const redis = Redis.fromEnv()
+
+const ratelimit = {
+  free: new Ratelimit({
+    redis,
+    analytics: true,
+    prefix: "ratelimit:free",
+    limiter: Ratelimit.slidingWindow(10, "10s"),
+  }),
+  paid: new Ratelimit({
+    redis,
+    analytics: true,
+    prefix: "ratelimit:paid",
+    limiter: Ratelimit.slidingWindow(60, "10s"),
+  })
+}
+
+
+await ratelimit.free.limit(ip)
+// or for a paid user you might have an email or userId available:
+await ratelimit.paid.limit(userId)
+
+```
+
 ## MultiRegion replicated ratelimiting
 
 Using a single redis instance has the downside of providing low latencies only
@@ -411,7 +452,7 @@ const ratelimit = new Ratelimit({
 You can enable analytics to get a better understanding of how your ratelimiting
 is performing. This is done by setting `analytics: true` in the options.
 
-All data is stored in the same Redis database.
+All data is stored in the same Redis database and writing analytics uses 1 command per `.limit` invocation.
 
 ```ts
 const ratelimit = new Ratelimit({

package/dist/index.d.ts

@@ -1,8 +1,3 @@
-import { Redis } from '@upstash/redis';
-
-type Unit = "ms" | "s" | "m" | "h" | "d";
-type Duration = `${number} ${Unit}` | `${number}${Unit}`;
-
 /**
  * EphemeralCache is used to block certain identifiers right away in case they have already exceedd the ratelimit.
  */
@@ -69,6 +64,13 @@ type RatelimitResponse = {
 type Algorithm<TContext> = (ctx: TContext, identifier: string, opts?: {
     cache?: EphemeralCache;
 }) => Promise<RatelimitResponse>;
+/**
+ * This is all we need from the redis sdk.
+ */
+interface Redis {
+    sadd: <TData>(key: string, ...members: TData[]) => Promise<number>;
+    eval: <TArgs extends unknown[], TData = unknown>(...args: [script: string, keys: string[], args: TArgs]) => Promise<TData>;
+}
 
 type Geo = {
     country?: string;
@@ -113,6 +115,9 @@ declare class Analytics {
     }>>;
 }
 
+type Unit = "ms" | "s" | "m" | "h" | "d";
+type Duration = `${number} ${Unit}` | `${number}${Unit}`;
+
 type RatelimitConfig<TContext> = {
     /**
      * The ratelimiter function to use.
@@ -161,7 +166,7 @@ type RatelimitConfig<TContext> = {
      * If enabled, the ratelimiter will store analytics data in redis, which you can check out at
      * https://upstash.com/ratelimit
      *
-     * @default true
+     * @default false
      */
     analytics?: boolean;
 };
@@ -212,7 +217,7 @@ declare abstract class Ratelimit<TContext extends Context> {
     /**
      * 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
+     * This method returns a promise 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.
@@ -234,23 +239,20 @@ declare abstract class Ratelimit<TContext extends Context> {
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
 }
 
-type RegionRatelimitConfig = {
+type MultiRegionRatelimitConfig = {
     /**
-     * Instance of `@upstash/redis`
+     * Instances of `@upstash/redis`
      * @see https://github.com/upstash/upstash-redis#quick-start
      */
-    redis: Redis;
+    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
+     * - MultiRegionRatelimit.fixedWindow
      */
-    limiter: Algorithm<RegionContext>;
+    limiter: Algorithm<MultiRegionContext>;
     /**
      * All keys in redis are prefixed with this.
      *
@@ -271,7 +273,7 @@ type RegionRatelimitConfig = {
      * 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.
+     * if the map or th ratelimit instance is created outside your serverless function handler.
      */
     ephemeralCache?: Map<string, number> | false;
     /**
@@ -293,21 +295,21 @@ type RegionRatelimitConfig = {
  *
  * @example
  * ```ts
- * const { limit } = new Ratelimit({
+ * const { limit } = new MultiRegionRatelimit({
  *    redis: Redis.fromEnv(),
- *    limiter: Ratelimit.slidingWindow(
- *      "30 m", // interval of 30 minutes
+ *    limiter: MultiRegionRatelimit.fixedWindow(
  *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
  *    )
  * })
  *
  * ```
  */
-declare class RegionRatelimit extends Ratelimit<RegionContext> {
+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: RegionRatelimitConfig);
+    constructor(config: MultiRegionRatelimitConfig);
     /**
      * Each requests inside a fixed time increases a counter.
      * Once the counter reaches a maxmimum allowed number, all further requests are
@@ -334,7 +336,7 @@ declare class RegionRatelimit extends Ratelimit<RegionContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<RegionContext>;
+    window: Duration): Algorithm<MultiRegionContext>;
     /**
      * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
      * costs than `slidingLogs` and improved boundary behavior by calcualting a
@@ -359,86 +361,26 @@ declare class RegionRatelimit extends Ratelimit<RegionContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<RegionContext>;
-    /**
-     * 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: 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): Algorithm<RegionContext>;
-    /**
-     * 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: number, 
-    /**
-     * The duration in which `tokens` requests are allowed.
-     */
-    window: Duration): Algorithm<RegionContext>;
+    window: Duration): Algorithm<MultiRegionContext>;
 }
 
-type MultiRegionRatelimitConfig = {
+type RegionRatelimitConfig = {
     /**
-     * Instances of `@upstash/redis`
+     * Instance of `@upstash/redis`
      * @see https://github.com/upstash/upstash-redis#quick-start
      */
-    redis: Redis[];
+    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
+     * - Ratelimiter.fixedWindow
+     * - Ratelimiter.slidingLogs
+     * - Ratelimiter.slidingWindow
+     * - Ratelimiter.tokenBucket
      */
-    limiter: Algorithm<MultiRegionContext>;
+    limiter: Algorithm<RegionContext>;
     /**
      * All keys in redis are prefixed with this.
      *
@@ -459,7 +401,7 @@ type MultiRegionRatelimitConfig = {
      * 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.
+     * if the map or the ratelimit instance is created outside your serverless function handler.
      */
     ephemeralCache?: Map<string, number> | false;
     /**
@@ -481,21 +423,21 @@ type MultiRegionRatelimitConfig = {
  *
  * @example
  * ```ts
- * const { limit } = new MultiRegionRatelimit({
+ * const { limit } = new Ratelimit({
  *    redis: Redis.fromEnv(),
- *    limiter: MultiRegionRatelimit.fixedWindow(
- *      10,     // Allow 10 requests per window of 30 minutes
+ *    limiter: Ratelimit.slidingWindow(
  *      "30 m", // interval of 30 minutes
+ *      10,     // Allow 10 requests per window of 30 minutes
  *    )
  * })
  *
  * ```
  */
-declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
+declare class RegionRatelimit extends Ratelimit<RegionContext> {
     /**
      * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
      */
-    constructor(config: MultiRegionRatelimitConfig);
+    constructor(config: RegionRatelimitConfig);
     /**
      * Each requests inside a fixed time increases a counter.
      * Once the counter reaches a maxmimum allowed number, all further requests are
@@ -522,7 +464,7 @@ declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<MultiRegionContext>;
+    window: Duration): Algorithm<RegionContext>;
     /**
      * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
      * costs than `slidingLogs` and improved boundary behavior by calcualting a
@@ -547,7 +489,70 @@ declare class MultiRegionRatelimit extends Ratelimit<MultiRegionContext> {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Algorithm<MultiRegionContext>;
+    window: Duration): Algorithm<RegionContext>;
+    /**
+     * 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: 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): Algorithm<RegionContext>;
+    /**
+     * 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: number, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window: Duration): Algorithm<RegionContext>;
 }
 
 export { Algorithm, Analytics, AnalyticsConfig, MultiRegionRatelimit, MultiRegionRatelimitConfig, RegionRatelimit as Ratelimit, RegionRatelimitConfig as RatelimitConfig };