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.