`xml-disassembler`

Disassemble XML files into smaller, more manageable files (XML/INI/JSON/JSON5/TOML/YAML) and reassemble the XML when needed.

This tool simplifies version control, improves diff readability, and streamlines collaboration when dealing with large XML files.

🚀 Features

Disassemble XML Files – Break down XML files into structured directories.
Reassemble XML Files – Recreate the original XML structure from disassembled parts.

NOTE: The xml-disassembler aims to reassemble the original XML 100% element-wise, however, the element sorting will vary. The reassembler will sort elements based on how they are sorted in the disassembled directories. "toml" format sorting varies compared to the other formats.
Multiple Disassembly Strategies – Provides 2 strategies to disassemble an XML file.
Ignore Files – Specify XML files to exclude from disassembly.
Logging – Enable detailed debugging logs.
Integrations – Works with tools like Salesforce CLI
Multiple Formats - The disassembled file format can be XML, INI, JSON, JSON5, TOML, or YAML based on preference. The reassembler will reassemble the original XML structure from these formats.

Table of Contents

Background
Install
Disassembling Files
Disassembly Strategies
- unique-id (default)
- grouped-by-tag
Reassembling Files
Use Case
Ignore File
XML Parser
Logging
Contributing
Template

Background

Large XML files, especially those generated by external tools, can be challenging to review and manage.
xml-disassembler helps by breaking down these files into smaller, more digestible chunks, making it easier to track changes and collaborate.

Instead of relying on complex XML diff algorithms, xml-disassembler provides a simple and accessible solution by splitting XML files into structured directories.

Install

Install the package using NPM:

npm install xml-disassembler

Disassembling Files

Disassemble a single XML file or multiple XML files within a directory into smaller files (XML/INI/JSON/JSON5/TOML/YAML).

/* 
FLAGS
- filePath:         Relative path to the XML file or directory to disassemble.
- uniqueIdElements: Comma-separated list of UID elements for naming disassembled files (nested elements).
                    Defaults to SHA-256 hash if UID is undefined or not found.
- prePurge:         Delete pre-existing disassembled files prior to disassembling the file.
- postPurge:        Delete the XML file after disassembling it.

- ignorePath:       Path to an XML disassembly ignore file.
- format:           File format for the disassembled files ("xml", "ini", "json", "json5", "toml", "yaml")
                    Defaults to "xml" if the format isn't supported or provided.
- strategy:         Disassemble strategy ("unique-id" or "grouped-by-tag")
                    Defaults to "unique-id" if strategy isn't supported or provided.
*/
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",
});

Disassembly Strategies

xml-disassembler supports two disassembly strategies to suit different use cases for nested elements. You can choose a strategy by setting the strategy option when calling disassemble().

unique-id (default)

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

Disassembles each nested element into its own file under sub-directories.

File names are generated using one or more unique identifier elements (uniqueIdElements) or fallback to a SHA-256 hash.

Leaf elements remain grouped in a file named after the original XML.

Best for maximum diff granularity and precision in version control.

Disassembled Directory Samples for Unique IDs

Format	Sample Directory - UIDs	Sample Directory - SHA-256 Hashes
XML
YAML
JSON
JSON5
TOML
INI

grouped-by-tag

Groups all nested elements by tag name into a single file (e.g., all <fieldPermissions> into fieldPermissions.xml).

Leaf elements remain grouped in a file named after the original XML.

Useful for simplifying diff views and reducing file count in large projects.

Disassembled Directory Samples for Grouped by Tag

Format	Sample Directory
XML
YAML
JSON
JSON5
TOML
INI

Reassembling Files

Reassemble a directory of disassembled files (XML/INI/JSON/JSON5/TOML/YAML) into a single XML file.

/* 
FLAGS
- filePath:        Relative path to the disassembled directory to reassemble.
- fileExtension:   File extension for the reassembled XML.
                   [default: `.xml`]
- postPurge:       Delete the disassembled files after reassembly.
*/
import { ReassembleXMLFileHandler } from "xml-disassembler";

const handler = new ReassembleXMLFileHandler();
await handler.reassemble({
  filePath: "test/baselines/general/HR_Admin",
  fileExtension: "permissionset-meta.xml",
  postPurge: true,
});

Use Case

See sf-decomposer for a Salesforce CLI use case.

Ignore File

Create an ignore file (.xmldisassemblerignore by default) to exclude XMLs from disassembly.

uses node-ignore (follows .gitignore spec 2.22.1)

XML Parser

Uses fast-xml-parser with support for:

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

Logging

Instead of printing to the terminal, the disassembler uses log4js to create a logging file. Logs are stored in disassemble.log.

By default, only errors are logged.

[2024-03-30T14:28:37.950] [ERROR] default - The XML file HR_Admin.no-nested-elements.xml only has leaf elements. This file will not be disassembled.

Enable debug logs using the setLogLevel function:

import {
  DisassembleXMLFileHandler,
  ReassembleXMLFileHandler,
  setLogLevel,
} from "xml-disassembler";

setLogLevel("debug");

Contributing

Contributions are welcome! See Contributing.

Template

This project was created from a template by Allan Oricil.

His original license remains in this project.