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:

• cache (Map): The evaluated nodes cache, which should be an instance of Map.
• config (Object, optional): Configuration options like log.

Throws: Errors if the cache is already exposed or if the provided cache is not an instance of Map.

⚙️ clearEvaluatedNodesCache()

Clears the globally exposed evaluated nodes cache. Useful for ensuring memory efficiency and clearing any globally accessible cache references.

Parameters:

• config (Object, optional): Configuration options like log.

Throws: An error if the cache is not currently exposed on the global window object.