@sha1n/about-time 0.0.5 → 0.0.8

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,21 +26,34 @@ 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);
+await delay(action, { time: 10 });
+await delay(action, { time: 10, units: TimeUnit.Milliseconds });
+await delay(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
+```
+
+## WithTimeout
+```ts
+// Execute a function and guards it with a specified timeout
+await withTimeout(action, { time: 10 });
+await withTimeout(action, { time: 10, units: TimeUnit.Milliseconds });
+await withTimeout(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
 ```
 
 ## Sleep
 ```ts
 // Pause execution for a specified amount of time
-await sleep(10, TimeUnit.Seconds);
+await sleep(10);
+await sleep(10, { units: TimeUnit.Seconds });
+await sleep(10, { units: TimeUnit.Seconds, unref: true });
 ```
 
 ## Stopwatch
@@ -58,8 +73,10 @@ const elapsed2 = elapsed(TimeUnit.Seconds);
 ## Until / Eventually
 ```ts
 // Wait for a condition to become true
-await until(condition, {timeout: 1, units: TimeUnit.Minute});
-await eventually(condition, {timeout: 1, units: TimeUnit.Minute});
+await until(condition, { deadline: 10000 });
+await until(condition, { deadline: 10000, interval: 100 });
+await until(condition, { deadline: 10000, interval: 100, units: TimeUnit.Milliseconds });
+await until(condition, { deadline: 10000, interval: 100, units: TimeUnit.Milliseconds, unref: true });
 ```
 
 ## Retry

package/dist/index.js

@@ -1,10 +1,11 @@
 "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.toMilliseconds = exports.TimeUnit = void 0;
+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; } });

package/dist/lib/utilities.js

@@ -1,17 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eventually = exports.until = exports.stopwatch = exports.delay = exports.sleep = void 0;
+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
+ * @param time the approximate time to sleep (expect it to be as accurate as setTimeout)
+ * @param options timer options minus the time property
  * @returns a promise that resolves when the specified time has elapsed.
  */
-function sleep(time, units) {
+function sleep(time, options) {
     return new Promise(resolve => {
-        setTimeout(resolve, (0, timeunit_1.toMilliseconds)(time, units));
+        const timeout = setTimeout(resolve, (0, timeunit_1.toMilliseconds)(time, options === null || options === void 0 ? void 0 : options.units));
+        if (options === null || options === void 0 ? void 0 : options.unref) {
+            timeout.unref();
+        }
     });
 }
 exports.sleep = sleep;
@@ -19,14 +27,17 @@ 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
+ * @param options timer options
  * @returns a promise that resolves when the specified time has elapsed.
  */
-function delay(action, time, units) {
+function delay(action, options) {
+    const { time, units, unref } = options;
     const delayMs = (0, timeunit_1.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);
+        if (unref) {
+            timer.unref();
+        }
     });
 }
 exports.delay = delay;
@@ -45,18 +56,18 @@ 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
+ * @param options poll-options
  * @returns a promise that resolves when the condition becomes true, or rejects when a set timeout is crossed.
  */
-async function until(condition, opts) {
+async function until(condition, options) {
     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 = (options === null || options === void 0 ? void 0 : options.deadline) ? Date.now() + (0, timeunit_1.toMilliseconds)(options.deadline, options.units) : Number.MAX_VALUE;
+    const interval = (options === null || options === void 0 ? void 0 : options.interval) ? (0, timeunit_1.toMilliseconds)(options.interval, options.units) : defaultInterval;
     return new Promise((resolve, reject) => {
         const handle = setInterval(() => {
             if (Date.now() > deadline) {
                 clearInterval(handle);
-                reject(new Error('Timeout'));
+                reject(new TimeoutError());
             }
             try {
                 if (condition()) {
@@ -69,6 +80,9 @@ async function until(condition, opts) {
                 reject(e);
             }
         }, interval);
+        if (options === null || options === void 0 ? void 0 : options.unref) {
+            handle.unref();
+        }
     });
 }
 exports.until = until;
@@ -77,3 +91,37 @@ exports.until = 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 options timer options
+ * @returns the action result
+ */
+async function withTimeout(action, options) {
+    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)(options.time, options.units));
+        if (options.unref) {
+            timer.unref();
+        }
+        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

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

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

@@ -1,21 +1,52 @@
 import { TimeUnit } from './timeunit';
+declare type TimerOptions = {
+    /**
+     * The time to set
+     */
+    readonly time: number;
+    /**
+     * Optional units for the specified time
+     */
+    readonly units?: TimeUnit;
+    /**
+     * Whether to call unref on the timer
+     */
+    readonly unref?: boolean;
+};
+declare type PollOptions = {
+    /**
+     * The poll interval to set
+     */
+    readonly interval?: number;
+    /**
+     * The overall deadline to set
+     */
+    readonly deadline?: number;
+    /**
+     * Time units for specified time properties
+     */
+    readonly units?: TimeUnit;
+    /**
+     * Whether to call unref on any intervals/timers
+     */
+    readonly unref?: boolean;
+};
 /**
  * Zzzz...
  *
- * @param time time to sleep
- * @param units the units on time
+ * @param time the approximate time to sleep (expect it to be as accurate as setTimeout)
+ * @param options timer options minus the time property
  * @returns a promise that resolves when the specified time has elapsed.
  */
-declare function sleep(time: number, units?: TimeUnit): Promise<void>;
+declare function sleep(time: number, options?: Omit<TimerOptions, 'time'>): 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
+ * @param options timer options
  * @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>;
+declare function delay<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T>;
 /**
  * Return a function that returns the elapsed time relative to this call.
  * @returns a function
@@ -25,16 +56,20 @@ 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
+ * @param options poll-options
  * @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>;
+declare function until(condition: () => boolean, options?: PollOptions): Promise<void>;
 /**
  * Alias to `until`
  */
 declare const eventually: typeof 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 options timer options
+ * @returns the action result
+ */
+declare function withTimeout<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T>;
+export { withTimeout, sleep, delay, stopwatch, until, eventually };

package/index.ts

@@ -1,5 +1,5 @@
 export { TimeUnit, toMilliseconds } from './lib/timeunit';
-export { sleep, delay, stopwatch, until, eventually } from './lib/utilities';
+export { withTimeout, sleep, delay, stopwatch, until, eventually } from './lib/utilities';
 export {
   RetryPolicy,
   retryAround,

package/lib/utilities.ts

@@ -1,15 +1,59 @@
 import { TimeUnit, toMilliseconds } from './timeunit';
 
+class TimeoutError extends Error {
+  constructor(message?: string) {
+    super(message || 'Timeout');
+  }
+}
+
+type TimerOptions = {
+  /**
+   * The time to set
+   */
+  readonly time: number;
+  /**
+   * Optional units for the specified time
+   */
+  readonly units?: TimeUnit;
+  /**
+   * Whether to call unref on the timer
+   */
+  readonly unref?: boolean;
+};
+
+type PollOptions = {
+  /**
+   * The poll interval to set
+   */
+  readonly interval?: number;
+  /**
+   * The overall deadline to set
+   */
+  readonly deadline?: number;
+  /**
+   * Time units for specified time properties
+   */
+  readonly units?: TimeUnit;
+  /**
+   * Whether to call unref on any intervals/timers
+   */
+  readonly unref?: boolean;
+};
+
 /**
  * Zzzz...
  *
- * @param time time to sleep
- * @param units the units on time
+ * @param time the approximate time to sleep (expect it to be as accurate as setTimeout)
+ * @param options timer options minus the time property
  * @returns a promise that resolves when the specified time has elapsed.
  */
-function sleep(time: number, units?: TimeUnit): Promise<void> {
+function sleep(time: number, options?: Omit<TimerOptions, 'time'>): Promise<void> {
   return new Promise(resolve => {
-    setTimeout(resolve, toMilliseconds(time, units));
+    const timeout = setTimeout(resolve, toMilliseconds(time, options?.units));
+
+    if (options?.unref) {
+      timeout.unref();
+    }
   });
 }
 
@@ -17,14 +61,18 @@ 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
+ * @param options timer options
  * @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>, options: TimerOptions): Promise<T> {
+  const { time, units, unref } = options;
   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);
+
+    if (unref) {
+      timer.unref();
+    }
   });
 }
 
@@ -44,22 +92,19 @@ 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
+ * @param options poll-options
  * @returns a promise that resolves when the condition becomes true, or rejects when a set timeout is crossed.
  */
-async function until(
-  condition: () => boolean,
-  opts?: { interval?: number; timeout: number; units?: TimeUnit }
-): Promise<void> {
+async function until(condition: () => boolean, options?: PollOptions): Promise<void> {
   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 = options?.deadline ? Date.now() + toMilliseconds(options.deadline, options.units) : Number.MAX_VALUE;
+  const interval = options?.interval ? toMilliseconds(options.interval, options.units) : defaultInterval;
 
   return new Promise<void>((resolve, reject) => {
     const handle = setInterval(() => {
       if (Date.now() > deadline) {
         clearInterval(handle);
-        reject(new Error('Timeout'));
+        reject(new TimeoutError());
       }
 
       try {
@@ -72,6 +117,10 @@ async function until(
         reject(e);
       }
     }, interval);
+
+    if (options?.unref) {
+      handle.unref();
+    }
   });
 }
 
@@ -80,4 +129,44 @@ 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 options timer options
+ * @returns the action result
+ */
+async function withTimeout<T>(action: () => T | Promise<T>, options: TimerOptions): 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(options.time, options.units));
+
+    if (options.unref) {
+      timer.unref();
+    }
+
+    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.5",
+  "version": "0.0.8",
   "description": "A set of essential time related utilities",
   "repository": "https://github.com/sha1n/about-time",
   "author": "Shai Nagar",
@@ -22,38 +22,38 @@
   ],
   "scripts": {
     "clean": "rm -rf ./dist",
-    "prebuild": "yarn run clean",
     "build": "tsc",
-    "test": "DEBUG=error:* jest --coverage",
+    "test": "DEBUG='error:*' jest --coverage && run lint",
     "lint": "eslint --fix --ext .js,.ts .",
-    "posttest": "npm run lint -s",
-    "prepublish": "yarn run build"
+    "prepublish": "run build"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/chance": "^1.1.3",
+    "@types/is-ci": "^3.0.0",
     "@types/jest": "^27.4.0",
     "@types/node": "^17.0.8",
     "@typescript-eslint/eslint-plugin": "^5.1.0",
     "@typescript-eslint/parser": "^5.1.0",
     "chance": "^1.1.8",
-    "eslint": "^7.32.0",
+    "eslint": "^8.9.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-import": "^2.25.2",
-    "eslint-plugin-jest": "^25.7.0",
+    "eslint-plugin-jest": "^26.0.0",
     "eslint-plugin-no-floating-promise": "^1.0.2",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.0.0",
-    "eslint-plugin-unused-imports": "^1.1.5",
-    "jest": "~27.4.7",
+    "eslint-plugin-unused-imports": "^2.0.0",
+    "is-ci": "^3.0.1",
+    "jest": "^27.5.1",
     "jest-environment-node": "^27.2.0",
-    "jest-extended": "^1.1.0",
-    "jest-html-reporters": "^3.0.3",
+    "jest-extended": "^2.0.0",
+    "jest-html-reporters": "^3.0.5",
     "jest-mock-extended": "^2.0.4",
     "jest-summary-reporter": "^0.0.2",
     "prettier": "^2.4.1",
     "ts-jest": "^27.1.3",
     "ts-node": "^10.4.0",
     "typescript": "^4.5.4"
-  }
+  },
+  "packageManager": "yarn@3.2.0"
 }