promievent
v0.1.5
Published
A TypeScript implementation of a Promise that can also emit events
Downloads
91
Maintainers
Readme
PromiEvent
A TypeScript implementation of a Promise that can also emit events.
A PromiEvent is a JavaScript Promise that is also a Node.js EventEmitter. This allows a Promise to emit lifecycle events before a Promise is resolved or rejected.
Installing
Using node.js:
npm install --save promievent
Node version support
Version 0.1.x supports PromiEvent.finally()
so needs to run on Node.js 10 or higher as it uses native Promise.prototype.finally
. See Node.js ES2015 Support for more details.
Version 0.0.x works on Node.js 8.
Usage
A PromiEvent can be used as a standard promise or an EventEmmiter, but it's best when used together. In the following example, the promise is resolved after 10 seconds but on each second a interval
event is emitted. An event is also emitted on the first and last second.
const promiEvent = new PromiEvent<number>((resolve, reject) =>
{
let counter = 0
const timer = setInterval(()=>
{
counter++
promiEvent.emit('interval', counter)
if (counter === 1) {
promiEvent.emit('first', counter)
}
if (counter === 10) {
promiEvent.emit('last', counter)
resolve(counter)
// stop the timer
clearInterval(timer)
}
}, 100)
})
The following registers an interval
event listener with the EventEmitter. This will print 10 lines.
promiEvent.on('interval', (count: number)=>
{
console.log(`interval number ${count}`)
})
The following register an interval
event listener that is only fired once. This will only print one line.
promiEvent.once('interval', (count: number)=>
{
console.log(`interval number ${count}`)
})
The following will resolve the promise and print one line with a count of 10.
promiEvent.then((count)=>
{
console.log(`interval number ${count}`)
}).catch((err)=>
{
console.log(`Something bad happened ${err.message}`)
// error handling
})
Or you can resolve the promise using async/await assuming this code is in an async function.
try {
const count = await promiEvent
console.log(`interval number ${count}`)
}
catch (err) {
console.log(`Something bad happened ${err.message}`)
// error handling
}
Credits
The inspiration for a Promise that emits events has come from Fabian Vogelsteller's Callbacks Promises Events in the Ethereum web3.js 1.x project. The JavaScript implementation is in web3-core-promievent.
The TypeScript implementation also got influence from Matthew Mueller's comments on an issue in Microsoft's TypeScript GitHub repo.
License
The MIT Licence.
See LICENSE.