@upstash/ratelimit 0.4.3 → 0.4.5-canary.0

package/dist/index.d.ts

@@ -1,558 +0,0 @@
-/**
- * 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>;
-/**
- * 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;
-    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 analytics;
-    private readonly table;
-    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>;
-    series<TFilter extends keyof Omit<Event, "time">>(filter: TFilter, cutoff: number): Promise<({
-        time: number;
-    } & Record<string, number>)[]>;
-    getUsage(cutoff?: number): Promise<Record<string, {
-        success: number;
-        blocked: number;
-    }>>;
-}
-
-type Unit = "ms" | "s" | "m" | "h" | "d";
-type Duration = `${number} ${Unit}` | `${number}${Unit}`;
-
-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 false
-     */
-    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 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.
-     *
-     * @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 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://console.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>;
-}
-
-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>;
-}
-
-export { Algorithm, Analytics, AnalyticsConfig, MultiRegionRatelimit, MultiRegionRatelimitConfig, RegionRatelimit as Ratelimit, RegionRatelimitConfig as RatelimitConfig };