xml-disassembler
TypeScript icon, indicating that this package has built-in type declarations

1.10.13 • Public • Published

xml-disassembler

NPM Downloads/week Maintainability codecov

Disassemble large XML files into smaller, modular files in formats like XML, INI, JSON, JSON5, TOML, or YAML—then reassemble them as needed.

Designed for improved version control, cleaner diffs, and easier team collaboration when dealing with complex XML structures.


Features

  • Disassemble XML Files – Break down XML into smaller components.
  • Reassemble XML – Rebuild the original XML from disassembled parts.
  • Multiple Output Formats – Choose XML, INI, JSON, JSON5, TOML, or YAML.
  • Two Disassembly Strategies – Choose between unique-id (default) or grouped-by-tag.
  • Ignore Rules – Exclude files from processing using an ignore file.
  • Logging – Log errors and debug information using log4js.
  • Salesforce Integration – Supports use cases like Salesforce metadata processing.

Note: Reassembly guarantees element-level fidelity, but element order may vary—especially when using TOML.

Table of Contents

Background

Managing large XML files—especially those generated by tools—can be painful. xml-disassembler solves this by splitting them into digestible pieces, optimized for Git diffs and team workflows.

No need for complex diffing tools—just structured directories with format-flexible files.


Install

Install the package using NPM:

npm install xml-disassembler

Disassembling Files

import { DisassembleXMLFileHandler } from "xml-disassembler";

const handler = new DisassembleXMLFileHandler();
await handler.disassemble({
  filePath: "test/baselines/general",
  uniqueIdElements:
    "application,apexClass,name,externalDataSource,flow,object,apexPage,recordType,tab,field",
  prePurge: true,
  postPurge: true,
  ignorePath: ".xmldisassemblerignore",
  format: "json",
  strategy: "unique-id",
});
Option Description
filePath Path to the XML file or directory
uniqueIdElements Comma-separated list of UID elements for naming nested files
prePurge Delete previous disassembly output before running (true or false, default false)
postPurge Delete the original XML after disassembly (true or false, default false)
ignorePath Path to the ignore file (default .xmldisassemblerignore)
format Output format: xml, ini, json, json5, toml, yaml
strategy Disassembly strategy: unique-id or grouped-by-tag

Disassembly Strategies

unique-id (default)

This is the strategy all previous versions of the xml-disassembler follow.

Each nested element is written to a separate file based on its unique identifier—or a SHA-256 hash fallback. Leaf elements remain grouped in a file named after the original XML.

Best for detailed diffs and granular version control.

Example Outputs

Format UID Example Hash Example
XML XML UID
XML Hash
YAML YAML UID
YAML Hash
JSON JSON UID
JSON Hash
JSON5 JSON5 UID
JSON5 Hash
TOML TOML UID
TOML Hash
INI INI UID
INI Hash

grouped-by-tag

Groups all nested elements by tag into a single file. Leaf elements still go into a base file named after the original XML.

Best for fewer files and easier manual inspection.

Example Outputs

Format Grouped by Tag Example
XML XML tag
YAML YAML tag
JSON JSON tag
JSON5 JSON5 tag
TOML TOML tag
INI INI tag

Reassembling Files

import { ReassembleXMLFileHandler } from "xml-disassembler";

const handler = new ReassembleXMLFileHandler();
await handler.reassemble({
  filePath: "test/baselines/general/HR_Admin",
  fileExtension: "permissionset-meta.xml",
  postPurge: true,
});
Option Description
filePath Directory containing disassembled files to reassemble
fileExtension Extension for the output XML file (default: .xml)
postPurge Delete disassembled files after successful reassembly (true or false, default false)

Use Case

See sf-decomposer for a Salesforce CLI use case.


Ignore File

Create an ignore file, similar to a .gitignore, to exclude XMLs from disassembly.

uses node-ignore


XML Parser

Uses fast-xml-parser with support for:

  • Character Data (CDATA): "![CDATA["
  • Comments: "!---"
  • Attributes: "@__**"

Logging

Logging uses log4js. Logs are written to disassemble.log.

import { setLogLevel } from "xml-disassembler";

setLogLevel("debug"); // Enables verbose logging

Contributing

Contributions are welcome! See Contributing.


Template

This project was created from a template by Allan Oricil.

His original license remains in this project.

Package Sidebar

Install

npm i xml-disassembler

Weekly Downloads

376

Version

1.10.13

License

ISC

Unpacked Size

500 kB

Total Files

54

Last publish

Collaborators

  • mcarvin