ezvent v1.0.7

ezvent

ezvent is a simple library for responding to and dispatching custom events. Weighing in at just over 1kb compressed it leaves a small footprint on your app, but provides simple yet powerful utility.

ezvent works great in both browser and node environments.

Installation

Via npm

npm install ezvent --save

Using the distrubuted code

Download the minified js file and include it in your project

<script src="dist/ezvent.min.js"></script>

Quick Start

import { Dispatcher } from "ezvent";

// Create a new Dispatcher
const MyDispatcher = new Dispatcher();

function messageReceived(data) {
  console.log("You got a new message: ", data.text);
}

// Add event listeners to the dispatcher
const eventId = MyDispatcher.on("Message", messageReceived);

// Add a listener that will fire only once
MyDispatcher.once("Message", (data) => {
  console.log("The first message was: ", data.text);
});

// Dispatch events to the dispatcher

MyDispatcher.dispatch("Message", { text: "Hello, World!" })

// Remove individual event listeners from the dispatcher
MyDispatcher.off("Message", messageReceived);
// or
MyDispatcher.off("Message", eventId);

// remove an entire event from the dispatcher
MyDispatcher.remove("Message");

Usage Examples

Events sent from a web socket

import { Dispatcher } from "ezvent";
import { addMessage, changeMessage, addNotification } from "./example/path";

const SocketDispatcher = new Dispatcher();
const socket = new WebSocket('ws://localhost:8080');

// Listen for socket messages
socket.addEventListener("message", (message) => {
  // dispatch the appropriate event
  const data = JSON.parse(message.data);
  SocketDispatcher.dispatch(data.event, data);
});

// Add event listeners for the events that come from the socket
SocketDispatcher.on("NewMessage", addMessage);
SocketDispatcher.on("MessageEdited", changeMessage);

// We can also turn event listeners off & back on
window.addEventListener("blur", () => {
    SocketDispatcher.on("NewMessage", addNotification);
});

window.addEventListener("focus", () => {
    SocketDispatcher.off("NewMessage", addNotification);
});

Documementation

Create a new instance

You create a new instance of ezvent.Dispatcher to get started. You'll use this instance to add and remove listeners, as well as dispatch events.

const ExampleDispatcher = new Dispatcher();

You can pass an optional data argument to the dispatcher when you create it:

const ExampleDispatcher = new Dispatcher(data);

This data will be stored on ExampleDispatcher.data. It can be useful to store data here about the dispatcher, or shared data that needs to be used by the event callbacks.

You could create many different instances all responsible for a different set of events.

Adding an event listener

Dispatcher.on() adds a new event event listener to the provided event name.

Takes two required arguments: the name of the event which will fire the callback, and the callback itself.

ExampleDispatcher.on(eventName, callback);

on() also takes an optional third argument - a counter. This is an integer that limits the amount of times this callback can be called. For example if you pass in a counter of 3, the callback will be called at max 3 times. The listener will then be removed.

ExampleDispatcher.on(eventName, callback, counter);

on() returns the generated id of the callback. You can pass this id into off() to remove the listener. See off() for more info.

Only fire a callback once

Dispatcher.once() is an alias for on() with the counter argument set to 1. Use it like this:

ExampleDispatcher.once("EventName", () => {/* ... */});

The listener will be removed after it has been called once.

The value of this inside callbacks

Provided you use a regular function instead of an arrow function, the value of this inside a callback will be an object representing the event listener. It will have the counter and event name present for you to use in the callback, as well as the callback itself and the callback's ID.

ExampleDispatcher.on("EventName", () => { console.log(this) });
// >> Window

ExampleDispatcher.on("EventName", function() { console.log(this) });
// >> { event, counter, id, callback }

Remove a listener

Dispatcher.off() takes two arguments, the event name that you wish to remove a listener from, and the callback (or callback id) that you wish to be removed from that event.

ExampleDispatcher.off(eventName, callback);

callback in this case must be either the exact function that you passed into on() to create the listener, or the id returned from calling on() - so you'll need this stored in a varible somewhere.

Alternatively you can access the callback from within the this object inside the scope of the callback - useful for conditionally removing a callback from inside that same callback.

const id = ExampleDispatcher.on(eventName, callback);
ExampleDispatcher.off(eventName, id);

Remove an entire event

Dispatcher.remove() removes every listener for an event and removes that event from the reactor, it takes one argument, the event name:

ExampleDispatcher.remove(eventName);

Dispatch an event

Dispatcher.dispatch() fires all the registered callbacks for the given event.

Takes one required argument - the name of the event you want to dispatch.

ExampleDispatcher.dispatch(eventName);

Any extra arguments will be passed on to the callbacks.

ExampleDispatcher.dispatch(eventName, data);

you can pass as many arguments as you like.

ExampleDispatcher.dispatch(eventName, a, b, c);

You would handle this by providing the arguments to the event listener:

ExampleDispatcher.on(eventName, (a, b, c) => {/* ... */});

Remove all events

Dispatcher.reset() removes all events for the given dispatcher.