@adonisjs/limiter/build/src/http_limiter.d.ts

Rate limiting package for AdonisJS framework

import type { HttpContext } from '@adonisjs/core/http';
import { type LimiterResponse } from './response.ts';
import type { LimiterManager } from './limiter_manager.ts';
import { type ThrottleException } from './errors.ts';
import type { LimiterConsumptionOptions, LimiterManagerStoreFactory } from './types.ts';
/**
 * HTTP rate limiter with a fluent API for configuring rate limiting on HTTP requests.
 * Automatically uses the request IP address as the key unless a custom key is specified.
 */
export declare class HttpLimiter<KnownStores extends Record<string, LimiterManagerStoreFactory>> {
    #private;
    constructor(manager: LimiterManager<KnownStores>, options?: LimiterConsumptionOptions);
    /**
     * Specifies which store to use for this rate limiter.
     *
     * @param store - Name of the configured store
     *
     * @example
     * ```ts
     * limiter
     *   .allowRequests(100)
     *   .every('1 hour')
     *   .store('redis')
     * ```
     */
    store(store: keyof KnownStores): this;
    /**
     * Sets the number of requests to allow during the specified duration.
     *
     * @param requests - Maximum number of requests
     *
     * @example
     * ```ts
     * limiter.allowRequests(100)
     * ```
     */
    allowRequests(requests: number): this;
    /**
     * Sets the duration window for the rate limit.
     *
     * @param duration - Duration in seconds or time expression (e.g., '1 minute', '1 hour')
     *
     * @example
     * ```ts
     * limiter.allowRequests(100).every('1 hour')
     * limiter.allowRequests(10).every(60) // 60 seconds
     * ```
     */
    every(duration: number | string): this;
    /**
     * Sets a custom key to uniquely identify the requester.
     * By default, the request IP address is used.
     *
     * @param key - Custom identifier (e.g., user ID, API key)
     *
     * @example
     * ```ts
     * limiter
     *   .allowRequests(100)
     *   .every('1 hour')
     *   .usingKey(ctx.auth.user.id)
     * ```
     */
    usingKey(key: string | number): this;
    /**
     * Registers a callback to customize the ThrottleException before it's thrown.
     * Useful for setting custom error messages or translations.
     *
     * @param callback - Function to modify the exception
     *
     * @example
     * ```ts
     * limiter
     *   .allowRequests(100)
     *   .every('1 hour')
     *   .limitExceeded((error) => {
     *     error.setMessage('Too many requests. Please slow down!')
     *     error.t('errors.rate_limit_exceeded')
     *   })
     * ```
     */
    limitExceeded(callback: (error: ThrottleException) => void): this;
    /**
     * Sets the block duration to penalize users who exceed the rate limit.
     * The key will be blocked for this duration after exhausting all requests.
     *
     * @param duration - Block duration in seconds or time expression
     *
     * @example
     * ```ts
     * limiter
     *   .allowRequests(100)
     *   .every('1 hour')
     *   .blockFor('15 mins')
     * ```
     */
    blockFor(duration: number | string): this;
    /**
     * Returns a JSON representation of the HTTP limiter configuration.
     */
    toJSON(): {
        inMemoryBlockDuration?: number | string | undefined;
        inMemoryBlockOnConsumed?: number | undefined;
        requests?: number | undefined;
        duration?: string | number | undefined;
        blockDuration?: number | string | undefined;
        store: keyof KnownStores | undefined;
    };
    /**
     * Throttles the HTTP request using the configured options.
     * Throws a ThrottleException if the rate limit is exceeded.
     *
     * @param prefix - Key prefix to namespace the limiter
     * @param ctx - HTTP context
     *
     * @example
     * ```ts
     * const response = await httpLimiter.throttle('api', ctx)
     * console.log(`Remaining: ${response.remaining}`)
     * ```
     */
    throttle(prefix: string, ctx: HttpContext): Promise<LimiterResponse>;
}