@sha1n/about-time 0.0.6 → 0.0.9

package/README.md

@@ -10,45 +10,62 @@
 A collection of essential time related utilities.
 
 - [About-Time](#about-time)
-  - [Install](#install)
-  - [Delay](#delay)
-  - [WithTimeout](#withtimeout)
-  - [Sleep](#sleep)
-  - [Stopwatch](#stopwatch)
-  - [Until / Eventually](#until--eventually)
+- [Install](#install)
+- [Utilities & Features](#utilities--features)
+  - [delay](#delay)
+  - [timeoutAround](#timeoutaround)
+  - [timeBounded](#timebounded)
+  - [sleep](#sleep)
+  - [stopwatch](#stopwatch)
+  - [until / eventually](#until--eventually)
   - [Retry](#retry)
     - [RetryPolicy](#retrypolicy)
       - [Simple retry policy](#simple-retry-policy)
       - [Fixed retry policy](#fixed-retry-policy)
       - [Exponential backoff retry policy](#exponential-backoff-retry-policy)
-    - [RetryAround](#retryaround)
-    - [Retriable](#retriable)
+    - [retryAround](#retryaround)
+    - [retriable](#retriable)
 
 
-## Install
+# Install
 ```bash
 npm i @sha1n/about-time
 ```
 
-## Delay
+# 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
+## timeoutAround
 ```ts
 // Execute a function and guards it with a specified timeout
-await withTimeout(action, 10, TimeUnit.Milliseconds);
+await timeoutAround(action, { time: 10 });
+await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds });
+await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
 ```
 
-## Sleep
+## timeBounded
+Wraps a given function with `timeoutAround` with the specified arguments.
+```ts
+const timeBoundAction = timeBounded(action, options);
+const result = await timeBoundAction();
+```
+
+
+## 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
+## stopwatch
 ```ts
 // Measure time between actions
 const elapsed = stopwatch();
@@ -62,11 +79,13 @@ const elapsed1 = elapsed(TimeUnit.Milliseconds);
 const elapsed2 = elapsed(TimeUnit.Seconds);
 ```
 
-## Until / Eventually
+## 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
@@ -96,14 +115,14 @@ interval<sub>i</sub> = min(limit, (exponential<sup>i</sup> - 1) / 2)
 const retryPolicy = exponentialBackoffRetryPolicy(/* count = */10, /* opts?: { exponential?: number, limit?: number, units?: TimeUnit }*/);
 ```
 
-### RetryAround
+### retryAround
 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, predicate);
 ```
 
-### Retriable
+### retriable
 Wraps a given function with `retryAround` with the specified arguments.
 ```ts
 const retriableAction = retriable(action, retryPolicy, predicate);

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

@@ -10,13 +10,16 @@ class TimeoutError extends Error {
 /**
  * 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;
@@ -24,17 +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) => {
         const timer = setTimeout(() => Promise.resolve(action()).then(resolve, reject), delayMs);
-        process.on('beforeExit', () => {
-            clearTimeout(timer);
-        });
+        if (unref) {
+            timer.unref();
+        }
     });
 }
 exports.delay = delay;
@@ -53,13 +56,13 @@ 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) {
@@ -77,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;
@@ -89,11 +95,10 @@ 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
+ * @param options timer options
  * @returns the action result
  */
-async function withTimeout(action, timeout, units) {
+async function withTimeout(action, options) {
     const promisedAction = new Promise((resolve, reject) => {
         try {
             resolve(action());
@@ -105,7 +110,10 @@ async function withTimeout(action, timeout, units) {
     const race = new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             reject(new TimeoutError());
-        }, (0, timeunit_1.toMilliseconds)(timeout, units));
+        }, (0, timeunit_1.toMilliseconds)(options.time, options.units));
+        if (options.unref) {
+            timer.unref();
+        }
         return Promise.resolve(promisedAction).then(r => {
             clearTimeout(timer);
             resolve(r);

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,14 +56,10 @@ 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`
  */
@@ -41,9 +68,8 @@ 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
+ * @param options timer options
  * @returns the action result
  */
-declare function withTimeout<T>(action: () => T | Promise<T>, timeout: number, units?: TimeUnit): Promise<T>;
+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 { timeoutAround, timeBounded, sleep, delay, stopwatch, until, eventually } from './lib/utilities';
 export {
   RetryPolicy,
   retryAround,

package/lib/utilities.ts

@@ -6,16 +6,54 @@ class TimeoutError extends Error {
   }
 }
 
+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();
+    }
   });
 }
 
@@ -23,17 +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) => {
     const timer = setTimeout(() => Promise.resolve(action()).then(resolve, reject), delayMs);
-    process.on('beforeExit', () => {
-      clearTimeout(timer);
-    });
+
+    if (unref) {
+      timer.unref();
+    }
   });
 }
 
@@ -53,16 +92,13 @@ 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(() => {
@@ -81,6 +117,10 @@ async function until(
         reject(e);
       }
     }, interval);
+
+    if (options?.unref) {
+      handle.unref();
+    }
   });
 }
 
@@ -93,11 +133,10 @@ const eventually = 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
+ * @param options timer options
  * @returns the action result
  */
-async function withTimeout<T>(action: () => T | Promise<T>, timeout: number, units?: TimeUnit): Promise<T> {
+async function timeoutAround<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T> {
   const promisedAction = new Promise<T>((resolve, reject) => {
     try {
       resolve(action());
@@ -109,7 +148,11 @@ async function withTimeout<T>(action: () => T | Promise<T>, timeout: number, uni
   const race = new Promise<T>((resolve, reject) => {
     const timer = setTimeout(() => {
       reject(new TimeoutError());
-    }, toMilliseconds(timeout, units));
+    }, toMilliseconds(options.time, options.units));
+
+    if (options.unref) {
+      timer.unref();
+    }
 
     return Promise.resolve(promisedAction).then(
       r => {
@@ -126,4 +169,10 @@ async function withTimeout<T>(action: () => T | Promise<T>, timeout: number, uni
   return race;
 }
 
-export { withTimeout, sleep, delay, stopwatch, until, eventually };
+function timeBounded<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T> {
+  return () => {
+    return timeoutAround(action, options);
+  };
+}
+
+export { timeoutAround, timeBounded, sleep, delay, stopwatch, until, eventually };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha1n/about-time",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "A set of essential time related utilities",
   "repository": "https://github.com/sha1n/about-time",
   "author": "Shai Nagar",
@@ -22,38 +22,39 @@
   ],
   "scripts": {
     "clean": "rm -rf ./dist",
-    "prebuild": "yarn run clean",
     "build": "tsc",
-    "test": "DEBUG=error:* jest --coverage",
     "lint": "eslint --fix --ext .js,.ts .",
-    "posttest": "npm run lint -s",
-    "prepublish": "yarn run build"
+    "jest": "DEBUG='error:*' jest --coverage",
+    "test": "run jest && run lint",
+    "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"
 }