Skip to content

Latest commit

 

History

History
91 lines (63 loc) · 3.25 KB

README.md

File metadata and controls

91 lines (63 loc) · 3.25 KB
Raw

is-dom-node

Build Status Code Coverage NPM Version License

Description

@xmldom/is-dom-node is a versatile TypeScript library designed to provide robust utility functions for working with DOM nodes. Whether you're developing for the browser or dealing with XML in NodeJS, this library offers a comprehensive set of functions for checking and asserting various types of DOM nodes. It's particularly useful when working with NodeJS libraries like xpath and @xmldom/xmldom, as it can validate the objects returned by these libraries.

Installation

npm install @xmldom/is-dom-node

Usage

Import the library and use it as follows:

import * as isDomNode from "@xmldom/is-dom-node";

const element = document.createElement("div");
const result = isDomNode.isElementNode(element); // Output: true

TypeScript Example

import * as isDomNode from "@xmldom/is-dom-node";

function handleNode(node: Node) {
  if (isDomNode.isElementNode(node)) {
    // TypeScript now knows `node` is an Element
    console.log(node.tagName);
  } else if (isDomNode.isTextNode(node)) {
    // TypeScript now knows `node` is a Text node
    console.log(node.wholeText);
  } else {
    try {
      // Assert that the node is a Comment node
      isDomNode.assertIsCommentNode(node);
      // TypeScript now knows `node` is a Comment node
      console.log(node.nodeValue);
    } catch (error) {
      console.error("Node is not a Comment node:", error);
    }
  }
}

API Overview

The API consists of two main types of functions:

is... Functions

These functions return a boolean value indicating whether the given object meets certain criteria:

  • isNodeLike: Checks if a given value resembles a DOM node.
  • isArrayOfNodes: Checks if the given value is an array of DOM nodes.
  • isElementNode, isAttributeNode, isTextNode, etc.: Check for specific types of DOM nodes.

assertIs... Functions

These functions assert that a given object meets certain criteria and throw an error if it doesn't:

  • assertIsNodeLike: Asserts that a given value is a DOM node.
  • assertIsArrayOfNodes: Asserts that the given value is an array of DOM nodes.
  • assertIsElementNode, assertIsAttributeNode, assertIsTextNode, etc.: Assert for specific types of DOM nodes.

TypeScript Type Narrowing

Both the is... and assertIs... functions can be used for TypeScript type narrowing. After a successful check or assertion, TypeScript will recognize the specific type of the DOM node, allowing for more robust and error-free code.

Features

  • Lightweight
  • Written in TypeScript
  • Comprehensive tests
  • Compatible with NodeJS XML libraries like xpath and @xmldom/xmldom

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.