added timeout utility function (#9)

README.md

@@ -12,6 +12,7 @@ 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)
@@ -35,6 +36,12 @@ npm i @sha1n/about-time
 await delay(action, 10, TimeUnit.Milliseconds);
 ```
 
+## WithTimeout
+```ts
+// Execute a function and guards it with a specified timeout
+await withTimeout(action, 10, TimeUnit.Milliseconds);
+```
+
 ## Sleep
 ```ts
 // Pause execution for a specified amount of time

lib/utilities.ts

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

package.json

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

test/withTimeout.spec.ts

@@ -0,0 +1,46 @@
+import 'jest-extended';
+import { TimeUnit } from '../lib/timeunit';
+import { until, withTimeout } from '../lib/utilities';
+import { anError, aString } from './randoms';
+
+describe('withTimeout', () => {
+  const expectedError = anError();
+  const expectedValue = aString();
+
+  test('should reject when the action rejects', async () => {
+    const action = () => Promise.reject(expectedError);
+
+    await expect(withTimeout(action, 1, TimeUnit.Minute)).rejects.toThrow(expectedError);
+  });
+
+  test('should reject when the action throws', async () => {
+    const action = () => {
+      throw expectedError;
+    };
+
+    await expect(withTimeout(action, 1, TimeUnit.Minute)).rejects.toThrow(expectedError);
+  });
+
+  test('should resolve to the action resolved value when resolves on time', async () => {
+    const action = () => Promise.resolve(expectedValue);
+
+    await expect(withTimeout(action, 1, TimeUnit.Minute)).resolves.toEqual(expectedValue);
+  });
+
+  test('should resolve to the action returned value when returns on time', async () => {
+    const action = () => expectedValue;
+
+    await expect(withTimeout(action, 1, TimeUnit.Minute)).resolves.toEqual(expectedValue);
+  });
+
+  // eslint-disable-next-line prettier/prettier
+  test('should reject with timeout when the action doesn\'t resolve on time', async () => {
+    let done = false;
+    const longAction = async () => {
+      await until(() => done);
+    };
+
+    await expect(withTimeout(longAction, 1, TimeUnit.Millisecond)).rejects.toThrow(/Timeout/);
+    done = true;
+  });
+});