xast utility to parse from XML

4.0.0 · active · verified Sun Apr 19

xast-util-from-xml is a utility within the unified ecosystem designed to parse serialized XML strings or `Uint8Array` into a `xast` (XML Abstract Syntax Tree) compliant syntax tree. Currently at version 4.0.0, the package maintains an active development status with major releases tied to significant internal changes and Node.js version updates. It leverages the `@rgrove/parse-xml` library for efficient and robust XML parsing, then transforms its output into the standardized `xast` format. This allows developers to programmatically interact with XML structures using a consistent AST representation, often for transformations or analysis. It is primarily differentiated by its integration into the broader `unified` and `xast` ecosystem, providing a predictable and well-typed interface for XML processing in JavaScript and TypeScript environments. The package is ESM-only and compatible with Node.js 16 and higher.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax in an ESM-only package or environment.

fix Replace `const fromXml = require('xast-util-from-xml')` with `import { fromXml } from 'xast-util-from-xml'`.
```
VFileMessage: Cannot parse XML (1:1): unknown:
```
cause The input XML string or buffer is malformed, invalid, or contains constructs not supported by the underlying `@rgrove/parse-xml` parser.

fix Examine the XML input for syntax errors (e.g., unclosed tags, invalid characters, incorrect nesting, problematic entities) and correct them to ensure it is well-formed.
```
SyntaxError: Cannot use import statement outside a module
```
cause Running an ESM-only package in a Node.js environment configured for CommonJS, or an older Node.js version (<16) that doesn't fully support ESM without specific configuration.

fix Ensure your `package.json` includes `"type": "module"` for your project, or rename your file to `.mjs`. Also, verify you are running Node.js v16 or higher.
```
TypeError: fs__WEBPACK_IMPORTED_MODULE_0__.promises.readFile is not a function (or similar for other Node.js built-ins in browser)
```
cause Attempting to run Node.js-specific modules (like `node:fs/promises`) within a browser environment without proper polyfills or build-time shimming.

fix Ensure your build process (e.g., Webpack, Rollup) correctly handles Node.js module resolution for browser targets, or load XML content in the browser using browser-native APIs like `fetch` or direct string assignment.

Warnings

breaking Version 4.0.0 and above require Node.js 16 or newer. Running on older Node.js versions will result in runtime errors related to unsupported syntax or module resolution.
Fix: Upgrade your Node.js environment to version 16 or a later LTS release.
breaking Version 4.0.0 switched to using the `exports` field in `package.json` for module resolution. This means direct imports of internal or private API paths (e.g., `xast-util-from-xml/lib/file`) will break.
Fix: Ensure all imports target the public `xast-util-from-xml` package entry point, typically `import { fromXml } from 'xast-util-from-xml'`.
breaking Version 3.0.0 replaced the internal `sax` parser with `@rgrove/parse-xml`. While providing improved parsing capabilities, this change can lead to more stringent error detection for malformed XML, potentially causing previously 'working' (but technically incorrect) XML to now throw parsing errors.
Fix: Review and correct any non-standard, malformed, or ambiguous XML input to ensure it is well-formed and valid according to XML specifications.
breaking Version 2.0.0 transitioned the package to be ESM-only. CommonJS `require()` statements are no longer supported and will cause runtime errors.
Fix: Migrate your codebase to use ECMAScript Modules (ESM) syntax, replacing `require()` calls with `import` statements. Ensure your Node.js project is configured for ESM (e.g., by adding `"type": "module"` to your `package.json` or using `.mjs` file extensions).
gotcha XML parsing, especially with user-provided data, can be a source of security vulnerabilities (e.g., XXE attacks, Billion Laughs attacks). The package does not inherently sanitize or protect against all XML-related exploits.
Fix: Never process untrusted XML input directly. Always implement robust input validation, sanitize data, and consider using tools or configurations that explicitly guard against known XML exploits before passing data to `fromXml`.

Install

npm install xast-util-from-xml npm
yarn add xast-util-from-xml yarn
pnpm add xast-util-from-xml pnpm

Imports

fromXml
wrong:
```
const fromXml = require('xast-util-from-xml')
```
correct:
```
import { fromXml } from 'xast-util-from-xml'
```
The package is ESM-only since v2 and has no default export. CommonJS `require` statements will fail.
fromXml (browser/Deno)
```
import { fromXml } from 'https://esm.sh/xast-util-from-xml@4'
```
For browser and Deno environments, use an import map or directly import from `esm.sh`.
Root (xast type)
```
import type { Root } from 'xast'
```
While `xast-util-from-xml` uses `xast` types internally and provides its own types for `fromXml`, the `Root` type itself is exported from the `xast` package.

Quickstart

Demonstrates parsing a string of XML content into a xast syntax tree and printing the resulting structure to the console.

import fs from 'node:fs/promises'
import {fromXml} from 'xast-util-from-xml'

async function parseExampleXml() {
  // Assume example.xml contains:
  // <album id="123">
  //   <name>Born in the U.S.A.</name>
  //   <artist>Bruce Springsteen</artist>
  //   <releasedate>1984-04-06</releasedate>
  // </album>

  // For demonstration, create a dummy file or use a string directly
  const xmlContent = `<album id="123"><name>Born in the U.S.A.</name><artist>Bruce Springsteen</artist><releasedate>1984-04-06</releasedate></album>`;
  const tree = fromXml(xmlContent);

  // In a real scenario, you'd read from a file:
  // const tree = fromXml(await fs.readFile('example.xml', 'utf8'))

  console.dir(tree, {depth: undefined})
}

parseExampleXml().catch(console.error)

view raw JSON →