Find-dom-nodes-by-content NPM

Easily locate DOM nodes containing specific content within a given context.

🌟 Features

Lightweight and Efficient: Minimal footprint with maximum performance.
XPath Evaluation: Utilizes XPath for precise node retrieval.
Caching: Optional caching mechanism for advanced scenarios.
Framework Agnostic: Works with any or no framework.

📦 Installation

# With npm
npm install find-dom-nodes-by-content

# With yarn
yarn add find-dom-nodes-by-content

🚀 Usage

Importing

Works with both ESM and CommonJS syntaxes:

// ESM
import {
  findDOMNodesByContent,
  exposeEvaluatedNodesCacheGlobally,
  clearEvaluatedNodesCache,
} from "find-dom-nodes-by-content";

// CommonJS
const {
  findDOMNodesByContent,
  exposeEvaluatedNodesCacheGlobally,
  clearEvaluatedNodesCache,
} = require("find-dom-nodes-by-content");

Finding DOM Nodes by Content

Retrieve an array of nodes based on content:

const nodes = findDOMNodesByContent({ text: "Hello" }, document.body);

📄 Docs

`⚙️ findDOMNodesByContent()`

Finds and returns DOM nodes containing the specified content by utilizing XPath. Users can fine-tune the search by providing various configuration options.

Parameters:

content (Object): Configuration for content search.
- text (string): Content to search for within the DOM nodes.
- textWrapper (string, optional, default = "): Wrapper for the content string in the XPath expression.
- nodeType (string, optional, default = *): Node type to target in the search.
- attributes (array, optional): Array of attribute objects to refine the search.
- logicalOperator (string, optional, default = "and"): How multiple criteria should be combined.
- nested (boolean, optional, default = false): Specifies whether to include nested nodes.
contextElement (Element | Document, optional): The context within which to conduct the search. Defaults to the entire document.
config (Object, optional, default = {})
Detailed configuration object for refining the search:
- expression (string, optional, default = '')
  An optional custom XPath expression. When provided, it takes precedence over the default content-based search.
- XPathNSResolver (XPathNSResolver, optional, default = null)
  Namespace resolver for XPath when searching within XML documents with namespaces.
- XPathResultType (number, optional, default = XPathResult.UNORDERED_NODE_ITERATOR_TYPE)
  Determines the type of result.
  - Examples:
    - XPathResult.UNORDERED_NODE_ITERATOR_TYPE: Returns an unordered iterator.
    - XPathResult.ORDERED_NODE_ITERATOR_TYPE: Returns an ordered iterator.
- customXPathResult (XPathResult, optional, default = null)
  An optional custom XPath result object.
- cache (Map, optional, default = null)
  A cache for storing and reusing results. Must be an instance of Map if used.
- returnIterator (boolean, optional, default = false)
  Determines the return type:
  - true: Returns an XPathResult iterator.
  - false: Returns an array of matching nodes.

Returns: Either an array of DOM nodes or an XPathResult iterator, based on the configuration.

Throws: Specific errors based on the context like unsupported environment, no nodes matching criteria, or cache being not an instance of Map.

`⚙️ exposeEvaluatedNodesCacheGlobally()`

Exposes a given evaluated nodes cache to the global window object. This facilitates the exposure of a cache from the find-dom-nodes-by-content library to a broader scope for possible debugging or other purposes.

Parameters: