xml-disassembler

Disassemble XML files into smaller, more manageable files and reassemble them 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.
• Unique Identifiers – Use specific XML elements as file names or fallback to SHA-256 hashes.
• Ignore Files – Specify XML files to exclude from disassembly.
• Logging – Enable detailed debugging logs.
• Integrations – Works with tools like Salesforce CLI
• Extensions - Extensions allow for JSON, YAML, and JSON5 transformations.

Table of Contents

• Background
• Install
• Disassembling Files
• Reassembling Files
• Example
• Use Case
• Ignore File
• XML Parser
• Logging
• Extensions
• 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.

/* 
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.
*/
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",
});

Reassembling Files

Reassemble a directory of disassembled XML files into a single XML file.

/* 
FLAGS
- filePath:        Relative path to the disassembled XML 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,
});

Example

Input XML file (HR_Admin.permissionset-meta.xml)

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <applicationVisibilities>
        <application>JobApps__Recruiting</application>
        <visible>true</visible>
    </applicationVisibilities>
    <classAccesses>
        <apexClass>Send_Email_Confirmation</apexClass>
        <enabled>true</enabled>
    </classAccesses>
    <fieldPermissions>
        <editable>true</editable>
        <field>Job_Request__c.Salary__c</field>
        <readable>true</readable>
    </fieldPermissions>
    <description>Grants all rights needed for an HR administrator to manage employees.</description>
    <label>HR Administration</label>
    <userLicense>Salesforce</userLicense>
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>true</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <viewAllRecords>true</viewAllRecords>
        <modifyAllRecords>true</modifyAllRecords>
        <object>Job_Request__c</object>
    </objectPermissions>
    <pageAccesses>
        <apexPage>Job_Request_Web_Form</apexPage>
        <enabled>true</enabled>
    </pageAccesses>
    <recordTypeVisibilities>
        <recordType>Recruiting.DevManager</recordType>
        <visible>true</visible>
    </recordTypeVisibilities>
    <tabSettings>
        <tab>Job_Request__c</tab>
        <visibility>Available</visibility>
    </tabSettings>
    <userPermissions>
        <enabled>true</enabled>
        <name>APIEnabled</name>
    </userPermissions>
</PermissionSet>

Disassembled XML Directory

Disassembled XML files using unique ID elements

Disassembled XML files using SHA-256 hashes

Use Case

See sf-decomposer for a Salesforce CLI use case:

• Disassemble Use Case
• Reassemble 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");

Extensions

These extensions expand on xml-disassembler:

• xml2json-disassembler
• xml2yaml-disassembler
• xml2json5-disassembler

Contributing

Contributions are welcome! See Contributing.

Template

This project was created from a template by Allan Oricil.

His original license remains in this project.