docs: add TSDoc comments (#68)

This makes the developer experience a bit nicer: the IDE will display the documentation inline for each of the options and the backOff function itself.

The values in the comments were sourced from the README and only slightly reformatted.

Author: no23reason

src/backoff.ts

@@ -7,6 +7,12 @@ import { DelayFactory } from "./delay/delay.factory";
 
 export { BackoffOptions, IBackOffOptions };
 
+/**
+ * Executes a function with exponential backoff.
+ * @param request the function to be executed
+ * @param options options to customize the backoff behavior
+ * @returns Promise that resolves to the result of the `request` function
+ */
 export async function backOff<T>(
   request: () => Promise<T>,
   options: BackoffOptions = {}

src/options.ts

@@ -1,14 +1,57 @@
+/**
+ * Type of jitter to apply to the delay.
+ * - `"none"`: no jitter is applied
+ * - `"full"`: full jitter is applied (random value between `0` and `delay`)
+ */
 export type JitterType = "none" | "full";
 
 export type BackoffOptions = Partial<IBackOffOptions>;
 
 export interface IBackOffOptions {
+  /**
+   * Decides whether the `startingDelay` should be applied before the first call.
+   * If `false`, the first call will occur without a delay.
+   * @defaultValue `false`
+   */
   delayFirstAttempt: boolean;
+  /**
+   * Decides whether a [jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
+   * should be applied to the delay. Possible values are `"full"` and `"none"`.
+   * @defaultValue `"none"`
+   */
   jitter: JitterType;
+  /**
+   * The maximum delay, in milliseconds, between two consecutive attempts.
+   * @defaultValue `Infinity`
+   */
   maxDelay: number;
+  /**
+   * The maximum number of times to attempt the function.
+   * Must be at least `1`.
+   * @defaultValue `10`
+   */
   numOfAttempts: number;
+  /**
+   * The `retry` function can be used to run logic after every failed attempt (e.g. logging a message,
+   * assessing the last error, etc.).
+   * It is called with the last error and the upcoming attempt number.
+   * Returning `true` will retry the function as long as the `numOfAttempts` has not been exceeded.
+   * Returning `false` will end the execution.
+   * @defaultValue a function that always returns `true`.
+   * @param e The last error thrown by the function.
+   * @param attemptNumber The upcoming attempt number.
+   * @returns `true` to retry the function, `false` to end the execution
+   */
   retry: (e: any, attemptNumber: number) => boolean | Promise<boolean>;
+  /**
+   * The delay, in milliseconds, before executing the function for the first time.
+   * @defaultValue `100`
+   */
   startingDelay: number;
+  /**
+   * The `startingDelay` is multiplied by the `timeMultiple` to increase the delay between reattempts.
+   * @defaultValue `2`
+   */
   timeMultiple: number;
 }