xml-disassembler 1.11.4 → 1.11.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/CONTRIBUTING.md +41 -17
- package/README.md +121 -100
- package/disassemble.log +452 -452
- package/dist/index.cjs.map +1 -1
- package/dist/index.min.cjs.map +1 -1
- package/dist/index.min.mjs.map +1 -1
- package/dist/index.min.umd.js.map +1 -1
- package/dist/index.mjs.map +1 -1
- package/dist/index.umd.js.map +1 -1
- package/package.json +6 -6
- /package/{samples/array-of-leafs → fixtures/array-of-leaves}/Dreamhouse.app-meta.xml +0 -0
- /package/{samples → fixtures}/attributes/notes.xml +0 -0
- /package/{samples → fixtures}/cdata/VidLand_US.marketingappextension-meta.xml +0 -0
- /package/{samples → fixtures}/comments/Numbers-fr.globalValueSetTranslation-meta.xml +0 -0
- /package/{samples → fixtures}/deeply-nested-unique-id-element/Get_Info.flow-meta.xml +0 -0
- /package/{samples → fixtures}/general/HR_Admin.permissionset-meta.xml +0 -0
- /package/{samples → fixtures}/ignore/HR_Admin.permissionset-meta.xml +0 -0
- /package/{samples → fixtures}/no-namespace/HR_Admin.permissionset-meta.xml +0 -0
- /package/{samples → fixtures}/no-nested-elements/HR_Admin.xml +0 -0
- /package/{samples → fixtures}/no-root-element/Assessment_Bot/Assessment_Bot.bot-meta.xml +0 -0
- /package/{samples → fixtures}/no-root-element/Assessment_Bot/botMlDomain/419e0199.botMlDomain-meta.xml +0 -0
- /package/{samples → fixtures}/no-root-element/Assessment_Bot.bot-meta.xml +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,13 @@
|
|
|
5
5
|
|
|
6
6
|
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.
|
|
7
7
|
|
|
8
|
+
## [1.11.5](https://github.com/mcarvin8/xml-disassembler/compare/v1.11.4...v1.11.5) (2026-02-04)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
* **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))
|
|
14
|
+
|
|
8
15
|
## [1.11.4](https://github.com/mcarvin8/xml-disassembler/compare/v1.11.3...v1.11.4) (2026-01-02)
|
|
9
16
|
|
|
10
17
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -1,30 +1,54 @@
|
|
|
1
|
-
# Contributing
|
|
1
|
+
# Contributing to xml-disassembler
|
|
2
2
|
|
|
3
|
-
Contributions are welcome
|
|
3
|
+
Contributions are welcome. This guide covers how to set up the project, run checks, and submit changes.
|
|
4
4
|
|
|
5
5
|
## Requirements
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
7
|
+
- **Node.js** ≥ 20
|
|
8
|
+
- **pnpm** ≥ 9
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Setup
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
1. **Fork and clone**
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Fork the repo on GitHub, then clone your fork:
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
```bash
|
|
17
|
+
git clone https://github.com/mcarvin8/xml-disassembler.git
|
|
18
|
+
cd xml-disassembler
|
|
19
|
+
```
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
pnpm install
|
|
20
|
-
```
|
|
21
|
+
2. **Install dependencies**
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
```bash
|
|
24
|
+
pnpm install
|
|
25
|
+
```
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
## Development workflow
|
|
25
28
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
+
1. Create a branch for your change.
|
|
30
|
+
2. Make your changes.
|
|
31
|
+
3. Run tests and lint (see below).
|
|
32
|
+
4. Commit. Pre-commit hooks will run Prettier via lint-staged.
|
|
33
|
+
5. Push and open a pull request.
|
|
29
34
|
|
|
30
|
-
|
|
35
|
+
## Scripts
|
|
36
|
+
|
|
37
|
+
| Command | Description |
|
|
38
|
+
| ---------------- | -------------------------- |
|
|
39
|
+
| `pnpm test` | Run Jest with coverage |
|
|
40
|
+
| `pnpm run lint` | Run ESLint |
|
|
41
|
+
| `pnpm format` | Format code with Prettier |
|
|
42
|
+
| `pnpm run build` | Build the library (Rollup) |
|
|
43
|
+
|
|
44
|
+
## Code quality
|
|
45
|
+
|
|
46
|
+
- **Tests** – New or changed behavior should have tests. The project aims for **≥ 90% code coverage**; keep coverage at or above that.
|
|
47
|
+
- **Linting** – Code must pass `pnpm run lint` (ESLint).
|
|
48
|
+
- **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.
|
|
49
|
+
|
|
50
|
+
## Submitting changes
|
|
51
|
+
|
|
52
|
+
1. **Pull request** – Open a PR against `main`. Describe what changed and why.
|
|
53
|
+
2. **Scope** – Prefer one logical change per PR (one fix or one feature).
|
|
54
|
+
3. **Checks** – Ensure CI passes (tests and lint). Run `pnpm test` and `pnpm run lint` locally before pushing.
|
package/README.md
CHANGED
|
@@ -1,69 +1,88 @@
|
|
|
1
|
-
#
|
|
1
|
+
# xml-disassembler
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/xml-disassembler)
|
|
4
4
|
[](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/LICENSE.md)
|
|
5
5
|
[](https://npmjs.org/package/xml-disassembler)
|
|
6
|
-
[](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
|
|
6
|
+
[](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
|
|
7
|
+
[](https://qlty.sh/gh/mcarvin8/projects/xml-disassembler)
|
|
7
8
|
[](https://snyk.io//test/github/mcarvin8/xml-disassembler?targetFile=package.json)
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
Split large XML files into smaller, version-control–friendly pieces—then reassemble them when needed. Output as XML, INI, JSON, JSON5, TOML, or YAML.
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
Useful for cleaner diffs, easier collaboration, and workflows like Salesforce metadata.
|
|
13
|
+
|
|
14
|
+
> **Rust implementation:** For a native, high-performance alternative, see [xml-disassembler-rust](https://github.com/mcarvin8/xml-disassembler-rust).
|
|
12
15
|
|
|
13
16
|
---
|
|
14
17
|
|
|
15
|
-
##
|
|
18
|
+
## Table of contents
|
|
16
19
|
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
20
|
+
- [Quick start](#quick-start)
|
|
21
|
+
- [Features](#features)
|
|
22
|
+
- [Install](#install)
|
|
23
|
+
- [Disassembling](#disassembling)
|
|
24
|
+
- [Disassembly strategies](#disassembly-strategies)
|
|
25
|
+
- [Reassembling](#reassembling)
|
|
26
|
+
- [Ignore file](#ignore-file)
|
|
27
|
+
- [Logging](#logging)
|
|
28
|
+
- [XML parser](#xml-parser)
|
|
29
|
+
- [Use case](#use-case)
|
|
30
|
+
- [Development](#development)
|
|
31
|
+
- [License](#license)
|
|
24
32
|
|
|
25
|
-
|
|
33
|
+
---
|
|
26
34
|
|
|
27
|
-
|
|
28
|
-
<details>
|
|
29
|
-
<summary>Table of Contents</summary>
|
|
35
|
+
## Quick start
|
|
30
36
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
37
|
+
```typescript
|
|
38
|
+
import {
|
|
39
|
+
DisassembleXMLFileHandler,
|
|
40
|
+
ReassembleXMLFileHandler,
|
|
41
|
+
} from "xml-disassembler";
|
|
42
|
+
|
|
43
|
+
// Disassemble: one XML → many small files
|
|
44
|
+
const disassemble = new DisassembleXMLFileHandler();
|
|
45
|
+
await disassemble.disassemble({
|
|
46
|
+
filePath: "path/to/YourFile.permissionset-meta.xml",
|
|
47
|
+
uniqueIdElements:
|
|
48
|
+
"application,apexClass,name,flow,object,recordType,tab,field",
|
|
49
|
+
format: "json",
|
|
50
|
+
strategy: "unique-id",
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// Reassemble: many small files → one XML
|
|
54
|
+
const reassemble = new ReassembleXMLFileHandler();
|
|
55
|
+
await reassemble.reassemble({
|
|
56
|
+
filePath: "path/to/YourFile",
|
|
57
|
+
fileExtension: "permissionset-meta.xml",
|
|
58
|
+
});
|
|
59
|
+
```
|
|
45
60
|
|
|
46
61
|
---
|
|
47
62
|
|
|
48
|
-
##
|
|
63
|
+
## Features
|
|
49
64
|
|
|
50
|
-
|
|
65
|
+
- **Disassemble** – Break XML into smaller components (by unique ID or by tag).
|
|
66
|
+
- **Reassemble** – Rebuild the original XML from disassembled output.
|
|
67
|
+
- **Multiple formats** – Output (and reassemble from) XML, INI, JSON, JSON5, TOML, or YAML.
|
|
68
|
+
- **Strategies** – `unique-id` (one file per nested element) or `grouped-by-tag` (one file per tag).
|
|
69
|
+
- **Ignore rules** – Exclude paths via a `.xmldisassemblerignore` file (same style as `.gitignore`).
|
|
70
|
+
- **Logging** – Configurable logging via `log4js` (writes to `disassemble.log` by default).
|
|
71
|
+
- **Salesforce-friendly** – Fits metadata and similar XML-heavy workflows.
|
|
51
72
|
|
|
52
|
-
|
|
73
|
+
Reassembly preserves element content and structure; element order may differ (especially with TOML).
|
|
53
74
|
|
|
54
75
|
---
|
|
55
76
|
|
|
56
77
|
## Install
|
|
57
78
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
```
|
|
79
|
+
```bash
|
|
61
80
|
npm install xml-disassembler
|
|
62
81
|
```
|
|
63
82
|
|
|
64
83
|
---
|
|
65
84
|
|
|
66
|
-
## Disassembling
|
|
85
|
+
## Disassembling
|
|
67
86
|
|
|
68
87
|
```typescript
|
|
69
88
|
import { DisassembleXMLFileHandler } from "xml-disassembler";
|
|
@@ -81,59 +100,57 @@ await handler.disassemble({
|
|
|
81
100
|
});
|
|
82
101
|
```
|
|
83
102
|
|
|
84
|
-
| Option | Description
|
|
85
|
-
| ------------------ |
|
|
86
|
-
| `filePath` | Path to the XML file or directory
|
|
87
|
-
| `uniqueIdElements` | Comma-separated
|
|
88
|
-
| `prePurge` |
|
|
89
|
-
| `postPurge` |
|
|
90
|
-
| `ignorePath` | Path to the ignore file (default `.xmldisassemblerignore`)
|
|
91
|
-
| `format` | Output format: `xml`, `ini`, `json`, `json5`, `toml`, `yaml
|
|
92
|
-
| `strategy` |
|
|
103
|
+
| Option | Description |
|
|
104
|
+
| ------------------ | --------------------------------------------------------------------------- |
|
|
105
|
+
| `filePath` | Path to the XML file or directory to disassemble. |
|
|
106
|
+
| `uniqueIdElements` | Comma-separated element names used to derive filenames for nested elements. |
|
|
107
|
+
| `prePurge` | Remove existing disassembly output before running (default: `false`). |
|
|
108
|
+
| `postPurge` | Remove the source XML after disassembly (default: `false`). |
|
|
109
|
+
| `ignorePath` | Path to the ignore file (default: `.xmldisassemblerignore`). |
|
|
110
|
+
| `format` | Output format: `xml`, `ini`, `json`, `json5`, `toml`, `yaml`. |
|
|
111
|
+
| `strategy` | `unique-id` or `grouped-by-tag`. |
|
|
93
112
|
|
|
94
113
|
---
|
|
95
114
|
|
|
96
|
-
## Disassembly
|
|
115
|
+
## Disassembly strategies
|
|
97
116
|
|
|
98
117
|
### unique-id (default)
|
|
99
118
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
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.
|
|
119
|
+
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.
|
|
103
120
|
|
|
104
|
-
|
|
121
|
+
Best for fine-grained diffs and version control.
|
|
105
122
|
|
|
106
|
-
**Example
|
|
123
|
+
**Example layouts**
|
|
107
124
|
|
|
108
|
-
| Format | UID
|
|
109
|
-
| --------- |
|
|
110
|
-
| **XML** | 
|
|
111
|
-
| **YAML** | 
|
|
112
|
-
| **JSON** | 
|
|
113
|
-
| **JSON5** | 
|
|
114
|
-
| **TOML** | 
|
|
115
|
-
| **INI** | 
|
|
125
|
+
| Format | UID-based layout | Hash-based layout |
|
|
126
|
+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| **XML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes.png) |
|
|
128
|
+
| **YAML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-yaml.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-yaml.png) |
|
|
129
|
+
| **JSON** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json.png) |
|
|
130
|
+
| **JSON5** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-json5.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-json5.png) |
|
|
131
|
+
| **TOML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-toml.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-toml.png) |
|
|
132
|
+
| **INI** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-ini.png) | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-hashes-ini.png) |
|
|
116
133
|
|
|
117
134
|
### grouped-by-tag
|
|
118
135
|
|
|
119
|
-
|
|
136
|
+
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.
|
|
120
137
|
|
|
121
|
-
|
|
138
|
+
Best for fewer files and quick inspection.
|
|
122
139
|
|
|
123
|
-
**Example
|
|
140
|
+
**Example layouts**
|
|
124
141
|
|
|
125
|
-
| Format |
|
|
126
|
-
| --------- |
|
|
127
|
-
| **XML** | 
|
|
128
|
-
| **YAML** | 
|
|
129
|
-
| **JSON** | 
|
|
130
|
-
| **JSON5** | 
|
|
131
|
-
| **TOML** | 
|
|
132
|
-
| **INI** | 
|
|
142
|
+
| Format | Layout |
|
|
143
|
+
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
144
|
+
| **XML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags.png) |
|
|
145
|
+
| **YAML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-yaml.png) |
|
|
146
|
+
| **JSON** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json.png) |
|
|
147
|
+
| **JSON5** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-json5.png) |
|
|
148
|
+
| **TOML** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-toml.png) |
|
|
149
|
+
| **INI** | [](https://raw.githubusercontent.com/mcarvin8/xml-disassembler/main/.github/images/disassembled-tags-ini.png) |
|
|
133
150
|
|
|
134
151
|
---
|
|
135
152
|
|
|
136
|
-
## Reassembling
|
|
153
|
+
## Reassembling
|
|
137
154
|
|
|
138
155
|
```typescript
|
|
139
156
|
import { ReassembleXMLFileHandler } from "xml-disassembler";
|
|
@@ -146,58 +163,62 @@ await handler.reassemble({
|
|
|
146
163
|
});
|
|
147
164
|
```
|
|
148
165
|
|
|
149
|
-
| Option | Description
|
|
150
|
-
| --------------- |
|
|
151
|
-
| `filePath` | Directory
|
|
152
|
-
| `fileExtension` |
|
|
153
|
-
| `postPurge` |
|
|
166
|
+
| Option | Description |
|
|
167
|
+
| --------------- | --------------------------------------------------------------------------------- |
|
|
168
|
+
| `filePath` | Directory that contains the disassembled files (e.g. `HR_Admin/`). |
|
|
169
|
+
| `fileExtension` | Suffix for the rebuilt XML file (e.g. `permissionset-meta.xml`). Default: `.xml`. |
|
|
170
|
+
| `postPurge` | Remove disassembled files after a successful reassembly (default: `false`). |
|
|
154
171
|
|
|
155
172
|
---
|
|
156
173
|
|
|
157
|
-
##
|
|
174
|
+
## Ignore file
|
|
175
|
+
|
|
176
|
+
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`).
|
|
158
177
|
|
|
159
|
-
|
|
178
|
+
Example:
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
# Skip these paths
|
|
182
|
+
**/secret.xml
|
|
183
|
+
**/generated/
|
|
184
|
+
```
|
|
160
185
|
|
|
161
186
|
---
|
|
162
187
|
|
|
163
|
-
##
|
|
188
|
+
## Logging
|
|
189
|
+
|
|
190
|
+
Logging uses [log4js](https://github.com/log4js-node/log4js-node). By default, logs go to `disassemble.log` at `error` level.
|
|
164
191
|
|
|
165
|
-
|
|
192
|
+
```typescript
|
|
193
|
+
import { setLogLevel } from "xml-disassembler";
|
|
166
194
|
|
|
167
|
-
|
|
195
|
+
setLogLevel("debug"); // Verbose logging
|
|
196
|
+
```
|
|
168
197
|
|
|
169
198
|
---
|
|
170
199
|
|
|
171
|
-
## XML
|
|
200
|
+
## XML parser
|
|
172
201
|
|
|
173
|
-
|
|
202
|
+
Parsing is done with [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser), with support for:
|
|
174
203
|
|
|
175
|
-
-
|
|
176
|
-
- Comments
|
|
177
|
-
- Attributes
|
|
204
|
+
- **CDATA** – `".
|
|
190
213
|
|
|
191
214
|
---
|
|
192
215
|
|
|
193
216
|
## Contributing
|
|
194
217
|
|
|
195
|
-
|
|
218
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, PR process, and coverage expectations.
|
|
196
219
|
|
|
197
220
|
---
|
|
198
221
|
|
|
199
|
-
##
|
|
200
|
-
|
|
201
|
-
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).
|
|
222
|
+
## License
|
|
202
223
|
|
|
203
|
-
|
|
224
|
+
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).
|