@AvocaJs/Echo

The Echo class is a utility that provides robust functionality for retrying asynchronous and synchronous jobs with configurable delay settings. It also includes methods for sleeping and setting/getting various configuration options.

Table of Contents

• Installation
• Usage
  • Instantiating Echo
  • Retrying Jobs
  • Setting Configuration
  • Sleeping
• API
  • Echo Class
  • Methods
• Error Handling
• Contributing
• License

Installation

To install the Echo utility, use the following command:

npm install @avocajs/echo

Usage

Instantiating Echo

You can create an instance of the Echo class with optional parameters to set the maximum number of retries, the delay between retries, and any additional delay after each retry.

import { Echo } from "@avocajs/echo";

const echo = new Echo(3, 500, 0); // Default values
// maxRetry: 3, retryDelay: 500ms, extraDelay: 0ms

Retrying Jobs

The retry method allows you to retry a given job (function) a specified number of times until it either resolves (for async jobs) or returns a value (for sync jobs), or the retries are exhausted. Here's how it works:

• Resolves: The retry method resolves when the job resolves or returns a value. This means the job retry is successful, and the retry ends.
• Rejects: The retry method rejects when the job continues to throw an error (sync) or reject (async) after the specified number of retries.

Example with Asynchronous Job

const echo = new Echo();

const asyncJob = async () => {
  // Simulate a job that may fail
  if (Math.random() > 0.5) {
    throw new Error("Random failure");
  }
  return "Success!";
};

echo
  .retry(asyncJob)
  .then((result) => console.log(result)) // Logs "Success!" if the job succeeds within the retry limit
  .catch((error) => console.error(error)); // Logs the error if all retries fail

Example with Synchronous Job

const echo = new Echo();

const syncJob = () => {
  // Simulate a job that may fail
  if (Math.random() > 0.5) {
    throw new Error("Random failure");
  }
  return "Success!";
};

echo
  .retry(syncJob)
  .then((result) => console.log(result)) // Logs "Success!" if the job succeeds within the retry limit
  .catch((error) => console.error(error)); // Logs the error if all retries fail

Setting Configuration

You can configure the retry behavior using the provided setter methods.

const echo = new Echo();

// Set maximum number of retries
echo.setMaxRetry(5);

// Set delay between retries
echo.setRetryDelay(1000);

// Set additional delay after each retry
echo.setExtraDelay(200);

Sleeping

The sleep method allows you to pause execution for a specified number of milliseconds.

await Echo.sleep(1000); // Sleeps for 1 second

API

Echo Class

Constructor

new Echo(maxRetry?: number, retryDelay?: number, extraDelay?: number);

• maxRetry (optional): The maximum number of retries (default: 3)
• retryDelay (optional): The delay between retries in milliseconds (default: 500)
• extraDelay (optional): The additional delay after each retry in milliseconds (default: 0)

Methods

retry<T>(job: Job<T>): Promise<T>

Retries the given job the specified number of times. Resolves when the job resolves or returns a value. Rejects when the job continues to fail after the specified number of retries.

static sleep(retryDelay: number): Promise<void>

Delays execution for the specified number of milliseconds.

setMaxRetry(maxRetry: number): void

Sets the maximum number of retries.

setRetryDelay(retryDelay: number): void

Sets the delay between retries.

setExtraDelay(extraDelay: number): void

Sets the additional delay after each retry.

getMaxRetry(): number

Gets the maximum number of retries.

getRetryDelay(): number

Gets the delay between retries.

getExtraDelay(): number

Gets the additional delay after each retry.

Error Handling

The Echo class uses a custom error type EchoError to indicate errors related to invalid configuration options.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.

Author

Essefri Mohamed For any queries, you can reach me at [email protected].