Type Alias IRateLimiterPolicy<TMetrics>

IRateLimiterPolicy: {
    getAttempts(currentMetrics: TMetrics, currentDate: Date): number;
    getExpiration(currentMetrics: TMetrics, currentDate: Date): Date;
    initialMetrics(currentDate: Date): TMetrics;
    shouldBlock(
        currentMetrics: TMetrics,
        limit: number,
        currentDate: Date,
    ): boolean;
    updateMetrics(currentMetrics: TMetrics, currentDate: Date): TMetrics;
}

Policy contract defining the rate limiting algorithm and metrics tracking. Implements the algorithm logic that determines when requests should be allowed or blocked.

All methods in this contract must be pure functions (no side effects, no mutations of input data). Implementations should return new copies of metrics rather than modifying the input. This allows the rate limiter to be stateless and thread-safe.

IMPORT_PATH: "@daiso-tech/core/rate-limiter/contracts"

Type Parameters

  • TMetrics = unknown

    The type of metrics object used to track rate limiter state (e.g., attempt counts, timestamps)

Type declaration

  • getAttempts:function
    • getAttempts(currentMetrics: TMetrics, currentDate: Date): number

    • Extracts the number of attempts used from the current metrics. Used by the adapter to provide state information to callers. This is the current attempt count within the configured limit.

      Parameters

      • currentMetrics: TMetrics

        The current tracking metrics

      • currentDate: Date

        Current date/time for calculations (e.g., accounting for expired requests)

      Returns number

      Number of attempts consumed in the current window

  • getExpiration:function
    • getExpiration(currentMetrics: TMetrics, currentDate: Date): Date

    • Calculates the expiration date for the current metrics. Determines when the rate limiter state should be automatically cleaned up.

      This method is critical for persistence: data persisted beyond this date should be deleted. If this method returns a date in the past, the adapter should treat the rate limiter as expired and allow requests with fresh metrics calculation.

      Common patterns:

      • Fixed-window: Return date of window end (e.g., start + duration)
      • Sliding-window: Return earliest tracked request + duration

      Parameters

      • currentMetrics: TMetrics

        The current tracking metrics

      • currentDate: Date

        Current date/time for calculating expiration

      Returns Date

      Date when this rate limiter state should expire and be cleaned up

  • initialMetrics:function
    • initialMetrics(currentDate: Date): TMetrics

    • Creates initial metrics for a new rate limiter. Called when initializing a rate limiter for the first time or after expiration. Should set up the data structures needed to track attempts in the current window.

      Parameters

      • currentDate: Date

        Current date/time for initializing window boundaries

      Returns TMetrics

      Fresh metrics object ready to track attempts

  • shouldBlock:function
    • shouldBlock(currentMetrics: TMetrics, limit: number, currentDate: Date): boolean

    • Determines if the rate limiter should block the current request. Evaluates current metrics against the configured limit. Returns true if the attempt limit has been exceeded (request should be blocked).

      Parameters

      • currentMetrics: TMetrics

        The current tracking metrics

      • limit: number

        Maximum allowed attempts in the window

      • currentDate: Date

        Current date/time for window boundary checks

      Returns boolean

      true if request should be blocked, false if allowed

  • updateMetrics:function
    • updateMetrics(currentMetrics: TMetrics, currentDate: Date): TMetrics

    • Updates metrics to record a new attempt. Called each time a request is evaluated by the rate limiter. Must return a new metrics object; the input should not be mutated.

      The returned metrics are stored and used for subsequent evaluations. For persistent storage, this updated state is serialized and persisted.

      Parameters

      • currentMetrics: TMetrics

        The metrics before this attempt

      • currentDate: Date

        Current date/time for the attempt

      Returns TMetrics

      New metrics object with the attempt recorded

Settings

Member Visibility