Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shalvah/burns
Manage your application's events without writing spaghetti code
https://github.com/shalvah/burns
event-broadcasting event-driven event-handlers events handlers listeners nodejs npm
Last synced: about 1 month ago
JSON representation
Manage your application's events without writing spaghetti code
- Host: GitHub
- URL: https://github.com/shalvah/burns
- Owner: shalvah
- Created: 2017-10-15T13:27:59.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2021-05-07T08:23:56.000Z (over 3 years ago)
- Last Synced: 2024-11-01T16:47:55.420Z (about 2 months ago)
- Topics: event-broadcasting, event-driven, event-handlers, events, handlers, listeners, nodejs, npm
- Language: JavaScript
- Homepage: http://shalvah.me/burns/
- Size: 1.66 MB
- Stars: 90
- Watchers: 4
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
Burns
Excellent
[](https://badge.fury.io/js/burns)
[](https://travis-ci.org/shalvah/burns)
[](https://dependabot.com)
[](https://www.npmjs.com/package/burns)
Burns is a lightweight (no dependencies!) Node.js module for managing application events elegantly. Define your events and handlers in one place and dispatch them when you need to.
Inspired by Laravel's [events](https://laravel.com/docs/master/events) and [broadcasting](https://laravel.com/docs/master/broadcasting) systems.
## What you get
- Easy visibility of all application events
- Default handler to catch generic events
- Attaching event handlers at multiple places
- Asynchronous handling of events
- Inbuilt event broadcasting
## Installation
```bash
npm install burns
```
## How to use
```js
const burns = require('burns');
```
Define an event handler:
```js
// handlers/order.js
function sendOrderShippedEmail(data)
{
mailer.sendEmail(`Hi ${data.userName}, Your order ${data.orderId} has been shipped`);
}
```
Register the event and attach the handler:
```js
let { sendOrderShippedEmail } = require('./handlers/order');
burns.registerEvents({
orderShipped: sendOrderShippedEmail
});
```
Dispatch the event when you're ready! 🚀
```js
burns.dispatch('orderShipped', {
orderId: order.id,
userName: user.name
});
```
### Registering events
Register events by calling ` registerEvents` with a single object. The names of your events should be the keys of this object and their handlers the values:
```js
burns.registerEvents({
newPurchase: sendInvoice,
orderShipped: notifyUser
});
```
You can also attach multiple handlers to a single event:
```js
burns.registerEvents({
userSignUp: [
userListener.sendEmail,
userListener.congratulateReferrer
]
})
```
Burns allows you to register events at multiple locations. This means that for a large application, you can have each application component define its own events and handlers by calling `registerEvents` wherever it needs to.
### Defining handlers
A handler is a function that responds to an event. A handler takes a single parameter, the event payload which you pass when dispatching the event:
```js
function sendInvoice(data)
{
let invoice = createInvoice(data.order, data.user);
mailer.sendEmail('Here is your order invoice', invoice);
}
burns.registerEvents({
newPurchase: sendInvoice,
});
// this will call sendInvoice with data = {}
burns.dispatch('newPurchase');
// this will call sendInvoice with data containing order and user
burns.dispatch('newPurchase', {
order: getOrder(),
user: findUser()
});
```
#### Stopping event propagation
Suppose you're running a subscription service (like Netflix) where you bill users every month. Your app can fire a `newBillingPeriod` event and perform multiple actions when this event is fired: charge the customer's card, extend their subscription, send them a invoice. Burns allows you to register multiple handlers for the event, and will call them in the order in which they were registered:
```js
burns.registerEvents({
newBillingPeriod: [
chargeCustomerCard,
extendCustomerSubscription,
sendCustomerInvoice,
]
})
```
If the process of charging the customer's card fails, you probably wouldn't want to go through with the other actions. In such a situation, you can prevent the subsequent handlers from being called by returning `false` from the current handler:
```js
function chargeCustomerCard(customer) {
if (!PaymentProcessor.chargeCard(customer)) {
// bonus: dispatch a 'chargeCardFailed` event. Cool, huh?
burns.dispatch('chargeCardFailed', customer);
return false;
}
}
```
#### Using a default handler
You may specify a `defaultHandler`. Burns will pass a dispatched event to this handler if no handlers are registered for it:
```js
function handleEverything (data) {}
burns.configure({
defaultHandler: handleEverything
});
// this will call handleEverything
burns.dispatch('unregisteredEvent', somePayload);
```
### Dispatching events
To dispatch an event, call ` dispatch` with the name of the event:
```js
burns.dispatch('postLiked');
```
You may also pass in a payload containing data to be transmitted with the event:
```js
burns.dispatch('postLiked', {
postId: 69,
likedBy: 42,
});
```
This object will be passed as an argument to the handler.
## Broadcasting events
Supposing you have an `orderStatusUpdated` event that is fired when the status of an order is updated, and you wish to update the order status on your frontend in realtime. Burns handles this for you via event broadcasting.
### Configuring broadcasting
You'll need to specify a `broadcaster`. For now, broadcasting is only supported to the console log (broadcaster: 'log') and [Pusher](http://pusher.com) (broadcaster: 'pusher'). The default broadcaster is `log`, which will log all broadcasts to the Node console. (You can disable broadcasting by setting `broadcaster: null`.)
If you're broadcasting with Pusher, pass in your credentials as a `pusher` object:
```js
burns.configure({
broadcaster: 'pusher',
pusher: {
appId: 'APP_ID',
key: 'APP_KEY',
secret: 'SECRET_KEY',
cluster: 'CLUSTER',
}
})
```
> âš To use the `pusher` broadcaster, you need to install the Pusher Node.js SDK: `npm install pusher`
### Broadcasting an event
Then register the `orderStatusUpdated` using the "advanced" configuration format:
```js
burns.registerEvents({
orderStatusUpdated: {
handlers: [
notifyUser
],
broadcastOn: 'orderStatusUpdates' // or an array of channels
}
});
```
The `broadcastOn` key specifies the name of the channel on which the event will be broadcast. It can be a string or a function that takes in the event payload and returns a channel name.
Now when you call
```js
burns.dispatch('orderStatusUpdated', order);
```
Burns will automatically publish a message on the channel `orderStatusUpdates` with the `order` object as the payload. All that's left is for you to listen for this event on the frontend.
If you'd like to exclude the client that triggered the event from receiving the broadcast, you can pass in an object as the third parameter to `dispatch()`. The 'exclude' key should contain the socket ID of the client to exclude:
```js
burns.dispatch('orderStatusUpdated', order, { exclude: socketId });
```
### Conditional broadcasting
You can also have conditional broadcasting by using the `broadcastIf` property.
```js
burns.registerEvents({
orderStatusUpdated: {
handlers: [
notifyUser
],
broadcastOn: 'orderStatusUpdates',
broadcastIf: process.env.NODE_ENV === 'production'
}
});
```
You may specify a function that takes the event payload and should return true or false:
```js
({
broadcastIf: (data) => data.user.notifications.enabled === true,
// your function can return a promise too. Burns will await the result
// broadcastIf: (data) => data.user.getSettings()
// .then(settings => settings.notifications.enabled === true),
})
```
`
## But Node already supports events natively!
Yes, and that's a great thing for handling events at lower levels in your code base (for instance, on `open` of a file, on `data` of a stream). When dealing with events at a higher level (such as a new user signing up), Burns is perfect for helping you keep your code clean and organized.
## Asynchronous vs. Synchronous
Unlike [Node.js' inbuilt events system](https://nodejs.org/api/events.html#events_asynchronous_vs_synchronous), Burns calls your event handlers asynchronously in the order in which they were registered. This means that the functions are queued behind whatever I/O event callbacks that are already in the event queue, thus enabling you to send a response to your user immediately, while your event gets handled in the background.
This also means that if you dispatch one event from a handler for another event, all of the original event's handlers will be executed first, before moving on to those for the newly-dispatched event.
## Like it?
Star and share, and give me a shout out [on Twitter](http://twitter.com/theshalvah)
## Contributing
If you have an bugfix, idea or feature you'd like to implement, you're welcome to send in a PR!
(Requires Node v8 or above)
- Clone the repo
```bash
git clone https://github.com/shalvah/burns.git
```
- Create a branch for your fix/feature:
```bash
git checkout -b my-patch
```
- Write your code. Add tests too, if you know how. If you're not sure how, just send in the PR anyway.
- Make sure all tests are passing
```bash
npm run test
```