@sha1n/about-time 0.0.7 → 0.0.10

package/README.md

@@ -12,18 +12,20 @@ A collection of essential time related utilities.
 - [About-Time](#about-time)
 - [Install](#install)
 - [Utilities & Features](#utilities--features)
-  - [Delay](#delay)
-  - [WithTimeout](#withtimeout)
-  - [Sleep](#sleep)
-  - [Stopwatch](#stopwatch)
-  - [Until / Eventually](#until--eventually)
+  - [delay](#delay)
+  - [delayed](#delayed)
+  - [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
@@ -32,25 +34,46 @@ npm i @sha1n/about-time
 ```
 
 # Utilities & Features
-## Delay
+## delay
 ```ts
-// Execute a function with delay and return it's value
-await delay(action, 10, TimeUnit.Milliseconds);
+// Executes a function with delay and returns it's value
+await delay(action, { time: 10 });
+await delay(action, { time: 10, units: TimeUnit.Milliseconds });
+await delay(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
 ```
 
-## WithTimeout
+## delayed
 ```ts
-// Execute a function and guards it with a specified timeout
-await withTimeout(action, 10, TimeUnit.Milliseconds);
+// Returns a new function that executes the specified action with delay and returns it's value
+const delayedAction = delayed(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
+const result = await delayedAction();
 ```
 
-## Sleep
+## timeoutAround
 ```ts
-// Pause execution for a specified amount of time
-await sleep(10, TimeUnit.Seconds);
+// Executes a function and guards it with a specified timeout
+await timeoutAround(action, { time: 10 });
+await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds });
+await timeoutAround(action, { time: 10, units: TimeUnit.Milliseconds, unref: true });
 ```
 
-## Stopwatch
+## timeBounded
+Wraps a given function with `timeoutAround` with the specified arguments.
+```ts
+const timeBoundAction = timeBounded(action, options);
+const result = await timeBoundAction();
+```
+
+
+## sleep
+```ts
+// Pauses execution for a specified amount of time
+await sleep(10);
+await sleep(10, { units: TimeUnit.Seconds });
+await sleep(10, { units: TimeUnit.Seconds, unref: true });
+```
+
+## stopwatch
 ```ts
 // Measure time between actions
 const elapsed = stopwatch();
@@ -64,11 +87,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});
+// Waits for a condition to become true
+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
@@ -98,14 +123,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,16 +1,30 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 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; } });
+exports.exponentialBackoffRetryPolicy = exports.simpleRetryPolicy = exports.fixedRetryPolicy = exports.retriable = exports.retryAround = exports.eventually = exports.until = exports.stopwatch = exports.timeBounded = exports.timeoutAround = exports.delay = exports.sleep = exports.toMilliseconds = void 0;
+__exportStar(require("./lib/types"), exports);
+var toMilliseconds_1 = require("./lib/toMilliseconds");
+Object.defineProperty(exports, "toMilliseconds", { enumerable: true, get: function () { return toMilliseconds_1.toMilliseconds; } });
+var delay_1 = require("./lib/delay");
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return delay_1.sleep; } });
+Object.defineProperty(exports, "delay", { enumerable: true, get: function () { return delay_1.delay; } });
+var timeout_1 = require("./lib/timeout");
+Object.defineProperty(exports, "timeoutAround", { enumerable: true, get: function () { return timeout_1.timeoutAround; } });
+Object.defineProperty(exports, "timeBounded", { enumerable: true, get: function () { return timeout_1.timeBounded; } });
+var stopwatch_1 = require("./lib/stopwatch");
+Object.defineProperty(exports, "stopwatch", { enumerable: true, get: function () { return stopwatch_1.stopwatch; } });
+var eventually_1 = require("./lib/eventually");
+Object.defineProperty(exports, "until", { enumerable: true, get: function () { return eventually_1.until; } });
+Object.defineProperty(exports, "eventually", { enumerable: true, get: function () { return eventually_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; } });

package/dist/lib/delay.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delayed = exports.delay = exports.sleep = void 0;
+const toMilliseconds_1 = require("./toMilliseconds");
+/**
+ * Zzzz...
+ *
+ * @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, options) {
+    return new Promise(resolve => {
+        const timeout = setTimeout(resolve, (0, toMilliseconds_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;
+/**
+ * Delays the execution of the specified action and returns its value.
+ *
+ * @param action a function to execute with delay
+ * @param options timer options
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+async function delay(action, options) {
+    await sleep(options.time, options);
+    const result = await action();
+    return result;
+}
+exports.delay = delay;
+/**
+ * Returns a new function that executes the specified action with delay.
+ *
+ * @param action a function to execute with delay
+ * @param options timer options
+ * @returns a new function.
+ */
+function delayed(action, options) {
+    return async () => {
+        return delay(action, options);
+    };
+}
+exports.delayed = delayed;

package/dist/lib/eventually.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventually = exports.until = void 0;
+const toMilliseconds_1 = require("./toMilliseconds");
+const types_1 = require("./types");
+/**
+ * Awaits a specified condition to evaluate to true with or without a timeout.
+ *
+ * @param condition the condition to wait for
+ * @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, options) {
+    const defaultInterval = 50;
+    const deadline = (options === null || options === void 0 ? void 0 : options.deadline) ? Date.now() + (0, toMilliseconds_1.toMilliseconds)(options.deadline, options.units) : Number.MAX_VALUE;
+    const interval = (options === null || options === void 0 ? void 0 : options.interval) ? (0, toMilliseconds_1.toMilliseconds)(options.interval, options.units) : defaultInterval;
+    return new Promise((resolve, reject) => {
+        const handle = setInterval(() => {
+            if (Date.now() > deadline) {
+                clearInterval(handle);
+                reject(new types_1.TimeoutError());
+            }
+            try {
+                if (condition()) {
+                    clearInterval(handle);
+                    resolve();
+                }
+            }
+            catch (e) {
+                clearInterval(handle);
+                reject(e);
+            }
+        }, interval);
+        if (options === null || options === void 0 ? void 0 : options.unref) {
+            handle.unref();
+        }
+    });
+}
+exports.until = until;
+/**
+ * Alias to `until`
+ */
+const eventually = until;
+exports.eventually = eventually;

package/dist/lib/retry.js

@@ -1,12 +1,13 @@
 "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");
+const toMilliseconds_1 = require("./toMilliseconds");
+const delay_1 = require("./delay");
+const types_1 = require("./types");
 class SimpleRetryPolicy {
     constructor(count, interval, units) {
         this.count = count;
-        this.interval = (0, timeunit_1.toMilliseconds)(interval, units);
+        this.interval = (0, toMilliseconds_1.toMilliseconds)(interval, units);
     }
     *intervals() {
         let count = this.count;
@@ -18,7 +19,7 @@ class SimpleRetryPolicy {
     }
 }
 class ExponentialBackoffRetryPolicy {
-    constructor(count, exponential = 2, limit = Infinity, units = timeunit_1.TimeUnit.Milliseconds) {
+    constructor(count, exponential = 2, limit = Infinity, units = types_1.TimeUnit.Milliseconds) {
         this.count = count;
         this.exponential = exponential;
         this.limit = limit;
@@ -37,7 +38,7 @@ class ExponentialBackoffRetryPolicy {
 class FixedRetryPolicy {
     constructor(intervals, units) {
         this._intervals = intervals.reduceRight((result, v) => {
-            result.push((0, timeunit_1.toMilliseconds)(v, units));
+            result.push((0, toMilliseconds_1.toMilliseconds)(v, units));
             return result;
         }, []);
     }
@@ -73,7 +74,7 @@ async function retryAround(action, policy, predicate = () => true) {
             if (next.done || !predicate(e)) {
                 throw e;
             }
-            await (0, utilities_1.sleep)(next.value);
+            await (0, delay_1.sleep)(next.value);
         }
     } while (!next.done);
     throw new Error('Unexpected error. This is most likely a bug.');

package/dist/lib/stopwatch.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stopwatch = void 0;
+const types_1 = require("./types");
+/**
+ * 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 || types_1.TimeUnit.Milliseconds);
+    };
+}
+exports.stopwatch = stopwatch;

package/dist/lib/timeout.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeoutAround = exports.timeBounded = void 0;
+const toMilliseconds_1 = require("./toMilliseconds");
+const types_1 = require("./types");
+/**
+ * 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 timeoutAround(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 types_1.TimeoutError());
+        }, (0, toMilliseconds_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.timeoutAround = timeoutAround;
+function timeBounded(action, options) {
+    return () => {
+        return timeoutAround(action, options);
+    };
+}
+exports.timeBounded = timeBounded;

package/dist/lib/toMilliseconds.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMilliseconds = void 0;
+/**
+ * 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/types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = 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;
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message || 'Timeout');
+    }
+}
+exports.TimeoutError = TimeoutError;

package/dist/lib/utilities.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eventually = exports.until = exports.stopwatch = exports.delay = exports.sleep = exports.withTimeout = void 0;
+exports.eventually = exports.until = exports.stopwatch = exports.delay = exports.sleep = exports.timeBounded = exports.timeoutAround = void 0;
 const timeunit_1 = require("./timeunit");
 class TimeoutError extends Error {
     constructor(message) {
@@ -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 timeoutAround(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);
@@ -116,4 +124,10 @@ async function withTimeout(action, timeout, units) {
     });
     return race;
 }
-exports.withTimeout = withTimeout;
+exports.timeoutAround = timeoutAround;
+function timeBounded(action, options) {
+    return () => {
+        return timeoutAround(action, options);
+    };
+}
+exports.timeBounded = timeBounded;

package/dist/types/index.d.ts

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

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

@@ -0,0 +1,26 @@
+import { TimerOptions } from './types';
+/**
+ * Zzzz...
+ *
+ * @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, 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 options timer options
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+declare function delay<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T>;
+/**
+ * Returns a new function that executes the specified action with delay.
+ *
+ * @param action a function to execute with delay
+ * @param options timer options
+ * @returns a new function.
+ */
+declare function delayed<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T>;
+export { sleep, delay, delayed };

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

@@ -0,0 +1,14 @@
+import { PollOptions } from './types';
+/**
+ * Awaits a specified condition to evaluate to true with or without a timeout.
+ *
+ * @param condition the condition to wait for
+ * @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, options?: PollOptions): Promise<void>;
+/**
+ * Alias to `until`
+ */
+declare const eventually: typeof until;
+export { until, eventually };

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

@@ -1,4 +1,4 @@
-import { TimeUnit } from './timeunit';
+import { TimeUnit } from './types';
 interface RetryPolicy {
     intervals(): Iterable<number>;
 }

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

@@ -0,0 +1,7 @@
+import { TimeUnit } from './types';
+/**
+ * Return a function that returns the elapsed time relative to this call.
+ * @returns a function
+ */
+declare function stopwatch(): (units?: TimeUnit) => number;
+export { stopwatch };

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

@@ -0,0 +1,11 @@
+import { TimerOptions } from './types';
+/**
+ * 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 timeoutAround<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T>;
+declare function timeBounded<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T>;
+export { timeBounded, timeoutAround };

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

@@ -0,0 +1,10 @@
+import { TimeUnit } from './types';
+/**
+ * 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 { toMilliseconds };

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

@@ -0,0 +1,48 @@
+declare enum TimeUnit {
+    Milliseconds = 1,
+    Millisecond = 1,
+    Seconds = 1000,
+    Second = 1000,
+    Minutes = 60000,
+    Minute = 60000,
+    Hours = 3600000,
+    Hour = 3600000,
+    Days = 86400000,
+    Day = 86400000
+}
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+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;
+};
+export { TimeUnit, PollOptions, TimeoutError, TimerOptions };

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,9 @@ 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>;
-export { withTimeout, sleep, delay, stopwatch, until, eventually };
+declare function timeoutAround<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T>;
+declare function timeBounded<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T>;
+export { timeoutAround, timeBounded, sleep, delay, stopwatch, until, eventually };

package/index.ts

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

package/lib/delay.ts

@@ -0,0 +1,48 @@
+import { toMilliseconds } from './toMilliseconds';
+import { TimerOptions } from './types';
+
+/**
+ * Zzzz...
+ *
+ * @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, options?: Omit<TimerOptions, 'time'>): Promise<void> {
+  return new Promise(resolve => {
+    const timeout = setTimeout(resolve, toMilliseconds(time, options?.units));
+
+    if (options?.unref) {
+      timeout.unref();
+    }
+  });
+}
+
+/**
+ * Delays the execution of the specified action and returns its value.
+ *
+ * @param action a function to execute with delay
+ * @param options timer options
+ * @returns a promise that resolves when the specified time has elapsed.
+ */
+async function delay<T>(action: () => T | Promise<T>, options: TimerOptions): Promise<T> {
+  await sleep(options.time, options);
+  const result = await action();
+
+  return result;
+}
+
+/**
+ * Returns a new function that executes the specified action with delay.
+ *
+ * @param action a function to execute with delay
+ * @param options timer options
+ * @returns a new function.
+ */
+function delayed<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T> {
+  return async () => {
+    return delay(action, options);
+  };
+}
+
+export { sleep, delay, delayed };

package/lib/eventually.ts

@@ -0,0 +1,45 @@
+import { toMilliseconds } from './toMilliseconds';
+import { PollOptions, TimeoutError } from './types';
+
+/**
+ * Awaits a specified condition to evaluate to true with or without a timeout.
+ *
+ * @param condition the condition to wait for
+ * @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, options?: PollOptions): Promise<void> {
+  const defaultInterval = 50;
+  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 TimeoutError());
+      }
+
+      try {
+        if (condition()) {
+          clearInterval(handle);
+          resolve();
+        }
+      } catch (e) {
+        clearInterval(handle);
+        reject(e);
+      }
+    }, interval);
+
+    if (options?.unref) {
+      handle.unref();
+    }
+  });
+}
+
+/**
+ * Alias to `until`
+ */
+const eventually = until;
+
+export { until, eventually };

package/lib/retry.ts

@@ -1,5 +1,6 @@
-import { TimeUnit, toMilliseconds } from './timeunit';
-import { sleep } from './utilities';
+import { toMilliseconds } from './toMilliseconds';
+import { sleep } from './delay';
+import { TimeUnit } from './types';
 
 interface RetryPolicy {
   intervals(): Iterable<number>;

package/lib/stopwatch.ts

@@ -0,0 +1,15 @@
+import { TimeUnit } from './types';
+
+/**
+ * Return a function that returns the elapsed time relative to this call.
+ * @returns a function
+ */
+function stopwatch(): (units?: TimeUnit) => number {
+  const startTime = Date.now();
+
+  return (units?: TimeUnit) => {
+    return (Date.now() - startTime) / (units || TimeUnit.Milliseconds);
+  };
+}
+
+export { stopwatch };

package/lib/timeout.ts

@@ -0,0 +1,50 @@
+import { toMilliseconds } from './toMilliseconds';
+import { TimerOptions, TimeoutError } from './types';
+
+/**
+ * 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 timeoutAround<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;
+}
+
+function timeBounded<T>(action: () => T | Promise<T>, options: TimerOptions): () => Promise<T> {
+  return () => {
+    return timeoutAround(action, options);
+  };
+}
+
+export { timeBounded, timeoutAround };

package/lib/{timeunit.ts → toMilliseconds.ts}

@@ -1,15 +1,4 @@
-enum TimeUnit {
-  Milliseconds = 1,
-  Millisecond = Milliseconds,
-  Seconds = 1000,
-  Second = Seconds,
-  Minutes = 1000 * 60,
-  Minute = Minutes,
-  Hours = 1000 * 60 * 60,
-  Hour = Hours,
-  Days = 1000 * 60 * 60 * 24,
-  Day = Days
-}
+import { TimeUnit } from './types';
 
 /**
  * Converts time value in other units to milliseconds.
@@ -22,4 +11,4 @@ function toMilliseconds(time: number, units?: TimeUnit): number {
   return time * (units ? units : 1);
 }
 
-export { TimeUnit, toMilliseconds };
+export { toMilliseconds };

package/lib/types.ts

@@ -0,0 +1,54 @@
+enum TimeUnit {
+  Milliseconds = 1,
+  Millisecond = Milliseconds,
+  Seconds = 1000,
+  Second = Seconds,
+  Minutes = 1000 * 60,
+  Minute = Minutes,
+  Hours = 1000 * 60 * 60,
+  Hour = Hours,
+  Days = 1000 * 60 * 60 * 24,
+  Day = Days
+}
+
+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;
+};
+
+export { TimeUnit, PollOptions, TimeoutError, TimerOptions };

package/package.json

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

package/lib/utilities.ts

@@ -1,129 +0,0 @@
-import { TimeUnit, toMilliseconds } from './timeunit';
-
-class TimeoutError extends Error {
-  constructor(message?: string) {
-    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: number, units?: TimeUnit): Promise<void> {
-  return new Promise(resolve => {
-    setTimeout(resolve, toMilliseconds(time, units));
-  });
-}
-
-/**
- * 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<T>(action: () => T | Promise<T>, time: number, units?: TimeUnit): Promise<T> {
-  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);
-    });
-  });
-}
-
-/**
- * Return a function that returns the elapsed time relative to this call.
- * @returns a function
- */
-function stopwatch(): (units?: TimeUnit) => number {
-  const startTime = Date.now();
-
-  return (units?: TimeUnit) => {
-    return (Date.now() - startTime) / (units || TimeUnit.Milliseconds);
-  };
-}
-
-/**
- * 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: () => boolean,
-  opts?: { interval?: number; timeout: number; units?: TimeUnit }
-): 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;
-
-  return new Promise<void>((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);
-  });
-}
-
-/**
- * Alias to `until`
- */
-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
- * @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 };