Skip to content

A DOM events API with delegation and type declarations.

License

Notifications You must be signed in to change notification settings

roydukkey/holosun

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Holosun

Release Version License

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.