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

• npm
• Github
• API documentation
• Changelog
• JSFiddle
• jsDelivr

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/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/umd/lambda-dom.min.js"></script>

<!-- Non-minified -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/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.

• DOMReadyP full 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.

• addClasses full 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.

• addClassesForMS full docs | source

  Adds classes to an element for a given amount of milliseconds.

• addClassesForNFrames full docs | source

  Adds classes to an element for a given amount of animation frames.

• deferFrames full docs | source

  Takes a positive (>= 0) integer n and a callback function, and executes the callback function after n animation frames have passed.

• deferFramesP full docs | source

  Returns a Promise<void> that resolves after n animation frames have passed. Like deferFrames but 'portable', so that many callbacks can subscribe to the 'event' of n frames having passed.

• display full 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.

• displayIf full 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.

• displayUsing full 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.

• getMeta full 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.

• hide full docs | source

  Hide the given element through the style.display property. This is a specialisation of display() that always sets display to 'none'.

• innerHTML full docs | source

  Takes an HTML string or null, and returns a function that takes Element objects. Sets innerHTML of given elements to the given string, or to an empty string if given null.

• innerText full docs | source

  Takes a string or null, and returns a function that takes HTMLElement objects. Sets innerText of given elements to the given string, or to an empty string if given null.

• onDOMReady full 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.

• onWindowLoad full 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.

• preventDefault full docs | source

  Takes events and calls their .preventDefault() method.

• queryAll full docs | source

  Calls querySelectorAll with given selector on given scope, or on document by default when the scope is omitted. Returns an array containing the found elements.

• queryAllWithin full 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.

• queryOne full docs | source

  Calls querySelector with given selector on given scope, or on document by default when the scope is omitted. Returns the first element matching given selector if any exists, or null otherwise. Attempts to parse the given CSS selector to determine the element type.

• queryOneWithin full 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.

• readDataset full 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.

• remove full docs | source

  Removes given element from the DOM if it's currently in it.

• removeClasses full 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.

• removeClassesForMS full docs | source

  Removes classes from an element for a given amount of milliseconds.

• removeClassesForNFrames full docs | source

  Removes classes from an element for a given amount of animation frames.

• setMeta full 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>.

• show full docs | source

  Shows the given element by unsetting any inline style.display value. This is a specialisation of display() 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'.

• showIf full 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 is true. If the condition is false, 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'.

• showUsing full 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'.

• style full docs | source

  Takes an object of style attribute values, and returns a new function that takes an element to apply those styles to.

• toggleClasses full 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 native DOMTokenList.toggle() method. Note that the value for force will be the same for all classes that are toggled.

• touchAll full 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.

• touchAllP full 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.

• touchElement full 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, and null is returned from touchElement.

• touchElementP full 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.

• windowLoadP full 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.

• writeDataset full 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.