html-cut

    1.0.1 • Public • Published

    html-cut

    A simple and robust way to extract copies of portions of DOM using numerical addresses as identifiers of cut points.

    About addresses:

    • Address are always relative to a root node.
    • Numbers of the addresses are 1-based indexes (don't you know 0-based indexes are evil?)
    • The address of the first child element of the root is [1], the second is [2].
    • The address of the first grandson is [1, 1], the second grandson is [1, 2], etc.
    • The address of the root is the empty array [] for consistency.

    Code examples

    See unit test for full documentation of each function!

    subNode

    Extract a portion of a DOM node while keeping the outer structure intact (essentially to maintain CSS intact on cloned portions):

    const { subNode } = require("html-cut");
    // <div id="root"><b>Be bold!</b><i>Think different</i><u>But be productive</u></div>
    const root = document.getElementById("root");
    const sub = subNode(root, { from: [1], to: [3], inclusive: false });
    console.log(sub.outerHTML);
    // <div id="root"><b>Be bold!</b><i>Think different</i></div>

    Let's say you want to cut at a point and get the portion of the DOM before, plus the portion after:

    const { subNode } = require("html-cut");
    // <div id="root"><b>Be bold!</b><i>Think different</i><u>But be productive</u></div>
    const root = document.getElementById("root");
    const cutAddress = [2];
    const before = subNode(root, { to: cutAddress, inclusive: false });
    console.log(before.outerHTML);
    // <div id="root"><b>Be bold!</b></div>
    const after = subNode(root, { from: cutAddress, inclusive: true });
    console.log(after.outerHTML);
    // <div id="root"><i>Think different</i><u>But be productive</u></div>

    cloneNodeProgressive

    It is possible to directly clone a portion of a root node to a target node, from a starting node/address until a dynamic condition is met:

    const { cloneNodeProgressive } = require("html-cut");
    // <div id="root"><b>Be bold!</b><i>Think different</i><u>But be productive</u></div>
    const source = document.getElementById("root");
    // <div />
    const target = document.createElement("div");
    // address must be given with the node because it will be incremented as cloning progresses
    const from = { node: source.firstChild, address: [1] };
    // Stop when a specific text node is met
    const stop = ({ current }) => current.nodeValue === "Think different";
    const overflow = cloneNodeProgressive(source, target, stop, from);
    // "overflow" represents the last visisted node in source, for which the lambda returned true
    // the overflow node that matched the lambda was the text node
    console.log(overflow);
    // { address: [2, 1], parent: [object HTMLElement], current: [object Text] }
    console.log(target.outerHTML);
    // <div><b>Be bold!</b><i>Think different</i></div>

    compareAddresses

    You can compare addresses through a total order function.

    const { compareAddresses } = require("html-cut");
    //  0 : equality
    compareAddresses([1, 2, 3], [1, 2, 3]);
    // -1 : the first address represents a node which is before the second
    compareAddresses([1, 2, 2], [1, 2, 3]);
    // +1 : the first address represents a node which is after the second
    compareAddresses([1, 2], [1]);

    getElementByAddress

    You can query a node by it's address, provided that you also give the root node:

    const { getElementByAddress } = require("html-cut");
    // <div id="root"><b>Be bold!</b><i>Think different</i></div>
    const root = document.getElementById("root");
    const result = getElementByAddress(root, [2]);
    console.log((result.outerHTML);
    // <i>Think different</i>

    getAddressOfElement

    You can also compute the address of a node, provided that you give the root:

    const { getAddressOfElement } = require("html-cut");
    // <div id="root"><b>Be bold!</b><i id="sub">Think different</i></div>
    const root = document.getElementById("root");
    const sub = document.getElementById("sub");
    const result = getAddressOfElement(root, sub);
    console.log(result);
    // [2]
    // also works for text children
    const subText = sub.firstChild;
    const resultText = getAddressOfElement(root, subText);
    console.log(resultText);
    // [2, 1]

    Utility

    And finally some utility functions:

    const { getFirstAddress, getLastAddress, nextNode } = require("html-cut");
    
    // <div id="root"><b id="sub">Be bold!</b><i>Think different</i></div>
    const root = document.getElementById("root");
    
    const firstAddress = getFirstAddress(root);
    const lastAddress = getLastAddress(root);
    console.log(firstAddress);
    // [1] of undefined if root is empty
    console.log(lastAddress);
    // [1, 4, 2, 1] for instance, or undefined if root is empty
    
    const sub = document.getElementById("sub");
    const result = nextNode(root, sub);
    // next node of a parent is it's first child
    console.log(result.nodeValue);
    // "Be bold!"

    Install

    npm i html-cut

    DownloadsWeekly Downloads

    2

    Version

    1.0.1

    License

    Apache-2.0

    Unpacked Size

    35.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar