@creejs/commons-retrier/types/retrier.d.ts

Common Utils About Task Retrying

/**
 * @extends EventEmitter
 */
export default class Retrier {
    /**
     * Creates a new Retrier instance with the specified name.
     * @param {string} name - The name to assign to the retrier.
     * @returns {Retrier} A new Retrier instance with the given name.
     */
    static naming(name: string): Retrier;
    /**
   * Creates and returns a Retrier instance configured for infinite retries.
   * @returns {Retrier} A Retrier instance with infinite retry behavior.
   */
    static infinite(): Retrier;
    /**
   * Creates a retrier configured to attempt an operation a specified number of times.
   * @param {number} times - The maximum number of retry attempts.
   * @returns {Retrier} A configured Retrier instance with the specified max retries.
   */
    static times(times: number): Retrier;
    /**
   * Alias for times.
   * @param {number} maxRetries - The maximum number of retry attempts.
   * @returns {Retrier} A configured Retrier instance with the specified max retries.
   */
    static maxRetries(maxRetries: number): Retrier;
    /**
   * Sets the minimum Interval for the retrier and returns the instance.
   * @param {number} min - The minimum Interval in milliseconds.
   * @returns {Retrier} The retrier instance with updated minimum Interval.
   */
    static min(min: number): Retrier;
    /**
   * Sets the maximum Interval for the retrier and returns the instance.
   * @param {number} max - The maximum Interval in milliseconds.
   * @returns {Retrier} The retrier instance with updated maximum Interval.
   */
    static max(max: number): Retrier;
    /**
   * Creates a retrier with the specified Interval range.
   * @param {number} min - Minimum Interval.
   * @param {number} max - Maximum Interval.
   * @returns {Retrier} A new Retrier instance configured with specified Interval range.
   */
    static range(min: number, max: number): Retrier;
    /**
   * Creates a retrier with a fixed interval between attempts.
   * @param {number} fixedInterval - The fixed interval in milliseconds between retry attempts.
   * @returns {Retrier} A new Retrier instance configured with the specified fixed interval.
   */
    static fixedInterval(fixedInterval: number): Retrier;
    /**
   * Creates a retrier with a fixed backoff strategy.
   * @param {number} fixedInterval - The fixed interval between retries in milliseconds.
   * @param {number} [jitter=500] - The maximum jitter to add to the interval in milliseconds.
   * @returns {Retrier} A retrier instance configured with fixed backoff.
   */
    static fixedBackoff(fixedInterval: number, jitter?: number): Retrier;
    /**
   * Creates a retrier with a fixed increase strategy.
   * @param {number} increasement - The fixed amount to increase on each retry.
   * @returns {Retrier} A retrier instance configured with fixed increase.
   */
    static fixedIncrease(increasement: number): Retrier;
    /**
   * Creates a retrier with a fixed increase strategy.
   * @param {number} increasement - The fixed amount to increase on each retry.
   * @param {number} [jitter=500] - The maximum jitter to add to the interval in milliseconds.
   * @returns {Retrier} A retrier instance configured with fixed increase.
   */
    static linearBackoff(increasement: number, jitter?: number): Retrier;
    /**
   * Creates a new Retrier instance with factor-increase strategy.
   * @param {number} factor - The factor by which to increase the interval on each retry.
   * @returns {Retrier} A new Retrier instance with factor-increase strategy.
   */
    static factorIncrease(factor: number): Retrier;
    /**
   * Creates a new Retrier instance with exponential-backoff strategy.
   * @param {number} [jitter=500]
   * @returns {Retrier} A new Retrier instance
   */
    static exponentialBackoff(jitter?: number): Retrier;
    /**
   * Creates a Retrier instance with a shuttle-interval strategt.
   * @param {number} stepLength - The interval step length of each change
   * @returns {Retrier} A configured Retrier instance with shuttle-interval strategt.
   */
    static shuttleInterval(stepLength: number): Retrier;
    /**
   * Creates a Retrier instance with a total-opertion timeout.
   * @param {number} timeout - The timeout value in milliseconds.
   * @returns {Retrier} A Retrier instance configured with the given timeout.
   */
    static timeout(timeout: number): Retrier;
    /**
   * Creates a retrier instance with a single-task timeout.
   * @param {number} timeout - The timeout duration in milliseconds for the retrier task.
   * @returns {Retrier} A Retrier instance configured with the given task timeout.
   */
    static taskTimeout(timeout: number): Retrier;
    /**
   * Creates a new Retrier instance, sets the task to be retried, and starts the retry process.
   * @param {Function} task - The asynchronous task static to be retried.
   * @returns {Promise<*>} A promise that resolves when the retry process completes.
   */
    static start(task: Function): Promise<any>;
    /**
     * Creates a new Retrier instance with a fixed interval policy.
     * @param {number} [fixedInterval=1000] - The fixed interval in milliseconds between retry attempts. Defaults to 1000ms if not provided.
     */
    constructor(fixedInterval?: number);
    /**
     * @type {Policy}
     */
    _policy: Policy;
    _maxRetries: number;
    _currentRetries: number;
    /**
     * Timetou for total operation
     * @type {number}
     */
    _timeout: number;
    /**
     * Timetou for single task
     */
    _taskTimeout: number;
    _name: string;
    /**
     * A Deferred Object as Singal to prevent Task concurrent start
     * @type {Deferred|undefined}
     */
    _taskingFlag: Deferred | undefined;
    /**
     *  A Deferred Object as Singal to prevent Task concurrent stop
     * @type {Deferred|undefined}
     */
    _breakFlag: Deferred | undefined;
    /**
     * Reason for break
     * @type {Error|undefined}
     */
    _breakReason: Error | undefined;
    get running(): boolean;
    /**
     * Sets the name of the retrier.
     * @param {string} retrierName - The name to assign to the retrier.
     * @returns {this} The retrier instance for chaining.
     */
    name(retrierName: string): this;
    /**
     * Sets the retry attempts to be infinite by setting max retries to maximum safe integer.
     * @returns {this} The retrier instance for chaining.
     */
    infinite(): this;
    /**
     * Sets the maximum number of retry attempts.
     * @param {number} times - The maximum number of retries.
     * @returns {this} The Retrier instance for chaining.
     */
    times(times: number): this;
    /**
     * Sets the maximum number of retry attempts.
     * @param {number} maxRetries - The maximum number of retries (must be positive).
     * @returns {this} The retrier instance for chaining.
     */
    maxRetries(maxRetries: number): this;
    /**
     * Sets the minimum retry delay in milliseconds.
     * @param {number} min - The minimum delay (must be positive and less than max).
     * @returns {this} The retrier instance for chaining.
     * @throws {Error} If min is not positive or is greater than/equal to max.
     */
    min(min: number): this;
    /**
     * Sets the maximum retry retry delay in milliseconds.
     * @param {number} max - The maximum delay (must be positive and greater than min).
     * @throws {Error} If max is not greater than min.
     * @returns {this} The retrier instance for chaining.
     */
    max(max: number): this;
    /**
     * Sets the minimum and maximum intervals for retries.
     * @param {number} min - Minimum delay in milliseconds (must be positive and less than max)
     * @param {number} max - Maximum delay in milliseconds (must be positive and greater than min)
     * @returns {Retrier} Returns the Retrier instance for chaining
     * @throws {Error} If min is not less than max or if values are not positive
     */
    range(min: number, max: number): Retrier;
    /**
     * Sets a fixed interval retry policy.
     * @param {number} fixedInterval - The fixed interval in milliseconds between retries.
     * @returns {Retrier} The Retrier instance for chaining.
     */
    fixedInterval(fixedInterval: number): Retrier;
    /**
     * sets a fixed backoff strategy.
     * @param {number} fixedInterval - The fixed interval between retries in milliseconds.
     * @param {number} [jitter=500] - The maximum jitter to add to the interval in milliseconds.
     * @returns {Retrier} A retrier instance configured with fixed backoff.
     */
    fixedBackoff(fixedInterval: number, jitter?: number): Retrier;
    /**
     * Sets a fixed increase policy for retry intervals.
     * @param {number} increasement - The fixed amount to increase the interval by on each retry.
     * @returns {this} The retrier instance for chaining.
     */
    fixedIncrease(increasement: number): this;
    /**
     * Sets a fixed increase policy for retry intervals.
     * @param {number} increasement - The fixed amount to increase the interval by on each retry.
     * @param {number} [jitter=500] - The maximum jitter to add to the interval in milliseconds.
     * @returns {this} The retrier instance for chaining.
     */
    linearBackoff(increasement: number, jitter?: number): this;
    /**
     * Sets a fixed increase factor for retry delays.
     * @param {number} factor - The multiplier for delay increase between retries.
     * @returns {this} The retrier instance for method chaining.
     */
    factorIncrease(factor: number): this;
    /**
     * Creates a new Retrier instance with exponential-backoff strategy.
     * @param {number} [jitter]
     * @returns {Retrier} A new Retrier instance
     */
    exponentialBackoff(jitter?: number): Retrier;
    /**
     * Sets a shuttle retry policy with the given step length.
     * @param {number} stepLength - The interval between retry attempts.
     * @returns {this} The Retrier instance for chaining.
     */
    shuttleInterval(stepLength: number): this;
    /**
     * Sets the timeout duration for each Task execution.
     * 1. must > 0
     * @param {number} timeout - The timeout duration in milliseconds.
     * @returns {this} The retrier instance for chaining.
     */
    taskTimeout(timeout: number): this;
    /**
     * Sets the timeout duration for all retries.
     * 1. <= 0 - no timeout
     * 2. \> 0 - timeout duration in milliseconds
     * @param {number} timeout - The timeout duration in milliseconds.
     * @returns {this} The retrier instance for chaining.
     */
    timeout(timeout: number): this;
    /**
     * Disables the timeout for the retrier.
     * @returns {this} The retrier instance for chaining.
     */
    noTimeout(): this;
    /**
     * Sets the task function to be retried.
     * @param {Function} task - The function to be executed and retried on failure.
     * @returns {this} Returns the retrier instance for chaining.
     */
    task(task: Function): this;
    _task: ForeverTask | Task | AlwaysTask | undefined;
    /**
     * alias of {@linkcode Retrier.task()}
     * @param {Function} task - The function to be executed and retried
     * @return {this}
     */
    retry(task: Function): this;
    /**
     * Executes the given task, and never stop
     * 1. if the task fails, will retry it after the interval generated by RetryPolicy
     * 2. if the task succeeds, reset RetryPolicy to Minimum Interval and continue to run the task
     * @param {Function} task - The async function to execute and retry.
     * @param {boolean} [resetAfterSuccess=true] - Whether to reset retry counters after success.
     * @returns {this} The Retrier instance for chaining.
     */
    always(task: Function, resetAfterSuccess?: boolean): this;
    /**
     *The task will execute forever despite of failure or success.
     * 1. call notimeout(), override and ignore Retrier total timeout setting
     * 2. call infinite(), override and ignore Retrier max retries setting
     * @param {Function} task
     * @param {boolean} [resetAfterSuccess=true]
     * @returns
     */
    forever(task: Function, resetAfterSuccess?: boolean): this;
    /**
     * Starts the retry process.
     * @returns {Promise<*>}
     */
    start(): Promise<any>;
    /**
     * Force an execution immediately.
     */
    wakeup(): void;
    /**
     * Stops the retrier with an optional reason. If already stopping, returns the existing break promise.
     * @param {Error} [reason] - Optional reason for stopping (defaults to 'Manually Stop' error).
     * @returns {Promise<void>} A promise that resolves when the retrier has fully stopped.
     */
    stop(reason?: Error): Promise<void>;
    /**
     * Resets the retry policy to its initial state.
     */
    resetRetryPolicy(): void;
    /**
     * Registers a listener function to be called on "retry" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onRetry(listener: Function): this;
    /**
     * Registers a listener for "error" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onError(listener: Function): this;
    /**
     * Registers a listener for "failure" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onFailure(listener: Function): this;
    /**
     * Registers a listener for "success" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onSuccess(listener: Function): this;
    /**
     * Registers a listener for "start" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onStart(listener: Function): this;
    /**
     * Registers a listener for "stop" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onStop(listener: Function): this;
    /**
     * Registers a listener for "timeout" events.
     * @param {Function} listener - The callback function
     */
    onTimeout(listener: Function): this;
    /**
     * Registers a listener for "task-timeout" events.
     * @param {Function} listener - The callback function
     * @returns {this}
     */
    onTaskTimeout(listener: Function): this;
    /**
     * Registers a listener for "completed" events.
     * @param {Function} listener - The callback function
     */
    onCompleted(listener: Function): this;
    /**
     * Registers a listener for the 'MaxRetries' event.
     * @param {Function} listener - The callback function to be executed when max retries are reached.
     * @returns {this}
     */
    onMaxRetries(listener: Function): this;
    /**
     *
     * @param {Task} task
     * @returns {Promise<void>}
     */
    _executeForeverTask(task: Task): Promise<void>;
    _sleepWaiter: import("@creejs/commons-lang/types/promise-utils").Waiter | undefined;
    /**
     * @param {Task} task
     * @returns {Promise<any>}
     */
    _executeEndableTask(task: Task): Promise<any>;
    /**
     * Assert if can change param's value
     * @param {string} param
     */
    _assertChangeable(param: string): void;
}
export type Policy = import("./policy.js").default;
export type Deferred = import("@creejs/commons-lang/types/promise-utils").Deferred;
import ForeverTask from './forever-task.js';
import Task from './task.js';
import AlwaysTask from './alway-task.js';