DOM Methods

bind$

Function to pre-register events for elements whose existence is uncertain by registering events on the parent element.

Since: 0.1.0

Arguments

Param	Type	Description
$element	Element	Parent element
eventType	string	Event type to listen for. It should be of the mouse event type
selector	string	A string containing one or more selectors to match.
listener	EvtListener	The object that receives a notification when an event of the specified type occurs.
[condition]	Function	Callback function that determine whether to fire an event listener

Declaration

declare function bind$<
  K extends MouseEventKeys,
  T extends Element = HTMLElement,
>(
  $element: Window | Document | Element,
  eventType: K,
  selector: string,
  listener: EvtListener<K, T>,
  condition?: BindCondition
);

// Types

/**
 * Callback function that determine whether to fire an event listener
 * @callback BindCondition
 * @param {Window | Document | Element} parent The parent element where the event is actually registered
 * @param {Element} target The selector element on which to fire the event.
 * @returns {boolean} Whether to fire an event
 */
type BindCondition = (
  parent: Window | Document | Element,
  target: Element
) => boolean;

type MouseEventKeys =
  | 'auxclick'
  | 'click'
  | 'contextmenu'
  | 'dblclick'
  | 'mousedown'
  | 'mouseenter'
  | 'mouseleave'
  | 'mousemove'
  | 'mouseout'
  | 'mouseover'
  | 'mouseup';

Examples

bind$(document.body, 'click', '.some-selector', (event) => console.log(event));

create$

Create Element

Arguments

Param	Type	Description
tagName	string	The tag name of element
[options]	Object	The element options

Declaration

declare function create$<
  K extends keyof HTMLElementTagNameMap,
  T = HTMLElementTagNameMap[K],
>(tagName: K, options?: CreateOptions<T>): HTMLElementTagNameMap[K];

// Types

type CreateOptions<T> = Partial<
  Omit<Writable<OmitFunction<T>>, keyof CreateCustomOptions>
> &
  CreateCustomOptions;

type CreateCustomOptions = {
  id?: string | undefined;
  className?: string | undefined;
  classList?: string[] | undefined;
  role?: AriaRole;
  style?: Partial<CSSStyleDeclaration> | undefined;
  dataset?: Record<string, string | boolean | number | undefined> | undefined;
};

type Writable<T> = { [P in WritableKeys<T>]: T[P] };

type OmitFunction<T> = { [P in Exclude<keyof T, FunctionKeys<T>>]: T[P] };

type WritableKeys<T> = {
  [P in keyof T]-?: IfEquals<
    { [Q in P]: T[P] },
    { -readonly [Q in P]: T[P] },
    P,
    never
  >;
}[keyof T];

type FunctionKeys<T> = {
  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
}[keyof T];

type IfEquals<X, Y, A = X, B = never> =
  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? A : B;

Examples

const $div = create$('div', { className: 'my-class', innerHTML: 'welcome' });
// <div class="my-class">welcome</div>

find$

Returns the first Element within the document that matches the specified selector, or group of selectors. If no matches are found, null is returned.

Since: 0.1.0

Arguments

Param	Type	Description
selector	string	A string containing one or more selectors to match.
[element = document]	Element | Document	The target element to find selector

Returns

Type	Description
Element | null	Returns the first element that is a descendant of node that matches selectors.

Declaration

declare function find$<T extends Element = HTMLElement>(
  selector: string,
  element?: Element | Document
): T | null;

Examples

find$('.some-class');

findAll$

Returns a static (not live) NodeList representing a list of the document's elements that match the specified group of selectors.

Since: 0.1.0

Arguments

Param	Type	Description
selector	string	A string containing one or more selectors to match.
[element = document]	Element | Document	The target element to find selector

Returns

Type	Description
NodeListOf<Element>	A non-live NodeList containing one Element object for each element that matches at least one of the specified selectors or an empty NodeList in case of no matches.

Declaration

declare function findAll$<T extends Element = HTMLElement>(
  selector: string,
  element?: Element | Document
): NodeListOf<T>;

Examples

const $items = findAll$('.some-item');

on

Bind event listener

Since: 0.1.0

Arguments

Param	Type	Description
element	Element | Window | Document	The element to bind event
eventType	string	A case-sensitive string representing the event type to listen for.
listener	(event: Event) => any	The object that receives a notification when an event of the specified type occurs.
[options]	AddEventListenerOptions | boolean	An object that specifies characteristics about the event listener. If true, allows you to take advantage of event bubbling for events that otherwise don’t support it.

Declaration

declare function on<
  K extends keyof HTMLElementEventMap,
  T extends Element = HTMLElement,
>(
  element: T,
  eventType: K,
  listener: EvtListener<K, T>,
  options?: AddEventListenerOptions | boolean
): void;
declare function on<K extends keyof WindowEventMap, T = Window>(
  element: T,
  eventType: K,
  listener: (event: WindowEventMap[K]) => any,
  options?: AddEventListenerOptions | boolean
): void;
declare function on<K extends keyof DocumentEventMap, T = Document>(
  element: T,
  eventType: K,
  listener: (event: DocumentEventMap[K]) => any,
  options?: AddEventListenerOptions | boolean
): void;
declare function on<T extends Window | Document | Element>(
  element: T,
  eventType: string,
  listener: (event: Event) => any,
  options?: AddEventListenerOptions | boolean
): void;

Examples

const handler = () => console.log('hi');
on(document.body, 'click', handler);
document.body.click(); // 'hi'

off

Unbind event listener

Since: 0.1.0

Arguments

Param	Type	Description
element	Element | Window | Document	The element to unbind event
eventType	string	A case-sensitive string representing the event type to listen for.
listener	(event: Event) => any	The object that receives a notification when an event of the specified type occurs.

Declaration

declare function off<
  K extends keyof HTMLElementEventMap,
  T extends Element = HTMLElement,
>(
  element: T,
  eventType: K,
  listener: EvtListener<K, T>,
  options?: AddEventListenerOptions | boolean
): void;
declare function off<K extends keyof WindowEventMap, T = Window>(
  element: T,
  eventType: K,
  listener: (event: WindowEventMap[K]) => any,
  options?: AddEventListenerOptions | boolean
): void;
declare function off<K extends keyof DocumentEventMap, T = Document>(
  element: T,
  eventType: K,
  listener: (event: DocumentEventMap[K]) => any,
  options?: AddEventListenerOptions | boolean
): void;
declare function off<T extends Window | Document | Element>(
  element: T,
  eventType: string,
  listener: (event: Event) => any,
  options?: AddEventListenerOptions | boolean
): void;

Examples

const handler = () => console.log('hi');
document.body.addEventListener('click', handler);
document.body.click(); // 'hi'
off(document.body, 'click', handler);
document.body.click(); //

useStorage

Create storage. For easy to use browser localStorage(or sessionStorage)

Since: 1.1.0

Arguments

Param	Type	Description
storageType	'local' | 'session'	The storage to use.

Returns

Type	Description
Storage	Returns storage

Declaration

declare function useStorage(storageType?: 'local' | 'session'): Storage;

type Storage = {
  /** Returns the current value associated with the given key, or null if the given key does not exist. */
  get<T, V = null>(key: string, defaultValue?: V): T | V;
  /** Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously. */
  set(key: string, value: any): void;
  /** Removes the key/value pair with the given key, if a key/value pair with the given key exists. */
  remove(key: string): void;
  /** Removes all key/value pairs, if there are any. */
  clear(): void;
};

Examples

const storage = useStorage();
storage.get('name'); // null
storage.get('name', 'Who are you?'); // 'Who are you?'

storage.set('name', 'Kim');
storage.get('name'); // 'Kim'

storage.set('data', { x: 1, y: 10 }); // Save stringify value, '{ "x": 1, "y": 10 }'
storage.get('data'); // Get parse value ,{ x: 1, y: 10 }

storage.remove('name');
storage.get('name'); // null

storage.clear();
storage.get('data'); // null