@sha1n/about-time 0.0.3 → 0.0.7

package/README.md

@@ -10,8 +10,10 @@
 A collection of essential time related utilities.
 
 - [About-Time](#about-time)
-  - [Install](#install)
+- [Install](#install)
+- [Utilities & Features](#utilities--features)
   - [Delay](#delay)
+  - [WithTimeout](#withtimeout)
   - [Sleep](#sleep)
   - [Stopwatch](#stopwatch)
   - [Until / Eventually](#until--eventually)
@@ -24,17 +26,24 @@ A collection of essential time related utilities.
     - [Retriable](#retriable)
 
 
-## Install
+# Install
 ```bash
 npm i @sha1n/about-time
 ```
 
+# Utilities & Features
 ## Delay
 ```ts
 // Execute a function with delay and return it's value
 await delay(action, 10, TimeUnit.Milliseconds);
 ```
 
+## WithTimeout
+```ts
+// Execute a function and guards it with a specified timeout
+await withTimeout(action, 10, TimeUnit.Milliseconds);
+```
+
 ## Sleep
 ```ts
 // Pause execution for a specified amount of time

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exponentialBackoffRetryPolicy = exports.simpleRetryPolicy = exports.fixedRetryPolicy = exports.retriable = exports.retryAround = exports.eventually = exports.until = exports.stopwatch = exports.delay = exports.sleep = exports.withTimeout = exports.toMilliseconds = exports.TimeUnit = void 0;
+var timeunit_1 = require("./lib/timeunit");
+Object.defineProperty(exports, "TimeUnit", { enumerable: true, get: function () { return timeunit_1.TimeUnit; } });
+Object.defineProperty(exports, "toMilliseconds", { enumerable: true, get: function () { return timeunit_1.toMilliseconds; } });
+var utilities_1 = require("./lib/utilities");
+Object.defineProperty(exports, "withTimeout", { enumerable: true, get: function () { return utilities_1.withTimeout; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return utilities_1.sleep; } });
+Object.defineProperty(exports, "delay", { enumerable: true, get: function () { return utilities_1.delay; } });
+Object.defineProperty(exports, "stopwatch", { enumerable: true, get: function () { return utilities_1.stopwatch; } });
+Object.defineProperty(exports, "until", { enumerable: true, get: function () { return utilities_1.until; } });
+Object.defineProperty(exports, "eventually", { enumerable: true, get: function () { return utilities_1.eventually; } });
+var retry_1 = require("./lib/retry");
+Object.defineProperty(exports, "retryAround", { enumerable: true, get: function () { return retry_1.retryAround; } });
+Object.defineProperty(exports, "retriable", { enumerable: true, get: function () { return retry_1.retriable; } });
+Object.defineProperty(exports, "fixedRetryPolicy", { enumerable: true, get: function () { return retry_1.fixedRetryPolicy; } });
+Object.defineProperty(exports, "simpleRetryPolicy", { enumerable: true, get: function () { return retry_1.simpleRetryPolicy; } });
+Object.defineProperty(exports, "exponentialBackoffRetryPolicy", { enumerable: true, get: function () { return retry_1.exponentialBackoffRetryPolicy; } });

package/dist/lib/retry.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exponentialBackoffRetryPolicy = exports.simpleRetryPolicy = exports.fixedRetryPolicy = exports.retriable = exports.retryAround = void 0;
+const timeunit_1 = require("./timeunit");
+const utilities_1 = require("./utilities");
+class SimpleRetryPolicy {
+    constructor(count, interval, units) {
+        this.count = count;
+        this.interval = (0, timeunit_1.toMilliseconds)(interval, units);
+    }
+    *intervals() {
+        let count = this.count;
+        while (count > 0) {
+            count -= 1;
+            yield this.interval;
+        }
+        return;
+    }
+}
+class ExponentialBackoffRetryPolicy {
+    constructor(count, exponential = 2, limit = Infinity, units = timeunit_1.TimeUnit.Milliseconds) {
+        this.count = count;
+        this.exponential = exponential;
+        this.limit = limit;
+        this.units = units;
+    }
+    *intervals() {
+        let index = 0;
+        while (index < this.count) {
+            const interval = Math.round((Math.pow(this.exponential, index) - 1) / 2);
+            yield Math.min(this.limit, interval) * this.units;
+            index += 1;
+        }
+        return;
+    }
+}
+class FixedRetryPolicy {
+    constructor(intervals, units) {
+        this._intervals = intervals.reduceRight((result, v) => {
+            result.push((0, timeunit_1.toMilliseconds)(v, units));
+            return result;
+        }, []);
+    }
+    *intervals() {
+        const intervals = [...this._intervals];
+        while (intervals.length > 0) {
+            yield intervals.pop();
+        }
+        return;
+    }
+}
+function simpleRetryPolicy(count, interval, opts) {
+    return Object.freeze(new SimpleRetryPolicy(count, interval, opts === null || opts === void 0 ? void 0 : opts.units));
+}
+exports.simpleRetryPolicy = simpleRetryPolicy;
+function fixedRetryPolicy(intervals, opts) {
+    return Object.freeze(new FixedRetryPolicy(intervals, opts === null || opts === void 0 ? void 0 : opts.units));
+}
+exports.fixedRetryPolicy = fixedRetryPolicy;
+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, predicate = () => true) {
+    let next;
+    const intervals = policy.intervals()[Symbol.iterator]();
+    do {
+        try {
+            return await action();
+        }
+        catch (e) {
+            next = intervals.next();
+            if (next.done || !predicate(e)) {
+                throw e;
+            }
+            await (0, utilities_1.sleep)(next.value);
+        }
+    } while (!next.done);
+    throw new Error('Unexpected error. This is most likely a bug.');
+}
+exports.retryAround = retryAround;
+function retriable(action, policy, predicate = () => true) {
+    return () => {
+        return retryAround(action, policy, predicate);
+    };
+}
+exports.retriable = retriable;

package/dist/lib/timeunit.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMilliseconds = exports.TimeUnit = void 0;
+var TimeUnit;
+(function (TimeUnit) {
+    TimeUnit[TimeUnit["Milliseconds"] = 1] = "Milliseconds";
+    TimeUnit[TimeUnit["Millisecond"] = 1] = "Millisecond";
+    TimeUnit[TimeUnit["Seconds"] = 1000] = "Seconds";
+    TimeUnit[TimeUnit["Second"] = 1000] = "Second";
+    TimeUnit[TimeUnit["Minutes"] = 60000] = "Minutes";
+    TimeUnit[TimeUnit["Minute"] = 60000] = "Minute";
+    TimeUnit[TimeUnit["Hours"] = 3600000] = "Hours";
+    TimeUnit[TimeUnit["Hour"] = 3600000] = "Hour";
+    TimeUnit[TimeUnit["Days"] = 86400000] = "Days";
+    TimeUnit[TimeUnit["Day"] = 86400000] = "Day";
+})(TimeUnit || (TimeUnit = {}));
+exports.TimeUnit = TimeUnit;
+/**
+ * Converts time value in other units to milliseconds.
+ *
+ * @param time a time value to be converted
+ * @param units the units of time
+ * @returns the time value in milliseconds
+ */
+function toMilliseconds(time, units) {
+    return time * (units ? units : 1);
+}
+exports.toMilliseconds = toMilliseconds;

package/dist/lib/utilities.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventually = exports.until = exports.stopwatch = exports.delay = exports.sleep = exports.withTimeout = void 0;
+const timeunit_1 = require("./timeunit");
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message || 'Timeout');
+    }
+}
+/**
+ * Zzzz...
+ *
+ * @param time time to sleep
+ * @param units the units on time
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+function sleep(time, units) {
+    return new Promise(resolve => {
+        setTimeout(resolve, (0, timeunit_1.toMilliseconds)(time, units));
+    });
+}
+exports.sleep = sleep;
+/**
+ * Delays the execution of the specified action and returns its value.
+ *
+ * @param action a function to execute with delay
+ * @param time time to sleep
+ * @param units the units on time
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+function delay(action, time, units) {
+    const delayMs = (0, timeunit_1.toMilliseconds)(time, units);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => Promise.resolve(action()).then(resolve, reject), delayMs);
+        process.on('beforeExit', () => {
+            clearTimeout(timer);
+        });
+    });
+}
+exports.delay = delay;
+/**
+ * Return a function that returns the elapsed time relative to this call.
+ * @returns a function
+ */
+function stopwatch() {
+    const startTime = Date.now();
+    return (units) => {
+        return (Date.now() - startTime) / (units || timeunit_1.TimeUnit.Milliseconds);
+    };
+}
+exports.stopwatch = stopwatch;
+/**
+ * Awaits a specified condition to evaluate to true with or without a timeout.
+ *
+ * @param condition the condition to wait for
+ * @param opts options that control evaluation intervals and timeout
+ * @returns a promise that resolves when the condition becomes true, or rejects when a set timeout is crossed.
+ */
+async function until(condition, opts) {
+    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;
+    return new Promise((resolve, reject) => {
+        const handle = setInterval(() => {
+            if (Date.now() > deadline) {
+                clearInterval(handle);
+                reject(new TimeoutError());
+            }
+            try {
+                if (condition()) {
+                    clearInterval(handle);
+                    resolve();
+                }
+            }
+            catch (e) {
+                clearInterval(handle);
+                reject(e);
+            }
+        }, interval);
+    });
+}
+exports.until = until;
+/**
+ * Alias to `until`
+ */
+const eventually = until;
+exports.eventually = eventually;
+/**
+ * Executes an action with a specified timeout. If the action times out, rejects with TimeoutError.
+ *
+ * @param action an action to execute with timeout
+ * @param timeout the timeout to set for the action
+ * @param units the time units
+ * @returns the action result
+ */
+async function withTimeout(action, timeout, units) {
+    const promisedAction = new Promise((resolve, reject) => {
+        try {
+            resolve(action());
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+    const race = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new TimeoutError());
+        }, (0, timeunit_1.toMilliseconds)(timeout, units));
+        return Promise.resolve(promisedAction).then(r => {
+            clearTimeout(timer);
+            resolve(r);
+        }, err => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+    return race;
+}
+exports.withTimeout = withTimeout;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { TimeUnit, toMilliseconds } from './lib/timeunit';
+export { withTimeout, sleep, delay, stopwatch, until, eventually } from './lib/utilities';
+export { RetryPolicy, retryAround, retriable, fixedRetryPolicy, simpleRetryPolicy, exponentialBackoffRetryPolicy } from './lib/retry';

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

@@ -0,0 +1,18 @@
+import { TimeUnit } from './timeunit';
+interface RetryPolicy {
+    intervals(): Iterable<number>;
+}
+declare function simpleRetryPolicy(count: number, interval: number, opts?: {
+    units?: TimeUnit;
+}): RetryPolicy;
+declare function fixedRetryPolicy(intervals: number[], opts?: {
+    units?: TimeUnit;
+}): RetryPolicy;
+declare function exponentialBackoffRetryPolicy(count: number, opts?: {
+    exponential?: number;
+    limit?: number;
+    units?: TimeUnit;
+}): RetryPolicy;
+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/dist/types/lib/timeunit.d.ts

@@ -0,0 +1,21 @@
+declare enum TimeUnit {
+    Milliseconds = 1,
+    Millisecond = 1,
+    Seconds = 1000,
+    Second = 1000,
+    Minutes = 60000,
+    Minute = 60000,
+    Hours = 3600000,
+    Hour = 3600000,
+    Days = 86400000,
+    Day = 86400000
+}
+/**
+ * Converts time value in other units to milliseconds.
+ *
+ * @param time a time value to be converted
+ * @param units the units of time
+ * @returns the time value in milliseconds
+ */
+declare function toMilliseconds(time: number, units?: TimeUnit): number;
+export { TimeUnit, toMilliseconds };

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

@@ -0,0 +1,49 @@
+import { TimeUnit } from './timeunit';
+/**
+ * Zzzz...
+ *
+ * @param time time to sleep
+ * @param units the units on time
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+declare function sleep(time: number, units?: TimeUnit): Promise<void>;
+/**
+ * Delays the execution of the specified action and returns its value.
+ *
+ * @param action a function to execute with delay
+ * @param time time to sleep
+ * @param units the units on time
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+declare function delay<T>(action: () => T | Promise<T>, time: number, units?: TimeUnit): Promise<T>;
+/**
+ * Return a function that returns the elapsed time relative to this call.
+ * @returns a function
+ */
+declare function stopwatch(): (units?: TimeUnit) => number;
+/**
+ * Awaits a specified condition to evaluate to true with or without a timeout.
+ *
+ * @param condition the condition to wait for
+ * @param opts options that control evaluation intervals and timeout
+ * @returns a promise that resolves when the condition becomes true, or rejects when a set timeout is crossed.
+ */
+declare function until(condition: () => boolean, opts?: {
+    interval?: number;
+    timeout: number;
+    units?: TimeUnit;
+}): Promise<void>;
+/**
+ * Alias to `until`
+ */
+declare const eventually: typeof until;
+/**
+ * Executes an action with a specified timeout. If the action times out, rejects with TimeoutError.
+ *
+ * @param action an action to execute with timeout
+ * @param timeout the timeout to set for the action
+ * @param units the time units
+ * @returns the action result
+ */
+declare function withTimeout<T>(action: () => T | Promise<T>, timeout: number, units?: TimeUnit): Promise<T>;
+export { withTimeout, sleep, delay, stopwatch, until, eventually };

package/index.ts

@@ -1,3 +1,10 @@
-export * from './lib/timeunit';
-export * from './lib/utilities';
-export * from './lib/retry';
+export { TimeUnit, toMilliseconds } from './lib/timeunit';
+export { withTimeout, sleep, delay, stopwatch, until, eventually } from './lib/utilities';
+export {
+  RetryPolicy,
+  retryAround,
+  retriable,
+  fixedRetryPolicy,
+  simpleRetryPolicy,
+  exponentialBackoffRetryPolicy
+} from './lib/retry';

package/lib/utilities.ts

@@ -1,5 +1,11 @@
 import { TimeUnit, toMilliseconds } from './timeunit';
 
+class TimeoutError extends Error {
+  constructor(message?: string) {
+    super(message || 'Timeout');
+  }
+}
+
 /**
  * Zzzz...
  *
@@ -24,7 +30,10 @@ function sleep(time: number, units?: TimeUnit): Promise<void> {
 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);
+    const timer = setTimeout(() => Promise.resolve(action()).then(resolve, reject), delayMs);
+    process.on('beforeExit', () => {
+      clearTimeout(timer);
+    });
   });
 }
 
@@ -51,10 +60,6 @@ async function until(
   condition: () => boolean,
   opts?: { interval?: number; timeout: number; units?: TimeUnit }
 ): Promise<void> {
-  if (condition()) {
-    return;
-  }
-
   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;
@@ -63,12 +68,17 @@ async function until(
     const handle = setInterval(() => {
       if (Date.now() > deadline) {
         clearInterval(handle);
-        reject(new Error('Timeout'));
+        reject(new TimeoutError());
       }
 
-      if (condition()) {
+      try {
+        if (condition()) {
+          clearInterval(handle);
+          resolve();
+        }
+      } catch (e) {
         clearInterval(handle);
-        resolve();
+        reject(e);
       }
     }, interval);
   });
@@ -79,4 +89,41 @@ async function until(
  */
 const eventually = until;
 
-export { sleep, delay, stopwatch, until, eventually };
+/**
+ * Executes an action with a specified timeout. If the action times out, rejects with TimeoutError.
+ *
+ * @param action an action to execute with timeout
+ * @param timeout the timeout to set for the action
+ * @param units the time units
+ * @returns the action result
+ */
+async function withTimeout<T>(action: () => T | Promise<T>, timeout: number, units?: TimeUnit): Promise<T> {
+  const promisedAction = new Promise<T>((resolve, reject) => {
+    try {
+      resolve(action());
+    } catch (e) {
+      reject(e);
+    }
+  });
+
+  const race = new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new TimeoutError());
+    }, toMilliseconds(timeout, units));
+
+    return Promise.resolve(promisedAction).then(
+      r => {
+        clearTimeout(timer);
+        resolve(r);
+      },
+      err => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+
+  return race;
+}
+
+export { withTimeout, sleep, delay, stopwatch, until, eventually };

package/package.json

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