painless-event-emitter v3.0.1
╔═╗┌─┐┬┌┐┌┬ ┌─┐┌─┐┌─┐ ╔═╗┬ ┬┌─┐┌┐┌┌┬┐ ╔═╗┌┬┐┬┌┬┐┌┬┐┌─┐┬─┐
╠═╝├─┤│││││ ├┤ └─┐└─┐ ║╣ └┐┌┘├┤ │││ │ ║╣ ││││ │ │ ├┤ ├┬┘
╩ ┴ ┴┴┘└┘┴─┘└─┘└─┘└─┘ ╚═╝ └┘ └─┘┘└┘ ┴ ╚═╝┴ ┴┴ ┴ ┴ └─┘┴└─
(Ascii-art generated by patorjk.com)
Upgrading
If upgrading from 1.0 to 2.0:
This is huge upgrade, make sure to read UPGRADE-2.0.md for details.
If upgrading from 2.0 to 3.0
It's not as big but there are some breaking changes, its a much more straightforward upgrade. Look at UPGRADE-3.0.md for details.
What is PainlessEventEmitter?
In Short, its a way to synchronously processes event listeners or
subscribers if you prefer asynchronously
.
It's like NodeJS's own EventEmitter but really just better!
- The native EventEmitter ignores emit return data while PainlessEventEmitter doesn't opening up a new world of code design possibilities.
- With PainlessEventEmitter you can connect them and allow emits to be passed down to connected children.
- Listeners can be sync or async, it doesn't matter. just return a promise or prefix with es6 async keyword if async.
But didn't EventEmitter stay synchronous for a reason?
Well, they did, but they're reasons don't make much sense. They claim it's to prevent race conditions, out-of-order calling, and logic errors which only happen if you call asynchronous code and move on to the next one right away.
But who does that? There are better systems, PainlessEventEmitter simply calls the listener, if the listener returns a promise or has the es6 async keyword it just waits for the promise to be resolved or rejected before moving onto the next listener.
So:
- The
listener call order is still kept
- There's
no room for race conditions and therefore logic errors
Its still asynchronous friendly which is critical in production code
especially since NodeJS and javascript is becoming more and more asynchronous everyday for good reason,its kind of a pain to not have a proper event emitter to support modern javascript.
Wait, won't returning all the return and error values get kind of messy?
Not if done right:
- Firstly,
only the non-undefined values are kept
, which cuts out most return values from most listeners as anything else is an explicit return and therefore important to keep. - Secondly,
errors are separated from regular returns
- Thirdly its a class that's returned, not some array, the class
provides
quick and simple properties
that allow pulling stuff likeonly the first value
,if there was an error
, orother common stuff
with ease.
Why is it called PainlessEventEmitter?
Because AsyncEventEmitter (async-event-emitter) was taken lol, it's close enough.
What about really long running listeners?
The emitter counts on listeners being responsible
, if there may be a
source that gets hung up for too long or indefinitely then that listener
should be built to handle that scenario accordingly
.
By doing it this way it can ensure that scenario's like that are handled
properly by their own listener rather than expanding and complicating
the code to do a catch-all
which may create issues or restrictions
in other listeners or complicate the API as a whole.
What does the emitter guarantee?
It guarantees:
All listeners will be called
regardless of any errors that may be thrown in other listeners.All non-undefined return values and thrown errors will be captured
An emit results object will always be returned
even if there are no listeners.
OK so how do I begin?
Well, the best thing to do is glance at the API which is available online here.
A lot of hard work went into getting the api complete and correct and there you will find all of your answers.
If you want a simple quick starter look here at this tutorial!
So what about this emit return object
The return value is really what sets this package apart from other
EventEmitters
apart from the awesome async features and additional
methods.
Check it out the api on the emit return object here.
This package is solid
This package is actively tested with Jasmine and thoroughly documented throughout. It also contains complete JSDoc comments and full online JSDoc generated documentation.
Do you like this package or have an issue?
If this package has helped you I encourage you to follow it, give it a star, or fork it on github. If you have any ideas, suggestions, issues, or ways to improve upon it then let us know over at github by filing an issue.
Contributions are also encouraged and the CONTRIBUTING.md file shows all the details on development and how to contribute back but its mostly just commit changes and send a pull request.
This project is licensed Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0.txt
Run it in your browser
Thanks to TonicDev, you now have a way to run this package right in your browser to test it out. If your on the NPM site you can see the TonicDev link on the right-hand side, otherwise you can always go to the link below.
TonicDev will load up a preset example we provide that you can play around with to get a feel for this package.
https://tonicdev.com/npm/painless-event-emitter
How to develop
To develop, git clone
this repository and npm install
to install the
development dependencies. Make sure to run npm run build
when
needed which will test & compile ES6/7 to ES5 and re-generate the docs.
You can run those individually if you want with npm run docs
and
npm run compile
. To auto-copy over docs from master to gh-pages run
npm run pages
before committing and pushing.
For testing, just run npm run test
If you want to contribute back read the CONTRIBUTING.md
file.
Documentation
Detailed documentation exists for this package, it should already by viewable on clone. Feel free to look through it for any questions you may have. The source code is also heavily documented if you want to look through it as well for answers.
Online docs exist here http://junestoolbox.github.io/painless-event-emitter/docs
Whats New
Check out the CHANGELOG.md file for latest changes and updates