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