subscribe-ui-event

With subscribe-ui-event, instead of calling multiple window.addEvenListener('scroll', eventHandler); by different components, call subscribe('scroll', eventHandler). It will only add single event listener and dispatch event to those who subscribe the event via eventemitter3.

Why single event? More performance and less memory consumption.

Single Event Listener v.s. Multiple Event Listeners

The jsperf runs 10 addEvenListener and 10 non-throttling subscribe, and the outcome is that the ops/sec of subscribe is slightly less. But in regular case, you will use throttling subscribe, and it will be more performant.

For 10 addEventListener, the difference of memory consumption between peak and trough is about 4.1K.

For 10 subscribe, the difference of memory consumption between peak and trough is about 1.0K.

Other Benifits

Do throttling by default.
Get document.body.scrollTop, window.innerWidth once.
Provide requestAnimationFrame throttle for the need of high performance.
Be able to use like scrollStart (see below) those edge events.

Install

ynpm install subscribe-ui-event

API

Subscription subscribe(String eventType, Function callback, Object? options)

Provide throttled version of window or document events, such like scroll, resize and visibilitychange to subscribe. It also provides some higher, compound events, such like viewportchange, which combines scroll, resize and visibilitychange events.

Note on IE8 or the below, the throttle will be turned off because the event object is global and will be deleted for setTimeout or rAF.

Example:

var subscribe = require('subscribe-ui-event').subscribe;
function eventHandler (e, payload) {
    // e is the native event object and
    // payload is the additional information
    ...
}
// 50ms throttle by default
var subscription = subscribe('scroll', eventHandler);
// remove later
subscription.unsubscribe();

Addtional Payload

The format of the payload is:

{
    type: <String>, // could be 'scroll', 'resize' ...
    // you need to pass options.enableScrollInfo = true to subscribe to get the following data
    scroll: {
        top: <Number>, // The scroll position, i.g., document.body.scrollTop
        delta: <Number> // The delta of scroll position, it is helpful for scroll direction
    },
    // you need to pass options.enableResizeInfo = true to subscribe to get the following data
    resize: {
        width: <Number>, // The client width
        height: <Number> // The client height
    }
}

Options

options.throttleRate allows of changing the throttle rate, and the default value is 50 (ms). Set 0 for no throttle. On IE8, there will be no throttle, because throttling will use setTimeout or rAF to achieve, and the event object passed into event handler will be overwritten.

options.context allows of setting the caller of callback function.

options.useRAF = true allows of using requestAnimationFrame instead of setTimeout.

options.enableScrollInfo = true allows of getting scrollTop.

options.enableResizeInfo = true allows of getting width and height of client.

eventType could be one of the following:

scroll - window.scoll
scrollStart - The start window.scoll
scrollEnd - The end window.scoll
resize - window.resize
resizeStart - The start window.resize
resizeEnd - The end window.resize
visibilitychange - document.visibilitychange
viewportchange - scroll + resize + visibilitychange

unsubscribe

Void unsubscribe(String eventType, Function callback)

Unsubscribe an event. Note that all subscriptions with the same eventHandler and the same event type will be unsubscribed together even if they have different options.

License

This software is free to use under the BSD license. See the LICENSE file for license text and copyright information.

kaesonho/subscribe-ui-event