Namespace: XMLUtilities

XMLUtilities

A generic utility object that contains functions used throughout MetacatUI to perform useful functions related to XML, but not used to store or manipulate any state about the application.
Since:
  • 2.33.0
Source:

Classes

ParseError

Methods

appendCdataElement(doc, parent, name, value) → {Element}

Append a child element containing CDATA. Split `]]>` across CDATA nodes because it cannot appear within a single CDATA section.
Parameters:
Name Type Description
doc XMLDocument XML document used to create elements.
parent Element Parent element that receives the child.
name string Child element name.
value string Text value to append.
Source:
Returns:
The appended child element.
Type
Element

appendTextElement(doc, parent, name, value) → {Element|null}

Append a child element with XML-safe text content.
Parameters:
Name Type Description
doc XMLDocument XML document used to create elements.
parent Element Parent element that receives the child.
name string Child element name.
value * Text value to append.
Since:
  • 2.39.0
Source:
Returns:
The appended child element, or null for nullish values.
Type
Element | null

extractTextBySelectors(xmlString, selectors) → {string}

Extract the first non-empty text matched by the provided selectors from an XML string.
Parameters:
Name Type Description
xmlString string XML text to search.
selectors Array.<string> Selectors to try in order.
Since:
  • 2.39.0
Source:
Throws:
When XML parsing fails unexpectedly
Type
Error
Returns:
The extracted text, or an empty string.
Type
string

extractXmlDeclaration(xmlString) → {string|null}

Extract the XML declaration from raw XML text, if present.
Parameters:
Name Type Description
xmlString string | null | undefined XML text to inspect.
Since:
  • 2.39.0
Source:
Returns:
XML declaration text.
Type
string | null

findDirectChildElement(node, name) → {Element|null}

Find the first direct child element with the given local name. Matching is case-insensitive and ignores namespace prefixes.
Parameters:
Name Type Description
node Node The parent XML node.
name string Local child element name to match.
Since:
  • 2.39.0
Source:
Returns:
The first matching child element, or null.
Type
Element | null

findDirectChildElements(node, name) → {Array.<Element>}

Find all direct child elements with the given local name. Matching is case-insensitive and ignores namespace prefixes.
Parameters:
Name Type Description
node Node The parent XML node.
name string Local child element name to match.
Since:
  • 2.39.0
Source:
Returns:
Matching child elements.
Type
Array.<Element>

findElementsBySimpleSelector(root, selector) → {Array.<Element>}

Find elements matching a simple selector, ignoring namespace prefixes in element names. Used as a fallback when querySelector cannot handle XML names safely.
Parameters:
Name Type Description
root Document | Element Parsed XML document or element to search.
selector string Simple selector such as `d1:identifier` or `parent > child`.
Since:
  • 2.39.0
Source:
Returns:
Matching elements, or an empty array.
Type
Array.<Element>

findFirstElement(documentOrNode, name) → {Element|null}

Find the first element with the given local name anywhere under a parsed XML document or node. Matching ignores namespace prefixes.
Parameters:
Name Type Description
documentOrNode Document | Node Parsed XML document or node.
name string Local element name to match.
Since:
  • 2.39.0
Source:
Returns:
The first matching element, or null.
Type
Element | null

findLastDirectChildElement(node, name) → {Element|null}

Find the last direct child element with the given local name. Matching is case-insensitive and ignores namespace prefixes.
Parameters:
Name Type Description
node Node The parent XML node.
name string Local child element name to match.
Since:
  • 2.39.0
Source:
Returns:
The last matching child element, or null.
Type
Element | null

getDirectChildText(node, name) → {string|null}

Extract trimmed text from the first matching direct child element.
Parameters:
Name Type Description
node Node Parent XML node
name string Local child element name to match
Since:
  • 2.39.0
Source:
Returns:
Matching child text, or null
Type
string | null

getDirectChildTexts(node, name) → {Array.<(string|null)>}

Extract trimmed text from all matching direct child elements.
Parameters:
Name Type Description
node Node The parent XML node.
name string Local child element name to match.
Since:
  • 2.39.0
Source:
Returns:
Matching child text values.
Type
Array.<(string|null)>

getNamespaceAttributes(element) → {Array.<{name:string, value:string}>}

Capture namespace declarations from an XML element in source order.
Parameters:
Name Type Description
element Element | null XML element to inspect.
Since:
  • 2.39.0
Source:
Returns:
Namespace attributes.
Type
Array.<{name:string, value:string}>

getNormalizedElementName(node) → {string}

Return a lower-cased local element name with any namespace prefix removed.
Parameters:
Name Type Description
node Node The XML node to inspect.
Since:
  • 2.39.0
Source:
Returns:
The normalized local name, or an empty string.
Type
string

getRequiredAttribute(element, attributeName, contextopt) → {string}

Require a non-empty attribute value on an element.
Parameters:
Name Type Attributes Description
element Element XML element to inspect.
attributeName string Attribute name to read.
context string <optional>
 Context label for errors.
Since:
  • 2.39.0
Source:
Throws:
Throws when the attribute is missing or empty.
Type
Error
Returns:
Trimmed attribute value.
Type
string

getRequiredElementText(documentOrNode, elementName, contextopt) → {string}

Extract the first non-empty text value from a given element. The element is matched by local name and searched for anywhere under the given document or node. Throws an error if the element is not found or if the text value is empty.
Parameters:
Name Type Attributes Description
documentOrNode Document | Node Parsed XML document or node.
elementName string Local element name to extract.
context string <optional>
 Context label for error messages.
Since:
  • 2.39.0
Source:
Throws:
When the document or required text is missing
Type
Error
Returns:
The extracted non-empty text value.
Type
string

getXMLSafeID(id) → {string|null}

Convert an identifier to the legacy XML-safe ID form used by rendered metadata annotations.
Parameters:
Name Type Description
id * Identifier.
Since:
  • 2.39.0
Source:
Returns:
XML-safe ID, or null for empty input.
Type
string | null

isValidXmlCodePoint(codePoint) → {boolean}

Checks if a Unicode code point is valid according to the XML 1.0 specification. See https://www.w3.org/TR/xml/#charsets for the valid character ranges.
Parameters:
Name Type Description
codePoint number The Unicode code point to check
Since:
  • 2.39.0
Source:
Returns:
True if the code point is valid in XML, false otherwise
Type
boolean

parseRequiredXmlString(xmlString, contextopt) → {Document}

Parse an XML string and require a non-empty XML document.
Parameters:
Name Type Attributes Description
xmlString string XML text to parse.
context string <optional>
 Context label for parse errors.
Since:
  • 2.39.0
Source:
Throws:
Throws when the XML is empty or invalid.
Type
ParseError
Returns:
Parsed XML document.
Type
Document

parseSimpleElementSelector(selector) → {Array.<{combinator: string, name: string}>|null}

Parses a simple CSS-like selector string into an array of selector parts, each with a combinator and a tag name. Supports descendant combinators (space) and child combinators (>), as well as optional namespace prefixes in tag names.
Parameters:
Name Type Description
selector string The simple selector string to parse (e.g. "d1:identifier", "parent > child")
Since:
  • 2.39.0
Source:
Returns:
An array of selector parts with combinators and tag names, or null if the selector is invalid, e.g. [{ combinator: "descendant", name: "identifier" }] for "d1:identifier", or [{ combinator: "descendant", name: "parent" }, { combinator: "child", name: "child" }] for "parent > child"
Type
Array.<{combinator: string, name: string}> | null

parseXmlString(xmlString, contextopt) → {Document|null}

Parse an XML string into a Document.
Parameters:
Name Type Attributes Description
xmlString string XML text to parse.
context string <optional>
 Context label for parse errors.
Since:
  • 2.39.0
Source:
Throws:
When input is not a string or cannot be parsed
Type
ParseError
Returns:
Parsed XML Document, or null for empty, whitespace-only, or nullish input.
Type
Document | null

parseXmlStringForRequiredElementText(xmlString, elementName, contextopt) → {Object}

Parse an XML response and extract the first non-empty text value for the requested element.
Parameters:
Name Type Attributes Description
xmlString string XML response text.
elementName string Local element name to extract.
context string <optional>
 Context label for error messages.
Since:
  • 2.39.0
Source:
Returns:
Parsed XML and extracted value.
Type
Object

removeInvalidXmlCharacters(textString) → {string|null}

Remove XML 1.0-invalid characters from text intended for XML text nodes. This helper does not escape `&`, `<`, or other XML syntax characters; those are handled by XMLSerializer during DOM serialization. See https://www.w3.org/TR/xml/#charsets
Parameters:
Name Type Description
textString * Value to normalize. Non-null values are coerced to a string before invalid XML characters are removed.
Since:
  • 2.39.0
Source:
Returns:
The normalized string, or null for nullish values.
Type
string | null

requireAllowedAttributeNames(element, allowedNames, contextopt, optionsopt) → {Array.<string>}

Require that an element contains only allowed attribute names. Namespace declaration attributes are ignored by default.
Parameters:
Name Type Attributes Description
element Element XML element to inspect.
allowedNames Array.<string> Allowed attribute names.
context string <optional>
 Context label for errors.
options object <optional>
 Additional options.
Properties
Name Type Attributes Description
allowNamespaceDeclarations boolean <optional>
 Whether xmlns attributes are ignored during validation.
Since:
  • 2.39.0
Source:
Throws:
Throws when an unexpected attribute is present.
Type
Error
Returns:
Present non-namespace attribute names.
Type
Array.<string>

requireDirectChildSequence(node, definitions, contextopt) → {Map.<string, Array.<Element>>}

Require that direct child elements match an ordered schema-like sequence, including min/max occurrence constraints.
Parameters:
Name Type Attributes Description
node Node Parent XML node.
definitions Array.<object> Ordered direct-child definitions
Properties
Name Type Attributes Description
name string Child element name
minOccurs number <optional>
 Minimum occurrences
maxOccurs number <optional>
 Maximum occurrences
context string <optional>
 Context label for errors.
Since:
  • 2.39.0
Source:
Throws:
Throws on unexpected, out-of-order, duplicate, or missing child elements.
Type
Error
Returns:
Matching child elements by local name
Type
Map.<string, Array.<Element>>

requireDocumentElement(documentOrElement, expectedName, contextopt) → {Element}

Require that the provided document or element has the expected root name. Matching is case-insensitive and ignores namespace prefixes.
Parameters:
Name Type Attributes Description
documentOrElement Document | Element Parsed XML document or root element.
expectedName string Expected root local name.
context string <optional>
 Context label for error messages.
Since:
  • 2.39.0
Source:
Throws:
Throws when the root is missing or has the wrong name.
Type
Error
Returns:
The validated root element.
Type
Element

requireNamespaceUri(element, allowedNamespaceUris, contextopt) → {string}

Require that an element uses one of the expected namespace URIs.
Parameters:
Name Type Attributes Description
element Element XML element to inspect.
allowedNamespaceUris Array.<string> Allowed namespace URIs.
context string <optional>
 Context label for errors.
Since:
  • 2.39.0
Source:
Throws:
Throws when the namespace URI is missing or unsupported.
Type
Error
Returns:
The matched namespace URI.
Type
string