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

Rate limiting package for AdonisJS framework

import { LimiterResponse } from './response.js';
import { ThrottleException } from './errors.js';
import type { LimiterStoreContract } from './types.js';
/**
 * Limiter acts as an adapter on top of the limiter
 * stores and offers additional APIs
 */
export declare class Limiter implements LimiterStoreContract {
    #private;
    /**
     * The number of configured requests on the store
     */
    get name(): string;
    /**
     * The number of configured requests on the store
     */
    get requests(): number;
    /**
     * The duration (in seconds) for which the requests are configured
     */
    get duration(): number;
    /**
     * The duration (in seconds) for which to block the key
     */
    get blockDuration(): number;
    constructor(store: LimiterStoreContract);
    /**
     * Consume 1 request for a given key. An exception is raised
     * when all the requests have already been consumed or if
     * the key is blocked.
     */
    consume(key: string | number): Promise<LimiterResponse>;
    /**
     * Increment the number of consumed requests for a given key.
     * No errors are thrown when limit has reached
     */
    increment(key: string | number): Promise<LimiterResponse>;
    /**
     * Decrement the number of consumed requests for a given key.
     */
    decrement(key: string | number): Promise<LimiterResponse>;
    /**
     * Consume 1 request for a given key and execute the provided
     * callback.
     */
    attempt<T>(key: string | number, callback: () => T | Promise<T>): Promise<T | undefined>;
    /**
     * Consume 1 request for a given key when the executed method throws
     * an error.
     *
     * - Check if all the requests have been exhausted. If yes, throw limiter
     *   error.
     * - Otherwise, execute the provided callback.
     * - Increment the requests counter, if provided callback throws an error and rethrow
     *   the error
     * - Delete key, if the provided callback succeeds and return the results.
     */
    penalize<T>(key: string | number, callback: () => T | Promise<T>): Promise<[null, T] | [ThrottleException, null]>;
    /**
     * Block a given key for the given duration. The duration must be
     * a value in seconds or a string expression.
     */
    block(key: string | number, duration: string | number): Promise<LimiterResponse>;
    /**
     * Manually set the number of requests exhausted for
     * a given key for the given time duration.
     *
     * For example: "ip_127.0.0.1" has made "20 requests" in "1 minute".
     * Now, if you allow 25 requests in 1 minute, then only 5 requests
     * are left.
     *
     * The duration must be a value in seconds or a string expression.
     */
    set(key: string | number, requests: number, duration?: string | number): Promise<LimiterResponse>;
    /**
     * Delete a given key
     */
    delete(key: string | number): Promise<boolean>;
    /**
     * Delete all keys blocked within the memory
     */
    deleteInMemoryBlockedKeys(): void;
    /**
     * Get limiter response for a given key. Returns null when
     * key doesn't exist.
     */
    get(key: string | number): Promise<LimiterResponse | null>;
    /**
     * Find the number of remaining requests for a given key
     */
    remaining(key: string | number): Promise<number>;
    /**
     * Find the number of seconds remaining until the key will
     * be available for new request
     */
    availableIn(key: string | number): Promise<number>;
    /**
     * Find if the current key is blocked. This method checks
     * if the consumed points are equal to or greater than
     * the allowed limit.
     */
    isBlocked(key: string | number): Promise<boolean>;
    /**
     * Clear the storage database
     */
    clear(): Promise<void>;
}