@creejs/commons-retrier 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# @creejs/commons-retrier
+
+Commons-retrier Library provides a Retrier to:
+
+- **Retry a task until it matches your want**
+
+- **Options**:
+
+  - **Times**
+
+    The max retires, how many times can we try?
+
+  - **Intervals**
+
+    After a retrying, what delay should we waiting for?
+
+    - **Minimum Interval**
+    - **Maximum Interval**
+    - **Change Policy**
+      - **Fixed Interval Policy**
+      - **Fixed Increase Policy**
+      - **Factor Increase Policy**
+      - **Shuttle Policy**
+
+  - **Timeout**
+
+    After the "timeout", whole retries will failed with last error
+
+  - **TaskTimeout**
+
+    Timeout of one Task execution
+
+And it supports two types of usage:
+
+1. **retry(task)**
+
+   Run the task at intervals, until the task succeeds.
+
+2. **always(task)**
+
+   Always run the task again and again, despit it fails or succeeds, until reaching the maxRetries, or total timeout
+
+## Install
+
+```shell
+npm intall @creejs/commons-retrier
+```
+
+## Usage
+
+1. retry(task)
+
+   ```javascript
+   'use strict'
+   const { Retrier } = require('@creejs/commons-retrier')
+   
+   // Chainable API to create and initialize Retrier
+   const retrier = Retrier.infinite() // no retry limit
+     .min(100) // min interval, 100ms
+     .max(300) // max interval, 300ms
+     .fixedIncrease(20) // each call, increase interval by 20ms
+   
+   // Task function to be retried
+   const task = (retries, latency) => {
+     if (retries <= 3) { // failed 3 times
+       throw new Error('Task failed') // fails, if throw error, or reject promise
+     }
+     return 'success' // succeed at 4th try
+   }
+   // will end retries when first successfully call happens
+   (async () => {
+     try {
+       const rtnVal = await retrier.task(task).start()
+       console.log(rtnVal)
+       // --> success
+     } catch (err) {
+       console.log(err)
+     }
+   })()
+   ```
+
+   
+
+2. always(task)
+
+   ```javas
+   'use strict'
+   
+   const { Retrier } = require('@creejs/commons-retrier')
+   
+   // Chainable API to create and initialize Retrier
+   const retrier = Retrier.times(4) // max retry 4 times
+     .min(100) // min interval, 100ms
+     .max(300) // max interval, 300ms
+     .fixedIncrease(20) // each call, increase interval by 20ms
+     .onSuccess((taskResult, retries, latency) => {
+       console.log(taskResult)
+     })
+     .onFailure((err, retries, latency) => {
+       console.error(err.message)
+     })
+     .onMaxRetries((nextRetries, maxRetries) => {
+       console.error(`Max retries reached, ${nextRetries} > maxRetries ${maxRetries}`)
+     })
+   
+   // Task function to be retried
+   const task = (retries, latency) => {
+     // succeed at 1, 2 try
+     if (retries <= 2) {
+       return `Latency ${latency}ms, Task succeeded at ${retries} try`
+     }
+     // fails at 3, 4 try, if throw error, or reject promise
+     throw new Error(`Latency ${latency}ms, Task failed at ${retries} try`)
+   }
+   
+   // will end retries when reach max retries
+   (async () => {
+     try {
+       await retrier.always(task).start()
+   
+       console.log('Finished All Retries')
+       // --> Latency 0ms, Task succeeded at 1 try
+       // --> 105ms, Task succeeded at 2 try
+       // --> Latency 228ms, Task failed at 3 try
+       // --> Latency 370ms, Task failed at 4 try
+       // --> Max retries reached, 5 > maxRetries 4
+       // --> Finished All Retries
+     } catch (err) {
+       console.log(err)
+     }
+   })()
+   ```
+
+   

package/index.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('./lib')

package/lib/alway-task.js

@@ -0,0 +1,44 @@
+'use strict'
+
+// owned
+// eslint-disable-next-line no-unused-vars
+const Retrier = require('./retrier')
+const Task = require('./task')
+
+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) {
+    return task instanceof AlwaysTask
+  }
+
+  /**
+   * 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, task, resetRetryPolicyAfterSuccess) {
+    super(retrier, task)
+    this.resetPolicy = resetRetryPolicyAfterSuccess
+  }
+
+  /**
+   * 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.
+   */
+  async execute (retries, latence, nextInterval) {
+    await super.execute(retries, latence, nextInterval)
+    if (this.succeeded && this.resetPolicy) {
+      this.retrier.resetRetryPolicy()
+    }
+  }
+}
+
+module.exports = AlwaysTask

package/lib/constants.js

@@ -0,0 +1,11 @@
+'use strict'
+// module vars
+const DefaultMinInterval = 50
+const DefaultMaxInterval = 30 * 1000 // 30s
+
+const DefaultMaxRetries = 3
+module.exports = {
+  DefaultMinInterval,
+  DefaultMaxInterval,
+  DefaultMaxRetries
+}

package/lib/event.js

@@ -0,0 +1,22 @@
+'use strict'
+const Start = 'start' // retry started
+const Stop = 'stop' // retry stopped
+const Retry = 'retry' // one retry began
+const Success = 'success' // one task running succeeded
+const Failure = 'failure' // one task ran failed
+const Timeout = 'timeout' // total timeout
+const TaskTimeout = 'task-timeout' // one task timed out
+const Completed = 'complete' // all retries completed
+const MaxRetries = 'max-retries' // Reach the max retries
+
+module.exports = {
+  Start,
+  Retry,
+  Success,
+  Failure,
+  Timeout,
+  TaskTimeout,
+  Stop,
+  Completed,
+  MaxRetries
+}

package/lib/index.js

@@ -0,0 +1,28 @@
+'use strict'
+// 3rd
+const { LangUtils } = require('@creejs/commons-lang')
+
+// owned
+const Policy = require('./policy')
+const Retrier = require('./retrier')
+const Event = require('./event')
+const RetrierFactory = require('./retrier-factory')
+
+/**
+ * Add all factory methods to Retrier as static methods.
+ * Now we can create do something like this:
+ * ```
+ * Retrier.name('myRetrier')
+ * Retrier.infinite()
+ * ...
+ * ```
+ */
+LangUtils.defaults(Retrier, RetrierFactory)
+
+module.exports = {
+  Policy,
+  Retrier,
+  Event,
+  RetrierFactory,
+  ...RetrierFactory
+}

package/lib/policy/factor-increase-policy.js

@@ -0,0 +1,46 @@
+'use strict'
+// 3rd
+// internal
+const { TypeAssert: { assertPositive } } = require('@creejs/commons-lang')
+// owned
+const Policy = require('../policy')
+
+class FactoreIncreasePolicy extends Policy {
+  /**
+   * each call to _next() increases the interval by lastInterval * factor
+   * @param {number} factor - the increasement factor, >= 1
+   */
+  constructor (factor) {
+    super()
+    assertPositive(factor, 'factor')
+    if (factor < 1) {
+      throw new Error('factor must be >= 1')
+    }
+    this._factor = factor
+  }
+
+  set factor (factor) {
+    assertPositive(factor, 'factor')
+    if (factor < 1) {
+      throw new Error('factor must be >= 1')
+    }
+    this._factor = factor
+  }
+
+  get factor () {
+    return this._factor
+  }
+
+  /**
+   * Interval ms of next execution
+   * @returns {number}
+   */
+  _next () {
+    if (this._nextInterval >= this._max) {
+      return this._max
+    }
+    return this._nextInterval * this.factor
+  }
+}
+
+module.exports = FactoreIncreasePolicy

package/lib/policy/fixed-increase-policy.js

@@ -0,0 +1,40 @@
+'use strict'
+// 3rd
+// internal
+const { TypeAssert: { assertPositive } } = require('@creejs/commons-lang')
+// owned
+const Policy = require('../policy')
+
+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) {
+    super()
+    assertPositive(increasement, 'increasement')
+    this._increasement = increasement
+  }
+
+  set increasement (increasement) {
+    assertPositive(increasement, 'increasement')
+    this._increasement = increasement
+  }
+
+  get increasement () {
+    return this._increasement
+  }
+
+  /**
+   * Interval ms of next execution
+   * @returns {number}
+   */
+  _next () {
+    if (this._nextInterval >= this._max) {
+      return this._max
+    }
+    return this._nextInterval + this.increasement
+  }
+}
+
+module.exports = FixedIncreasePolicy

package/lib/policy/fixed-interval-policy.js

@@ -0,0 +1,38 @@
+'use strict'
+// 3rd
+// internal
+const { TypeAssert: { assertPositive } } = require('@creejs/commons-lang')
+// owned
+const Policy = require('../policy')
+
+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) {
+    super()
+    assertPositive(interval, 'interval')
+    this._interval = interval
+  }
+
+  set interval (interval) {
+    assertPositive(interval, 'interval')
+    this._interval = interval
+  }
+
+  get interval () {
+    return this._interval
+  }
+
+  /**
+   * Interval ms of next execution
+   * @returns {number}
+   * @throws {Error} Always throws "Not Implemented Yet" error.
+   */
+  _next () {
+    return this.interval
+  }
+}
+
+module.exports = FixedIntervalPolicy

package/lib/policy/shuttle-policy.js

@@ -0,0 +1,49 @@
+'use strict'
+// 3rd
+// internal
+const { TypeAssert: { assertPositive } } = require('@creejs/commons-lang')
+
+// owned
+const Policy = require('../policy')
+
+class ShuttlePolicy extends Policy {
+  /**
+   * the inteval value shuttles between min and max
+   * @param {number} stepLength - the step length to change
+   */
+  constructor (stepLength) {
+    super()
+    assertPositive(stepLength, 'stepLength')
+    this._stepLength = stepLength
+    this.increasement = stepLength
+  }
+
+  set stepLength (stepLength) {
+    assertPositive(stepLength, 'stepLength')
+    this._stepLength = stepLength
+    this.increasement = stepLength
+  }
+
+  get stepLength () {
+    return this._stepLength
+  }
+
+  /**
+   * Interval ms of next execution
+   * @returns {number}
+   * @throws {Error} Always throws "Not Implemented Yet" error.
+   */
+  _next () {
+    const nextInterval = this._nextInterval + this.increasement
+    if (nextInterval >= this._max) {
+      this.increasement = -this.stepLength
+      return this._max
+    } else if (nextInterval <= this._min) {
+      this.increasement = this.stepLength
+      return this._min
+    }
+    return nextInterval
+  }
+}
+
+module.exports = ShuttlePolicy

package/lib/policy.js

@@ -0,0 +1,131 @@
+'use strict'
+// internal
+const {
+  TypeAssert: { assertPositive },
+  TypeUtils: { isNumber }
+} = require('@creejs/commons-lang')
+// owned
+const { DefaultMaxInterval, DefaultMinInterval } = require('./constants')
+// module vars
+
+class Policy {
+  /**
+   * Creates a new Policy instance with specified retry bounds.
+   */
+  constructor () {
+    this._min = DefaultMinInterval
+    this._max = DefaultMaxInterval
+    this._nextInterval = this._min
+  }
+
+  /**
+   * Copies settings to target policy.
+   * @param {Policy} targetPolicy - The policy to modify.
+   */
+  copyPolicySetting (targetPolicy) {
+    targetPolicy.range(this._min, this._max)
+    targetPolicy._nextInterval = this._nextInterval
+  }
+
+  /**
+   * 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, max) {
+    assertPositive(min, 'min')
+    assertPositive(max, 'max')
+    if (min >= max) {
+      throw new Error('min must < max')
+    }
+    this._min = min
+    if (this._nextInterval < this._min) {
+      this._nextInterval = this._min
+    }
+    this._max = max
+    if (this._nextInterval > this._max) {
+      this._nextInterval = this._max
+    }
+    return 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) {
+    assertPositive(min, 'min')
+    if (min >= this._max) {
+      throw new Error('min must < max')
+    }
+    this._min = min
+    this._nextInterval = this._min
+    return 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) {
+    assertPositive(max, 'max')
+    if (max <= this._min) {
+      throw new Error('max must > min')
+    }
+    this._max = max
+    if (this._nextInterval > this._max) {
+      this._nextInterval = this._max
+    }
+    return this
+  }
+
+  reset () {
+    this._nextInterval = this._min
+    return this
+  }
+
+  /**
+   * Interval ms of next execution
+   * @returns {number}
+   * @throws {Error} Always throws "Not Implemented Yet" error.
+   */
+  generate () {
+    const rtnVal = this._nextInterval
+    this._increase()
+    return rtnVal
+  }
+
+  _increase () {
+    const nextInterval = this._next()
+    if (!isNumber(nextInterval)) {
+      throw new Error('Generated Next Interval Not Number')
+    }
+    if (nextInterval < this._min) {
+      return (this._nextInterval = this._min)
+    } else if (nextInterval > this._max) {
+      return (this._nextInterval = this._max)
+    }
+    return (this._nextInterval = nextInterval)
+  }
+
+  /**
+   * subclass should implement this method
+   * @returns {number} The interval in milliseconds to wait before the next retry attempt.
+   * @protected
+   */
+  _next () {
+    throw new Error('Not Impled Yet')
+  }
+}
+module.exports = Policy

package/lib/retrier-factory.js

@@ -0,0 +1,173 @@
+'use strict'
+// owned
+const Retrier = require('./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.
+ */
+function name (name) {
+  const retrier = new Retrier()
+  retrier.name(name)
+  return retrier
+}
+
+/**
+ * Creates and returns a Retrier instance configured for infinite retries.
+ * @returns {Retrier} A Retrier instance with infinite retry behavior.
+ */
+function infinite () {
+  const retrier = new Retrier()
+  retrier.infinite()
+  return 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.
+ */
+function times (times) {
+  const retrier = new Retrier()
+  retrier.times(times)
+  return retrier
+}
+
+/**
+ * Alias for times.
+ * @param {number} maxRetries - The maximum number of retry attempts.
+ * @returns {Retrier} A configured Retrier instance with the specified max retries.
+ */
+function maxRetries (maxRetries) {
+  const retrier = new Retrier()
+  retrier.maxRetries(maxRetries)
+  return 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.
+ */
+function min (min) {
+  const retrier = new Retrier()
+  retrier.min(min)
+  return 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.
+ */
+function max (max) {
+  const retrier = new Retrier()
+  retrier.max(max)
+  return 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.
+ */
+function range (min, max) {
+  const retrier = new Retrier()
+  retrier.range(min, max)
+  return 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.
+ */
+function fixedInterval (fixedInterval) {
+  const retrier = new Retrier()
+  retrier.fixedInterval(fixedInterval)
+  return 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.
+ */
+function fixedIncrease (increasement) {
+  const retrier = new Retrier()
+  retrier.fixedIncrease(increasement)
+  return 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.
+ */
+function factorIncrease (factor) {
+  const retrier = new Retrier()
+  retrier.factorIncrease(factor)
+  return 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.
+ */
+function shuttleInterval (stepLength) {
+  const retrier = new Retrier()
+  retrier.shuttleInterval(stepLength)
+  return 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.
+ */
+function timeout (timeout) {
+  const retrier = new Retrier()
+  retrier.timeout(timeout)
+  return 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.
+ */
+function taskTimeout (timeout) {
+  const retrier = new Retrier()
+  retrier.taskTimeout(timeout)
+  return 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.
+ */
+function start (task) {
+  const retrier = new Retrier()
+  retrier.task(task)
+  return retrier.start()
+}
+
+module.exports = {
+  name,
+  infinite,
+  times,
+  maxRetries,
+  min,
+  max,
+  range,
+  fixedInterval,
+  fixedIncrease,
+  factorIncrease,
+  shuttleInterval,
+  timeout,
+  taskTimeout,
+  start
+}

package/lib/retrier.js

@@ -0,0 +1,534 @@
+'use strict'
+
+// internal
+const {
+  TypeAssert: { assertPositive, assertString, assertFunction, assertNumber },
+  TypeUtils: { isNil },
+  PromiseUtils
+} = require('@creejs/commons-lang')
+const { EventEmitter } = require('@creejs/commons-events')
+
+// owned
+// eslint-disable-next-line no-unused-vars
+const Policy = require('./policy')
+const Event = require('./event')
+const FixedIntervalPolicy = require('./policy/fixed-interval-policy')
+const FixedIncreasePolicy = require('./policy/fixed-increase-policy')
+const FactoreIncreasePolicy = require('./policy/factor-increase-policy')
+const ShuttlePolicy = require('./policy/shuttle-policy')
+const Task = require('./task')
+const AlwaysTask = require('./alway-task')
+const { DefaultMaxRetries } = require('./constants')
+
+// module vars
+const TaskTimoutFlag = '!#@%$&^*'
+
+/**
+ * @extends EventEmitter
+ */
+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) {
+    EventEmitter.mixin(this)
+    /**
+     * @type {Policy}
+     */
+    this._policy = new FixedIntervalPolicy(fixedInterval ?? 1000)
+    this._maxRetries = DefaultMaxRetries
+    this._currentRetries = 1
+    /**
+     * Timetou for total operation
+     * @type {number}
+     */
+    this._timeout = 120000 // 120s
+    /**
+     * Timetou for single task
+     */
+    this._taskTimeout = 2000 // 20s
+    this._name = 'unamed' // Retrier name
+
+    /**
+     * A Deferred Object as Singal to prevent Task concurrent start
+     * @type {{resolve:Function, reject:Function, promise: Promise<*>}|undefined}
+     */
+    this._taskingFlag = undefined
+
+    /**
+     *  A Deferred Object as Singal to prevent Task concurrent stop
+     * @type {{resolve:Function, reject:Function, promise: Promise<*>}|undefined}
+     */
+    this._breakFlag = undefined
+    /**
+     * Reason for break
+     * @type {Error|undefined}
+     */
+    this._breakReason = undefined
+  }
+
+  get running () {
+    return !isNil(this._taskingFlag)
+  }
+
+  /**
+   * 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) {
+    assertString(retrierName, 'retrierName')
+    this._name = retrierName
+    return this
+  }
+
+  /**
+   * Sets the retry attempts to be infinite by setting max retries to maximum safe integer.
+   * @returns {Object} The retrier instance for chaining.
+   */
+  infinite () {
+    this._maxRetries = Infinity
+    return 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) {
+    return this.maxRetries(times)
+  }
+
+  /**
+   * 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) {
+    assertPositive(maxRetries, 'maxRetries')
+    this._maxRetries = maxRetries
+    return 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) {
+    this._policy.min(min)
+    return 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) {
+    this._policy.max(max)
+    return 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, max) {
+    this._policy.range(min, max)
+    return this
+  }
+
+  /**
+   * 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) {
+    const oldPolicy = this._policy
+    if (oldPolicy instanceof FixedIntervalPolicy) {
+      oldPolicy.interval = fixedInterval
+      return this
+    }
+    const newPolicy = new FixedIntervalPolicy(fixedInterval)
+    oldPolicy?.copyPolicySetting(newPolicy)
+    newPolicy.reset()
+    this._policy = newPolicy
+    return this
+  }
+
+  /**
+   * 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) {
+    const oldPolicy = this._policy
+    if (oldPolicy instanceof FixedIncreasePolicy) {
+      oldPolicy.increasement = increasement
+      return this
+    }
+    const newPolicy = new FixedIncreasePolicy(increasement)
+    oldPolicy?.copyPolicySetting(newPolicy)
+    newPolicy.reset()
+    this._policy = newPolicy
+    return 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) {
+    const oldPolicy = this._policy
+    if (oldPolicy instanceof FactoreIncreasePolicy) {
+      oldPolicy.factor = factor
+      return this
+    }
+    const newPolicy = new FactoreIncreasePolicy(factor)
+    oldPolicy?.copyPolicySetting(newPolicy)
+    newPolicy.reset()
+    this._policy = newPolicy
+    return 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) {
+    const oldPolicy = this._policy
+    if (oldPolicy instanceof ShuttlePolicy) {
+      oldPolicy.stepLength = stepLength
+      return this
+    }
+    const newPolicy = new ShuttlePolicy(stepLength)
+    oldPolicy?.copyPolicySetting(newPolicy)
+    newPolicy.reset()
+    this._policy = newPolicy
+    return 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) {
+    assertPositive(timeout, 'timeout')
+    this._taskTimeout = timeout
+    return 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 {Object} The retrier instance for chaining.
+   */
+  timeout (timeout) {
+    assertNumber(timeout, 'timeout')
+    this._timeout = timeout
+    return 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) {
+    assertFunction(task, 'task')
+    this._task = new Task(this, task)
+    return this
+  }
+
+  /**
+   * alias of {@linkcode Retrier.task()}
+   * @param {Function} task - The function to be executed and retried
+   * @return {this}
+   */
+  retry (task) {
+    this.task(task)
+    return 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, resetAfterSuccess = false) {
+    this._task = new AlwaysTask(this, task, resetAfterSuccess)
+    return this
+  }
+
+  /**
+   * Starts the retry process.
+   * @returns {Promise<*>}
+   */
+  async start () {
+    if (this._task == null) {
+      throw new Error('No Task to Retry')
+    }
+    if (this._taskingFlag != null) {
+      return this._taskingFlag.promise
+    }
+    const startAt = Date.now()
+    let lastError = null
+    // @ts-ignore
+    this.emit(Event.Start, startAt)
+    this._taskingFlag = PromiseUtils.defer()
+    let latency = null
+    while (true) {
+      // need to stop?
+      if (this._breakFlag != null) {
+        this._taskingFlag.reject(this._breakReason)
+        break
+      }
+
+      latency = Date.now() - startAt
+
+      // total timeout?
+      if (!isInfinite(this._timeout) && latency >= this._timeout) { // total timeout
+        // @ts-ignore
+        this.emit(Event.Timeout, this._currentRetries, latency, this._timeout)
+        // always task, treat as success, resolve the whole promise with <void>
+        if (AlwaysTask.isAlwaysTask(this._task)) {
+          this._taskingFlag.resolve()
+          break
+        }
+        this._taskingFlag.reject(lastError ?? new Error(`Timeout "${this._timeout}" Exceeded`))
+        break
+      }
+
+      // @ts-ignore
+      this.emit(Event.Retry, this._currentRetries, latency)
+      const task = this._task // take task, it may be changed in events' callback functions
+      const nextDelay = this._policy.generate()
+      try {
+        try {
+          await PromiseUtils.timeout(task.execute(this._currentRetries, latency, nextDelay), this._taskTimeout, TaskTimoutFlag)
+        } catch (err) {
+          // @ts-ignore
+          if (err.message === TaskTimoutFlag) {
+            // @ts-ignore
+            this.emit(Event.TaskTimeout, this._currentRetries, latency, this._taskTimeout)
+          }
+          throw err
+        }
+        // @ts-ignore
+        if (task.failed) {
+          lastError = task.error
+          throw task.error
+        }
+        const rtnVal = task.result
+        // @ts-ignore
+        this.emit(Event.Success, rtnVal, this._currentRetries, latency)
+
+        // Not AwaysTask, we can finish all the retries with success
+        if (!AlwaysTask.isAlwaysTask(task)) {
+          this._taskingFlag.resolve(rtnVal)
+          break
+        }
+        // AwaysTask, continue to run the task
+      } catch (e) {
+        // @ts-ignore
+        this.emit(Event.Failure, e, this._currentRetries, latency)
+      }
+      const nextRetries = ++this._currentRetries
+      // next retry, max retries reached?
+      if (this._currentRetries > this._maxRetries) {
+        // @ts-ignore
+        this.emit(Event.MaxRetries, nextRetries, this._maxRetries)
+        // always task, treat as success, resolve the whole promise with <void>
+        if (AlwaysTask.isAlwaysTask(task)) {
+          this._taskingFlag.resolve()
+          break
+        }
+        this._taskingFlag.reject(lastError ?? new Error(`Max Retries Exceeded, Retring ${this._currentRetries} times > max ${this._maxRetries}`))
+        break
+      }
+      await PromiseUtils.delay(nextDelay)
+    }
+    this._taskingFlag.promise.finally(() => {
+      this.resetRetryPolicy()
+      this._taskingFlag = undefined
+      const spent = Date.now() - startAt
+      // @ts-ignore
+      this.emit(Event.Completed, this._currentRetries, spent)
+    })
+    return this._taskingFlag.promise
+  }
+
+  /**
+   * 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.
+   */
+  async stop (reason) {
+    // @ts-ignore
+    this.emit(Event.Stop, reason)
+    if (this._taskingFlag == null) {
+      return // no task running
+    }
+    if (this._breakFlag != null) {
+      // @ts-ignore
+      return this._breakFlag.promise
+    }
+    this._breakFlag = PromiseUtils.defer()
+    this._breakReason = reason ?? new Error('Manually Stop')
+    // @ts-ignore
+    this.once(Event.Completed, () => {
+      // @ts-ignore
+      this._breakFlag.resolve()
+    })
+
+    // @ts-ignore
+    this._breakFlag.promise.finally(() => {
+      this._breakFlag = undefined
+      this._breakReason = undefined
+    })
+    return this._breakFlag.promise
+  }
+
+  /**
+   * Resets the retry policy to its initial state.
+   */
+  resetRetryPolicy () {
+    this._policy.reset()
+  }
+
+  /**
+   * Registers a listener function to be called on "retry" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onRetry (listener) {
+    // @ts-ignore
+    this.on(Event.Retry, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "error" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onError (listener) {
+    // @ts-ignore
+    this.on(Event.Error, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "failure" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onFailure (listener) {
+    // @ts-ignore
+    this.on(Event.Failure, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "success" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onSuccess (listener) {
+    // @ts-ignore
+    this.on(Event.Success, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "start" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onStart (listener) {
+    // @ts-ignore
+    this.on(Event.Start, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "stop" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onStop (listener) {
+    // @ts-ignore
+    this.on(Event.Stop, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "timeout" events.
+   * @param {Function} listener - The callback function
+   */
+  onTimeout (listener) {
+    // @ts-ignore
+    this.on(Event.Timeout, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "task-timeout" events.
+   * @param {Function} listener - The callback function
+   * @returns {this}
+   */
+  onTaskTimeout (listener) {
+    // @ts-ignore
+    this.on(Event.TaskTimeout, listener)
+    return this
+  }
+
+  /**
+   * Registers a listener for "completed" events.
+   * @param {Function} listener - The callback function
+   */
+  onCompleted (listener) {
+    // @ts-ignore
+    this.on(Event.Completed, listener)
+    return 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) {
+    // @ts-ignore
+    this.on(Event.MaxRetries, listener)
+    return this
+  }
+}
+
+/**
+   * Checks if a value represents infinity or a non-positive number.
+   * @param {number} value - The value to check
+   * @returns {boolean} True if the value is <= 0 or Infinity, false otherwise
+   */
+function isInfinite (value) {
+  return value <= 0 || value === Infinity
+}
+
+module.exports = Retrier

package/lib/task.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const { TypeAssert: { assertNotNil, assertFunction } } = require('@creejs/commons-lang')
+// owned
+// eslint-disable-next-line no-unused-vars
+const Retrier = require('./retrier')
+
+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, task) {
+    assertNotNil(retrier, 'retrier')
+    assertFunction(task, 'task')
+    this.retrier = retrier
+    this.task = task
+    this.result = undefined
+    this.error = undefined
+  }
+
+  get failed () {
+    return this.error != null
+  }
+
+  get succeeded () {
+    return this.error == null
+  }
+
+  /**
+   * 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.
+   */
+  async execute (retries, latence, nextInterval) {
+    try {
+      this.result = await this.task(retries, latence, nextInterval)
+      this.error = undefined
+    } catch (e) {
+      this.error = e
+    }
+  }
+
+  dispose () {
+    // @ts-ignore
+    this.retrier = undefined
+  }
+}
+
+module.exports = Task

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@creejs/commons-retrier",
+  "version": "1.0.0",
+  "description": "Common Utils About Task Retrying",
+  "main": "index.js",
+  "private": false,
+  "files": [
+    "index.js",
+    "lib/",
+    "types/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frameworkee/commons.git"
+  },
+  "scripts": {
+    "dts": "tsc",
+    "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"
+  }
+}