config-disassembler

Node.js bindings for the Rust config-disassembler crate via napi-rs.

Use it to disassemble large configuration files into smaller, version-control–friendly files and reassemble them later.

The Node bindings closely mirror the Rust crate APIs and behavior. For complete documentation and behavior details, see the Rust crate documentation.

---

Install

npm install config-disassembler

---

XML API Examples

Use this to disassemble a large XML into smaller files (XML, JSON, JSON5, YAML) and reassemble the XML.

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

const disassemble = new DisassembleXMLFileHandler();

/* Disassemble XML Options
* filePath = required. Path to the XML file or directory to disassemble.
* strategy = optional (default: unique-id). Disassembly strategy (unique-id or grouped-by-tag).
* uniqueIdElements = optional for unique-id strategy. Comma-separated element names used to derive filenames for nested elements.
* multiLevel = optional for unique-id strategy. One or more multi-level specs: file_pattern:root_to_strip:unique_id_elements. Pass a string (single rule) or a string[] for several rules; semicolon-separated strings are also accepted.
* splitTags = optional for grouped-by-tag strategy. split or group nested tags.
* prePurge = optional (default: false). Delete any pre-existing disassembled files before disassembly.
* postPurge = optional (default: false). Delete the XML file after successfully disassembling it.
* format = optional (default: xml). Output format: xml, json, json5, yaml.
* ignorePath = optional (default: .cdignore). Path to a .gitignore-like file to skip files while disassembling.
*/

// Disassemble using unique-ID strategy
disassemble.disassemble({
  filePath: "My.permissionset-meta.xml",
  uniqueIdElements:
    "application,apexClass,name,flow,object,recordType,tab,field",
  strategy: "unique-id",
  format: "json",
  prePurge: true,
  postPurge: true,
  ignorePath: ".cdignore",
});

// Or, disassemble using grouped-by-tag strategy
disassemble.disassemble({
  filePath: "My.permissionset-meta.xml",
  strategy: "grouped-by-tag",
  format: "json",
});

// Or, disassemble using grouped-by-tag strategy with split-tags
disassemble.disassemble({
  filePath: "My.permissionset-meta.xml",
  strategy: "grouped-by-tag",
  splitTags: "objectPermissions:split:object,fieldPermissions:group:field",
});

// Or, disassemble an XML over multiple-levels with unique-id strategy
disassemble.disassemble({
  filePath: "Cloud_Kicks_Inner_Circle.loyaltyProgramSetup-meta.xml",
  strategy: "unique-id",
  uniqueIdElements: "fullName,name,processName",
  multiLevel: "programProcesses:programProcesses:parameterName,ruleName",
  postPurge: true,
});

const reassemble = new ReassembleXMLFileHandler();

/* Reassemble XML Options
* filePath = required. Folder containing disassembled files to reassemble into 1 XML.
* fileExtension = optional (default: `.xml`). Set explicit file extension.
* postPurge = optional (default: false). Delete disassembled files after reassembly.
*/ 

reassemble.reassemble({
  filePath: "My",
  fileExtension: "permissionset-meta.xml",
  postPurge: true,
});

---

Value-Format API Examples

Use this for JSON, JSON5, JSONC, YAML, TOML, TOON, and INI configs.

import {
  DisassembleConfigFileHandler,
  ReassembleConfigFileHandler,
} from "config-disassembler";

// Disassemble config
const disassemble = new DisassembleConfigFileHandler();

const outputDir = disassemble.disassemble({
  input: "config.json",
  outputFormat: "yaml",
  uniqueId: "id",
});

// Reassemble config
const reassemble = new ReassembleConfigFileHandler();

reassemble.reassemble({
  inputDir: outputDir,
  output: "config.rebuilt.json",
  outputFormat: "json",
});

---

Supported Platforms

This package ships with prebuilt native binaries as platform-specific optional npm packages — your package manager installs only the one matching your os / cpu / libc:

Platform	Architectures
macOS	x64 (Intel), arm64 (Apple Silicon)
Linux	x64 (gnu + musl), arm64 (gnu + musl)
Windows	x64, arm64, ia32

If your platform or architecture isn't listed, please open an issue.

---

Use Case

For a use-case using the XML API, see sf-decomposer.

---

License

MIT