xml-disassembler

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

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

Native Rust: Core logic is in the xml-disassembler crate; this package provides Node.js bindings via Neon.

Table of contents

• Quick start
• Features
• Install
• Disassembling
• Disassembly strategies
  • Split tags (splitTags)
• Multi-level disassembly
• Reassembling
• Ignore file
• Logging
• Implementation
• Use case
• Contributing
• 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, JSON, JSON5, 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 – Uses env_logger; set RUST_LOG for verbosity (e.g. RUST_LOG=debug).
• Salesforce-friendly – Fits metadata and similar XML-heavy workflows.

Reassembly preserves element content and structure.

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. | | multiLevel | Optional. Multi-level spec: file_pattern:root_to_strip:unique_id_elements. See Multi-level disassembly. | | splitTags | Optional. With strategy: "grouped-by-tag": split or group nested tags. See Split tags. | | 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, json, json5, 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 | | |

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.

await handler.disassemble({
  filePath: "my.xml",
  strategy: "grouped-by-tag",
  format: "yaml",
});

Reassembly preserves element content and structure.

Split tags (splitTags)

With strategy: "grouped-by-tag", you can optionally split or group specific nested tags into subdirectories instead of a single file per tag. Useful for permission sets and similar metadata: e.g. one file per objectPermissions under objectPermissions/, and fieldPermissions grouped by object under fieldPermissions/.

Spec: Comma-separated rules. Each rule is tag:mode:field or tag:path:mode:field (path defaults to tag). mode is split (one file per array item, filename from field) or group (group array items by field, one file per group).

// Permission set: objectPermissions → one file per object; fieldPermissions → one file per field value
await handler.disassemble({
  filePath: "fixtures/split-tags/HR_Admin.permissionset-meta.xml",
  strategy: "grouped-by-tag",
  splitTags: "objectPermissions:split:object,fieldPermissions:group:field",
  format: "xml",
});

Creates HR_Admin/ with e.g. objectPermissions/Job_Request__c.objectPermissions-meta.xml, objectPermissions/Account.objectPermissions-meta.xml, fieldPermissions/<fieldValue>.fieldPermissions-meta.xml, plus the main HR_Admin.permissionset-meta.xml with the rest. Reassembly requires no changes: the existing reassemble command merges subdirs and files back into one XML.

Example layouts

| Format | Layout | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | XML | | | YAML | | | JSON | | | JSON5 | |

Multi-level disassembly

For XML with nested repeatable blocks (e.g. programProcesses inside LoyaltyProgramSetup), you can disassemble in one call and reassemble in one call. Pass a multi-level spec so the tool further splits matching files and later merges them in the right order.

Spec format: file_pattern:root_to_strip:unique_id_elements
Example: programProcesses:programProcesses:parameterName,ruleName — for files whose name contains programProcesses, strip the programProcesses root and disassemble by parameterName and ruleName.

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

const disassemble = new DisassembleXMLFileHandler();
await disassemble.disassemble({
  filePath: "Cloud_Kicks_Inner_Circle.loyaltyProgramSetup-meta.xml",
  uniqueIdElements: "fullName,name,processName",
  multiLevel: "programProcesses:programProcesses:parameterName,ruleName",
  postPurge: true,
});

const reassemble = new ReassembleXMLFileHandler();
await reassemble.reassemble({
  filePath: "Cloud_Kicks_Inner_Circle",
  fileExtension: "loyaltyProgramSetup-meta.xml",
  postPurge: true,
});

| Option | Description | | ------------ | --------------------------------------------------------------------------- | | multiLevel | Optional. file_pattern:root_to_strip:unique_id_elements for nested split. |

A .multi_level.json config is written in the disassembly root so reassembly knows how to merge inner levels first, then the top level. No extra options are needed for reassembly.

Caveat: Multi-level reassembly removes disassembled directories after reassembling each level, even when you do not pass postPurge. This is required so the next level can merge the reassembled XML files. Use version control (e.g. Git) to recover the tree if needed, or run reassembly only in a pipeline where these changes can be discarded.

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 is the same as .gitignore (e.g. patterns, **/, negation).

Example:

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

Logging

The Rust crate uses env_logger. Set RUST_LOG to control verbosity (e.g. RUST_LOG=debug).

Implementation

The core logic is implemented in Rust (xml-disassembler) and exposed to Node.js via Neon. Building from source requires Rust and Node.js.

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.