@yankeeinlondon/happy-wrapper
v3.5.7
Published
A functional API surface wrapping happy-dom
Downloads
13,647
Readme
happy-wrapper
A wrapper around the popular happy-dom API which provides a more functional interaction model.
Note:
- version 3.x bumps the version of happy-dom up to the 12.x.y versions.
- version 3.4 onward have switched to using the
happy-dom-without-chrome
dependency so that this library is equally as happy running in a browser as it is running on a server.
Examples
Attributes
Partially compose a tag change operation:
const toDiv = ChangeTagName('div'); const toTable = ChangeTagName('table');
and then apply it later to HTML text, an IElement node, a doc fragment, etc.:
// "<div>hello world</div>" const html = toDiv("<span>hello world</span>"); // IElement which wraps the HTML "<table>hello world</table>" const el = toTable(createElement("<span>hello world</span>"));
Change classes on an element:
const html = "<span class='nada'>hello world</span>" // "<span class='foobar'>hello world</span>" const changed = pipe( html, addClass("foobar"), removeClass("nada") )
Selections
Select a node (or whole document):
const html = "<html>...</html>"; const sel = select(html);
Query and return a node or node list
// returns first H1 node or null if not found const h1: IElement | null = sel.findFirst('h1'); // throw an error if not found const h1b: IElement = sel.findFirst("h1", "couldn't find the H1 selector");
Iterate over a selector and mutate the selected nodes
import { pipe } from "fp-ts/lib/function.js"; return html.updateAll('h1')(el => pipe( el, addClass("foobar"), changeTagName("h2"), wrap('<div class="was-h1">') ) );
Note: you don't have to use a library like fp-ts but because the exposed API surface is functional in many ways, utilities like pipe and flow can be quite handy.
Documentation Via Typing
Formal documentation is not expected to every be much but we believe that strong typescript types are the way to express documentation that is both easier to maintain and easier to consume.
All available symbols are named exports and can be explored via symbol completion in your editor of choice. Further, an attempt has been made to provide rich types that describe and properly limit the scope of type so that you're use is hopefully understood and safe.
Re-Exports
To avoid any small API variations that might exist in future happy-dom
versions we do re-export the key symbols from that library. That includes:
IElement
,IText
, andINode
Document
, andDocumentFragment
Note: we actually re-export
DocumentFragment
as bothDocumentFragment
and asFragment
. We do this because the type forDocumentFragment
will be auto-associated to the browser's DOM if you don't explicitly state it and Happy DOM's implementation is a subset of the full DOM so you'll get typing errors that may seem baffling. To avoid this we prefer use of the short and explicit type ofFragment
.
Contributions
This library was built with a specific purpose in mind and therefore it's surface area may have some gaps in terms of addressing all obvious use-cases around the DOM. Happy to work with anyone who wants to add in a PR to make this a better subset.
License
This library is made available for use under the MIT open source license.