@yveskaufmann/retry - npm Package Compare versions

Comparing version 0.1.2 to 0.1.3

dist/retry.d.ts

@@ -0,1 +1,4 @@
+/**
+ * Options to configure a retriable operation.
+ */
 export interface RetryOptions<T> {
@@ -7,11 +10,12 @@ /**
     /**
-     * When set to true a MaxRetryAttemptsReached will be thrown if the max attempts of retries
-     * is reached.
+     * When set to true a MaxRetryAttemptsReached will be thrown if
+     * the retry attempt limit is reached.
      *
      * You should not use this option if you are interested into result/error that
-     * was produced by the operation in the last retry attempt.
+     * was produced by the operation.
      */
     throwMaxAttemptError?: boolean;
     /**
-     * Helps to identify the retryable operation in produced errors and logging.
+     * Helps to identify the retryable operation in errors
+     * and logging.
      */
@@ -40,2 +44,5 @@ nameOfOperation?: string;
 }
+/**
+ * List of built-in delay strategies.
+ */
 declare class Delays {
@@ -47,17 +54,29 @@ /**
     /**
-     * Constant delay between retries.
+     * Constant delay in milliseconds between retries.
      */
-    constant(delay: number): (attempts: number) => number;
+    constant(delayInMs: number): (attempts: number) => number;
     /**
      * Linear slope per attempt;
      */
-    linear(delay: number): (attempts: number) => number;
+    linear(delayInMs: number): (attempts: number) => number;
     /**
      * Quadratic slope per attempt
      */
-    potential(delay: number): (attempts: number) => number;
+    potential(delayInMs: number): (attempts: number) => number;
 }
+/**
+ * List of built-in retry conditions.
+ */
 declare class Conditions {
+    /**
+     * Retries a operation on any thrown error.
+     */
     onAnyError(): (result: unknown, err: Error) => boolean;
+    /**
+     * Retries a operation in any case.
+     */
     always(): (result: unknown, err: Error) => boolean;
+    /**
+     * Retries a operation if it returned a nullthy value.
+     */
     onNullResult(): (result: unknown, err: Error) => boolean;
@@ -75,5 +94,18 @@ }
     /**
+     * The do function invokes a given operation,
+     * and will re-invoke this operation if @link{RetryOptions#retryWhen}
+     * applied with the operation reults returns true.
      *
-     * @param param0
-     * @returns
+     * The operation will not further retried if the @link{RetryOptions#maxRetries}
+     * limit is reached, in this case either the return value
+     * from the previous operation invocation is returned or the error that
+     * was last thrown by invoked operation will be thrown by the do method.
+     *
+     * @param options Configuration of the retry options
+     *
+     * @throws MaxRetryAttemptsReached if the retry attempt limit is reached and the option @link{RetryOptions#throwMaxAttemptError}
+     * was enabled otherwise the error from the last invocation will be thrown.
+     *
+     * @returns The result of the last operation invocation.
+     *
      */
@@ -86,3 +118,3 @@ static do<T>({ operation, retryWhen: retryCondition, maxRetries, delay, throwMaxAttemptError, nameOfOperation, }: {
  * This error will be thrown if the maximum retry attempts of a
- * operation are reached.
+ * operation is reached buf only if @{link RetryOptions#throwMaxAttemptError} was set to true.
  */
@@ -99,4 +131,15 @@ export declare class MaxRetryAttemptsReached extends Error {
 }
+/**
+ * This method decorator marks a method as retriable.
+ *
+ * It uses the same options as @{link Retry#do} with the execption
+ * that the operation is the annotated method.
+ *
+ * NOTE: That the annotated method have to be async or it should at east
+ * return a promise.
+ *
+ * @param options Configuration of the retry options
+ */
 export declare function Retryable(options: RetryOptions<unknown>): MethodDecorator;
 export {};
 //# sourceMappingURL=retry.d.ts.map

dist/retry.js

@@ -14,2 +14,5 @@ "use strict";
 const wait_1 = require("./wait");
+/**
+ * List of built-in delay strategies.
+ */
 class Delays {
@@ -23,6 +26,6 @@ /**
     /**
-     * Constant delay between retries.
+     * Constant delay in milliseconds between retries.
      */
-    constant(delay) {
-        return (attempts) => delay;
+    constant(delayInMs) {
+        return (attempts) => delayInMs;
     }
@@ -32,4 +35,4 @@ /**
      */
-    linear(delay) {
-        return (attempts) => attempts * delay;
+    linear(delayInMs) {
+        return (attempts) => attempts * delayInMs;
     }
@@ -39,13 +42,25 @@ /**
      */
-    potential(delay) {
-        return (attempts) => Math.pow(2, Math.max(attempts - 1, 0)) * delay;
+    potential(delayInMs) {
+        return (attempts) => Math.pow(2, Math.max(attempts - 1, 0)) * delayInMs;
     }
 }
+/**
+ * List of built-in retry conditions.
+ */
 class Conditions {
+    /**
+     * Retries a operation on any thrown error.
+     */
     onAnyError() {
         return (result, err) => err != null;
     }
+    /**
+     * Retries a operation in any case.
+     */
     always() {
         return (result, err) => true;
     }
+    /**
+     * Retries a operation if it returned a nullthy value.
+     */
     onNullResult() {
@@ -57,5 +72,18 @@ return (result, err) => err == null && result == null;
     /**
+     * The do function invokes a given operation,
+     * and will re-invoke this operation if @link{RetryOptions#retryWhen}
+     * applied with the operation reults returns true.
      *
-     * @param param0
-     * @returns
+     * The operation will not further retried if the @link{RetryOptions#maxRetries}
+     * limit is reached, in this case either the return value
+     * from the previous operation invocation is returned or the error that
+     * was last thrown by invoked operation will be thrown by the do method.
+     *
+     * @param options Configuration of the retry options
+     *
+     * @throws MaxRetryAttemptsReached if the retry attempt limit is reached and the option @link{RetryOptions#throwMaxAttemptError}
+     * was enabled otherwise the error from the last invocation will be thrown.
+     *
+     * @returns The result of the last operation invocation.
+     *
      */
@@ -111,3 +139,3 @@ static do({ operation, retryWhen: retryCondition, maxRetries, delay, throwMaxAttemptError, nameOfOperation, }) {
  * This error will be thrown if the maximum retry attempts of a
- * operation are reached.
+ * operation is reached buf only if @{link RetryOptions#throwMaxAttemptError} was set to true.
  */
@@ -130,2 +158,13 @@ class MaxRetryAttemptsReached extends Error {
 exports.MaxRetryAttemptsReached = MaxRetryAttemptsReached;
+/**
+ * This method decorator marks a method as retriable.
+ *
+ * It uses the same options as @{link Retry#do} with the execption
+ * that the operation is the annotated method.
+ *
+ * NOTE: That the annotated method have to be async or it should at east
+ * return a promise.
+ *
+ * @param options Configuration of the retry options
+ */
 function Retryable(options) {
@@ -132,0 +171,0 @@ return function (target, property, descriptor) {

package.json

 {
   "name": "@yveskaufmann/retry",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Utility for retrying promise based operation on certain situations.",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

@@ -5,13 +5,15 @@ [![npm version](https://badge.fury.io/js/@yveskaufmann%2Fretry.svg)](https://badge.fury.io/js/@yveskaufmann%2Fretry)
 
-# retry-utility
+# @yveskaufmann/retry - retry-utility
 
-Utility for retrying promise based operation on certain situations.
+Utility for retrying promise based operation when a certain response or error is returned.
 
-* Provides an imperative API.
-* Class decorators to mark async functions to be retryable
-  Supports various backoff strategies: fixed, linear, exponential.
+* Provides an imperative API for non class methods
+* Class decorators to mark async methods to be retryable
+* Supports various backoff strategies: fixed, linear, exponential
 
 ## Installation
 
-  npm install @yveskaufmann/retry
+```sh 
+npm install @yveskaufmann/retry
+```
 
@@ -21,11 +23,9 @@ ## Usage
 The example below demonstrates how to annotate
-methods to mark them as retryable. When `retryWhen`
+methods to mark them as retriable. When `retryWhen`
 return `true` the method is retried until it reaches the
 `maxRetries` limit.
 
-When the retry limit is reached last result is returned
-or the last error is thrown.
+When the retry limit is reached, the last return value is returned
+or the last thrown error is thrown.
 
-When the limit is reached the last result, or the last thrown
-
 > NOTE: The Retryable annotation only works with methods that returning promises like async methods.
@@ -56,4 +56,3 @@
 
-This utility can also be used without annotating
-class methods.
+This utility can also be used with async functions:
 
@@ -69,4 +68,232 @@ ```typescript
 
-## API
+## API Reference
 
-The API is documented in the provided typescript definition file.
+  - [RetryOptions](#retryoptions)
+  - [Retry](#retry)
+    - [Retry#Delays](#retrydelays)
+    - [Retry#Conditions](#retryconditions)
+  - [Retryable](#retryable)
+  - [MaxRetryAttemptsReached](#maxretryattemptsreached)
+
+### RetryOptions
+
+```typescript 
+/**
+ * Options to configure a retriable operation.
+ */
+interface RetryOptions<T> {
+  /**
+   * The maximum amount of times a operation should be re-tried. 
+   * Excluding the *initial attempt.
+   */
+  maxRetries?: number;
+
+  /**
+   * When set to true a MaxRetryAttemptsReached will be thrown if 
+   * the retry attempts limit is reached.
+   *
+   * You should not use this option, 
+   * if you are interested into result/error that was produced 
+   * by the operation.
+   */
+  throwMaxAttemptError?: boolean;
+
+  /**
+   * Helps to identify the retryable operation in errors 
+   * and loggings.
+   */
+  nameOfOperation?: string;
+
+  /**
+   * Defines the condition on which a operation should be 
+   * retried, a implementation should return true 
+   * if a retry is desired.
+   *
+   * @param result The result from the current attempt, 
+   * can be null if no error was thrown by the operation.
+   * 
+   * @param error  The error that was thrown by the operation 
+   * during the latest attempt.
+   *
+   * @returns True if a retry should be done.
+   *
+   */
+  retryWhen: (result: T, err: Error) => boolean;
+
+  /**
+   * Calculates the delay between retries in milliseconds.
+   *
+   * @param attempts Count of failed attempts
+   * 
+   * @param error The error that was thrown by the operation 
+   *  during the previous attempt.
+   *
+   * @returns A delay duration in  milliseconds.
+   */
+  delay?: (attempts: number, error?: Error) => number;
+}
+```
+
+### Retry
+
+This is the retry class that provides access to built-in delay(backoff) strategies and built-in retry conditions.
+
+```typescript
+class Retry {
+  /**
+   * List of built-in delays
+   */
+  public static readonly Delays = new Delays();
+
+  /**
+   * List of built-in retry conditions
+   */
+  public static readonly Conditions = new Conditions();
+ 
+ /**
+   * The do function invokes a given operation,
+   * and will re-invoke this operation if 
+   * @link{RetryOptions#retryWhen} applied with the
+   * operation reults returns true.
+   *
+   * The operation will not further retried if the 
+   * @link{RetryOptions#maxRetries} limit is reached, 
+   * in this case either the return value from the previous 
+   * operation invocation is returned or the error that
+   * was last thrown by the invoked operation will be thrown.
+   *
+   * @param options Configuration of the retry options
+   *
+   * @throws MaxRetryAttemptsReached if the retry attempt limit 
+   * is reached and the option @link{RetryOptions#throwMaxAttemptError} 
+   * was enabled  otherwise the error from the last invocation 
+   * will be thrown.
+   *
+   * @returns The result of the last operation invocation.
+   */
+  public static async do<T>(options: RetryOptions<T>): Promise<T>;
+}
+```
+
+### RetryDelays
+
+```typescript 
+/**
+ * List of built-in delay strategies.
+ */
+class Delays {
+  /**
+   * No delay between retries
+   */
+  public none();
+
+  /**
+   * Constant delay in milliseconds between retries.
+   */
+  public constant(delayInMs: number);
+
+  /**
+   * Linear sloping delay per attempt
+   */
+  public linear(delayInMs: number);
+  
+  /**
+   * Quadratic sloping delays per attempt
+   */
+  public potential(delayInMs: number);
+}
+```
+
+A custom delay strategy can be created by implementing 
+a function that fulfill the interface below:
+
+```typescript 
+  /**
+   * Calculates the delay between retries in milliseconds.
+   *
+   * @param attempts Count of failed attempts
+   * @param error The error that was thrown by the operation 
+   * during the previous attempt.
+   *
+   * @returns A delay duration in  milliseconds.
+   */
+  () => (attempts: number, error?: Error) => number
+```
+
+### RetryConditions
+
+```typescript 
+/**
+ * List of built-in retry conditions.
+ */
+class Conditions {
+  /**
+   * Retries a operation on any thrown error.
+   */
+  public onAnyError();
+
+  /**
+   * Retries a operation in any case.
+   */
+  public always();
+
+  /**
+   * Retries a operation if it returned a nullthy value.
+   */
+  public onNullResult();
+}
+```
+
+A custom retry-condition can be created by implementing 
+a function that fulfills the following interface:
+
+```typescript 
+ /**
+   * Defines the condition on which a operation should be retried a implementation
+   * should return true if a retry is desired.
+   *
+   * @param result The result from the current attempt, can be null if no error was thrown by the operation.
+   * @param error  The error that was thrown by the operation during the current attempt.
+   *
+   * @returns True if a retry should be done.
+   *
+   */
+  retryWhen: (result: T, err: Error) => boolean;
+```
+
+### Retryable
+
+```typescript 
+/**
+ * This method decorator marks a method as retriable.
+ *
+ * It uses the same options as @{link Retry#do} with the execption
+ * that the operation is the annotated method.
+ *
+ * NOTE: That the annotated method have to be async or it should at east
+ * return a promise.
+ *
+ * @param options Configuration of the retry options
+ */
+function Retryable(options: RetryOptions<unknown>): MethodDecorator
+```
+
+### MaxRetryAttemptsReached
+
+```typescript 
+/**
+ * This error will be thrown if the maximum retry attempts of a
+ * operation is reached buf only if @{link RetryOptions#throwMaxAttemptError} was set to true.
+ */
+class MaxRetryAttemptsReached extends Error {
+  /**
+   * Can contain the cause of this error,
+   * which follows the specs of Error Cause proposal:
+   *
+   * https://tc39.es/proposal-error-cause/
+   */
+  public readonly cause: Error;
+
+  constructor(message: string, cause?: Error);
+}
+```

No alert changes

Improved metrics

Total package byte prevSize

44343

increased by25.21%

Lines of code

363

increased by29.18%

Number of lines in readme file

296

increased by328.99%

No dependency changes