@upstash/ratelimit 0.1.0-alpha.0 → 0.1.2

package/types/global.d.ts

@@ -0,0 +1,98 @@
+import type { Duration } from "./duration.js";
+import type { Algorithm, GlobalContext } from "./types.js";
+import { Ratelimit } from "./ratelimit.js";
+import type { Redis } from "./types.js";
+export declare type GlobalRatelimitConfig = {
+    /**
+     * 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:
+     * - GlobalRatelimit.fixedWindow
+     */
+    limiter: Algorithm<GlobalContext>;
+    /**
+     * All keys in redis are prefixed with this.
+     *
+     * @default `@upstash/ratelimit`
+     */
+    prefix?: string;
+};
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new GlobalRatelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: GlobalRatelimit.fixedWindow(
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+export declare class GlobalRatelimit extends Ratelimit<GlobalContext> {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config: GlobalRatelimitConfig);
+    /**
+     * 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<GlobalContext>;
+    /**
+     * 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<GlobalContext>;
+}

package/types/mod.d.ts

@@ -1,2 +1,5 @@
-export * from "./ratelimiter.js";
-export * from "./types.js";
+export { RegionRatelimit as Ratelimit } from "./region.js";
+export type { RegionRatelimitConfig as RatelimitConfig } from "./region.js";
+export { GlobalRatelimit } from "./global.js";
+export type { GlobalRatelimitConfig } from "./global.js";
+export type { Algorithm } from "./types.js";

package/types/ratelimit.d.ts

@@ -0,0 +1,85 @@
+import type { Algorithm, Context, RatelimitResponse } from "./types.js";
+export declare 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;
+};
+/**
+ * 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;
+    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>;
+}

package/types/{ratelimiter.d.ts → region.d.ts}

@@ -1,6 +1,8 @@
 import type { Duration } from "./duration.js";
-import type { Ratelimiter, RatelimitResponse, Redis } from "./types.js";
-export declare type RatelimitConfig = {
+import type { Algorithm, RegionContext } from "./types.js";
+import type { Redis } from "./types.js";
+import { Ratelimit } from "./ratelimit.js";
+export declare type RegionRatelimitConfig = {
     /**
      * Instance of `@upstash/redis`
      * @see https://github.com/upstash/upstash-redis#quick-start
@@ -16,7 +18,7 @@ export declare type RatelimitConfig = {
      * - Ratelimiter.slidingWindow
      * - Ratelimiter.tokenBucket
      */
-    limiter: Ratelimiter;
+    limiter: Algorithm<RegionContext>;
     /**
      * All keys in redis are prefixed with this.
      *
@@ -39,57 +41,11 @@ export declare type RatelimitConfig = {
  *
  * ```
  */
-export declare class Ratelimit {
-    private readonly redis;
-    private readonly limiter;
-    private readonly prefix;
+export 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: RatelimitConfig);
-    /**
-     * 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>;
+    constructor(config: RegionRatelimitConfig);
     /**
      * Each requests inside a fixed time increases a counter.
      * Once the counter reaches a maxmimum allowed number, all further requests are
@@ -116,7 +72,7 @@ export declare class Ratelimit {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Ratelimiter;
+    window: Duration): Algorithm<RegionContext>;
     /**
      * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
      * costs than `slidingLogs` and improved boundary behavior by calcualting a
@@ -141,7 +97,7 @@ export declare class Ratelimit {
     /**
      * The duration in which `tokens` requests are allowed.
      */
-    window: Duration): Ratelimiter;
+    window: Duration): Algorithm<RegionContext>;
     /**
      * You have a bucket filled with `{maxTokens}` tokens that refills constantly
      * at `{refillRate}` per `{interval}`.
@@ -173,5 +129,5 @@ export declare class Ratelimit {
      * A newly created bucket starts with this many tokens.
      * Useful to allow higher burst limits.
      */
-    maxTokens: number): Ratelimiter;
+    maxTokens: number): Algorithm<RegionContext>;
 }

package/types/types.d.ts

@@ -1,9 +1,14 @@
-export declare type Redis = {
-    eval: <TArgs extends unknown[], TData = unknown>(...args: [script: string, keys: string[], args: TArgs]) => Promise<unknown>;
-};
-export declare type Context = {
+export interface Redis {
+    eval: (script: string, keys: string[], values: unknown[]) => Promise<unknown>;
+    sadd: (key: string, ...members: string[]) => Promise<number>;
+}
+export declare type RegionContext = {
     redis: Redis;
 };
+export declare type GlobalContext = {
+    redis: Redis[];
+};
+export declare type Context = RegionContext | GlobalContext;
 export declare type RatelimitResponse = {
     /**
      * Whether the request may pass(true) or exceeded the limit(false)
@@ -22,4 +27,4 @@ export declare type RatelimitResponse = {
      */
     reset: number;
 };
-export declare type Ratelimiter = (ctx: Context, identifier: string) => Promise<RatelimitResponse>;
+export declare type Algorithm<TContext> = (ctx: TContext, identifier: string) => Promise<RatelimitResponse>;