From e01d0d853470c150e35427c2b857117db18923f5 Mon Sep 17 00:00:00 2001 From: Avril Date: Fri, 11 Feb 2022 21:21:16 +0000 Subject: [PATCH] Update README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fortune for async-timeout-js's current commit: Blessing − 吉 --- README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 759fe18..31eb3d7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,27 @@ -# AsyncTimeout - A promisified wrapper for `setTimeout()` and `setInterval()` +# AsyncTimeout - `setTimeout()` and `setInterval()` for async code. +The class `AsyncTimeout(function, timeout)`. +An async wrapper around `setTimeout()`, and an async iterator wrapper around `setInterval()`, which resolves to/yields the return value of the supplied function for both `.timeout()` and `.interval()` respectively. + +## Methods + +There are two methods on the class `AsyncTimeout(func, time)`: +* `timeout()`: Creates an `await`able promise that will resolve to the value of `func()` when the timeout `time` is reached. +* `interval()`: Creates a `for await`able async iterator that will resolve to the value of `func()` each `time` it is called. To cancel the interval, simply break from the loop or stop calling `.next()` on the returned async iterator. + +## Parameters +* `thing` - The function to call after the timeout/interval. The result of the promise (or the yield for `interval()`) is the result of this function call. If the funtion throws, then the rejection of the promise will be that error thrown. +* `interval` - The time to wait for the timeout or interval + +## Example usages +See `example()` in the file for detail. + +### `setTimeout()` promisified +`await (new AsyncTimeout(() => "value", 100)).timeout() /* === "value" */` is `setTimeout(()=> "value", 100)` promisified. + +### `setInterval()` async iterator-ifyed. +`for await (const value of new AsyncTimeout(() => "value", 100)).interval()) { /* value === "value" */ }` is `setInterval(()=> "value", 100)` with each interval promisified. +`value` will be the result of each interval call, so the function passed can capture, interact with, and return whatever it wants during the interval and each `value` will be the result of it being called again at each interval (as is expected.) + +This is an infinite iterator. To cancel the interval, simply break out of the `for await` loop or otherwise stop using the iterator returned from `.interval()`.