JarCasting 
DOM queries that always return an array.
Introduction
Modern browsers enable us to perform DOM queries natively, e.g:
let cookies = document.querySelectorAll(".cookie");
But we all want to loop over the returned elements. So in practice, we’ve got to do a little more work, particularly converting the resulting NodeList to an array, e.g:
let cookies;
try {
let query = document.querySelectorAll(".cookie");
cookies = Array.prototype.slice.call(query);
} catch (err) {
console.error(err.message);
}
cookies.forEach(cookie => {
// ...
});
Tealight provides a familiar API to perform native queries, without the extra work.
tealight(".cookie").forEach(cookie => {
// ...
});
Installation
Browser
A simple and fast way to get started is to include this script on your page:
<script src="https://unpkg.com/tealight"></script>
This will create the global variable tealight.
Module
$ npm install tealight
CommonJS
const tealight = require("tealight");
ES2015
import tealight from "tealight";
Usage
tealight accepts a single argument target and will always return an array of 0 or more DOM nodes.
For the examples below, we will query against this HTML fragment:
<div id="jar">
<div class="chocolate-chip cookie"></div>
<div class="peanut-butter cookie"></div>
<div class="short-bread cookie"></div>
</div>
tealight(target: string): Array<HTMLElement>
string targets will be used as CSS selectors.
tealight("#jar");
// => [ <div#jar> ]
tealight(".cookie");
// => [ <div.chocolate-chip.cookie>, <div.peanut-butter.cookie>, <div.short-bread.cookie> ]
tealight(target: HTMLElement): Array<HTMLElement>
HTMLElement targets will simply be wrapped in an Array
const node = document.querySelector("#jar");
tealight(node);
// => [ <div#jar> ]
tealight(target: HTMLCollection) : Array<HTMLElement>
HTMLCollection arguments will be converted to Array.
const nodeList = document.querySelectorAll(".cookie");
tealight(nodeList);
// => [ <div.chocolate-chip.cookie>, <div.peanut-butter.cookie>, <div.short-bread.cookie> ]
tealight(target: Array<any>): Array<HTMLElement>
Array targets will be filtered, leaving only HTMLElement
let node = document.querySelector("#jar");
let array = [node, null, ".cookie"];
tealight(array);
// => [ <div#jar> ]
Copyright 2020 Julian Lloyd
Open source under the MIT License.