xml-disassembler 1.10.7 → 1.10.8

package/CHANGELOG.md

@@ -5,6 +5,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.10.8](https://github.com/mcarvin8/xml-disassembler/compare/v1.10.7...v1.10.8) (2025-05-17)
+
+
+### Bug Fixes
+
+* assert non-null on root element and remove default declaration ([9bd9fbd](https://github.com/mcarvin8/xml-disassembler/commit/9bd9fbd2b4d9afa94bab3c851c9555cecaab9726))
+
 ## [1.10.7](https://github.com/mcarvin8/xml-disassembler/compare/v1.10.6...v1.10.7) (2025-05-14)
 
 

package/README.md

@@ -2,22 +2,23 @@
 
 [![NPM](https://img.shields.io/npm/v/xml-disassembler.svg?label=xml-disassembler)](https://www.npmjs.com/package/xml-disassembler) [![Downloads/week](https://img.shields.io/npm/dw/xml-disassembler.svg)](https://npmjs.org/package/xml-disassembler)
 
-Disassemble XML files into smaller, more manageable files (XML/INI/JSON/JSON5/TOML/YAML) and reassemble the XML when needed.
+Disassemble large XML files into smaller, modular files in formats like XML, INI, JSON, JSON5, TOML, or YAML—then reassemble them as needed.
 
-This tool simplifies version control, improves diff readability, and streamlines collaboration when dealing with large XML files.
+Designed for improved version control, cleaner diffs, and easier team collaboration when dealing with complex XML structures.
 
 ---
 
-## 🚀 Features
+## Features
 
-- **Disassemble XML Files** – Break down XML files into structured directories.
-- **Reassemble XML Files** – Recreate the original XML structure from disassembled parts.
-  > **NOTE**: The `xml-disassembler` aims to reassemble the original XML 100% element-wise, however, the element sorting will vary. The reassembler will sort elements based on how they are sorted in the disassembled directories. "toml" format sorting varies compared to the other formats.
-- **Multiple Disassembly Strategies** – Provides 2 strategies to disassemble an XML file.
-- **Ignore Files** – Specify XML files to exclude from disassembly.
-- **Logging** – Enable detailed debugging logs.
-- **Integrations** – Works with tools like Salesforce CLI
-- **Multiple Formats** - The disassembled file format can be XML, INI, JSON, JSON5, TOML, or YAML based on preference. The reassembler will reassemble the original XML structure from these formats.
+- **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 -->
 <details>
@@ -38,12 +39,15 @@ This tool simplifies version control, improves diff readability, and streamlines
 - [Template](#template)
 </details>
 
+---
+
 ## 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.
+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.
 
-Instead of relying on complex XML diff algorithms, `xml-disassembler` provides a simple and accessible solution by splitting XML files into structured directories.
+No need for complex diffing tools—just structured directories with format-flexible files.
+
+---
 
 ## Install
 
@@ -53,25 +57,11 @@ Install the package using NPM:
 npm install xml-disassembler
 ```
 
-## Disassembling Files
+---
 
-Disassemble a single XML file or multiple XML files within a directory into smaller files (XML/INI/JSON/JSON5/TOML/YAML).
+## Disassembling Files
 
 ```typescript
-/* 
-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.
-- format:           File format for the disassembled files ("xml", "ini", "json", "json5", "toml", "yaml")
-                    Defaults to "xml" if the format isn't supported or provided.
-- strategy:         Disassemble strategy ("unique-id" or "grouped-by-tag")
-                    Defaults to "unique-id" if strategy isn't supported or provided.
-*/
 import { DisassembleXMLFileHandler } from "xml-disassembler";
 
 const handler = new DisassembleXMLFileHandler();
@@ -87,25 +77,31 @@ await handler.disassemble({
 });
 ```
 
-## Disassembly Strategies
+| 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                        |
+| `postPurge`        | Delete the original XML after disassembly                                |
+| `ignorePath`       | Path to the ignore file                                                  |
+| `format`           | Output format: `xml`, `ini`, `json`, `json5`, `toml`, `yaml`             |
+| `strategy`         | Disassembly strategy: `unique-id` or `grouped-by-tag`                    |
 
-`xml-disassembler` supports two disassembly strategies to suit different use cases for nested elements. You can choose a strategy by setting the strategy option when calling disassemble().
+---
+
+## Disassembly Strategies
 
 ### unique-id (default)
 
 > This is the strategy all previous versions of the `xml-disassembler` follow.
 
-Disassembles each nested element into its own file under sub-directories.
-
-File names are generated using one or more unique identifier elements (uniqueIdElements) or fallback to a SHA-256 hash.
-
-Leaf elements remain grouped in a file named after the original XML.
+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 maximum diff granularity and precision in version control.
+> Best for detailed diffs and granular version control.
 
-**Disassembled Directory Samples for Unique IDs**
+**Example Outputs**
 
-| Format    | Sample Directory - UIDs                                                                                                       | Sample Directory - SHA-256 Hashes                                                                                                                   |
+| Format    | UID Example                                                                                                       | Hash Example                                                                                                                   |
 | --------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
 | **XML**   | ![XML UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled.png)<br>         | ![XML Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes.png)<br>         |
 | **YAML**  | ![YAML UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-yaml.png)<br>   | ![YAML Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-yaml.png)<br>   |
@@ -116,15 +112,13 @@ Best for maximum diff granularity and precision in version control.
 
 ### grouped-by-tag
 
-Groups all nested elements by tag name into a single file (e.g., all `<fieldPermissions>` into `fieldPermissions.xml`).
+Groups all nested elements by tag into a single file. Leaf elements still go into a base file named after the original XML.
 
-Leaf elements remain grouped in a file named after the original XML.
+> Best for fewer files and easier manual inspection.
 
-Useful for simplifying diff views and reducing file count in large projects.
+**Example Outputs**
 
-**Disassembled Directory Samples for Grouped by Tag**
-
-| Format    | Sample Directory                                                                                                            |
+| Format    | Grouped by Tag Example                                                                                                            |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | **XML**   | ![XML tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags.png)<br>         |
 | **YAML**  | ![YAML tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-yaml.png)<br>   |
@@ -133,18 +127,11 @@ Useful for simplifying diff views and reducing file count in large projects.
 | **TOML**  | ![TOML tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-toml.png)<br>   |
 | **INI**   | ![INI tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-ini.png)<br>     |
 
-## Reassembling Files
+---
 
-Reassemble a directory of disassembled files (XML/INI/JSON/JSON5/TOML/YAML) into a single XML file.
+## Reassembling Files
 
 ```typescript
-/* 
-FLAGS
-- filePath:        Relative path to the disassembled 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();
@@ -155,15 +142,27 @@ await handler.reassemble({
 });
 ```
 
+| 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    |
+
+---
+
 ## Use Case
 
 See [`sf-decomposer`](https://github.com/mcarvin8/sf-decomposer) for a Salesforce CLI use case.
 
+---
+
 ## Ignore File
 
 Create an ignore file (`.xmldisassemblerignore` by default) to exclude XMLs from disassembly.
 
-- uses [`node-ignore`](https://github.com/kaelzhang/node-ignore) (follows [.gitignore spec 2.22.1](https://git-scm.com/docs/gitignore))
+> uses [`node-ignore`](https://github.com/kaelzhang/node-ignore) (follows [.gitignore spec 2.22.1](https://git-scm.com/docs/gitignore))
+
+---
 
 ## XML Parser
 
@@ -173,32 +172,26 @@ Uses [`fast-xml-parser`](https://github.com/NaturalIntelligence/fast-xml-parser)
 - Comments: `"!---"`
 - Attributes: `"@__**"`
 
-## Logging
-
-Instead of printing to the terminal, the disassembler uses [`log4js`](https://github.com/log4js-node/log4js-node) 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.
-```
+## Logging
 
-Enable debug logs using the `setLogLevel` function:
+Logging uses [`log4js`](https://github.com/log4js-node/log4js-node). Logs are written to `disassemble.log`.
 
 ```typescript
-import {
-  DisassembleXMLFileHandler,
-  ReassembleXMLFileHandler,
-  setLogLevel,
-} from "xml-disassembler";
+import { setLogLevel } from "xml-disassembler";
 
-setLogLevel("debug");
+setLogLevel("debug"); // Enables verbose logging
 ```
 
+---
+
 ## Contributing
 
 Contributions are welcome! See [Contributing](https://github.com/mcarvin8/xml-disassembler/blob/main/CONTRIBUTING.md).
 
+---
+
 ## Template
 
 This project was created from a template by [Allan Oricil](https://github.com/AllanOricil).