CtrlK
BlogDocsLog inGet started
Tessl Logo

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

namespaces.mddocs/

Namespace Management

XML namespace handling including qualified names and namespace registration for proper XML serialization and parsing.

Capabilities

QName Class

Qualified names for representing namespaced XML elements and attributes.

/**
 * QName constructor for qualified names
 * @param {string} text_or_uri - Either full qualified name or namespace URI
 * @param {string} tag - Optional tag name when first parameter is URI
 */
class QName {
  constructor(text_or_uri, tag);
}

/**
 * Get string representation of qualified name
 * @returns {string} Qualified name as string
 */
toString(): string;

Usage Examples:

const et = require('elementtree');

// Create QName from full qualified name
const qname1 = new et.QName('{http://example.com/ns}element');
console.log(qname1.toString()); // "{http://example.com/ns}element"

// Create QName from URI and tag
const qname2 = new et.QName('http://example.com/ns', 'element');
console.log(qname2.toString()); // "{http://example.com/ns}element"

// Access QName properties
console.log(qname1.text); // "{http://example.com/ns}element"

Namespace Registration

Register namespace prefixes for cleaner XML serialization output.

/**
 * Register namespace prefix for serialization
 * @param {string} prefix - Namespace prefix
 * @param {string} uri - Namespace URI
 */
function register_namespace(prefix, uri);

Usage Examples:

const et = require('elementtree');

// Register custom namespace
et.register_namespace('custom', 'http://example.com/custom');
et.register_namespace('data', 'http://example.com/data');

// Create namespaced elements
const customElement = et.Element('{http://example.com/custom}item');
const dataElement = et.Element('{http://example.com/data}record');

// Serialize with registered prefixes
const xml1 = et.tostring(customElement, {xml_declaration: false});
console.log(xml1);
// Output: <custom:item xmlns:custom="http://example.com/custom" />

const xml2 = et.tostring(dataElement, {xml_declaration: false});
console.log(xml2);
// Output: <data:record xmlns:data="http://example.com/data" />

Built-in Namespace Prefixes

ElementTree includes well-known namespace prefixes by default.

Built-in Namespaces:

// Well-known namespace mappings (built-in)
const builtInNamespaces = {
  "http://www.w3.org/XML/1998/namespace": "xml",
  "http://www.w3.org/1999/xhtml": "html", 
  "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf",
  "http://schemas.xmlsoap.org/wsdl/": "wsdl",
  "http://www.w3.org/2001/XMLSchema": "xs",
  "http://www.w3.org/2001/XMLSchema-instance": "xsi",
  "http://purl.org/dc/elements/1.1/": "dc"
};

Usage Examples:

const et = require('elementtree');

// Use built-in XML namespace
const xmlElement = et.Element('{http://www.w3.org/XML/1998/namespace}lang');
xmlElement.text = 'en';

const xml = et.tostring(xmlElement, {xml_declaration: false});
console.log(xml);
// Output: <xml:lang xmlns:xml="http://www.w3.org/XML/1998/namespace">en</xml:lang>

// Use built-in XHTML namespace
const htmlElement = et.Element('{http://www.w3.org/1999/xhtml}div');
htmlElement.text = 'Content';

const htmlXml = et.tostring(htmlElement, {xml_declaration: false});
console.log(htmlXml);
// Output: <html:div xmlns:html="http://www.w3.org/1999/xhtml">Content</html:div>

Namespaced Elements Creation

Create elements with namespaces using different approaches.

Usage Examples:

const et = require('elementtree');

// Method 1: Using full qualified name string
const element1 = et.Element('{http://example.com/ns}item');

// Method 2: Using QName object
const qname = new et.QName('http://example.com/ns', 'item');
const element2 = et.Element(qname);

// Method 3: Register namespace first, then use
et.register_namespace('ns', 'http://example.com/ns');
const element3 = et.Element('{http://example.com/ns}item');

// All methods create equivalent elements
console.log(element1.tag); // "{http://example.com/ns}item"
console.log(element2.tag === qname); // true (QName object)
console.log(element3.tag); // "{http://example.com/ns}item"

Namespaced Attributes

Apply namespaces to element attributes.

Usage Examples:

const et = require('elementtree');

// Register namespace for attributes
et.register_namespace('meta', 'http://example.com/metadata');

const element = et.Element('item');

// Set namespaced attribute
element.set('{http://example.com/metadata}id', '12345');
element.set('{http://example.com/metadata}type', 'data');

// Set regular attribute
element.set('name', 'test');

const xml = et.tostring(element, {xml_declaration: false});
console.log(xml);
// Output: <item name="test" meta:id="12345" meta:type="data" xmlns:meta="http://example.com/metadata" />

// Access namespaced attributes
console.log(element.get('{http://example.com/metadata}id')); // "12345"
console.log(element.get('name')); // "test"

Default Namespace Handling

Handle default namespaces in XML serialization.

Usage Examples:

const et = require('elementtree');

const root = et.Element('document');
const section = et.SubElement(root, 'section');
const item = et.SubElement(section, 'item');
item.text = 'content';

const etree = new et.ElementTree(root);

// Serialize with default namespace
const xml = etree.write({
  xml_declaration: false,
  default_namespace: 'http://example.com/default',
  indent: 2
});

console.log(xml);
/* Output:
<document xmlns="http://example.com/default">
  <section>
    <item>content</item>
  </section>
</document>
*/

Mixed Namespace Documents

Create documents with multiple namespaces.

Usage Examples:

const et = require('elementtree');

// Register multiple namespaces
et.register_namespace('book', 'http://example.com/book');
et.register_namespace('author', 'http://example.com/author');

const library = et.Element('library');

// Add namespaced book element
const book = et.SubElement(library, '{http://example.com/book}book');
book.set('isbn', '978-0123456789');

// Add namespaced title (using same namespace as book)
const title = et.SubElement(book, '{http://example.com/book}title');
title.text = 'Advanced XML Processing';

// Add author from different namespace
const author = et.SubElement(book, '{http://example.com/author}author');
author.set('{http://example.com/author}id', 'auth-001');
author.text = 'Jane Doe';

const xml = et.tostring(library, {xml_declaration: false, indent: 2});
console.log(xml);
/* Output:
<library>
  <book:book isbn="978-0123456789" xmlns:book="http://example.com/book">
    <book:title>Advanced XML Processing</book:title>
    <author:author author:id="auth-001" xmlns:author="http://example.com/author">Jane Doe</author:author>
  </book:book>
</library>
*/

XPath with Namespaces

Use QName objects in XPath expressions for namespaced element selection.

Usage Examples:

const et = require('elementtree');

// Create document with namespaced elements
et.register_namespace('ns', 'http://example.com/ns');

const root = et.Element('root');
const nsItem = et.SubElement(root, '{http://example.com/ns}item');
nsItem.text = 'namespaced content';
const regularItem = et.SubElement(root, 'item');
regularItem.text = 'regular content';

// Use QName in XPath
const qname = new et.QName('http://example.com/ns', 'item');
const nsElement = root.find(qname);
console.log(nsElement.text); // "namespaced content"

// Regular XPath still works for non-namespaced elements
const regularElement = root.find('item');
console.log(regularElement.text); // "regular content"

Namespace Prefix Restrictions

Certain prefix formats are reserved and will cause errors.

Usage Examples:

const et = require('elementtree');

try {
  // This will throw an error - 'ns' followed by digits is reserved
  et.register_namespace('ns25', 'http://example.com/test');
} catch (error) {
  console.error('Error:', error.message);
  // Output: Error: Prefix format reserved for internal use
}

// Valid prefixes
et.register_namespace('custom', 'http://example.com/custom');  // OK
et.register_namespace('ns', 'http://example.com/ns');          // OK  
et.register_namespace('data1', 'http://example.com/data1');    // OK
et.register_namespace('my-ns', 'http://example.com/my-ns');    // OK

Namespace Auto-generation

When no prefix is registered, ElementTree auto-generates prefixes.

Usage Examples:

const et = require('elementtree');

// Create elements with unregistered namespaces
const element1 = et.Element('{http://unknown1.com}item');
const element2 = et.Element('{http://unknown2.com}data');

const root = et.Element('root');
root.append(element1);
root.append(element2);

const xml = et.tostring(root, {xml_declaration: false, indent: 2});
console.log(xml);
/* Output (auto-generated prefixes):
<root>
  <ns0:item xmlns:ns0="http://unknown1.com" />
  <ns1:data xmlns:ns1="http://unknown2.com" />
</root>
*/

Complex Namespace Example

Comprehensive example showing advanced namespace usage.

Usage Examples:

const et = require('elementtree');

// Register namespaces
et.register_namespace('soap', 'http://schemas.xmlsoap.org/soap/envelope/');
et.register_namespace('custom', 'http://example.com/custom');

// Create SOAP-like document
const envelope = et.Element('{http://schemas.xmlsoap.org/soap/envelope/}Envelope');

const header = et.SubElement(envelope, '{http://schemas.xmlsoap.org/soap/envelope/}Header');
const authToken = et.SubElement(header, '{http://example.com/custom}AuthToken');
authToken.text = 'abc123';
authToken.set('{http://example.com/custom}type', 'bearer');

const body = et.SubElement(envelope, '{http://schemas.xmlsoap.org/soap/envelope/}Body');
const request = et.SubElement(body, '{http://example.com/custom}GetUserRequest');
const userId = et.SubElement(request, '{http://example.com/custom}UserId');
userId.text = '12345';

const xml = et.tostring(envelope, {
  xml_declaration: true,
  encoding: 'utf-8',
  indent: 2
});

console.log(xml);
/* Output:
<?xml version='1.0' encoding='utf-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <custom:AuthToken custom:type="bearer" xmlns:custom="http://example.com/custom">abc123</custom:AuthToken>
  </soap:Header>
  <soap:Body>
    <custom:GetUserRequest xmlns:custom="http://example.com/custom">
      <custom:UserId>12345</custom:UserId>
    </custom:GetUserRequest>
  </soap:Body>
</soap:Envelope>
*/

Install with Tessl CLI

npx tessl i tessl/npm-elementtree

docs

elements.md

index.md

namespaces.md

parsing.md

serialization.md

special-elements.md

xpath.md

tile.json