From 05587dfc9341f04499d16b8b4345502c4290e306 Mon Sep 17 00:00:00 2001 From: Shai Nagar Date: Fri, 25 Feb 2022 22:26:08 +0200 Subject: [PATCH] naming changes and add timeBounded timeout wrapper util (#40) * naming changes and add timeBounded timeout wrapper util * updated exports --- README.md | 43 +++++++++++-------- index.ts | 2 +- lib/utilities.ts | 10 ++++- test/{withTimeout.spec.ts => timeout.spec.ts} | 14 +++--- 4 files changed, 42 insertions(+), 27 deletions(-) rename test/{withTimeout.spec.ts => timeout.spec.ts} (60%) diff --git a/README.md b/README.md index 5427bf9..ffb1555 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,19 @@ 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) + - [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,7 +33,7 @@ npm i @sha1n/about-time ``` # Utilities & Features -## Delay +## delay ```ts // Execute a function with delay and return it's value await delay(action, { time: 10 }); @@ -40,15 +41,23 @@ 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, { time: 10 }); -await withTimeout(action, { time: 10, units: TimeUnit.Milliseconds }); -await withTimeout(action, { time: 10, units: TimeUnit.Milliseconds, unref: true }); +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); @@ -56,7 +65,7 @@ await sleep(10, { units: TimeUnit.Seconds }); await sleep(10, { units: TimeUnit.Seconds, unref: true }); ``` -## Stopwatch +## stopwatch ```ts // Measure time between actions const elapsed = stopwatch(); @@ -70,7 +79,7 @@ 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, { deadline: 10000 }); @@ -106,14 +115,14 @@ intervali = min(limit, (exponentiali - 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); diff --git a/index.ts b/index.ts index faa96bb..6c397d0 100644 --- a/index.ts +++ b/index.ts @@ -1,5 +1,5 @@ export { TimeUnit, toMilliseconds } from './lib/timeunit'; -export { withTimeout, sleep, delay, stopwatch, until, eventually } from './lib/utilities'; +export { timeoutAround, timeBounded, sleep, delay, stopwatch, until, eventually } from './lib/utilities'; export { RetryPolicy, retryAround, diff --git a/lib/utilities.ts b/lib/utilities.ts index 137024f..8b6ed86 100644 --- a/lib/utilities.ts +++ b/lib/utilities.ts @@ -136,7 +136,7 @@ const eventually = until; * @param options timer options * @returns the action result */ -async function withTimeout(action: () => T | Promise, options: TimerOptions): Promise { +async function timeoutAround(action: () => T | Promise, options: TimerOptions): Promise { const promisedAction = new Promise((resolve, reject) => { try { resolve(action()); @@ -169,4 +169,10 @@ async function withTimeout(action: () => T | Promise, options: TimerOption return race; } -export { withTimeout, sleep, delay, stopwatch, until, eventually }; +function timeBounded(action: () => T | Promise, options: TimerOptions): () => Promise { + return () => { + return timeoutAround(action, options); + }; +} + +export { timeoutAround, timeBounded, sleep, delay, stopwatch, until, eventually }; diff --git a/test/withTimeout.spec.ts b/test/timeout.spec.ts similarity index 60% rename from test/withTimeout.spec.ts rename to test/timeout.spec.ts index c3e543f..bee78ab 100644 --- a/test/withTimeout.spec.ts +++ b/test/timeout.spec.ts @@ -1,16 +1,16 @@ import 'jest-extended'; import { TimeUnit } from '../lib/timeunit'; -import { until, withTimeout } from '../lib/utilities'; +import { until, timeBounded } from '../lib/utilities'; import { anError, aString } from './randoms'; -describe('withTimeout', () => { +describe('timeoutAround/timeBounded', () => { const expectedError = anError(); const expectedValue = aString(); test('should reject when the action rejects', async () => { const action = () => Promise.reject(expectedError); - await expect(withTimeout(action, { time: 1, units: TimeUnit.Minute })).rejects.toThrow(expectedError); + await expect(timeBounded(action, { time: 1, units: TimeUnit.Minute })()).rejects.toThrow(expectedError); }); test('should reject when the action throws', async () => { @@ -18,19 +18,19 @@ describe('withTimeout', () => { throw expectedError; }; - await expect(withTimeout(action, { time: 1, units: TimeUnit.Minute })).rejects.toThrow(expectedError); + await expect(timeBounded(action, { time: 1, units: 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, { time: 1, units: TimeUnit.Minute })).resolves.toEqual(expectedValue); + await expect(timeBounded(action, { time: 1, units: 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, { time: 1, units: TimeUnit.Minute })).resolves.toEqual(expectedValue); + await expect(timeBounded(action, { time: 1, units: TimeUnit.Minute })()).resolves.toEqual(expectedValue); }); // eslint-disable-next-line prettier/prettier @@ -40,7 +40,7 @@ describe('withTimeout', () => { await until(() => done); }; - await expect(withTimeout(longAction, { time: 1, units: TimeUnit.Millisecond })).rejects.toThrow(/Timeout/); + await expect(timeBounded(longAction, { time: 1, units: TimeUnit.Millisecond })()).rejects.toThrow(/Timeout/); done = true; }); });