Spank my DOM 🔞
A tiny, modular set of DOM utilities, written in TypeScript.
Installation
> npm install spank-my-domFunctions
-
toArray(iterable) ⇒
Array.<T> -
toggleAttr(element, name, value, [force]) ⇒
boolean -
setAttr(element, name, value) ⇒
void -
getAttr(element, name) ⇒
null|string -
hasAttr(element, name) ⇒
boolean -
removeAttr(element, name) ⇒
void -
toggleAria(element, name, value, [force]) ⇒
boolean -
setAria(element, name, value) ⇒
void -
getAria(element, name) ⇒
null|string -
hasAria(element, name) ⇒
boolean -
removeAria(element, name) ⇒
void -
toggleData(element, name, value, [force]) ⇒
boolean -
setData(element, name, value) ⇒
void -
getData(element, name) ⇒
null|string -
hasData(element, name) ⇒
boolean -
removeData(element, name) ⇒
void -
toggleClass(element, tokens, [force]) ⇒
boolean -
addClass(element, ...tokens) ⇒
void -
removeClass(element, ...tokens) ⇒
void -
classesContaining(search, context, [ignoreCase]) ⇒
Array.<string> -
classesEndingWith(search, context, [ignoreCase]) ⇒
Array.<string> -
classesStartingWith(search, context, [ignoreCase]) ⇒
Array.<string> -
dispatch(target, type, [options]) ⇒
boolean -
on(target, type, listener, [options]) ⇒
void -
off(target, type, listener, [options]) ⇒
void -
offDelegate(target, selectors, type, listener, [options]) ⇒
void -
onDelegate(target, selectors, type, listener, [options]) ⇒
void -
serialise(...items) ⇒
string -
loadImage(path) ⇒
Promise.<HTMLImageElement> -
loadImages(...paths) ⇒
Promise.<Array.<HTMLImageElement>> -
parseJson(input, reviver) ⇒
object -
create(tagName, [options]) ⇒
Element -
empty(element) ⇒
void -
replace(element, ...replacements) ⇒
void -
find(selectors, context) ⇒
null|Element -
findOrThrow(selectors, context) ⇒
Element -
findAll(selectors, context) ⇒
Array.<Element> -
toBoolean(input) ⇒
boolean -
toNumber(input) ⇒
number -
closest(element, selector) ⇒
null|Element -
siblingsAfter(element, [selector]) ⇒
Array.<Element> -
siblingsBefore(element, [selector]) ⇒
Array.<Element> -
siblings(element, [selector]) ⇒
Array.<Element>
toArray(iterable) ⇒ Array.<T>
Creates an array from an iterable object.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| iterable |
Iterable.<T> | ArrayLike.<T>
|
The iterable object to convert to an array. |
toggleAttr(element, name, value, [force]) ⇒ boolean
Toggle the attribute of an element. If force is included, turns the toggle into a one way-only operation. If set to false, the attribute will only be removed. If set to true, the attribute will only be added.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to toggle the attribute on. |
| name | string |
The name of the attribute. |
| value |
string | number | boolean
|
The value of the attribute. |
| [force] | boolean |
Restrict toggle to a one-way operation only. |
setAttr(element, name, value) ⇒ void
Set an attribute on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to set the attribute on. |
| name | string |
The name of the attribute. |
| value | unknown |
The value of the attribute. |
getAttr(element, name) ⇒ null | string
Get the attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to retrieve the attribute from. |
| name | string |
The name of the attribute. |
hasAttr(element, name) ⇒ boolean
Check if an attribute exists on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to check. |
| name | string |
The name of the attribute. |
removeAttr(element, name) ⇒ void
Remove an attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to remove the attribute from. |
| name | string |
The name of the attribute. |
toggleAria(element, name, value, [force]) ⇒ boolean
Toggle the aria attribute of an element. If force is included, turns the toggle into a one way-only operation. If set to false, the aria attribute will only be removed. If set to true, the aria attribute will only be added.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to toggle the aria attribute on. |
| name | string |
The name of the aria attribute. |
| value | unknown |
The value of the aria attribute. |
| [force] | boolean |
Restrict toggle to a one-way operation only. |
setAria(element, name, value) ⇒ void
Set an aria attribute on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to set the aria attribute on. |
| name | string |
The name of the aria attribute. |
| value | unknown |
The value of the aria attribute. |
getAria(element, name) ⇒ null | string
Get the aria attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to retrieve the aria attribute from. |
| name | string |
The name of the aria attribute. |
hasAria(element, name) ⇒ boolean
Check if an aria attribute exists on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to check. |
| name | string |
The name of the aria attribute. |
removeAria(element, name) ⇒ void
Remove a aria attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to remove the aria attribute from. |
| name | string |
The name of the aria attribute. |
toggleData(element, name, value, [force]) ⇒ boolean
Toggle the data attribute of an element. If force is included, turns the toggle into a one way-only operation. If set to false, the data attribute will only be removed. If set to true, the data attribute will only be added.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to toggle the data attribute on. |
| name | string |
The name of the data attribute. |
| value | unknown |
The value of the data attribute. |
| [force] | boolean |
Restrict toggle to a one-way operation only. |
setData(element, name, value) ⇒ void
Set a data attribute on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to set the data attribute on. |
| name | string |
The name of the data attribute. |
| value | unknown |
The value of the data attribute. |
getData(element, name) ⇒ null | string
Get the data attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to retrieve the data attribute from. |
| name | string |
The name of the data attribute. |
hasData(element, name) ⇒ boolean
Check if a data attribute exists on an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to check. |
| name | string |
The name of the data attribute. |
removeData(element, name) ⇒ void
Remove a data attribute from an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to remove the data attribute from. |
| name | string |
The name of the data attribute. |
toggleClass(element, tokens, [force]) ⇒ boolean
Toggle one or more classes of an element. If force is included, turns the toggle into a one way-only operation. If set to false, the classes will only be removed. If set to true, the classes will only be added.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to toggle the class(es) on. |
| tokens |
string | Array.<string>
|
The class(es) to toggle. |
| [force] | boolean |
Restrict toggle to a one-way operation only. |
addClass(element, ...tokens) ⇒ void
Add one or more classes to an element.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to add the class(es) to. |
| ...tokens | Array.<string> |
The class(es) to add. |
removeClass(element, ...tokens) ⇒ void
Remove one or more classes from an element.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to remove the class(es) from. |
| ...tokens | Array.<string> |
The class(es) to remove. |
classesContaining(search, context, [ignoreCase]) ⇒ Array.<string>
Get classes from an element or string that contain a specified string.
Since: 1.0.0
| Param | Type | Default | Description |
|---|---|---|---|
| search | string |
The string to search for. | |
| context |
Element | string
|
The context to perform the search on. | |
| [ignoreCase] | boolean |
false |
Set the case-sensitivity of the search. |
classesEndingWith(search, context, [ignoreCase]) ⇒ Array.<string>
Get classes from an element or string that end with a specified string.
Since: 1.0.0
| Param | Type | Default | Description |
|---|---|---|---|
| search | string |
The string to search for. | |
| context |
Element | string
|
The context to perform the search on. | |
| [ignoreCase] | boolean |
false |
Set the case-sensitivity of the search. |
classesStartingWith(search, context, [ignoreCase]) ⇒ Array.<string>
Get classes from an element or string that start with a specified string.
Since: 1.0.0
| Param | Type | Default | Description |
|---|---|---|---|
| search | string |
The string to search for. | |
| context |
Element | string
|
The context to perform the search on. | |
| [ignoreCase] | boolean |
false |
Set the case-sensitivity of the search. |
dispatch(target, type, [options]) ⇒ boolean
Dispatch a synthetic event to a target.
Returns: boolean - false if event is cancelable, and at least one of the event
handlers which received event called preventDefault(). Otherwise true.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| target | EventTarget |
The target to dispatch the event to. |
| type | string |
The name of the event. |
| [options] |
CustomEventInit | EventInit
|
Additional event properties. |
on(target, type, listener, [options]) ⇒ void
Add an event listener to the target.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| target | EventTarget |
The target to add the listener to. |
| type | string |
The listener type. |
| listener |
EventListener | EventListenerObject
|
The listener callback. |
| [options] |
boolean | AddEventListenerOptions
|
The listener options. |
off(target, type, listener, [options]) ⇒ void
Remove an event listener from the target.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| target | EventTarget |
The target to remove the listener from. |
| type | string |
The listener type. |
| listener |
EventListener | EventListenerObject
|
The listener callback. |
| [options] |
boolean | AddEventListenerOptions
|
The listener options. |
offDelegate(target, selectors, type, listener, [options]) ⇒ void
Remove a delegate listener from the target.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| target | EventTarget |
The target to remove the listener from. |
| selectors | string |
The selectors that would have been matched against. |
| type | string |
The listener type. |
| listener |
EventListener | EventListenerObject
|
The listener callback. |
| [options] |
boolean | AddEventListenerOptions
|
The listener options. |
onDelegate(target, selectors, type, listener, [options]) ⇒ void
Add a delegate event listener to the target. The callback argument will be invoked when the event is dispatched on any descendant element that matches the given selectors.
The Event object returned in the listener callback includes a non-standard
method stopDelegation(), which stops any further traversal up the DOM tree
in search of matches.
The listener callback includes a second argument index, which indicates
how many times the callback has been fired during the current event.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| target | EventTarget |
The target to add the listener to. |
| selectors | string |
The selectors to match against when an event is dispatched. |
| type | string |
The listener type. |
| listener |
EventListener | EventListenerObject
|
The listener callback. |
| [options] |
boolean | AddEventListenerOptions
|
The listener options. |
serialise(...items) ⇒ string
Encode one or more serialisable items as a query string. This is aimed primarily, but not exclusively, at form elements.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| ...items |
HTMLFormElement | Object.<string, any> | Array.<Array.<string, any>>
|
The item(s) to encode. |
loadImage(path) ⇒ Promise.<HTMLImageElement>
Load an image asynchronously.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| path | string |
The image to load. |
loadImages(...paths) ⇒ Promise.<Array.<HTMLImageElement>>
Load one or more images asynchronously.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| ...paths | Array.<string> |
The image(s) to load. |
parseJson(input, reviver) ⇒ object
Convert a JSON string into an object.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| input | string |
A valid JSON string. |
| reviver | function |
A function that transforms the results. |
create(tagName, [options]) ⇒ Element
Creates an instance of the element for the specified tag, allowing you to define attributes and content at the same time.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| tagName | string |
The type of element to be created. |
| [options] | Object |
Additional options. |
| [options.attributes] | Object.<string, (string|number|boolean)> |
Attributes to be added to the element. |
| [options.children] | Array.<Element> |
Child elements to append to the element. |
| [options.innerHTML] | string |
Set the HTML of the element. |
empty(element) ⇒ void
Empty an element.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to empty. |
replace(element, ...replacements) ⇒ void
Replace the contents of an element with one or more items.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element to replace the contents of. |
| ...replacements | Array.<Node, string> |
The new items to insert into the element. |
find(selectors, context) ⇒ null | Element
Returns the first element within context that matches the given selectors.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| selectors | string |
The selectors to match against. |
| context |
Document | DocumentFragment | Element
|
The context from which to search from. |
findOrThrow(selectors, context) ⇒ Element
Returns the first element within context that matches the given selectors.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| selectors | string |
The selectors to match against. |
| context |
Document | DocumentFragment | Element
|
The context from which to search from. |
findAll(selectors, context) ⇒ Array.<Element>
Returns all descendant elements within context that match the given selectors.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| selectors | string |
The selectors to match against. |
| context |
Document | DocumentFragment | Element
|
The context from which to search from. |
toBoolean(input) ⇒ boolean
Convert a string into a boolean.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| input | string |
The string to convert. |
toNumber(input) ⇒ number
Convert a string into a number.
Since: 1.0.0
| Param | Type | Description |
|---|---|---|
| input | string |
The string to convert. |
closest(element, selector) ⇒ null | Element
Returns the first ancestor that matches selector. Not inclusive of element.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element from which to search. |
| selector | string |
Selector to match ancestors against. |
siblingsAfter(element, [selector]) ⇒ Array.<Element>
Get the following siblings of an element, optionally filtered by a selector.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element whose siblings will be returned. |
| [selector] | string |
Optional selector to match siblings against. |
siblingsBefore(element, [selector]) ⇒ Array.<Element>
Get the preceding siblings of an element, optionally filtered by a selector.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element whose siblings will be returned. |
| [selector] | string |
Optional selector to match siblings against. |
siblings(element, [selector]) ⇒ Array.<Element>
Get the siblings of an element, optionally filtered by a selector.
Since: 0.2.0
| Param | Type | Description |
|---|---|---|
| element | Element |
The element whose siblings will be returned. |
| [selector] | string |
Optional selector to match siblings against. |