@creejs/commons-retrier 1.0.8 → 2.0.2

package/lib/retrier.js

@@ -1,530 +0,0 @@
-// internal
-import { TypeAssert, TypeUtils, PromiseUtils } from '@creejs/commons-lang'
-import { EventEmitter } from '@creejs/commons-events'
-
-// owned
-// eslint-disable-next-line no-unused-vars
-import Policy from './policy.js'
-import Event from './event.js'
-import FixedIntervalPolicy from './policy/fixed-interval-policy.js'
-import FixedIncreasePolicy from './policy/fixed-increase-policy.js'
-import FactoreIncreasePolicy from './policy/factor-increase-policy.js'
-import ShuttlePolicy from './policy/shuttle-policy.js'
-import Task from './task.js'
-import AlwaysTask from './alway-task.js'
-import { DefaultMaxRetries } from './constants.js'
-
-// module vars
-const { assertPositive, assertString, assertFunction, assertNumber } = TypeAssert
-const { isNil } = TypeUtils
-const TaskTimoutFlag = '!#@%$&^*'
-
-/**
- * @extends EventEmitter
- */
-export default 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
-}
-
-export { Retrier as RetrierType }

package/lib/task.js

@@ -1,58 +0,0 @@
-import { TypeAssert } from '@creejs/commons-lang'
-// owned
-
-/**
- * @typedef {import('./retrier.js').default} Retrier
- */
-
-// module vars
-const { assertNotNil, assertFunction } = TypeAssert
-export default 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
-  }
-}
-
-export { Task as TaskType }