or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

building.mdconfiguration.mdindex.mdparsing.mdprocessing.md
tile.json

tessl/npm-xml2js

Simple XML to JavaScript object converter.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/xml2js@0.6.x

To install, run

npx @tessl/cli install tessl/npm-xml2js@0.6.0

index.mddocs/

xml2js

xml2js is a bidirectional XML to JavaScript object converter that simplifies XML parsing and building for Node.js applications. It offers multiple parsing approaches including callback-based, promise-based, and stream-based parsing with extensive configuration options for handling attributes, text content, namespaces, and data transformation.

Package Information

  • Package Name: xml2js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install xml2js

Core Imports

const xml2js = require('xml2js');
const { parseString, parseStringPromise, Parser, Builder } = require('xml2js');

For ES modules:

import xml2js from 'xml2js';
import { parseString, parseStringPromise, Parser, Builder } from 'xml2js';

Basic Usage

const xml2js = require('xml2js');

// Simple XML parsing with callback
const xmlString = '<root><name>John</name><age>30</age></root>';
xml2js.parseString(xmlString, (err, result) => {
  if (err) throw err;
  console.log(result); // { root: { name: ['John'], age: ['30'] } }
});

// Promise-based parsing
xml2js.parseStringPromise(xmlString)
  .then(result => console.log(result))
  .catch(err => console.error(err));

// Building XML from JavaScript object
const builder = new xml2js.Builder();
const obj = { root: { name: 'John', age: 30 } };
const xml = builder.buildObject(obj);
console.log(xml); // <?xml version="1.0" encoding="UTF-8"?>...

Architecture

xml2js is built around several key components:

  • SAX Parser Integration: Uses the SAX parser for efficient, streaming XML parsing
  • Configuration System: Extensive options for customizing parsing and building behavior
  • Processing Pipeline: Built-in text processors for common transformations
  • Event-Driven Architecture: Parser class extends EventEmitter for advanced usage patterns
  • xmlbuilder Integration: Uses xmlbuilder-js for reliable XML generation

Capabilities

XML Parsing

Core XML parsing functionality with multiple API approaches for different use cases. Supports callback-based, promise-based, and class-based parsing with extensive configuration.

function parseString(xml: string, callback: (err: Error | null, result?: any) => void): void;
function parseString(xml: string, options: ParserOptions, callback: (err: Error | null, result?: any) => void): void;

function parseStringPromise(xml: string): Promise<any>;
function parseStringPromise(xml: string, options: ParserOptions): Promise<any>;

class Parser extends EventEmitter {
  constructor(options?: ParserOptions);
  parseString(xml: string, callback: (err: Error | null, result?: any) => void): void;
  parseStringPromise(xml: string): Promise<any>;
  reset(): void;
}

XML Parsing

XML Building

XML generation functionality for converting JavaScript objects to well-formed XML strings with customizable formatting and structure options.

class Builder {
  constructor(options?: BuilderOptions);
  buildObject(rootObj: any): string;
}

XML Building

Text Processing

Built-in text processing functions for common XML data transformations including normalization, type conversion, and namespace handling.

const processors: {
  normalize: (str: string) => string;
  firstCharLowerCase: (str: string) => string;
  stripPrefix: (str: string) => string;
  parseNumbers: (str: string) => string | number;
  parseBooleans: (str: string) => string | boolean;
};

Text Processing

Configuration

Default configuration presets and validation error handling for different API versions and usage patterns.

const defaults: {
  "0.1": { explicitArray: boolean; ignoreAttrs: boolean; /* ... */ };
  "0.2": { explicitArray: boolean; ignoreAttrs: boolean; /* ... */ };
};

class ValidationError extends Error {
  constructor(message: string);
}

Configuration

Types

interface ParserOptions {
  attrkey?: string;
  charkey?: string;
  explicitCharkey?: boolean;
  trim?: boolean;
  normalize?: boolean;
  normalizeTags?: boolean;
  explicitRoot?: boolean;
  explicitArray?: boolean;
  ignoreAttrs?: boolean;
  mergeAttrs?: boolean;
  validator?: (xpath: string, currentValue: any, newValue: any) => any;
  xmlns?: boolean;
  explicitChildren?: boolean;
  childkey?: string;
  preserveChildrenOrder?: boolean;
  charsAsChildren?: boolean;
  includeWhiteChars?: boolean;
  async?: boolean;
  strict?: boolean;
  attrNameProcessors?: Array<(name: string) => string>;
  attrValueProcessors?: Array<(value: string, name: string) => any>;
  tagNameProcessors?: Array<(name: string) => string>;
  valueProcessors?: Array<(value: string, name: string) => any>;
  emptyTag?: string | (() => string);
  chunkSize?: number;
}

interface BuilderOptions {
  attrkey?: string;
  charkey?: string;
  rootName?: string;
  xmldec?: {
    version?: string;
    encoding?: string;
    standalone?: boolean;
  };
  doctype?: any;
  renderOpts?: {
    pretty?: boolean;
    indent?: string;
    newline?: string;
  };
  headless?: boolean;
  allowSurrogateChars?: boolean;
  cdata?: boolean;
}