eventhandling v0.0.4

eventhandling

Well-defined methods and declarations for firing events on EventTarget objects. Typed with Flow and built with ES-modules.

Installation

Simply do: npm install eventhandling.

What is it?

Well-defined methods and declarations for firing events on EventTarget objects. This library handles UIEvents, an interface that is implemented primarily through the following event types in the browser:

• MouseEvent
• TouchEvent
• WheelEvent
• KeyboardEvent
• FocusEvent
• CustomEvent

This library gives you some helper methods for easing up working with these kinds of events as well as typings to let you know which event types and configuration properties that are supported.

Example 1 - CustomEvent

import {fire} from "eventhandling";

window.addEventListener("myAwesomeEvent", e => console.log("Clicked!"));
fire("myAwesomeEvent");
// prints 'Clicked!' to the console.

Example 2 - MouseEvent

import {fireMouseEvent} from "eventhandling";

window.addEventListener("click", e => console.log("Clicked!"));
fireMouseEvent("click");
// prints 'Clicked!' to the console.

Example 3 - Listen once with Promises.

import {waitUntilFired} from "eventhandling";

async function aFunction () {
	await waitUntilFired("click", window);
	// Will continue execution from here when a 'click' event has been fired on the window object.
}

Changelog:

v0.04:

• Added a new method: waitUntilAnyIsFired().

v0.03:

• Changed the event type of fire() from Event to CustomEvent to enable the details object.

v0.02:

• Fixed typing errors.

v0.01:

• First release!

Usage

Import it in your project like this:

import {fire, ...} from "eventhandling"; // (standard) Transpiled to ES5.
// or

import {fire, ...} from "eventhandling/native" // Transpiled to ES5, native ES-modules.
// or

import {fire, ...} from "eventhandling/typed" // Flow typings, ES-modules.

Documentation

Types

type MouseEventName = "click"|"dblclick"|"mousedown"|"mouseenter"|"mouseleave"|"mousemove"|"mouseout"|"mouseover"|"mouseup";
type WheelEventName = "wheel";
type KeyboardEventName = "keydown"|"keyup";
type FocusEventName = "blur"|"focus"|"focusin"|"focusout";
type TouchEventName = "touchstart"|"touchend"|"touchmove"|"touchcancel";

interface EventDetails {
	bubbles: boolean;
	cancelable: boolean;
}

interface MouseEventDetails extends EventDetails {
	view?: Window;
	target?: EventTarget;
	detail?: number;
	screenX?: number;
	screenY?: number;
	clientX?: number;
	clientY?: number;
	altKey?: boolean;
	ctrlKey?: boolean;
	shiftKey?: boolean;
	metaKey?: boolean;
	button?: 0|1|2;
}

interface TouchEventDetails extends EventDetails {
	touches?: TouchList;
	targetTouches?: TouchList;
	changedTouches?: changedTouches;
	altKey?: boolean;
	metaKey?: boolean;
	ctrlKey?: boolean;
	shiftKey?: boolean;
}

interface FocusEventDetails extends EventDetails {
	view?: Window;
	target?: EventTarget;
	relatedTarget?: EventTarget;
	detail?: number;
}

interface WheelEventDetails extends MouseEventDetails {
	deltaX?: number;
	deltaY?: number;
	deltaZ?: number;
	deltaMode?: number;
}

interface KeyboardEventDetails extends EventDetails {
	view?: Window;
	target?: EventTarget;
	detail?: 0;
	key?: string;
	code?: string;
	altKey?: boolean;
	ctrlKey?: boolean;
	shiftKey?: boolean;
	metaKey?: boolean;
	repeat?: boolean;
	isComposing?: boolean;
}

Methods

fire()

fire (eventName: string, target?: EventTarget = window, detail?: any = null, config?: EventDetails): CustomEvent

Fires a CustomEvent on the the target.

Arguments

eventName: string

The event to fire. Can be anything - it's a Custom Event!

target?: EventTarget = window

The EventTarget to fire the event on.

detail?: any = null

Any details to go along with the event.

config?: EventDetails

The configuration object for the event. Defaults to { bubbles: true, cancelable: false }

Returns

Event

The constructed Event object.

fireMouseEvent()

fireMouseEvent (eventName: MouseEventName, target?: EventTarget = window, config?: MouseEventDetails): MouseEvent

Fires a MouseEvent on the target.

Arguments

eventName: MouseEventName

The MouseEvent event type to fire.

target?: EventTarget = window

The EventTarget to fire the MouseEvent on.

config?: MouseEventDetails

The configuration object for the TouchEvent. Defaults to { button: 0, bubbles: true, cancelable: false }.

Returns

MouseEvent

The constructed MouseEvent object.

fireTouchEvent()

fireTouchEvent (eventName: TouchEventName, target?: EventTarget = window, config?: TouchEventDetails): TouchEvent

Fires a TouchEvent on the target.

Arguments

eventName: TouchEventName

The TouchEvent event type to fire.

target?: EventTarget = window

The EventTarget to fire the TouchEvent on.

config?: TouchEventDetails

The configuration object for the TouchEvent. Defaults to { bubbles: true, cancelable: false }.

Returns

TouchEvent

The constructed TouchEvent object.

fireWheelEvent()

fireWheelEvent (eventName: WheelEventName, target?: EventTarget = window, config?: WheelEventDetails): WheelEvent

Fires a WheelEvent on the target.

Arguments

eventName: WheelEventName

The WheelEvent event type to fire.

target?: EventTarget = window

The EventTarget to fire the WheelEvent on.

config?: WheelEventDetails

The configuration object for the WheelEvent. Defaults to { button: 0, bubbles: true, cancelable: false }.

Returns

WheelEvent

The constructed WheelEvent object.

fireFocusEvent()

fireFocusEvent (eventName: FocusEventName, target?: EventTarget = window, config?: FocusEventDetails): FocusEvent

Fires a FocusEvent on the target.

Arguments

eventName: FocusEventName

The FocusEvent event type to fire.

target?: EventTarget = window

The EventTarget to fire the FocusEvent on.

config?: FocusEventDetails

The configuration object for the FocusEvent. Defaults to { bubbles: true, cancelable: false }.

Returns

FocusEvent

The constructed FocusEvent object.

fireKeyboardEvent()

fireKeyboardEvent (eventName: KeyboardEventName, target?: EventTarget = window, config: KeyboardEventDetails): KeyboardEvent

Fires a KeyboardEvent on the target.

Arguments

eventName: KeyboardEventName

The KeyboardEvent event type to fire.

target?: EventTarget = window

The EventTarget to fire the KeyboardEvent on.

config: KeyboardEventDetails

The configuration object for the KeyboardEvent. Must be supplied and have a value for the code property. Defaults to { bubbles: true, cancelable: false }.

Returns

KeyboardEvent

The constructed KeyboardEvent object.

waitUntilFired()

waitUntilFired (eventName: string, target: EventTarget, callback?: Function): Promise<Event>

Returns a promise that resolves when the given event is fired on the target.

Arguments

eventName: string

The event type to listen for.

target: EventTarget

The EventTarget to listen for the event on.

callback?: Function

Optionally a callback function to call if for some reason you don't like Promises.

Returns

Promise<Event>

A promise that resolves when the given event is fired on the target.

waitUntilAnyIsFired (eventNames: string[], target: EventTarget, callback?: Function): Promise<Event>

Returns a promise that resolves when any of the given events fires for the first time.

Arguments

eventName: string[] - An array of event names to listen for.

target: EventTarget - The EventTarget to listen for the event on.

callback?: Function - Optionally a callback function to call if for some reason you don't like Promises.

Returns

Promise<Event> - A promise that resolves when the first of the given event names is fired on the target.

Example

let img = new Image();
img.src = "my-image.jpg";
const result = await waitUntilAnyIsFired(["load", "error"], img);
console.log(e) // Prints the event to the console.

waitUntilFiredOnEach()

waitUntilFiredOnEach (eventName: string, targets: Array<EventTarget>): Promise<Event[]>

Returns a promise that resolves when the given event is fired on all the targets.

Arguments

eventName: string

The event type to listen for.

targets: Array<EventTarget>

The targets to listen for the event on.

Returns

Promise<Event[]>

A Promise that resolves with the values of the events when the event is fired on all the given targets.