https://github.com/magicdawn/promise.timeout
add timeout support for async function
https://github.com/magicdawn/promise.timeout
Last synced: about 1 year ago
JSON representation
add timeout support for async function
- Host: GitHub
- URL: https://github.com/magicdawn/promise.timeout
- Owner: magicdawn
- Created: 2016-05-13T08:51:46.000Z (about 10 years ago)
- Default Branch: main
- Last Pushed: 2024-01-24T07:56:25.000Z (over 2 years ago)
- Last Synced: 2025-05-07T14:25:30.442Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 153 KB
- Stars: 11
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# promise.timeout
> add timeout support for async function
[](https://github.com/magicdawn/promise.timeout/actions/workflows/ci.yml)
[](https://codecov.io/gh/magicdawn/promise.timeout)
[](https://www.npmjs.com/package/promise.timeout)
[](https://www.npmjs.com/package/promise.timeout)
[](http://magicdawn.mit-license.org)
## Install
```sh
$ pnpm add promise.timeout
```
## Note
- this module targets ES5 environment.
- this module require global `AbortController`, Node.js has builtin global since v15
## API
```js
var ptimeout = require('promise.timeout')
```
`ptimeout(fn, timeout)`
- `fn` the async function
- `timeout` in ms
```js
var ptimeout = require('promise.timeout')
// a function will cost 20ms
function test() {
return new Promise(function (resolve, reject) {
setTimeout(function () {
resolve(20)
}, 20)
})
}
var test10 = ptimeout(test, 10)
var test50 = ptimeout(test, 50)
// 10 timeout
try {
await test10()
} catch (e) {
e.should.be.ok()
e.should.be.instanceof(ptimeout.TimeoutError)
e.message.should.match(/timeout/)
e.timeout.should.equal(10)
}
// 50 ok
var _50 = await test50()
_50.should.be.ok()
_50.should.equal(20)
```
### singal
ptimeout will provide an extra runtime argument `signal: AbortSignal`, you can use the signal to register abort action.
when timeout reached, the abort action will be executed
```js
var ptimeout = require('promise.timeout')
// a function will cost 20ms
function test(signal) {
return new Promise(function (resolve, reject) {
var timer = setTimeout(function () {
resolve(20)
}, 20)
// clean up
signal.addEventListener('abort', () => {
clearTimeout(timer)
})
})
}
var test10 = ptimeout(test, 10)
try {
await test10()
} catch (e) {
e.should.ok()
}
```
## FAQ
### Q: why move to `AbortController`
### A:
- easy to type, easy to strip signal argument, easy to use with TypeScript
- AND it's shiped in Node.js https://nodejs.org/api/globals.html#class-abortcontroller
- for browser, users should consider a polyfill for `AbortController` & `AbortSignal` if not provided nativly
old version use `onCancel` to register clean up action
### Q: Why onCancel
### A: Think `onCancel` like the AbortController
with `AbortController` you need to
```js
function normalFn(a, r, g, s, controller: AbortController) {
controller.signal.addEventListener('abort', () => {
// cancel operations that starts in `normalFn` body
})
}
```
- and `ptimeout` will call the `controller.abort()` if any timeout exceeds
- and with `onCancel`, you provide a cancel operation to ptimeout, ptimeout will call that
That's the same, and I don't want to depend on an extra package [abort-controller](https://github.com/mysticatea/abort-controller)
## See Also
- [promise.timeout](https://github.com/magicdawn/promise.timeout)
- [promise.retry](https://github.com/magicdawn/promise.retry)
- [promise.map](https://github.com/magicdawn/promise.map)
- [promise.ify](https://github.com/magicdawn/promise.ify)
- [promise.cb](https://github.com/magicdawn/promise.cb)
- [promise.obj](https://github.com/magicdawn/promise.obj)
- [promise.sleep](https://github.com/magicdawn/promise.sleep)
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## License
the MIT License http://magicdawn.mit-license.org