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

Rate limiting package for AdonisJS framework

import { type Limiter } from './limiter.ts';
import { type LimiterResponse } from './response.ts';
import { type ThrottleException } from './errors.ts';
/**
 * Manages multiple limiters and executes operations across them.
 * Useful for applying rate limits across multiple dimensions simultaneously
 * (e.g., per user and per IP).
 */
export declare class MultiLimiter {
    #private;
    constructor(limiters: {
        key: string | number;
        limiter: Limiter;
    }[]);
    /**
     * Returns the list of configured limiters with their keys.
     */
    list(): {
        key: string | number;
        limiter: Limiter;
    }[];
    /**
     * Consumes one request across all limiters sequentially.
     * Throws a ThrottleException if any limiter exceeds its rate limit.
     *
     * @example
     * ```ts
     * const multi = limiter.multi([
     *   { key: 'user:123', requests: 100, duration: '1 hour' },
     *   { key: 'ip:192.168.1.1', requests: 1000, duration: '1 hour' }
     * ])
     *
     * const responses = await multi.consume()
     * ```
     */
    consume(): Promise<LimiterResponse[]>;
    /**
     * Increments the consumed request count across all limiters.
     * Does not throw when limits are reached.
     */
    increment(): Promise<LimiterResponse[]>;
    /**
     * Decrements the consumed request count across all limiters.
     * Will not decrement below zero.
     */
    decrement(): Promise<LimiterResponse[]>;
    /**
     * Retrieves the current rate limit state for all limiters.
     */
    get(): Promise<(LimiterResponse | null)[]>;
    /**
     * Sets the number of consumed requests for all limiters.
     *
     * @param requests - Number of requests consumed
     * @param duration - Optional duration in seconds or time expression
     */
    set(requests: number, duration?: string | number): Promise<LimiterResponse[]>;
    /**
     * Deletes all limiter keys, resetting their rate limit states.
     */
    delete(): Promise<boolean[]>;
    /**
     * Attempts to consume requests across all limiters and execute the callback if successful.
     * Returns undefined if any rate limit is exceeded.
     *
     * @param callback - Function to execute if all rate limits allow
     *
     * @example
     * ```ts
     * const result = await multi.attempt(async () => {
     *   return await performOperation()
     * })
     *
     * if (!result) {
     *   console.log('Rate limit exceeded on one or more limiters')
     * }
     * ```
     */
    attempt<T>(callback: () => T | Promise<T>): Promise<T | undefined>;
    /**
     * Executes the callback and penalizes on failure by consuming requests across all limiters.
     * Useful for rate limiting failed operations across multiple dimensions.
     *
     * - Returns error if any rate limit is exhausted
     * - Executes callback if all limiters have available requests
     * - Increments counters and blocks keys on callback failure
     * - Resets all keys on callback success
     *
     * @param callback - Function to execute
     *
     * @example
     * ```ts
     * const [error, result] = await multi.penalize(async () => {
     *   return await attemptLogin(credentials)
     * })
     *
     * if (error) {
     *   throw error
     * }
     * ```
     */
    penalize<T>(callback: () => T | Promise<T>): Promise<[null, T] | [ThrottleException, null]>;
}