xpath.js

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in a JavaScript module (ESM) context or a browser without a CommonJS loader.
  fix Ensure your environment is set up for CommonJS modules, or use a bundler (like Webpack) to transpile the code for ESM. For native Node.js ESM, this package is not directly compatible. Alternatively, change your file extension to `.cjs` if using Node.js modules.

• TypeError: Cannot read properties of undefined (reading 'localName')

  cause This error typically occurs when an XPath expression doesn't match any nodes, resulting in an empty array or `undefined` being accessed without a check.
  fix Always check if the result array from `select()` is not empty and contains the expected elements before attempting to access properties like `[0].localName` or `[0].data`. For example: `const nodes = select(doc, '//nonexistent'); if (nodes.length > 0) { console.log(nodes[0].localName); }`

• Error: Document not an instance of Node

  cause `xpath.js` expects a DOM `Node` object (typically an `Element` or `Document`) as its first argument. This error indicates that the provided argument is not a valid Node instance, often because the XML parsing failed or an incorrect object was passed.
  fix Ensure that the XML document is successfully parsed into a DOM structure using a library like `xmldom` before passing it to `xpath.js`. Verify that `new dom().parseFromString(xml, 'text/xml')` returns a valid document object.

Warnings

• breaking This package is an older CommonJS module (v1.1.0) and does not support native ES Modules (ESM) syntax (`import ... from '...'`) without transpilation. Directly using `import` statements in a native ESM context will result in a runtime error.
  Fix: For Node.js environments, use `const select = require('xpath.js');`. If you require ESM, consider using a bundler (like Webpack or Rollup) or evaluate more modern XPath libraries that offer native ESM support.
• gotcha The `xpath.js` library is based on XPath 1.0, which means it lacks many features introduced in XPath 2.0 and 3.x, such as advanced data types, sequences, user-defined functions, and JSON support.
  Fix: Ensure your XPath expressions conform to the XPath 1.0 specification. For more advanced querying needs, consider alternative, more actively maintained XPath 2.0/3.x libraries or parsing methods.
• breaking The `xpath.js` GitHub repository has not seen activity in approximately five years, indicating the package is abandoned. This means there will be no new features, bug fixes, or security updates, potentially leading to compatibility issues with newer Node.js versions or unaddressed vulnerabilities.
  Fix: Assess the risks of using an unmaintained library. For critical applications, consider migrating to an actively maintained XPath library. Regularly review `npm audit` for any reported vulnerabilities, though updates are unlikely.
• gotcha Using XPath to query user-supplied XML or allowing user input directly into XPath expressions without proper sanitization can lead to XPath Injection vulnerabilities. This is analogous to SQL Injection and can allow attackers to read unauthorized data or manipulate application logic.
  Fix: Always sanitize and validate any user input that is incorporated into XPath expressions. Implement strict input filtering, use parameterized queries if available (not directly supported by this library, so manual sanitization is crucial), and restrict error messages to prevent information disclosure. Consider libraries designed to mitigate injection risks if user input is unavoidable.

Install

• npm install xpath.js npm
• yarn add xpath.js yarn
• pnpm add xpath.js pnpm

Imports

• select
  wrong:

  import { select } from 'xpath.js';

  correct:

  import select from 'xpath.js'; // Requires transpilation or CommonJS fallback
  const select = require('xpath.js');

  This package is an older, CommonJS-first module. While modern bundlers might transpile `import select from 'xpath.js'`, the native import syntax for named exports (`import { select } from 'xpath.js'`) is incorrect as the package exports a default function. For Node.js, `require('xpath.js')` is the direct and intended usage.

Quickstart

This quickstart demonstrates how to parse an XML string using `xmldom` and then use `xpath.js` to select nodes, extract text content, and retrieve attribute values using XPath 1.0 expressions.

const select = require('xpath.js');
const dom = require('xmldom').DOMParser;

// Install xmldom: npm install xmldom

const xml = "<book><title>Harry Potter</title><author>J.K. Rowling</author></book>";
const doc = new dom().parseFromString(xml, 'text/xml');

// Select the title node
const titleNodes = select(doc, "//title");
console.log('Title node:', titleNodes[0].localName + ": " + titleNodes[0].firstChild.data);

// Get text value directly
const titleText = select(doc, "//title/text()")[0].data;
console.log('Title text:', titleText);

// Select an attribute value
const xmlWithAttr = "<book author='J. K. Rowling'><title>Harry Potter</title></book>";
const docWithAttr = new dom().parseFromString(xmlWithAttr, 'text/xml');
const author = select(docWithAttr, "/book/@author")[0].value;
console.log('Author attribute:', author);