tessl/npm-elementtree

XML Serialization and Parsing module based on Python's ElementTree.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

XML Parsing

Name: tessl/npm-elementtree
Author: tessl

Parse XML documents and perform document-level operations including XPath queries and tree navigation.

Capabilities

Parse Function

Parse XML source string into an ElementTree instance.

/**
 * Parse XML source into ElementTree
 * @param {string} source - XML source string
 * @param {object} parser - Optional parser instance
 * @returns {ElementTree} ElementTree instance with parsed content
 */
function parse(source, parser);

Usage Examples:

const et = require('elementtree');

// Parse XML string
const xml = '<root><item id="1">Hello</item><item id="2">World</item></root>';
const etree = et.parse(xml);

console.log(etree.findtext('item')); // "Hello"
console.log(etree.findall('item').length); // 2

XML Function

Parse XML source string and return the root element directly.

/**
 * Parse XML source and return root element
 * @param {string} data - XML source string
 * @returns {Element} Root element of parsed XML
 */
function XML(data);

Usage Examples:

const et = require('elementtree');

// Parse and get root element
const root = et.XML('<root><item>Test</item></root>');
console.log(root.tag); // "root"
console.log(root.findtext('item')); // "Test"

ElementTree Class

Document wrapper providing tree-level operations and XPath queries.

/**
 * ElementTree constructor
 * @param {Element} element - Root element for the tree
 */
class ElementTree {
  constructor(element);
}

ElementTree Parsing Methods

Methods for parsing XML content into the ElementTree instance.

/**
 * Parse XML source into this tree
 * @param {string} source - XML source string
 * @param {object} parser - Optional parser instance
 * @returns {Element} Root element of parsed content
 */
parse(source, parser): Element;

Usage Examples:

const et = require('elementtree');

// Create empty tree and parse into it
const etree = new et.ElementTree();
const root = etree.parse('<data><item>Test</item></data>');

console.log(root.tag); // "data"
console.log(etree.findtext('item')); // "Test"

ElementTree Root Management

Methods for accessing and managing the root element.

/**
 * Get the root element of the tree
 * @returns {Element} Root element
 */
getroot(): Element;

Usage Examples:

const et = require('elementtree');

const root = et.Element('root');
const etree = new et.ElementTree(root);

console.log(etree.getroot().tag); // "root"

ElementTree XPath Methods

XPath query methods available at the document level.

/**
 * Find first element matching XPath expression
 * @param {string} path - XPath expression
 * @returns {Element|null} First matching element or null
 */
find(path): Element | null;

/**
 * Find all elements matching XPath expression
 * @param {string} path - XPath expression
 * @returns {Element[]} Array of matching elements
 */
findall(path): Element[];

/**
 * Find text content of first element matching XPath expression
 * @param {string} path - XPath expression
 * @param {string} defvalue - Default value if no match found
 * @returns {string|null} Text content or default value
 */
findtext(path, defvalue): string | null;

Usage Examples:

const et = require('elementtree');

const xml = `
  <library>
    <book id="1">
      <title>JavaScript Guide</title>
      <author>John Doe</author>
    </book>
    <book id="2">
      <title>Node.js Handbook</title>
      <author>Jane Smith</author>
    </book>
  </library>
`;

const etree = et.parse(xml);

// Find first book
const firstBook = etree.find('book');
console.log(firstBook.get('id')); // "1"

// Find all books
const allBooks = etree.findall('book');
console.log(allBooks.length); // 2

// Find text content
const firstTitle = etree.findtext('book/title');
console.log(firstTitle); // "JavaScript Guide"

// Find with default value
const missing = etree.findtext('book/isbn', 'N/A');
console.log(missing); // "N/A"

ElementTree Iteration

Iteration methods for traversing the entire document tree.

/**
 * Iterate over all elements in the tree
 * @param {string|null} tag - Tag name to filter by, or null for all elements
 * @param {function} callback - Callback function receiving each element
 */
iter(tag, callback): void;

Usage Examples:

const et = require('elementtree');

const xml = '<root><item>1</item><item>2</item><other>3</other></root>';
const etree = et.parse(xml);

// Iterate over all elements
etree.iter(null, function(element) {
  console.log(element.tag);
});
// Output: root, item, item, other

// Iterate over specific tag
etree.iter('item', function(element) {
  console.log(element.text);
});
// Output: 1, 2

Parser Infrastructure

ElementTree uses a modular parser system built on the SAX parsing approach with configurable parsers and tree builders.

// Parser infrastructure components  
const parser = require('elementtree/lib/parser');
const TreeBuilder = require('elementtree/lib/treebuilder').TreeBuilder;
const constants = require('elementtree/lib/constants');

// Get parser by name (currently only 'sax' is supported)
function get_parser(name): Parser;

// TreeBuilder class for constructing element trees
class TreeBuilder {
  constructor(element_factory?);
  close(): Element;
  data(data: string): void;
  start(tag: string, attrs: object): void;
  end(tag: string): Element;
}

Default Parser Configuration:

const et = require('elementtree');
const constants = require('elementtree/lib/constants');

console.log(constants.DEFAULT_PARSER); // 'sax'

// Default parsing uses SAX parser internally
const etree = et.parse('<root><item>content</item></root>');

Custom Parser Usage:

const et = require('elementtree');
const parser = require('elementtree/lib/parser');
const TreeBuilder = require('elementtree/lib/treebuilder').TreeBuilder;

// Create custom parser instance
const saxParser = parser.get_parser('sax');
const treeBuilder = new TreeBuilder();
const xmlParser = new saxParser.XMLParser(treeBuilder);

// Use with parse function
const etree = new et.ElementTree();
etree.parse('<root><test>content</test></root>', xmlParser);

// Or with custom element factory
const customTreeBuilder = new TreeBuilder(et.Element);
const customParser = new saxParser.XMLParser(customTreeBuilder);
etree.parse('<custom><data>info</data></custom>', customParser);

Parser Architecture:

SAX Parser: Stream-based XML parser that fires events for XML tokens
TreeBuilder: Converts SAX events into Element tree structure
Element Factory: Creates Element instances (customizable via TreeBuilder constructor)
Parser Interface: Standardized interface allowing future parser implementations

Error Handling

XML parsing may throw errors for malformed XML or invalid XPath expressions. The library uses custom error types from the elementtree/lib/errors module.

// Custom error types
const SyntaxError = require('elementtree/lib/errors').SyntaxError;

Common Error Scenarios:

const et = require('elementtree');

// 1. Malformed XML parsing errors
try {
  const etree = et.parse('<root><unclosed>');
} catch (error) {
  console.error('XML parsing error:', error.message);
  // Handle XML structure errors
}

// 2. XPath syntax errors (custom SyntaxError)
try {
  const etree = et.parse('<root></root>');
  etree.findall('/absolute/path'); // Absolute paths not supported
} catch (error) {
  if (error instanceof et.SyntaxError) {
    console.error('XPath syntax error:', error.message);
    console.error('Invalid token:', error.token);
  }
}

// 3. Invalid XPath expressions
const invalidXPaths = [
  './/@bar',     // Invalid attribute syntax
  '[@bar',       // Unclosed attribute bracket
  '[@foo=bar]',  // Unquoted attribute value
  '[@',          // Incomplete attribute syntax
  '/bar'         // Absolute path (not supported)
];

invalidXPaths.forEach(xpath => {
  try {
    etree.findall(xpath);
  } catch (error) {
    console.error(`XPath "${xpath}" failed:`, error.message);
  }
});

Error Types:

XML Parse Errors: Thrown by the underlying SAX parser for malformed XML
XPath Syntax Errors: Custom SyntaxError with token property for invalid XPath expressions
Standard Errors: Other JavaScript errors for invalid method arguments or runtime issues

Install with Tessl CLI