@unseenco/e

The complete (but tiny) js events solution - An event bus/emitter, simple DOM event API, and incredibly efficient delegated events.

Usage no npm install needed!

<script type="module">
  import unseencoE from 'https://cdn.skypack.dev/@unseenco/e';
</script>

README

E is a library which combines a eventBus/emitter, DOM events management, delegated events, and event-based utils into a single lightweight and performant library.

npm

E works in all major browsers and IE11. It includes any polyfills it needs to work in IE11 by default.

Getting started

In order to save a few bytes, the default package does not support IE11, and imports as an ES6 module (suitable for webpack and other ES6 environments).

In order to use, E must be instantiated:

import Events from '@unseenco/e'

const E = new Events()

If you need to support IE11, you can bring in the library as a polyfilled UMD module using the following:

import Events from '@unseenco/e/dist/es5'

And finally, if you want to be old-school, bring in the CDN version to add E to the window (very lame).

DOM Events

The on method attaches an event to one or many DOM elements with an easy to use API:

E.on('click', '.js-open', callback)
E.on('resize', window, callback)

// Also accepts NodeLists/Arrays of elements
E.on('click', document.querySelectorAll('.btn'), callback)

// With a HTMLElement
E.on('click', document.getElementById('unique'), callback)

// You can also pass additional addEventListener options as a 4th param
E.on('click', '#btn', callback, { passive: true })

You can also add a callback to multiple events at once:

E.on('click keyup', '.js-open', callback)

Delegated Events

Events bound with delegate are bound to the document instead of the element, which removes the need to rebind/remove events during page transitions, or when the DOM updates after load.

Intercepted events are dispatched to the correct handler using Selector Set, which matches the event target element incredibly efficiently.

The delegate method currently only accepts a selector string to match elements:

E.delegate('click', '.js-open', callback)

You can delegate a callback to multiple events at once:

E.delegate('input keyup', '.js-input', callback)

Removing Events

You can remove a bound handler using the off method. The arguments are exactly the same as the on method, and events can be removed by passing a string, HTMLElement, or a NodeList.

E.off('click', '.js-open', callback)

If an element has the same callback for multiple events, you can remove them all at once:

E.off('click focus', '.js-open', callback)

Event Bus

The API for the event bus uses the exact same methods as above, but without supplying a DOM element.

Registering a bus event

Use the on method to register an event and a listener. As many listeners can be subscribed to your event as you like.

E.on('my.bus.event', callback)

Emitting a bus event

Use the emit method without an element will attempt to dispatch a bus event. If one exists, all listeners will be run in the order they were originally added:

E.emit('my.bus.event')

// you can also pass arguments through
E.emit('my.bus.event', arg1, arg2)

Removing a listener from a bus event

You can subscribe one or all events from the bus using off:

// Will remove the supplied callback if found
E.off('my.bus.event', callback)

// Will remove all listeners for the bus event
E.off('my.bus.event')

Binding handlers to maintain scope

There are many ways to ensure that your event handlers keep the correct context when working with OO.

Closure method (preferred)

Probably the simplest method way to keep scope in handlers:

// Include @babel/plugin-proposal-class-properties for property support in classes
class Foo {
    bar = (e) => {
        console.log(this)
    }
}

Using bindAll

Unseen.e has a handy bindAll method if you prefer to do it the old fashioned way:

class Foo {
    constructor() {
        E.bindAll(this, ['bar'])
    }

    bar() {
        console.log(this)
    }
}

You can also call bindAll without providing any methods to automatically bind all public methods to the current instance:

class Foo {
    constructor() {
        // Will bind bar, but not privateBar
        E.bindAll(this)
    }

    bar() {
        console.log(this)
    }
    
    #privateBar() {
    
    }
}