Holosun

An 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])

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 | An options object specifying characteristics about the triggered 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>