Holosun

A DOM events API with delegation and type declarations. Holosun is built to remain completely interoperable with the native events API.

Usage

The distribution provided at ./dist/holosun.umd.js can be used directly in the browser, with the API begin namespaced as a holosun global variable.

Or, use the package like any other node package:

// ES6 module syntax
import * as holosun from 'holosun';
import { on, off } from 'holosun';

// CommonJS syntax
const holosun = require('holosun');
const { on, off } = require('holosun');

Alteratively, importing TypeScript directly will allow transpiled code to be optimize, including only the required portions of Holosun.

import { on, off } from 'holosun/typescript';

Note: this package includes a proper ECMAScript module.

API Summary

function	description
holosun.on()	Attach an event listener that will be called whenever a specified event type is delivered to the given target.
holosun.one()	Attach an event listener that will be called once whenever each of the specified event types are delivered to the given target.
holosun.any()	Attach an event listener that will be called once whenever any of the specified event types are delivered to the given target.
holosun.off()	Detach event listeners of the specified event types from the given target.
holosun.trigger()	Executes all listeners attached to the given target for the specified event types.

API

holosun.on()

on (target, types, listener[, useCapture | options])

Attach an event listener that will be called whenever a specified event type is delivered to the given target.

on (node, selector, types, listener[, useCapture | options])

Attach an event listener that will be called whenever a specified event type is delivered to the given node from specific descendants.

Parameters

parameter	type	description
target	EventTarget	The target on which the event listener is attached.
node	Node	The node on which the event listener is attached.
selector	string	A selector string to filter the descendants of the given node that trigger the event.
types	string	A case-sensitive string representing the event types to listen for.
listener	EventListener | EventListenerObject | null	The object that receives a notification (an object that implements the Event interface) when an event of a specified type occurs. This must be an object implementing the EventListener interface, or a function.
useCapture	boolean	Whether or not events of these types will be dispatched to the registered listener before being dispatched to any target beneath it in the DOM tree.
options	AddEventListenerOptions	An options object specifying characteristics about the event listener.

Returns

The provided listener when successfully attached; otherwise, undefined.

holosun.one()

one (target, types, listener[, useCapture | options])

Attach an event listener that will be called once whenever each of the specified event types are delivered to the given target.

one (node, selector, types, listener[, useCapture | options])

Attach an event listener that will be called once whenever each of the specified event types are delivered to the given node from specific descendants.

Parameters & Returns

Same as holosun.on().

holosun.any()

any (target, types, listener[, useCapture | options])

Attach an event listener that will be called once whenever any of the specified event types are delivered to the given target.

any (node, selector, types, listener[, useCapture | options])

Attach an event listener that will be called once whenever any of the specified event types are delivered to the given node from specific descendants.

Parameters & Returns

Same as holosun.on().

holosun.off()

off (target, types)

Detach all event listeners of the specified event types from the given target.

off (target, types, listener[, useCapture | options])

Detach an event listener of the specified event types from the given target.

off (node, selector, types)

Detach all event listeners of the specified event types from the given node for the specified selector.

off (node, selector, types, listener[, useCapture | options])

Detach an event listener of the specified event types from the given node for the specified selector.

Parameters

parameter	type	description
target	EventTarget	The target from which the event listener is detached.
node	Node	The node from which the event listener is detached.
selector	string	A selector which should match the one used when attaching event listeners.
types	string	A case-sensitive string representing the event types to detach.
listener	EventListener | EventListenerObject | null	The event listener to detach from the event target.
useCapture	boolean	Whether or not the EventListener to be detached is registered as a capturing listener.
options	EventListenerOptions	An options object specifying characteristics about the event listener.

Returns

true when successfully detached at least one listener; otherwise, false.

holosun.trigger()

trigger (target, types[, options][, useCustomEvent])

Executes all listeners attached to the given target for the specified event types.

Parameters

parameter	type	description
target	EventTarget	The target on which the specified events are executed.
types	string	A case-sensitive string representing the event types to execute.
options	EventInit | CustomEventInit	An options object specifying characteristics about the triggered event.
useCustomEvent	boolean	Whether or not to trigger an event or a custom event.

Returns

A list of tuples, where the first value is the event type and the second is true; unless the event is cancelable and at least one of the event listeners, which received the event, called Event.preventDefault(), the second value is false.

ECMAScript Modules

This library comes with ECMAScript Modules (ESM) support for Node.js versions that support it as well as bundlers like rollup.js and webpack (targeting both, Node.js and browser environments).

CDN Builds

ECMAScript Modules

To load this module directly into modern browsers that support loading ECMAScript Modules you can make use of jspm:

<script type="module">
  import { on } from 'https://jspm.dev/holosun';
  on(document, 'click', () => {
    window.location.href = 'https://youtu.be/950sXulKXGs?t=10';
  });
</script>

UMD

To load this module directly into older browsers you can use the UMD (Universal Module Definition) builds from any of the following CDNs.

These CDNs all provide the entire API as a holosun global variable:

<script>
  holosun.on(document, 'click', () => {
    window.location.href = 'https://youtu.be/950sXulKXGs?t=10';
  });
</script>

Using UNPKG

<script src="https://unpkg.com/holosun@latest/dist/holosun.umd.js"></script>

Using jsDelivr

<script src="https://cdn.jsdelivr.net/npm/holosun@latest/dist/holosun.umd.js"></script>

Support Limiters

These are some of the common limiting issues which are not addressed in this library. You might consider using core-js when building Holosun into a project.

1. Element.prototype.matches is not available in IE, however there is a polyfill available for IE9+.
2. Map, Set, WeakMap, WeakSet is not available before IE 11, there are multiple polyfills.