@upstash/ratelimit 0.3.0-rc.1 → 0.3.2

package/dist/index.d.ts

@@ -0,0 +1,571 @@
+import { Redis } from '@upstash/redis';
+
+type Unit = "ms" | "s" | "m" | "h" | "d";
+type Duration = `${number} ${Unit}`;
+
+/**
+ * EphemeralCache is used to block certain identifiers right away in case they have already exceedd the ratelimit.
+ */
+interface EphemeralCache {
+    isBlocked: (identifier: string) => {
+        blocked: boolean;
+        reset: number;
+    };
+    blockUntil: (identifier: string, reset: number) => void;
+    set: (key: string, value: number) => void;
+    get: (key: string) => number | null;
+    incr: (key: string) => number;
+}
+type RegionContext = {
+    redis: Redis;
+    cache?: EphemeralCache;
+};
+type MultiRegionContext = {
+    redis: Redis[];
+    cache?: EphemeralCache;
+};
+type Context = RegionContext | MultiRegionContext;
+type RatelimitResponse = {
+    /**
+     * Whether the request may pass(true) or exceeded the limit(false)
+     */
+    success: boolean;
+    /**
+     * Maximum number of requests allowed within a window.
+     */
+    limit: number;
+    /**
+     * How many requests the user has left within the current window.
+     */
+    remaining: number;
+    /**
+     * Unix timestamp in milliseconds when the limits are reset.
+     */
+    reset: number;
+    /**
+     * For the MultiRegion setup we do some synchronizing in the background, after returning the current 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
+     *
+     * ```ts
+     * const { pending } = await ratelimit.limit("id")
+     * event.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)
+     * ```
+     */
+    pending: Promise<unknown>;
+};
+type Algorithm<TContext> = (ctx: TContext, identifier: string, opts?: {
+    cache?: EphemeralCache;
+}) => Promise<RatelimitResponse>;
+
+type Geo = {
+    country?: string;
+    city?: string;
+    region?: string;
+    ip?: string;
+};
+type Event = Geo & {
+    identifier: string;
+    time: number;
+    success: boolean;
+};
+type AnalyticsConfig = {
+    redis: Redis;
+    prefix?: string;
+};
+/**
+ * The Analytics package is experimental and can change at any time.
+ */
+declare class Analytics {
+    private readonly redis;
+    private readonly prefix;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Try to extract the geo information from the request
+     *
+     * This handles Vercel's `req.geo` and  and Cloudflare's `request.cf` properties
+     * @param req
+     * @returns
+     */
+    extractGeo(req: {
+        geo?: Geo;
+        cf?: Geo;
+    }): Geo;
+    record(event: Event): Promise<void>;
+    /**
+     * Aggregates the events by the given field and returns the number of successes and failures per value
+     *
+     * @param aggregateBy - The field to aggregate by
+     * @param cutoff - Timestamp in milliseconds to limit the aggregation to `cutoff` until now
+     * @returns
+     */
+    aggregate<TAggregateBy extends keyof Omit<Event, "time">>(aggregateBy: TAggregateBy, cutoff?: number): Promise<Record<string, Record<string, {
+        success: number;
+        blocked: number;
+    }>>>;
+    /**
+     * Builds a timeseries of the aggreagated value
+     *
+     * @param aggregateBy - The field to aggregate by
+     * @param cutoff - Timestamp in milliseconds to limit the aggregation to `cutoff` until now
+     * @returns
+     */
+    series<TAggregateBy extends keyof Omit<Event, "time">>(aggregateBy: TAggregateBy, cutoff?: number): Promise<({
+        time: number;
+    } & Record<string, number>)[]>;
+    getUsage(cutoff?: number): Promise<Record<string, {
+        success: number;
+        blocked: number;
+    }>>;
+}
+
+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;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter 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.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * 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.
+     */
+    ephemeralCache?: Map<string, number> | false;
+    /**
+     * If set, the ratelimiter will allow requests to pass after this many milliseconds.
+     *
+     * Use this if you want to allow requests in case of network problems
+     *
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * If enabled, the ratelimiter will store analytics data in redis, which you can check out at
+     * https://upstash.com/ratelimit
+     *
+     * @default true
+     */
+    analytics?: boolean;
+};
+/**
+ * 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
+ *    ),
+ * })
+ *
+ * ```
+ */
+declare abstract class Ratelimit<TContext extends Context> {
+    protected readonly limiter: Algorithm<TContext>;
+    protected readonly ctx: TContext;
+    protected readonly prefix: string;
+    protected readonly timeout: number;
+    protected readonly analytics?: Analytics;
+    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, req?: {
+        geo?: Geo;
+    }) => 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>;
+}
+
+type RegionRatelimitConfig = {
+    /**
+     * Instance 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:
+     * - Ratelimiter.fixedWindow
+     * - Ratelimiter.slidingLogs
+     * - Ratelimiter.slidingWindow
+     * - Ratelimiter.tokenBucket
+     */
+    limiter: Algorithm<RegionContext>;
+    /**
+     * All keys in redis are prefixed with this.
+     *
+     * @default `@upstash/ratelimit`
+     */
+    prefix?: string;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter 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.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * 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.
+     */
+    ephemeralCache?: Map<string, number> | false;
+    /**
+     * If set, the ratelimiter will allow requests to pass after this many milliseconds.
+     *
+     * Use this if you want to allow requests in case of network problems
+     */
+    timeout?: number;
+    /**
+     * If enabled, the ratelimiter will store analytics data in redis, which you can check out at
+     * https://upstash.com/ratelimit
+     *
+     * @default true
+     */
+    analytics?: boolean;
+};
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new Ratelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: Ratelimit.slidingWindow(
+ *      "30 m", // interval of 30 minutes
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+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: RegionRatelimitConfig);
+    /**
+     * 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<RegionContext>;
+    /**
+     * 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<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>;
+}
+
+type MultiRegionRatelimitConfig = {
+    /**
+     * 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:
+     * - MultiRegionRatelimit.fixedWindow
+     */
+    limiter: Algorithm<MultiRegionContext>;
+    /**
+     * All keys in redis are prefixed with this.
+     *
+     * @default `@upstash/ratelimit`
+     */
+    prefix?: string;
+    /**
+     * If enabled, the ratelimiter will keep a global cache of identifiers, that have
+     * exhausted their ratelimit. In serverless environments this is only possible if
+     * you create the ratelimiter 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.
+     *
+     * Whenever an identifier has exceeded its limit, the ratelimiter will add it to an
+     * internal list together with its reset timestamp. If the same identifier makes a
+     * new request before it is reset, we can immediately reject it.
+     *
+     * 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.
+     */
+    ephemeralCache?: Map<string, number> | false;
+    /**
+     * If set, the ratelimiter will allow requests to pass after this many milliseconds.
+     *
+     * Use this if you want to allow requests in case of network problems
+     */
+    timeout?: number;
+    /**
+     * If enabled, the ratelimiter will store analytics data in redis, which you can check out at
+     * https://upstash.com/ratelimit
+     *
+     * @default true
+     */
+    analytics?: boolean;
+};
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new MultiRegionRatelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: MultiRegionRatelimit.fixedWindow(
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *      "30 m", // interval of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+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: MultiRegionRatelimitConfig);
+    /**
+     * 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<MultiRegionContext>;
+    /**
+     * 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<MultiRegionContext>;
+}
+
+export { Algorithm, Analytics, AnalyticsConfig, Event, Geo, MultiRegionRatelimit, MultiRegionRatelimitConfig, RegionRatelimit as Ratelimit, RegionRatelimitConfig as RatelimitConfig };