js2xmlparser

To achieve specific XML structures, use these property patterns within your JavaScript objects:

Attributes

To add an attribute to an element, use the @ key. Example: { "@": { type: "home" }, street: "123 St" } becomes <street type="home">123 St</street>.

Mixed Content (Text Values)

To add text content to an element that also has attributes, use the # key. Example: { "@": { type: "home" }, "#": "123-555-4567" } becomes <phone type="home">123-555-4567</phone>.

Multiple Elements

To create multiple sibling elements with the same name, wrap the objects in an array. Example: phone: [ { "#": "1" }, { "#": "2" } ] becomes <phone>1</phone><phone>2</phone>.

To add js2xmlparser to your Node.js project, use the standard npm installation command.

npm install js2xmlparser

The wrapHandlers property in IOptions allows you to customize how arrays and Sets are wrapped in XML.

• Function Signature: A wrap handler is a function with the signature (key: string, value: unknown) => string | null.
• Behavior: The function receives the current key and the array/set being processed. It should return a new string to be used as the element name, or null to use the default behavior.
• Wildcard: You can provide a handler for the key "*" to apply to all arrays/sets, or provide specific keys to target specific array names.
• Nesting: If the handler returns a new name, the library may create an additional wrapper element depending on the returned value.

The typeHandlers property in IOptions allows you to intercept the conversion process for specific JavaScript types.

• Type Matching: Handlers are matched using Object.prototype.toString.call(value). For example, an object might be matched by [object Object].
• Wildcard Handler: You can provide a handler for the key "*" in typeHandlers to act as a catch-all for any type.
• Suppression: If a handler returns Absent.instance, the corresponding XML element or attribute will be omitted from the output.

Use IDeclarationOptions to control the <?xml ... ?> declaration at the start of your document.

• include (boolean): Whether to include the declaration. Default: true.
• encoding (string): The encoding attribute (e.g., "UTF-8").
• standalone (string): The standalone attribute. Must be "yes" or "no".
• version (string): The XML version. Default: "1.0".

const declaration: IDeclarationOptions = {
    include: true,
    encoding: 'UTF-8',
    standalone: 'yes',
    version: '1.0'
};

Use IDtdOptions to include a Document Type Definition (DTD) in the generated XML.

• include (boolean): Whether to include a DTD. Default: false.
• name (string): The name of the DTD. Required if include is true.
• sysId (string): The system identifier.
• pubId (string): The public identifier. If provided, sysId must also be provided.

const dtd: IDtdOptions = {
    include: true,
    name: 'html',
    pubId: '-//W3C//DTD XHTML 1.0 Strict//EN',
    sysId: 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'
};

Use IFormatOptions to control the visual layout (pretty-printing) of the XML.

• pretty (boolean): Enables pretty-printing. Default: true (via Options class implementation).
• indent (string): The string used for indentation. Default: four spaces.
• newline (string): The newline character. Default: "\n".
• doubleQuotes (boolean): If true, uses " for attributes; otherwise uses '. Default: false (single quotes).

const format: IFormatOptions = {
    pretty: true,
    indent: '    ',
    newline: '\n',
    doubleQuotes: false
};

If you are building an XML document manually using xmlcreate and want to inject a JavaScript object into a specific element, use parseToExistingElement.

Note: This function does not add a root element, an XML declaration, or a DTD. It only parses the object as children of the provided element.

import { parseToExistingElement } from 'js2xmlparser';
import { XmlElement } from 'xmlcreate';

const element = new XmlElement({ name: 'root' });
const obj = { item: 'value' };

parseToExistingElement(element, obj);
console.log(element.toString());

Use the parse function to convert a JavaScript object into a complete XML string. You must provide a root element name; the object's contents will be converted into children of this root element.

Key features:

• Supports XML declarations and DTDs via the options object.
• Handles formatting (indentation/newlines) via options.format.
• Automatically handles nested objects, arrays, Maps, and Sets.

import { parse } from 'js2xmlparser';

const obj = { name: 'John', age: 30 };
const xml = parse('user', obj, { 
  declaration: { include: true },
  format: { indent: '  ' }
});

console.log(xml);

The library exports several interfaces for configuring the parsing process. These are primarily used when calling parse() or parseToExistingElement().

• IOptions: The base configuration interface.
• IDeclarationOptions: Configuration for the XML declaration.
• IDtdOptions: Configuration for the Document Type Definition (DTD), including name, pubId, and sysId.
• IFormatOptions: Configuration for the output string formatting (e.g., indentation).
• ITypeHandlers: Mapping of type strings to handler functions.
• IWrapHandlers: Mapping of keys (including "*") to array/set wrapping functions.