@foundatiofx/fetchclient/types/src/RateLimiter.d.ts

A typed JSON fetch client with middleware support for Deno, Node and the browser.

/**
 * Per-group rate limiter options that can override the global options.
 */
export interface GroupRateLimiterOptions {
    /**
     * Maximum number of requests allowed per time window for this group.
     */
    maxRequests?: number;
    /**
     * Time window in milliseconds for this group.
     */
    windowSeconds?: number;
    /**
     * Callback function called when rate limit is exceeded for this group.
     * @param resetTime - Time when the rate limit will reset (in milliseconds since epoch)
     */
    onRateLimitExceeded?: (resetTime: number) => void;
}
/**
 * Configuration options for the rate limiter.
 */
export interface RateLimiterOptions {
    /**
     * Maximum number of requests allowed per time window.
     */
    maxRequests: number;
    /**
     * Time window in seconds.
     */
    windowSeconds: number;
    /**
     * Optional group generator function to create unique rate limit buckets.
     * If not provided, a global rate limit is applied.
     * @param url - The request URL
     * @returns A string group to identify the rate limit bucket
     */
    getGroupFunc?: (url: string) => string;
    /**
     * Callback function called when rate limit is exceeded.
     * @param resetTime - Time when the rate limit will reset (in milliseconds since epoch)
     */
    onRateLimitExceeded?: (resetTime: number) => void;
    /**
     * Optional group-specific rate limit options.
     * Map of group keys to their specific rate limit options.
     */
    groups?: Record<string, GroupRateLimiterOptions>;
}
/**
 * A rate limiter that tracks requests per time window.
 */
export declare class RateLimiter {
    private readonly options;
    private readonly buckets;
    private readonly groupOptions;
    constructor(options: RateLimiterOptions);
    /**
     * Checks if a request is allowed and updates the rate limit state.
     * @param url - The request URL
     * @returns True if the request is allowed, false if rate limit is exceeded
     */
    isAllowed(url: string): boolean;
    /**
     * Gets the current request count for a specific key.
     * @param url - The request URL
     * @returns The current number of requests in the time window
     */
    getRequestCount(url: string): number;
    /**
     * Gets the remaining requests allowed for a specific key.
     * @param url - The request URL
     * @returns The number of remaining requests allowed
     */
    getRemainingRequests(url: string): number;
    /**
     * Gets the time when the rate limit will reset for a specific key.
     * @param url - The request URL
     * @returns The reset time in milliseconds since epoch, or null if no bucket exists
     */
    getResetTime(url: string): number | null;
    /**
     * Clears the rate limit state for a specific key.
     * @param url - The request URL
     */
    clearBucket(url: string): void;
    /**
     * Gets the group key for a URL.
     * @param url - The request URL
     * @returns The group key
     */
    getGroup(url: string): string;
    /**
     * Gets the options for a specific group. Falls back to global options if not set.
     * @param group - The group key
     * @returns The options for the group
     */
    getGroupOptions(group: string): GroupRateLimiterOptions;
    /**
     * Checks if a group has specific options set.
     * @param group - The group key
     * @returns True if the group has options, false otherwise
     */
    hasGroupOptions(group: string): boolean;
    /**
     * Sets options for a specific group.
     * @param group - The group key
     * @param options - The options to set
     */
    setGroupOptions(group: string, options: GroupRateLimiterOptions): void;
    /**
     * Sets rate limit options for a request.
     * @param url - The request URL
     * @param options - The options to set for this group
     */
    setOptionsForRequest(url: string, options: GroupRateLimiterOptions): void;
    /**
     * Updates rate limit options for a request based on standard rate limit headers.
     * @param url - The request URL
     * @param method - The HTTP method
     * @param headers - The response headers containing rate limit information
     */
    updateFromHeadersForRequest(url: string, headers: Headers): void;
    /**
     * Updates rate limit options based on standard rate limit headers.
     * @param group - The group key
     * @param headers - The response headers containing rate limit information
     */
    updateFromHeaders(group: string, headers: Headers): void;
    /**
     * Clears all rate limit state.
     */
    clearAll(): void;
}
/**
 * Creates a group generator function that groups requests by domain only (no protocol).
 * @param url - The request URL
 * @returns A string representing the domain without protocol
 */
export declare function groupByDomain(url: string): string;
/**
 * IETF rate limit header information structure.
 */
export interface RateLimitInfo {
    /** The policy name/identifier */
    policy: string;
    /** Maximum requests allowed (quota) */
    limit: number;
    /** Remaining requests */
    remaining: number;
    /** Reset time in seconds from now */
    resetSeconds: number;
    /** Window duration in seconds */
    windowSeconds?: number;
}
/**
 * Creates an IETF standard RateLimit header value.
 * @param info - The rate limit information
 * @returns The formatted RateLimit header value
 */
export declare function buildRateLimitHeader(info: Omit<RateLimitInfo, "limit" | "windowSeconds">): string;
/**
 * Creates an IETF standard RateLimit-Policy header value.
 * @param info - The rate limit information
 * @returns The formatted RateLimit-Policy header value
 */
export declare function buildRateLimitPolicyHeader(info: Omit<RateLimitInfo, "remaining" | "resetSeconds">): string;
/**
 * Parses an IETF standard RateLimit header value.
 * @param headerValue - The RateLimit header value to parse
 * @returns The parsed rate limit information or null if invalid
 */
export declare function parseRateLimitHeader(headerValue: string): Partial<RateLimitInfo> | null;
/**
 * Parses an IETF standard RateLimit-Policy header value.
 * @param headerValue - The RateLimit-Policy header value to parse
 * @returns The parsed rate limit policy information or null if invalid
 */
export declare function parseRateLimitPolicyHeader(headerValue: string): Partial<RateLimitInfo> | null;
//# sourceMappingURL=RateLimiter.d.ts.map