xml-disassembler

Split large XML files into smaller, version-control–friendly pieces—then reassemble them when needed. Output as XML, INI, JSON, JSON5, TOML, or YAML.

Useful for cleaner diffs, easier collaboration, and workflows like Salesforce metadata.

Rust implementation: For a native, high-performance alternative, see xml-disassembler-rust.

---

Table of contents

• Quick start
• Features
• Install
• Disassembling
• Disassembly strategies
• Reassembling
• Ignore file
• Logging
• XML parser
• Use case
• Development
• License

---

Quick start

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

// Disassemble: one XML → many small files
const disassemble = new DisassembleXMLFileHandler();
await disassemble.disassemble({
  filePath: "path/to/YourFile.permissionset-meta.xml",
  uniqueIdElements:
    "application,apexClass,name,flow,object,recordType,tab,field",
  format: "json",
  strategy: "unique-id",
});

// Reassemble: many small files → one XML
const reassemble = new ReassembleXMLFileHandler();
await reassemble.reassemble({
  filePath: "path/to/YourFile",
  fileExtension: "permissionset-meta.xml",
});

---

Features

• Disassemble – Break XML into smaller components (by unique ID or by tag).
• Reassemble – Rebuild the original XML from disassembled output.
• Multiple formats – Output (and reassemble from) XML, INI, JSON, JSON5, TOML, or YAML.
• Strategies – unique-id (one file per nested element) or grouped-by-tag (one file per tag).
• Ignore rules – Exclude paths via a .xmldisassemblerignore file (same style as .gitignore).
• Logging – Configurable logging via log4js (writes to disassemble.log by default).
• Salesforce-friendly – Fits metadata and similar XML-heavy workflows.

Reassembly preserves element content and structure; element order may differ (especially with TOML).

---

Install

npm install xml-disassembler

---

Disassembling

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 to disassemble.
uniqueIdElements	Comma-separated element names used to derive filenames for nested elements.
prePurge	Remove existing disassembly output before running (default: false).
postPurge	Remove the source XML after disassembly (default: false).
ignorePath	Path to the ignore file (default: .xmldisassemblerignore).
format	Output format: xml, ini, json, json5, toml, yaml.
strategy	unique-id or grouped-by-tag.

---

Disassembly strategies

unique-id (default)

Each nested element is written to its own file, named by a unique identifier (or a SHA-256 hash if no UID is available). Leaf content stays in a file named after the original XML.

Best for fine-grained diffs and version control.

Example layouts

Format	UID-based layout	Hash-based layout
XML
YAML
JSON
JSON5
TOML
INI

grouped-by-tag

All nested elements with the same tag go into one file per tag. Leaf content stays in the base file named after the original XML.

Best for fewer files and quick inspection.

Example layouts

Format	Layout
XML
YAML
JSON
JSON5
TOML
INI

---

Reassembling

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 that contains the disassembled files (e.g. HR_Admin/).
fileExtension	Suffix for the rebuilt XML file (e.g. permissionset-meta.xml). Default: .xml.
postPurge	Remove disassembled files after a successful reassembly (default: false).

---

Ignore file

Exclude files or directories from disassembly using an ignore file (default: .xmldisassemblerignore). Syntax matches node-ignore (similar to .gitignore).

Example:

# Skip these paths
**/secret.xml
**/generated/

---

Logging

Logging uses log4js. By default, logs go to disassemble.log at error level.

import { setLogLevel } from "xml-disassembler";

setLogLevel("debug"); // Verbose logging

---

XML parser

Parsing is done with fast-xml-parser, with support for:

• CDATA – "![CDATA["
• Comments – "!---"
• Attributes – "@__**"

---

Use case

For a Salesforce CLI integration example, see sf-decomposer.

---

Contributing

See CONTRIBUTING.md for code style, PR process, and coverage expectations.

---

License

This project is based on a template by Allan Oricil; the original template code is under the ISC license. The xml-disassembler code is under the MIT license.