@sha1n/about-time 0.0.7 → 0.0.8

package/README.md

@@ -35,19 +35,25 @@ npm i @sha1n/about-time
 ## 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, 10, TimeUnit.Milliseconds);
+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
@@ -67,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/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/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/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 withTimeout<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 => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha1n/about-time",
-  "version": "0.0.7",
+  "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"
 }