README
lambda-dom
Functions for browser development that help with programming web projects in a functional style.
This package aims to provide some convenient, practical helpers for DOM manipulation and interaction, querying elements and implementing safe continuation patterns to facilitate a slightly more functional programming style in vanilla web projects.
Many functions are curried, the Sanctuary JS way, but not all of them. There are also some functions that take rest parameters: (...args)
. It just depends on the situation.
Quick links
Installation & usage
npm
Install the package with npm:
npm install --save lambda-dom
All functions are exported from one index file. Import the functions you want to use:
import { deferFrames, getMeta, touchAll, ... } from 'lambda-dom'
cdn
Alternatively you can grab the UMD bundle from a CDN like jsDelivr to get started quickly:
<!-- VERSIONED (safe) -->
<!-- Minified - Extended URL has sourcemaps support -->
<script src="https://cdn.jsdelivr.net/npm/lambda-dom@2.0.2"></script>
<script src="https://cdn.jsdelivr.net/npm/lambda-dom@2.0.2/umd/lambda-dom.min.js"></script>
<!-- Non-minified -->
<script src="https://cdn.jsdelivr.net/npm/lambda-dom@2.0.2/umd/lambda-dom.js"></script>
<!-- LATEST (risky in terms of potential breaking changes) -->
<!-- Minified - Extended URL version has sourcemaps support -->
<script src="https://cdn.jsdelivr.net/npm/lambda-dom"></script>
<script src="https://cdn.jsdelivr.net/npm/lambda-dom/umd/lambda-dom.min.js"></script>
<!-- Non-minified -->
<script src="https://cdn.jsdelivr.net/npm/lambda-dom/umd/lambda-dom.js"></script>
Here's a jsfiddle that includes the bundle from jsDelivr. The bundle exposes the global variable LD
that contains all the functions:
<script>
LD.deferFrames(100, function() {
console.log('100 animation frames later...');
});
</script>
Contributing
If you have suggestions how to improve this package, or want to contribute by adding new useful functions you're absolutely welcome to do so. File an issue, or even better, submit a PR. If you like this package and think it is useful please leave a star on Github 😃
Development and testing
Install (This package requires yarn v1
for dependency management) - To get started, clone the repository and install the dependencies. If you don't have yarn installed you can use npx
to install:
npx yarn
Build - There are 3 builds for the package: ES modules, CommonJS modules, and UMD bundles. The package can be built with:
npm run build
Testing - The test suite is built with Jest and run with ts-jest
, and can be run with:
npm run test
License
The MIT License (MIT). See license file for more information.
Available functions
Below is an overview of the included functions. Visit the documentation page for the full documentation of this package, including type signatures and examples.
DOMReadyPfull docs | source
Returns a promise that resolves as soon as possible after the DOM content is loaded. If the
document.readyState
is'interactive'
or'complete'
at call-time, the returned promise resolves immediately, otherwise it resolves upon the DOMContentLoaded event.addClassesfull docs | source
Curried function that first takes a list of classes, then returns a new function that takes the element to add those classes to.
addClassesForMSfull docs | source
Adds classes to an element for a given amount of milliseconds.
addClassesForNFramesfull docs | source
Adds classes to an element for a given amount of animation frames.
deferFramesfull docs | source
Takes a positive (>= 0) integer
n
and a callback function, and executes the callback function after n animation frames have passed.deferFramesPfull docs | source
Returns a
Promise<void>
that resolves after n animation frames have passed. LikedeferFrames
but 'portable', so that many callbacks can subscribe to the 'event' of n frames having passed.displayfull docs | source
Takes a CSS display value and returns a function that takes elements. When applied to an element the returned function assigns the given display value to the given element's
style.display
property.displayIffull docs | source
Takes a boolean condition and a CSS display value, and returns a function that takes elements. The returned function will set
style.display
onto given elements to either given value or to'none'
based on the given cond boolean.displayUsingfull docs | source
Takes a predicate function for elements and a CSS display value, and returns a function that takes elements. The returned function will set
style.display
onto given elements to either given value or to'none'
based on the result of applying the predicate to those elements.getMetafull docs | source
Get the value of the content attribute for the first (and presumably only)
<meta>
element with given name as the value for its name attribute. Optionally takes a transformer to deserialize string values.hidefull docs | source
Hide the given element through the
style.display
property. This is a specialisation ofdisplay()
that always sets display to'none'
.innerHTMLfull docs | source
Takes an HTML string or
null
, and returns a function that takesElement
objects. SetsinnerHTML
of given elements to the given string, or to an empty string if givennull
.innerTextfull docs | source
Takes a string or
null
, and returns a function that takesHTMLElement
objects. SetsinnerText
of given elements to the given string, or to an empty string if givennull
.onDOMReadyfull docs | source
Takes a callback that is executed as soon as possible after the DOM content is loaded. If the
document.readyState
is either'interactive'
or'complete'
at call-time, the callback is called immediately, otherwise it is called upon the DOMContentLoaded event.onWindowLoadfull docs | source
Takes a callback that is executed as soon as possible after the window is loaded. If the
document.readyState
is'complete'
at call-time, the callback is called immediately, otherwise it is called upon the window load event.preventDefaultfull docs | source
Takes events and calls their
.preventDefault()
method.queryAllfull docs | source
Calls
querySelectorAll
with given selector on given scope, or ondocument
by default when the scope is omitted. Returns an array containing the found elements.queryAllWithinfull docs | source
Takes an element as scope for CSS selector queries. Returns a function that takes selectors to query elements for within the set scope. The returned function finds all elements matching given selector and returns them in an array.
queryOnefull docs | source
Calls
querySelector
with givenselector
on givenscope
, or ondocument
by default when the scope is omitted. Returns the first element matching given selector if any exists, ornull
otherwise. Attempts to parse the given CSS selector to determine the element type.queryOneWithinfull docs | source
Takes an element as scope for CSS selector queries. Returns a function that takes selectors to query elements for within the set scope. The returned function finds the first element matching given selector and returns it. Returns
null
if no matching element exists.readDatasetfull docs | source
Read dataset values. Takes a dataset key and optionally a transformer for the corresponding value, and returns a new function that takes the element to read the dataset key from.
removefull docs | source
Removes given element from the DOM if it's currently in it.
removeClassesfull docs | source
Curried function that first takes a list of classes, then returns a new function that takes the element to remove those classes from.
removeClassesForMSfull docs | source
Removes classes from an element for a given amount of milliseconds.
removeClassesForNFramesfull docs | source
Removes classes from an element for a given amount of animation frames.
setMetafull docs | source
Takes a string name and returns a new function that takes a string content, and then updates the
<meta>
tag with the given name if it exists, or otherwise creates a new one. The meta element to which the content value was set is returned for reference. When a new element is created it will be appended to the end of<head>
.showfull docs | source
Shows the given element by unsetting any inline
style.display
value. This is a specialisation ofdisplay()
that always unsets inline display.Note
This function assumes that given elements are shown by default - ie. there's no CSS rule that has set the element's display to
'none'
.showIffull docs | source
Takes a boolean condition, and returns a function that takes elements. The returned function will unset
style.display
onto a given element if the given condition istrue
. If the condition isfalse
,style.display
is set to'none'
.Note
This function assumes that given elements are shown by default - ie. there's no CSS rule that has set the element's display to
'none'
.showUsingfull docs | source
Takes a predicate function for elements and returns a function that takes elements to conditionally show depending on the result of applying the predicate function to given elements.
Note
This function assumes that given elements are shown by default - ie. there's no CSS rule that has set the element's display to
'none'
.stylefull docs | source
Takes an object of style attribute values, and returns a new function that takes an element to apply those styles to.
toggleClassesfull docs | source
Curried function that first takes a list of classes, then returns a new function that takes the element on which to toggle those classes. The second function optionally takes the second argument
force: boolean
to use on the nativeDOMTokenList.toggle()
method. Note that the value for force will be the same for all classes that are toggled.touchAllfull docs | source
Takes an array of selectors and a callback function. When for all selectors an element is found, the callback is called with each found element in order. Optionally takes a scope as third argument to use for the element search.
touchAllPfull docs | source
Takes an array of selectors. Returns a promise that will only resolve when for all selectors an element is found. The promise value is an array of the elements in the order of the selector array. Optionally takes a scope as third argument to use for the element search.
This function is useful as an alternative for
touchAll
in async functions. When awaited it'll block all further execution of the function when not all elements are found.touchElementfull docs | source
Finds the first element within the set scope that matches selector. If found the element is applied to the given callback function, and the function's return value will be propagated as return value of
touchElement
. If no element is found, the callback is not invoked, andnull
is returned fromtouchElement
.touchElementPfull docs | source
Finds the first element within the set scope that matches a given selector. If found the returned promise resolves with the element. If no element is found, the promise will never resolve. Like
touchElement
but 'portable', so that many callbacks can subscribe to the 'event' of the element being found.windowLoadPfull docs | source
Returns a promise that resolves as soon as possible after the window is loaded. If the
document.readyState
is'complete'
at call-time, the returned promise resolves immediately, otherwise it resolves upon the window load event.writeDatasetfull docs | source
Write dataset values. Takes a key, and returns a new function that takes the value, which in turn returns the last function that takes the element to write the key-value pair to.