# `xml-disassembler`
[](https://www.npmjs.com/package/xml-disassembler)
[](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/LICENSE.md)
[](https://npmjs.org/package/xml-disassembler)
[](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler) [](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
[](https://snyk.io//test/github/mcarvin8/xml-disassembler?targetFile=package.json)
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](#background)
- [Install](#install)
- [Disassembling Files](#disassembling-files)
- [Disassembly Strategies](#disassembly-strategies)
- [unique-id (default)](#unique-id-default)
- [grouped-by-tag](#grouped-by-tag)
- [Reassembling Files](#reassembling-files)
- [Use Case](#use-case)
- [Ignore File](#ignore-file)
- [XML Parser](#xml-parser)
- [Logging](#logging)
- [Contributing](#contributing)
- [Template & License](#template-&-license)
---
## 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
```typescript
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** | 
| 
|
| **YAML** | 
| 
|
| **JSON** | 
| 
|
| **JSON5** | 
| 
|
| **TOML** | 
| 
|
| **INI** | 
| 
|
### 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** | 
|
| **YAML** | 
|
| **JSON** | 
|
| **JSON5** | 
|
| **TOML** | 
|
| **INI** | 
|
---
## Reassembling Files
```typescript
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`](https://github.com/mcarvin8/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`](https://github.com/kaelzhang/node-ignore)
---
## XML Parser
Uses [`fast-xml-parser`](https://github.com/NaturalIntelligence/fast-xml-parser) with support for:
- Character Data (CDATA): `". Logs are written to `disassemble.log`.
```typescript
import { setLogLevel } from "xml-disassembler";
setLogLevel("debug"); // Enables verbose logging
```
---
## Contributing
Contributions are welcome! See [Contributing](https://github.com/mcarvin8/xml-disassembler/blob/main/CONTRIBUTING.md).
---
## Template & License
This project is based on a template by [Allan Oricil](https://github.com/AllanOricil) and licensed under the ISC license. The original code remains under the [ISC license](https://github.com/mcarvin8/xml-disassembler/blob/main/LICENSE.isc).
All contributions specific to the `xml-disassembler` is licensed under the [MIT license](https://github.com/mcarvin8/xml-disassembler/blob/main/LICENSE.md).