@creejs/commons-retrier/README.md

Common Utils About Task Retrying

# @creejs/commons-retrier

Commons-retrier Library provides a Retrier to:

- **Retry a task until it matches what you want**

- **Options**:

  - **Times**

    The max retires, how many times can we try?

  - **Intervals**

    After a retrying, what delay should we wait for?

    - **Minimum Interval**
    - **Maximum Interval**
    - **Change Policy**
      - **Fixed Interval Policy**
      - **Fixed Increase Policy**
      - **Factor Increase Policy**
      - **Shuttle Policy**
      - **Exponential Backoff with Jitter**
      - **Fixed Backoff with Jitter**
      - **Linear Backoff with Jitter**

  - **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
      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)

   ```javascript
      
   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)
     }
   })()
   ```