https://github.com/roydukkey/holosun

A DOM events API with delegation and type declarations.
https://github.com/roydukkey/holosun
delegation ecmascript-modules event-listener
Last synced: about 1 year ago
JSON representation
A DOM events API with delegation and type declarations.
Host: GitHub
URL: https://github.com/roydukkey/holosun
Owner: roydukkey
License: other
Created: 2021-04-09T22:09:50.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2021-08-13T20:27:12.000Z (over 4 years ago)
Last Synced: 2025-03-15T18:14:10.540Z (about 1 year ago)
Topics: delegation, ecmascript-modules, event-listener
Language: TypeScript
Homepage:
Size: 90.8 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

          
# Holosun

[![Release Version](https://img.shields.io/npm/v/holosun.svg)](https://www.npmjs.com/package/holosun)

[![License](https://img.shields.io/badge/License-Apache%202-blue.svg)](https://github.com/roydukkey/holosun/blob/master/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:

```js

// 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.

```js

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

```

Note: this package includes a proper [ECMAScript module](#ecmascript-modules).

## API Summary

| function | description |

| --- | --- |

| [`holosun.on()`](#holosunon) | Attach an event listener that will be called whenever a specified event type is delivered to the given target. |

| [`holosun.one()`](#holosunone) | Attach an event listener that will be called once whenever each of the specified event types are delivered to the given target. |

| [`holosun.any()`](#holosunany) | Attach an event listener that will be called once whenever any of the specified event types are delivered to the given target. |

| [`holosun.off()`](#holosunoff) | Detach event listeners of the specified event types from the given target. |

| [`holosun.trigger()`](#holosuntrigger) | 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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target on which the event listener is attached. |

| `node` | [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/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 type](https://developer.mozilla.org/en-US/docs/Web/Events)s to listen for. |

| `listener` | [`EventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|
[`EventListenerObject`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|
`null` | The object that receives a notification (an object that implements the [Event](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) | 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()`](#holosunon).

### 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()`](#holosunon).

### 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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target from which the event listener is detached. |

| `node` | [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/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 type](https://developer.mozilla.org/en-US/docs/Web/Events)s to detach. |

| `listener` | [`EventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|
[`EventListenerObject`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|
`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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#parameters) | 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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target on which the specified events are executed. |

| `types` | `string` | A case-sensitive string representing the [event type](https://developer.mozilla.org/en-US/docs/Web/Events)s to execute. |

| `options` | [`EventInit`](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event#values) \| [`CustomEventInit`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#parameters) | An options object specifying characteristics about the triggered event. |

| `useCustomEvent` | `boolean` | Whether or not to trigger an [event](https://developer.mozilla.org/en-US/docs/Web/Events) or a [custom event](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent). |

##### 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()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault), the second value is `false`.

## ECMAScript Modules

This library comes with [ECMAScript Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) support for Node.js versions that support it as well as bundlers like [rollup.js](https://rollupjs.org/guide/en/#tree-shaking) and [webpack](https://webpack.js.org/guides/tree-shaking/) (targeting both, Node.js and browser environments).

## CDN Builds

### ECMAScript Modules

To load this module directly into modern browsers that [support loading ECMAScript Modules](https://caniuse.com/#feat=es6-module) you can make use of [jspm](https://jspm.org/):

```html

  import { on } from 'https://jspm.dev/holosun';

  on(document, 'click', () => {

    window.location.href = 'https://youtu.be/950sXulKXGs?t=10';

  });

```

### UMD

To load this module directly into older browsers you can use the [UMD (Universal Module Definition)](https://github.com/umdjs/umd) builds from any of the following CDNs.

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

```html

  holosun.on(document, 'click', () => {

    window.location.href = 'https://youtu.be/950sXulKXGs?t=10';

  });

```

#### Using [UNPKG](https://unpkg.com/browse/holosun/dist/)

```html

```

#### Using [jsDelivr](https://cdn.jsdelivr.net/npm/holosun@latest/dist/)

```html

```

## Support Limiters

These are some of the common limiting issues which are not addressed in this library. You might consider using [`core-js`](https://github.com/zloirock/core-js) when building Holosun into a project.

1. `Element.prototype.matches` is not available in IE, however there is a [polyfill](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches#polyfill) available for IE9+.

1. `Map`, `Set`, `WeakMap`, `WeakSet` is not available before IE 11, there are multiple polyfills.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/roydukkey/holosun

Awesome Lists containing this project

README
