@sha1n/about-time 0.0.1 → 0.0.2

package/README.md

@@ -7,7 +7,7 @@
 
 # About-Time
 
-A set of essential time related utilities.
+A collection of essential time related utilities.
 
 - [About-Time](#about-time)
   - [Install](#install)
@@ -78,20 +78,27 @@ const retryPolicy = fixedRetryPolicy([3, 10, 50, 100], TimeUnit.Milliseconds);
 ```
 
 #### Exponential backoff retry policy
+Exponential backoff formula based retry policy with optional custom exponent base and a limit. 
+The optional `limit` provides control over maximum pause intervals, so they don't soar beyond reasonable values.
+
+**The formula used by this implementation is the following:** 
+
+interval<sub>i</sub> = min(limit, (exponential<sup>i</sup> - 1) / 2)
+
 ```ts
-// 10 retries, starting with 10 milliseconds and then exponentially increases the delay based on the default power value without a limit.
 const retryPolicy = exponentialBackoffRetryPolicy(/* count = */10, /* opts?: { exponential?: number, limit?: number, units?: TimeUnit }*/);
 ```
 
 ### RetryAround
-Executes the given function with the retries based on the specified policy.
+Executes the given function with retries based on the specified policy and *optional* predicate.
+The predicate provides control over which errors we want to retry on.
 ```ts
-const result = await retryAround(action, retryPolicy);
+const result = await retryAround(action, retryPolicy, predicate);
 ```
 
 ### Retriable
-Wraps a given function with `retryAround` with the specified policy.
+Wraps a given function with `retryAround` with the specified arguments.
 ```ts
-const retriableAction = retriable(action, retryPolicy);
+const retriableAction = retriable(action, retryPolicy, predicate);
 const result = await retriableAction();
 ```

package/dist/lib/retry.js

@@ -61,7 +61,7 @@ function exponentialBackoffRetryPolicy(count, opts) {
     return Object.freeze(new ExponentialBackoffRetryPolicy(count, opts === null || opts === void 0 ? void 0 : opts.exponential, opts === null || opts === void 0 ? void 0 : opts.limit, opts === null || opts === void 0 ? void 0 : opts.units));
 }
 exports.exponentialBackoffRetryPolicy = exponentialBackoffRetryPolicy;
-async function retryAround(action, policy) {
+async function retryAround(action, policy, predicate = () => true) {
     let next;
     const intervals = policy.intervals()[Symbol.iterator]();
     do {
@@ -70,7 +70,7 @@ async function retryAround(action, policy) {
         }
         catch (e) {
             next = intervals.next();
-            if (next.done) {
+            if (next.done || !predicate(e)) {
                 throw e;
             }
             await (0, utilities_1.sleep)(next.value);
@@ -79,9 +79,9 @@ async function retryAround(action, policy) {
     throw new Error('Unexpected error. This is most likely a bug.');
 }
 exports.retryAround = retryAround;
-function retriable(action, policy) {
+function retriable(action, policy, predicate = () => true) {
     return () => {
-        return retryAround(action, policy);
+        return retryAround(action, policy, predicate);
     };
 }
 exports.retriable = retriable;

package/dist/lib/utilities.js

@@ -10,7 +10,7 @@ const timeunit_1 = require("./timeunit");
  * @returns a promise that resolves when the specified time has elapsed.
  */
 function sleep(time, units) {
-    return new Promise((resolve) => {
+    return new Promise(resolve => {
         setTimeout(resolve, (0, timeunit_1.toMilliseconds)(time, units));
     });
 }
@@ -53,12 +53,8 @@ async function until(condition, opts) {
         return;
     }
     const defaultInterval = 50;
-    const deadline = opts
-        ? Date.now() + (0, timeunit_1.toMilliseconds)(opts.timeout, opts.units)
-        : Number.MAX_VALUE;
-    const interval = (opts === null || opts === void 0 ? void 0 : opts.interval)
-        ? (0, timeunit_1.toMilliseconds)(opts.interval, opts.units)
-        : defaultInterval;
+    const deadline = opts ? Date.now() + (0, timeunit_1.toMilliseconds)(opts.timeout, opts.units) : Number.MAX_VALUE;
+    const interval = (opts === null || opts === void 0 ? void 0 : opts.interval) ? (0, timeunit_1.toMilliseconds)(opts.interval, opts.units) : defaultInterval;
     return new Promise((resolve, reject) => {
         const handle = setInterval(() => {
             if (Date.now() > deadline) {

package/dist/types/lib/retry.d.ts

@@ -13,6 +13,6 @@ declare function exponentialBackoffRetryPolicy(count: number, opts?: {
     limit?: number;
     units?: TimeUnit;
 }): RetryPolicy;
-declare function retryAround<T>(action: () => T | Promise<T>, policy: RetryPolicy): Promise<T>;
-declare function retriable<T>(action: () => T | Promise<T>, policy: RetryPolicy): () => Promise<T>;
+declare function retryAround<T>(action: () => T | Promise<T>, policy: RetryPolicy, predicate?: (e: Error) => boolean): Promise<T>;
+declare function retriable<T>(action: () => T | Promise<T>, policy: RetryPolicy, predicate?: (e: Error) => boolean): () => Promise<T>;
 export { RetryPolicy, retryAround, retriable, fixedRetryPolicy, simpleRetryPolicy, exponentialBackoffRetryPolicy };

package/lib/retry.ts

@@ -8,11 +8,7 @@ interface RetryPolicy {
 class SimpleRetryPolicy implements RetryPolicy {
   private readonly interval: number;
 
-  constructor(
-    private readonly count: number,
-    interval: number,
-    units?: TimeUnit
-  ) {
+  constructor(private readonly count: number, interval: number, units?: TimeUnit) {
     this.interval = toMilliseconds(interval, units);
   }
 
@@ -68,18 +64,11 @@ class FixedRetryPolicy implements RetryPolicy {
   }
 }
 
-function simpleRetryPolicy(
-  count: number,
-  interval: number,
-  opts?: { units?: TimeUnit }
-): RetryPolicy {
+function simpleRetryPolicy(count: number, interval: number, opts?: { units?: TimeUnit }): RetryPolicy {
   return Object.freeze(new SimpleRetryPolicy(count, interval, opts?.units));
 }
 
-function fixedRetryPolicy(
-  intervals: number[],
-  opts?: { units?: TimeUnit }
-): RetryPolicy {
+function fixedRetryPolicy(intervals: number[], opts?: { units?: TimeUnit }): RetryPolicy {
   return Object.freeze(new FixedRetryPolicy(intervals, opts?.units));
 }
 
@@ -87,19 +76,13 @@ function exponentialBackoffRetryPolicy(
   count: number,
   opts?: { exponential?: number; limit?: number; units?: TimeUnit }
 ): RetryPolicy {
-  return Object.freeze(
-    new ExponentialBackoffRetryPolicy(
-      count,
-      opts?.exponential,
-      opts?.limit,
-      opts?.units
-    )
-  );
+  return Object.freeze(new ExponentialBackoffRetryPolicy(count, opts?.exponential, opts?.limit, opts?.units));
 }
 
 async function retryAround<T>(
   action: () => T | Promise<T>,
-  policy: RetryPolicy
+  policy: RetryPolicy,
+  predicate: (e: Error) => boolean = () => true
 ): Promise<T> {
   let next: IteratorResult<number, undefined>;
   const intervals = policy.intervals()[Symbol.iterator]();
@@ -109,7 +92,7 @@ async function retryAround<T>(
     } catch (e) {
       next = intervals.next();
 
-      if (next.done) {
+      if (next.done || !predicate(e)) {
         throw e;
       }
 
@@ -122,18 +105,12 @@ async function retryAround<T>(
 
 function retriable<T>(
   action: () => T | Promise<T>,
-  policy: RetryPolicy
+  policy: RetryPolicy,
+  predicate: (e: Error) => boolean = () => true
 ): () => Promise<T> {
   return () => {
-    return retryAround(action, policy);
+    return retryAround(action, policy, predicate);
   };
 }
 
-export {
-  RetryPolicy,
-  retryAround,
-  retriable,
-  fixedRetryPolicy,
-  simpleRetryPolicy,
-  exponentialBackoffRetryPolicy
-};
+export { RetryPolicy, retryAround, retriable, fixedRetryPolicy, simpleRetryPolicy, exponentialBackoffRetryPolicy };

package/lib/utilities.ts

@@ -8,7 +8,7 @@ import { TimeUnit, toMilliseconds } from './timeunit';
  * @returns a promise that resolves when the specified time has elapsed.
  */
 function sleep(time: number, units?: TimeUnit): Promise<void> {
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     setTimeout(resolve, toMilliseconds(time, units));
   });
 }
@@ -21,11 +21,7 @@ function sleep(time: number, units?: TimeUnit): Promise<void> {
  * @param units the units on time
  * @returns a promise that resolves when the specified time has elapsed.
  */
-function delay<T>(
-  action: () => T | Promise<T>,
-  time: number,
-  units?: TimeUnit
-): Promise<T> {
+function delay<T>(action: () => T | Promise<T>, time: number, units?: TimeUnit): Promise<T> {
   const delayMs = toMilliseconds(time, units);
   return new Promise((resolve, reject) => {
     setTimeout(() => Promise.resolve(action()).then(resolve, reject), delayMs);
@@ -60,12 +56,8 @@ async function until(
   }
 
   const defaultInterval = 50;
-  const deadline = opts
-    ? Date.now() + toMilliseconds(opts.timeout, opts.units)
-    : Number.MAX_VALUE;
-  const interval = opts?.interval
-    ? toMilliseconds(opts.interval, opts.units)
-    : defaultInterval;
+  const deadline = opts ? Date.now() + toMilliseconds(opts.timeout, opts.units) : Number.MAX_VALUE;
+  const interval = opts?.interval ? toMilliseconds(opts.interval, opts.units) : defaultInterval;
 
   return new Promise<void>((resolve, reject) => {
     const handle = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha1n/about-time",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A set of essential time related utilities",
   "repository": "https://github.com/sha1n/about-time",
   "author": "Shai Nagar",