@nchannel/exemel NPM

eXeMeL

Node library for converting between XML and JSON

Install

npm install @nchannel/exemel

Usage

XML -> JS Object / JSON

new XmlElementStream(options) -> stream

Extracts elements from xml and converts them to JS Objects; outputs one element at a time.

By default the readable side of the returned stream will operate in objectMode, however, when the stringify option is set to a truthy value the stream will operate in normal mode

Options:

selector String|RegExp|Array<String|RegExp> (Default: RegExp(/.*/) Selects all root elements) Determines which elements to convert to JSON. Strings are interpreted as XPaths. Arrays are evaluated until the first match is found. See note on XPaths
trim Boolean (Default: true) Trim whitespace from the beginning and end of text elements
coerce Boolean (Default: false) Attempt Number and Boolean type coercion against text elements (Suggest setting trim = true when using this option)
flattenText Boolean (Default: true) Causes text elements to be keyed using their parent's name when the parent does not have attributes
textKey String (Default: $value) Key to use for text elements when flattenText = false or when the text element's parent has attributes
attributesKey String (Default: $attributes) Key to use for the attributes object
cdataKey String (Default: $cdata) Key to use for cdata elements
commentKey String (Default: $comment) Key to use for comments
ignoreAttributes Boolean (Default: false) Don't output attributes in the converted JSON
ignoreComments (Boolean (Default: false) Don't output comments in the converted JSON
ignoreCdata Boolean (Default: false) Don't output cdata in the converted JSON
ignoreText Boolean (Default: false) Don't output text elements in the converted JSON
forceArray Array<String> (Default: []) Force matching elements to be an array. Provide the XPath to the element
blacklist Array<String|RegExp> (Default: []) Names of elements which should not be converted to JSON
rename Object (Default: {}) Key renaming map. Takes the form: {"before": "after"}
stringify Boolean (Default: false) If true will output stringified JSON
pretty Boolean (Default: true) Pretty print stringified JSON. Only applies when stringify = true
indent Number (Default: 2) Number of spaces to indent pretty printed JSON. Only applies when pretty = true

toJs(xml, options, callback)

A courtesy function wrapping XmlElementStream.

xml An XML string
options - See above
callback - Callback function invoked for each emitted element. callback(error, element)

JS Object -> XML

toXml(obj, options) -> string

Converts a JS Object to XML. obj will be cloned via JSON.parse(JSON.stringify(obj)) and therefore may not contain circular references.

Options:

textKey String (Default: $value) Key used to denote text elements within an object
attributesKey String (Default: $attributes) Key used to denote attributes
commentKey String (Default: $comment) Key used to denote comments
cdataKey String (Default: $cdata) Key used to denote cdata
ignoreAttributes Boolean (Default: false) Don't output attributes in the converted XML
ignoreComments (Boolean (Default: false) Don't output comments in the converted XML
ignoreCdata Boolean (Default: false) Don't output cdata in the converted XML
ignoreText Boolean (Default: false) Don't output text elements in the converted XML
selfClosingTags Boolean (Default: false) Use self closing tags when the node has no children
formattedTextElements Boolean (Default: false) Format text elements on their own line with indentation. Only applies when pretty = true
pretty Boolean (Default: true) Pretty print formatted XML
indent Number (Default: 2) Number of spaces to indent pretty printed XML. Only applies when pretty = true

Values associated with keys textKey, commentKey, and cdataKey may be either a string or an Array<string>.

Additionally, attributesKey must be associated with an object where each key is an attribute name and the value (string) is the attribute value.