@creejs/commons-retrier 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creejs/commons-retrier",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Common Utils About Task Retrying",
   "main": "index.js",
   "private": false,
@@ -10,6 +10,7 @@
     "types/",
     "README.md"
   ],
+  "types": "types/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -19,16 +20,12 @@
   },
   "scripts": {
     "dts": "tsc",
-    "generate-docs": "node_modules/.bin/jsdoc -c ./jsdoc.json"
+    "generate-docs": "../../node_modules/.bin/jsdoc -c ./jsdoc.json"
   },
   "author": "rodney.vin@gmail.com",
   "license": "Apache-2.0",
   "dependencies": {
-    "@creejs/commons-lang": "^1.0.0",
-    "@creejs/commons-events": "^1.0.0"
-  },
-  "devDependencies": {
-    "better-docs": "^2.7.3",
-    "jsdoc": "^4.0.4"
+    "@creejs/commons-events": "^2.0.0",
+    "@creejs/commons-lang": "^2.0.0"
   }
 }

package/types/alway-task.d.ts

@@ -0,0 +1,27 @@
+export = AlwaysTask;
+declare class AlwaysTask extends Task {
+    /**
+     * Checks if the given task is an instance of AlwaysTask.
+     * @param {*} task - The task to check.
+     * @returns {boolean} True if the task is an instance of AlwaysTask, false otherwise.
+     */
+    static isAlwaysTask(task: any): boolean;
+    /**
+     * Creates an AlwaysTask instance.
+     * @param {Retrier} retrier - The retrier instance to use for retry logic
+     * @param {Function} task - The task function to execute
+     * @param {boolean} resetRetryPolicyAfterSuccess - Whether to reset retry policy after successful execution
+     */
+    constructor(retrier: Retrier, task: Function, resetRetryPolicyAfterSuccess: boolean);
+    resetPolicy: boolean;
+    /**
+     * Executes the task with the given retry parameters.
+     * @param {number} retries - The number of retries attempted so far.
+     * @param {number} latence - The current latency ms.
+     * @param {number} nextInterval - The next interval ms.
+     * @returns {Promise<*>} The result of the task execution.
+     */
+    execute(retries: number, latence: number, nextInterval: number): Promise<any>;
+}
+import Task = require("./task");
+import Retrier = require("./retrier");

package/types/constants.d.ts

@@ -0,0 +1,3 @@
+export const DefaultMinInterval: 50;
+export const DefaultMaxInterval: number;
+export const DefaultMaxRetries: 3;

package/types/event.d.ts

@@ -0,0 +1,9 @@
+export const Start: "start";
+export const Retry: "retry";
+export const Success: "success";
+export const Failure: "failure";
+export const Timeout: "timeout";
+export const TaskTimeout: "task-timeout";
+export const Stop: "stop";
+export const Completed: "complete";
+export const MaxRetries: "max-retries";

package/types/index.d.ts

@@ -0,0 +1,25 @@
+declare const _exports: {
+    name: typeof RetrierFactory.name;
+    infinite: typeof RetrierFactory.infinite;
+    times: typeof RetrierFactory.times;
+    maxRetries: typeof RetrierFactory.maxRetries;
+    min: typeof RetrierFactory.min;
+    max: typeof RetrierFactory.max;
+    range: typeof RetrierFactory.range;
+    fixedInterval: typeof RetrierFactory.fixedInterval;
+    fixedIncrease: typeof RetrierFactory.fixedIncrease;
+    factorIncrease: typeof RetrierFactory.factorIncrease;
+    shuttleInterval: typeof RetrierFactory.shuttleInterval;
+    timeout: typeof RetrierFactory.timeout;
+    taskTimeout: typeof RetrierFactory.taskTimeout;
+    start: typeof RetrierFactory.start;
+    Policy: typeof Policy;
+    Retrier: typeof Retrier;
+    Event: typeof Event;
+    RetrierFactory: typeof RetrierFactory;
+};
+export = _exports;
+import RetrierFactory = require("./retrier-factory");
+import Policy = require("./policy");
+import Retrier = require("./retrier");
+import Event = require("./event");

package/types/policy/factor-increase-policy.d.ts

@@ -0,0 +1,12 @@
+export = FactoreIncreasePolicy;
+declare class FactoreIncreasePolicy extends Policy {
+    /**
+     * each call to _next() increases the interval by lastInterval * factor
+     * @param {number} factor - the increasement factor, >= 1
+     */
+    constructor(factor: number);
+    _factor: number;
+    set factor(factor: number);
+    get factor(): number;
+}
+import Policy = require("../policy");

package/types/policy/fixed-increase-policy.d.ts

@@ -0,0 +1,12 @@
+export = FixedIncreasePolicy;
+declare class FixedIncreasePolicy extends Policy {
+    /**
+     * each call to _next() increases the interval by "increasement".
+     * @param {number} increasement - The fixed interval (in milliseconds) between retry attempts.
+     */
+    constructor(increasement: number);
+    _increasement: number;
+    set increasement(increasement: number);
+    get increasement(): number;
+}
+import Policy = require("../policy");

package/types/policy/fixed-interval-policy.d.ts

@@ -0,0 +1,12 @@
+export = FixedIntervalPolicy;
+declare class FixedIntervalPolicy extends Policy {
+    /**
+     * Creates a fixed interval retry policy with the specified interval.
+     * @param {number} interval - The fixed interval (in milliseconds) between retry attempts.
+     */
+    constructor(interval: number);
+    _interval: number;
+    set interval(interval: number);
+    get interval(): number;
+}
+import Policy = require("../policy");

package/types/policy/shuttle-policy.d.ts

@@ -0,0 +1,13 @@
+export = ShuttlePolicy;
+declare class ShuttlePolicy extends Policy {
+    /**
+     * the inteval value shuttles between min and max
+     * @param {number} stepLength - the step length to change
+     */
+    constructor(stepLength: number);
+    _stepLength: number;
+    increasement: number;
+    set stepLength(stepLength: number);
+    get stepLength(): number;
+}
+import Policy = require("../policy");

package/types/policy.d.ts

@@ -0,0 +1,52 @@
+export = Policy;
+declare class Policy {
+    _min: number;
+    _max: number;
+    _nextInterval: number;
+    /**
+     * Copies settings to target policy.
+     * @param {Policy} targetPolicy - The policy to modify.
+     */
+    copyPolicySetting(targetPolicy: Policy): void;
+    /**
+     * Sets a fixed interval retry policy.
+    }
+  
+    /**
+     * 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 {this} 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): this;
+    /**
+     * Sets the minimum retry delay in milliseconds.
+     * 1. will change currentInterval to min
+     * @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;
+    reset(): this;
+    /**
+     * Interval ms of next execution
+     * @returns {number}
+     * @throws {Error} Always throws "Not Implemented Yet" error.
+     */
+    generate(): number;
+    _increase(): number;
+    /**
+     * subclass should implement this method
+     * @returns {number} The interval in milliseconds to wait before the next retry attempt.
+     * @protected
+     */
+    protected _next(): number;
+}

package/types/retrier-factory.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+export function name(name: string): Retrier;
+/**
+ * Creates and returns a Retrier instance configured for infinite retries.
+ * @returns {Retrier} A Retrier instance with infinite retry behavior.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function fixedInterval(fixedInterval: 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.
+ */
+export function fixedIncrease(increasement: 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.
+ */
+export function factorIncrease(factor: 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.
+ */
+export function 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.
+ */
+export function 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.
+ */
+export function 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 function to be retried.
+ * @returns {Promise<*>} A promise that resolves when the retry process completes.
+ */
+export function start(task: Function): Promise<any>;
+import Retrier = require("./retrier");

package/types/retrier.d.ts

@@ -0,0 +1,233 @@
+export = Retrier;
+/**
+ * @extends EventEmitter
+ */
+declare class Retrier {
+    /**
+     * 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 {{resolve:Function, reject:Function, promise: Promise<*>}|undefined}
+     */
+    _taskingFlag: {
+        resolve: Function;
+        reject: Function;
+        promise: Promise<any>;
+    } | undefined;
+    /**
+     *  A Deferred Object as Singal to prevent Task concurrent stop
+     * @type {{resolve:Function, reject:Function, promise: Promise<*>}|undefined}
+     */
+    _breakFlag: {
+        resolve: Function;
+        reject: Function;
+        promise: Promise<any>;
+    } | 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 {Object} The retrier instance for chaining.
+     */
+    infinite(): Object;
+    /**
+     * 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 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 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;
+    /**
+     * 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 {Object} The retrier instance for chaining.
+     */
+    taskTimeout(timeout: number): Object;
+    /**
+     * 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 {Object} The retrier instance for chaining.
+     */
+    timeout(timeout: number): Object;
+    /**
+     * 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: 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=false] - Whether to reset retry counters after success.
+     * @returns {this} The Retrier instance for chaining.
+     */
+    always(task: Function, resetAfterSuccess?: boolean): this;
+    /**
+     * Starts the retry process.
+     * @returns {Promise<*>}
+     */
+    start(): Promise<any>;
+    /**
+     * 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;
+}
+import Policy = require("./policy");
+import Task = require("./task");
+import AlwaysTask = require("./alway-task");

package/types/task.d.ts

@@ -0,0 +1,28 @@
+export = Task;
+declare class Task {
+    /**
+     * Creates a new Task instance.
+     * @param {Retrier} retrier - The retrier instance.
+     * @param {Function} task - The function to be executed as the task.
+     */
+    constructor(retrier: Retrier, task: Function);
+    retrier: Retrier;
+    task: Function;
+    result: any;
+    error: unknown;
+    get failed(): boolean;
+    get succeeded(): boolean;
+    /**
+     * Executes the task with the given retry parameters.
+     * 1. if execution throw error, keep error in this.error
+     * 2. if execution return value, keep it in this.result
+     * 3. always return Promise<void>
+     * @param {number} retries - The number of retries attempted so far.
+     * @param {number} latence - The current latency ms.
+     * @param {number} nextInterval - The next interval ms.
+     * @returns {Promise<void>} The result of the task execution.
+     */
+    execute(retries: number, latence: number, nextInterval: number): Promise<void>;
+    dispose(): void;
+}
+import Retrier = require("./retrier");