feat: implement retry helper

Author: jlenon7

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@athenna/common",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "description": "The Athenna common helpers to use in any Node.js ESM project.",
   "license": "MIT",
   "author": "João Lenon <lenon@athenna.io>",
@@ -75,6 +75,7 @@
   },
   "dependencies": {
     "@fastify/formbody": "^8.0.2",
+    "@humanwhocodes/retry": "^0.4.3",
     "bytes": "^3.1.2",
     "callsite": "^1.0.0",
     "chalk": "^5.4.1",

package.json

@@ -16,9 +16,9 @@ export class Enum extends Macroable {
    * @example
    * ```ts
    * export class StatusEnum extends Enum {
-   *   static PENDING = 'pending'
-   *   static APPROVED = 'approved'
-   *   static BLOCKED = 'blocked'
+   *   public static PENDING = 'pending' as const
+   *   public static APPROVED = 'approved' as const
+   *   public static BLOCKED = 'blocked' as const
    * }
    *
    * const keys = StatusEnum.keys() // [ 'PENDING', 'APPROVED', 'BLOCKED' ]
@@ -34,9 +34,9 @@ export class Enum extends Macroable {
    * @example
    * ```ts
    * export class StatusEnum extends Enum {
-   *   static PENDING = 'pending'
-   *   static APPROVED = 'approved'
-   *   static BLOCKED = 'blocked'
+   *   public static PENDING = 'pending' as const
+   *   public static static APPROVED = 'approved' as const
+   *   public static BLOCKED = 'blocked' as const
    * }
    *
    * const values = StatusEnum.values() // ['pending', 'approved', 'blocked']
@@ -52,7 +52,7 @@ export class Enum extends Macroable {
    * @example
    * ```ts
    * export class StatusEnum extends Enum {
-   *   static PENDING = 'pending'
+   *   public static PENDING = 'pending' as const
    * }
    *
    * const entries = StatusEnum.entries() // [['PENDING', 'pending']]

src/helpers/Enum.ts

@@ -0,0 +1,75 @@
+/**
+ * @athenna/common
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Retrier } from '@humanwhocodes/retry'
+import type { Exception } from '#src/helpers/Exception'
+
+export class RetryBuilder {
+  private fn: (error: Error | Exception) => Promise<any>
+  private options: {
+    timeout?: number
+    maxDelay?: number
+    concurrency?: number
+  } = {}
+
+  /**
+   * Set the timeout for the retry.
+   */
+  public setTimeout(timeout: number) {
+    this.options.timeout = timeout
+
+    return this
+  }
+
+  /**
+   * Set the maximum delay between retries.
+   */
+  public setMaxDelay(maxDelay: number) {
+    this.options.maxDelay = maxDelay
+
+    return this
+  }
+
+  /**
+   * Set the number of concurrent retries.
+   */
+  public setConcurrency(concurrency: number) {
+    this.options.concurrency = concurrency
+
+    return this
+  }
+
+  /**
+   * Create a new retry instance to retry a function when it
+   * throws an error. Firstly define which errors should be
+   * retried and then define the function to retry.
+   *
+   * @example
+   * ```ts
+   * const text = await Retry
+   *    .build()
+   *    .whenError(error => error.code === 'ENFILE')
+   *    .retry(() => fs.readFile('README.md', 'utf8'))
+   * ```
+   */
+  public whenError(fn: (error: Exception) => any | Promise<any>) {
+    this.fn = fn
+
+    return new Retrier(this.fn, this.options)
+  }
+}
+
+export class Retry {
+  /**
+   * Create a new retry builder instance.
+   */
+  public static build() {
+    return new RetryBuilder()
+  }
+}

src/helpers/Retry.ts

@@ -31,6 +31,7 @@ export * from '#src/helpers/Options'
 export * from '#src/helpers/Otp'
 export * from '#src/helpers/Parser'
 export * from '#src/helpers/Path'
+export * from '#src/helpers/Retry'
 export * from '#src/helpers/Route'
 export * from '#src/helpers/Sleep'
 export * from '#src/helpers/String'

src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @athenna/common
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Retry } from '#src'
+import { readFile } from 'fs/promises'
+import { Test, type Context } from '@athenna/test'
+
+export default class RetryTest {
+  @Test()
+  public async shouldRetryAFunctionWhenItThrowsASpecificError({ assert }: Context) {
+    await assert.rejects(() =>
+      Retry.build()
+        .setTimeout(500)
+        .whenError(error => error.code === 'ENOENT')
+        .retry(() => readFile('READMEE.md', 'utf8'))
+    )
+  }
+
+  @Test()
+  public async shouldRetryAFunctionWhenItThrowsASpecificErrorAndReturnTheResult({ assert }: Context) {
+    const text = await Retry.build()
+      .whenError(error => error.code === 'ENOENT')
+      .retry(() => readFile('README.md', 'utf8'))
+
+    assert.isDefined(text)
+  }
+}