xml-disassembler 1.11.4 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@
 
 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.
 
+## [2.0.0](https://github.com/mcarvin8/xml-disassembler/compare/v1.11.5...v2.0.0) (2026-02-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* 
+
+### Features
+
+* embed Rust xml-disassembler via Neon addon ([#191](https://github.com/mcarvin8/xml-disassembler/issues/191)) ([af991a8](https://github.com/mcarvin8/xml-disassembler/commit/af991a84402bffad17b7832d72d56019f425d957))
+
+## [1.11.5](https://github.com/mcarvin8/xml-disassembler/compare/v1.11.4...v1.11.5) (2026-02-04)
+
+
+### Bug Fixes
+
+* **deps:** bump fast-xml-parser from 5.3.3 to 5.3.4 ([#185](https://github.com/mcarvin8/xml-disassembler/issues/185)) ([d038294](https://github.com/mcarvin8/xml-disassembler/commit/d03829412f9128b589f0da1b83458037db7d15bb))
+
 ## [1.11.4](https://github.com/mcarvin8/xml-disassembler/compare/v1.11.3...v1.11.4) (2026-01-02)
 
 

package/CONTRIBUTING.md

@@ -1,30 +1,54 @@
-# Contributing
+# Contributing to xml-disassembler
 
-Contributions are welcome! If you would like to contribute, please fork the repository, make your changes, and submit a pull request.
+Contributions are welcome. This guide covers how to set up the project, run checks, and submit changes.
 
 ## Requirements
 
-- `pnpm >= 9`
-- `node >= 20`
+- **Node.js** ≥ 20
+- **pnpm** ≥ 9
 
-## Installation
+## Setup
 
-### 1) Fork the repository
+1. **Fork and clone**
 
-### 2) Install Dependencies
+   Fork the repo on GitHub, then clone your fork:
 
-This will install all the tools needed to contribute
+   ```bash
+   git clone https://github.com/mcarvin8/xml-disassembler.git
+   cd xml-disassembler
+   ```
 
-```bash
-pnpm install
-```
+2. **Install dependencies**
 
-## Testing
+   ```bash
+   pnpm install
+   ```
 
-When developing, run the provided tests for new additions.
+## Development workflow
 
-```bash
-pnpm test
-```
+1. Create a branch for your change.
+2. Make your changes.
+3. Run tests and lint (see below).
+4. Commit. Pre-commit hooks will run Prettier via lint-staged.
+5. Push and open a pull request.
 
-All updates should meet the 90% code coverage threshold.
+## Scripts
+
+| Command          | Description                |
+| ---------------- | -------------------------- |
+| `pnpm test`      | Run Jest with coverage     |
+| `pnpm run lint`  | Run ESLint                 |
+| `pnpm format`    | Format code with Prettier  |
+| `pnpm run build` | Build the library (Rollup) |
+
+## Code quality
+
+- **Tests** – New or changed behavior should have tests. The project aims for **≥ 90% code coverage**; keep coverage at or above that.
+- **Linting** – Code must pass `pnpm run lint` (ESLint).
+- **Formatting** – Code is formatted with Prettier. Use `pnpm format` to fix formatting; the pre-commit hook also runs Prettier on staged files via lint-staged.
+
+## Submitting changes
+
+1. **Pull request** – Open a PR against `main`. Describe what changed and why.
+2. **Scope** – Prefer one logical change per PR (one fix or one feature).
+3. **Checks** – Ensure CI passes (tests and lint). Run `pnpm test` and `pnpm run lint` locally before pushing.

package/README.md

@@ -1,69 +1,88 @@
-# `xml-disassembler`
+# xml-disassembler
 
 [![NPM](https://img.shields.io/npm/v/xml-disassembler.svg?label=xml-disassembler)](https://www.npmjs.com/package/xml-disassembler)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/LICENSE.md)
 [![Downloads/week](https://img.shields.io/npm/dw/xml-disassembler.svg)](https://npmjs.org/package/xml-disassembler)
-[![Maintainability](https://qlty.sh/badges/e226ad95-4b8d-484a-9484-25862941262d/maintainability.svg)](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler) [![Code Coverage](https://qlty.sh/badges/e226ad95-4b8d-484a-9484-25862941262d/test_coverage.svg)](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
+[![Maintainability](https://qlty.sh/badges/e226ad95-4b8d-484a-9484-25862941262d/maintainability.svg)](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
+[![Code Coverage](https://qlty.sh/badges/e226ad95-4b8d-484a-9484-25862941262d/test_coverage.svg)](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
 [![Known Vulnerabilities](https://snyk.io//test/github/mcarvin8/xml-disassembler/badge.svg?targetFile=package.json)](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.
+Split large XML files into smaller, version-control–friendly pieces—then reassemble them when needed. Output as XML, JSON, JSON5, or YAML.
 
-Designed for improved version control, cleaner diffs, and easier team collaboration when dealing with complex XML structures.
+Useful for cleaner diffs, easier collaboration, and workflows like Salesforce metadata.
 
----
-
-## Features
+> **Native Rust:** Core logic is in the [xml-disassembler](https://crates.io/crates/xml-disassembler) crate; this package provides Node.js bindings via [Neon](https://neon-bindings.com).
 
-- **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>
-  <summary>Table of Contents</summary>
+## Table of contents
 
-- [Background](#background)
+- [Quick start](#quick-start)
+- [Features](#features)
 - [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)
+- [Disassembling](#disassembling)
+- [Disassembly strategies](#disassembly-strategies)
+- [Reassembling](#reassembling)
+- [Ignore file](#ignore-file)
 - [Logging](#logging)
+- [Implementation](#implementation)
+- [Use case](#use-case)
 - [Contributing](#contributing)
-- [Template & License](#template-&-license)
-</details>
+- [License](#license)
 
 ---
 
-## Background
+## Quick start
 
-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.
+```typescript
+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",
+});
 
-No need for complex diffing tools—just structured directories with format-flexible files.
+// Reassemble: many small files → one XML
+const reassemble = new ReassembleXMLFileHandler();
+await reassemble.reassemble({
+  filePath: "path/to/YourFile",
+  fileExtension: "permissionset-meta.xml",
+});
+```
 
 ---
 
-## Install
+## Features
 
-Install the package using NPM:
+- **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](https://docs.rs/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
+
+```bash
 npm install xml-disassembler
 ```
 
 ---
 
-## Disassembling Files
+## Disassembling
 
 ```typescript
 import { DisassembleXMLFileHandler } from "xml-disassembler";
@@ -81,59 +100,53 @@ await handler.disassemble({
 });
 ```
 
-| 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`                                  |
+| 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`, `json`, `json5`, `yaml`.                              |
+| `strategy`         | `unique-id` or `grouped-by-tag`.                                            |
 
 ---
 
-## Disassembly Strategies
+## Disassembly strategies
 
 ### unique-id (default)
 
-> This is the strategy all previous versions of the `xml-disassembler` follow.
+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.
 
-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 fine-grained diffs and version control.
 
-> Best for detailed diffs and granular version control.
+**Example layouts**
 
-**Example Outputs**
-
-| 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>   |
-| **JSON**  | ![JSON UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json.png)<br>   | ![JSON Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json.png)<br>   |
-| **JSON5** | ![JSON5 UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json5.png)<br> | ![JSON5 Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json5.png)<br> |
-| **TOML**  | ![TOML UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-toml.png)<br>   | ![TOML Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-toml.png)<br>   |
-| **INI**   | ![INI UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-ini.png)<br>     | ![INI Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-ini.png)<br>     |
+| Format    | UID-based layout                                                                                                                                                                                                               | Hash-based layout                                                                                                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **XML**   | [![XML UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled.png)               | [![XML Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes.png)               |
+| **YAML**  | [![YAML UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-yaml.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-yaml.png)    | [![YAML Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-yaml.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-yaml.png)    |
+| **JSON**  | [![JSON UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json.png)    | [![JSON Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json.png)    |
+| **JSON5** | [![JSON5 UID](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json5.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json5.png) | [![JSON5 Hash](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json5.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json5.png) |
 
 ### 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.
+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 easier manual inspection.
+Best for fewer files and quick inspection.
 
-**Example Outputs**
+**Example layouts**
 
-| 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>   |
-| **JSON**  | ![JSON tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json.png)<br>   |
-| **JSON5** | ![JSON5 tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json5.png)<br> |
-| **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>     |
+| Format    | Layout                                                                                                                                                                                                                                   |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **XML**   | [![XML tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags.png)               |
+| **YAML**  | [![YAML tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-yaml.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-yaml.png)    |
+| **JSON**  | [![JSON tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json.png)    |
+| **JSON5** | [![JSON5 tag](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json5.png)](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json5.png) |
 
 ---
 
-## Reassembling Files
+## Reassembling
 
 ```typescript
 import { ReassembleXMLFileHandler } from "xml-disassembler";
@@ -146,58 +159,52 @@ 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 (`true` or `false`, default `false`) |
+| 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`).       |
 
 ---
 
-## Use Case
+## Ignore file
 
-See [`sf-decomposer`](https://github.com/mcarvin8/sf-decomposer) for a Salesforce CLI use case.
+Exclude files or directories from disassembly using an ignore file (default: `.xmldisassemblerignore`). Syntax matches [node-ignore](https://github.com/kaelzhang/node-ignore) (similar to `.gitignore`).
 
----
+Example:
 
-## Ignore File
-
-Create an ignore file, similar to a `.gitignore`, to exclude XMLs from disassembly.
-
-> uses [`node-ignore`](https://github.com/kaelzhang/node-ignore)
+```
+# Skip these paths
+**/secret.xml
+**/generated/
+```
 
 ---
 
-## XML Parser
-
-Uses [`fast-xml-parser`](https://github.com/NaturalIntelligence/fast-xml-parser) with support for:
+## Logging
 
-- Character Data (CDATA): `"![CDATA["`
-- Comments: `"!---"`
-- Attributes: `"@__**"`
+The Rust crate uses [env_logger](https://docs.rs/env_logger). Set `RUST_LOG` to control verbosity (e.g. `RUST_LOG=debug`).
 
 ---
 
-## Logging
+## Implementation
 
-Logging uses [`log4js`](https://github.com/log4js-node/log4js-node). Logs are written to `disassemble.log`.
+The core logic is implemented in Rust ([xml-disassembler](https://crates.io/crates/xml-disassembler)) and exposed to Node.js via [Neon](https://neon-bindings.com). Building from source requires Rust and Node.js.
 
-```typescript
-import { setLogLevel } from "xml-disassembler";
+---
 
-setLogLevel("debug"); // Enables verbose logging
-```
+## Use case
+
+For a Salesforce CLI integration example, see [sf-decomposer](https://github.com/mcarvin8/sf-decomposer).
 
 ---
 
 ## Contributing
 
-Contributions are welcome! See [Contributing](https://github.com/mcarvin8/xml-disassembler/blob/main/CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, PR process, and coverage expectations.
 
 ---
 
-## 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).
+## License
 
-All contributions specific to the `xml-disassembler` is licensed under the [MIT license](https://github.com/mcarvin8/xml-disassembler/blob/main/LICENSE.md).
+This project is based on a template by [Allan Oricil](https://github.com/AllanOricil); the original template code is under the [ISC license](LICENSE.isc). The xml-disassembler code is under the [MIT license](LICENSE.md).