@aurahelper/package-generator/README.md

Aura Helper Package Generator Module to create Salesforce XML Package, to deploy, retrieve or delete elements on your Org. Support to create package from JSON File, Git Diffs or Mergin other packages.

# **Aura Helper Package Generator Module**

[![Version](https://img.shields.io/npm/v/@aurahelper/package-generator?logo=npm)](https://www.npmjs.com/package/@aurahelper/package-generator)
[![Total Downloads](https://img.shields.io/npm/dt/@aurahelper/package-generator?logo=npm)](https://www.npmjs.com/package/@aurahelper/package-generator)
[![Downloads/Month](https://img.shields.io/npm/dm/@aurahelper/package-generator?logo=npm)](https://www.npmjs.com/package/@aurahelper/package-generator)
[![Issues](https://img.shields.io/github/issues/jjlongoria/aura-helper-package-generator)](https://github.com/JJLongoria/aura-helper-package-generator/issues)
[![Known Vulnerabilities](https://snyk.io/test/github/JJLongoria/aura-helper-package-generator/badge.svg)](https://snyk.io/test/github/JJLongoria/aura-helper-package-generator)
[![Code Size](https://img.shields.io/github/languages/code-size/jjlongoria/aura-helper-package-generator)](https://github.com/JJLongoria/aura-helper-package-generator)
[![License](https://img.shields.io/github/license/jjlongoria/aura-helper-package-generator?logo=github)](https://github.com/JJLongoria/aura-helper-package-generator/blob/master/LICENSE)

Aura Helper Package Generator Module contains a powerfull class to create and merge package files to deploy, retrieve or delete metadata from your Salesforce's projects.

You can choose to merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file or merge all files into one package or destructive file.

Also you can create packages XML files from a JSON file (See [Metadata JSON Format](#metadata-file) section). Use Aura Helper Metadata Factory [@aurahelper/metadata-factory](https://github.com/JJLongoria/aura-helper-metadata-factory) to help to you to create the JSON file from a project in your computer ([@aurahelper/metadata-factory](https://github.com/JJLongoria/aura-helper-metadata-factory)) or download metadata using Aura Helper Connector [@ah/connetor](https://github.com/JJLongoria/aura-helper-connector) to download it

To handle the JSON file types better, you can use MetadataType, MetadataObject and MetadataItem classes from [@aurahelper/core](https://github.com/JJLongoria/aura-helper-core) > Types. Also you can use this classes to create your own JSON file and use the validateJSON() method to check if the file is correct.

Other **important and usefull** feature is the Ignore Metadata option. You can create an .ahignore.json file (see [Ignore File](#ignore-file) section) to ignore the specified metadata on the file and exclude from the package to avoid deploy, delete or retrieve the metadata files. This Feature is util in some use cases, like Custom Label values unique for every environment (like ids...), or to avoid deploy some user permissions, or when you creating autogenerated package (from git for example) and like to exclude some metadata automatically.

---

## *Table of Contents*

- [**PackageGenerator Class**](#packagegenerator-class)

- [**Ignore metadata from your package**](#ignore-metadata-from-your-package)

- [**Metadata JSON Format**](#metadata-json-format)
  
- [**Ignore File**](#ignore-file)

---

# [**PackageGenerator Class**](#packagegenerator-class)
Class to create and merge package files to deploy, retrieve or delete metadata from your Salesforce's projects.

Can merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file or merge all files into one package or destructive file.

The file names must contains at least the "package" word to identify the package XML files and destructiveChanges or destrutiveChangesPost to the destructive files. For example: package1.xml, destructiveChanges_uat.xml, destructiveChangesPost-v34...

You can choose a custom API Version to create the packages, if not specified API version, the package generator get the higher API version from each file types, that is, for package XML files, get the higher API of the Package XML files passed, and the same with other file types.

The setters methods are defined like a builder pattern to make it more usefull

### *Class Members*
- [**Fields**](#fields)

- [**Constructors**](#constructors)

- [**Methods**](#methods)

</br>

# [**Fields**](#fields)
The fields that start with _ are for internal use only (Does not modify this fields to a correct PackageGenerator work). To the rest of fields, setter methods are recommended instead modify fields.


### [**apiVersion**](#packagegenerator-fields-apiversion)
True to remove ignored elements from the result object, false only for unselect elements 
- `string` | `number`

### [**mergePackageFiles**](#packagegenerator-fields-mergepackagefiles)
true if want to merge the provided package files. If undefiend ot not has param, also set to true
- `boolean`

### [**mergeDestructives**](#packagegenerator-fields-mergedestructives)
true if want to merge the provided destructive files into one single file. If undefiend ot not has param, also set to true
- `boolean`

### [**isDestructive**](#packagegenerator-fields-isdestructive)
true if you want to merge all files into one destructive file (valid option to merge packages full). If undefiend ot not has param, also set to true
- `boolean`

### [**beforeDeploy**](#packagegenerator-fields-beforedeploy)
true if want to merge destructive files into before deploy destructive file when select mergeDestructives. If undefiend ot not has param, also set to true
- `boolean`

### [**explicit**](#packagegenerator-fields-explicit)
true if you want to put all metadata types explicit into the file, false to use wildcards when are all checked
- `boolean`

### [**ignoreFile**](#packagegenerator-fields-ignorefile)
path to the ignore file to ignore some metadata types from the packages
- `string`

### [**typesToIgnore**](#packagegenerator-fields-typestoignore)
List with the Metadata Type API Names to ignore. This parameter is used to ignore only the specified metadata (also must be in ignore file) and avoid ignore all metadata types specified on the file.
- `string[]`

</br>

# [**Constructors**](#constructors)

## [**constructor(apiVersion)**](#packagegenerator-class-constructors-construct)
Constructor to instance a new PackageGenerator object. All parameters are optional and you can use the setters methods to set the values when you want.

### **Parameters:**
  - **apiVersion**: Path to the ignore file
    - `string` | `number`

</br>

# [**Methods**](#packagegenerator-class-methods)

  - [**setApiVersion(apiVersion)**](#setapiversionapiversion)

    Method to Set the api version to create the packages

  - [**setMergePackagesFiles(mergePackageFiles)**](#setmergepackagesfilesmergepackagefiles)

    Method to set if merge package files

  - [**setMergeDestructives(mergeDestructives)**](#setmergedestructivesmergedestructives)

    Method to set if merge destructive files

  - [**setIsDestructive(isDestructive)**](#setisdestructiveisdestructive)

    Method to set if merge all package and XML destructive files into one destructive file

  - [**setBeforeDeploy(beforeDeploy)**](#setbeforedeploybeforedeploy)

    Method to set if the destructive file to create is before deploy, in otherwise create destructive files after deploy

  - [**setExplicit(explicit)**](#setexplicitexplicit)

    Method to set if put all elements explicit on the package XML or use wildcards when apply

  - [**setIgnoreFile(ignoreFile)**](#setignorefileignorefile)

    Method to set the path to the ignore file

  - [**setTypesToIgnore(typesToIgnore)**](#settypestoignoretypestoignore)

    Method to set the Metadata Types to ignore from package (Also must be exists on ignore file)

  - [**mergePackages(packageOrDestructiveFiles, outputFolder)**](#mergepackagespackageordestructivefiles-outputfolder)

    Method to merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file.

  - [**mergePackagesFull(packageOrDestructiveFiles, outputFolder)**](#mergepackagesfullpackageordestructivefiles-outputfolder)
  
    Method to merge all provided files into only one file. You can choose if merge all into a package.xml, destructiveChanges.xml or destructiveChangesPost.xml

  - [**getPackageContent(metadataOrPath, useIgnoreDestructive)**](#getpackagecontentmetadataorpath)

    Method to get the Package XML format content as String to the selected Metadata JSON file or Metadata JSON Object

  - [**createPackage(metadataOrPath, outputFolder)**](#createpackagemetadataorpath-outputfolder)

    Method to create a package XML file with the selected Metadata JSON file or Metadata JSON Object

  - [**createBeforeDeployDestructive(metadataOrPath, outputFolder)**](#createbeforedeploydestructivemetadataorpath-outputfolder)

    Method to create a before deploy destructive file with the selected Metadata JSON file or Metadata JSON Object

  - [**createAfterDeployDestructive(metadataOrPath, outputFolder)**](#createafterdeploydestructivemetadataorpath-outputfolder)

    Method to create an after deploy destructive file with the selected Metadata JSON file or Metadata JSON Object

  - [**validateJSON(metadataOrPath)**](#validatejsonmetadataorpath)

    Static Method to validate a Metadata JSON file or Metadata JSON Object format. If is not valid, throw several exceptions.
---

## [**setApiVersion(apiVersion)**](#setapiversionapiversion)
Method to Set the api version to create the packages

### **Parameters:**
  - **apiVersion**: Api version to create the package. If not provided use the latest api version of the provided files
    - `string` | `number`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set the api version**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setApiVersion('50');
    generator.setApiVersion('50.0');
    generator.setApiVersion(50);
    generator.setApiVersion(50.0);
```
---

## [**setMergePackagesFiles(mergePackageFiles)**](#setmergepackagesfilesmergepackagefiles)
Method to set if merge package files

### **Parameters:**
  - **mergePackageFiles**: true if want to merge the provided package files. If undefiend ot not has param, also set to true
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set if merge package files**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setMergePackagesFiles(true);
    generator.setMergePackagesFiles();  // Also set to true
```
---

## [**setMergeDestructives(mergeDestructives)**](#setmergedestructivesmergedestructives)
Method to set if merge destructive files

### **Parameters:**
  - **mergeDestructives**: true if want to merge the provided destructive files into one single file. If undefiend ot not has param, also set to true
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set if merge destructive files**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setMergeDestructives(true);
    generator.setMergeDestructives();  // Also set to true
```
---

## [**setIsDestructive(isDestructive)**](#setisdestructiveisdestructive)
Method to set if merge all package and XML destructive files into one destructive file

### **Parameters:**
  - **isDestructive**: true if you want to merge all files into one destructive
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set if merge all package and destructive files into one destructive**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setIsDestructive(true);
    generator.setIsDestructive();  // Also set to true
```
---

## [**setBeforeDeploy(beforeDeploy)**](#setbeforedeploybeforedeploy)
Method to set if the destructive file to create is before deploy, in otherwise create destructive files after deploy

### **Parameters:**
  - **beforeDeploy**: true if want to merge destructive files into before deploy destructive file when select mergeDestructives. If undefiend ot not has param, also set to true
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set if merge all package and destructive files into one destructive**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setBeforeDeploy(true);
    generator.setBeforeDeploy();  // Also set to true
```
---

## [**setExplicit(explicit)**](#setexplicitexplicit)
Method to set if put all elements explicit on the package XML or use wildcards when apply

### **Parameters:**
  - **explicit**: true if you want to put all metadata types explicit into the file, false to use wildcards when are all checked
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set explicit**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setExplicit(true);
    generator.setExplicit();  // Also set to true
```
---

## [**setIgnoreFile(ignoreFile)**](#setignorefileignorefile)
Method to set the path to the ignore file

### **Parameters:**
  - **ignoreFile**: path to the ignore file to ignore some metadata types from the packages
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set file to ignore Metadata Types**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setIgnoreFile('path/to/the/ignore/file.json');
```
---

## [**setTypesToIgnore(typesToIgnore)**](#settypestoignoretypestoignore)
Method to set the Metadata Types to ignore from package (Also must be exists on ignore file)

### **Parameters:**
  - **typesToIgnore**: List with the Metadata Type API Names to ignore. This parameter is used to ignore only the specified metadata (also must be in ignore file) and avoid ignore all metadata types specified on the file.
    - `boolean`

### **Return:**
Return the package generator instance
- `PackageGenerator`

### **Examples:**

**Set Metadata Types to ignore**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';

    const generator = new PackageGenerator();
    generator.setTypesToIgnore('CustomObject');
    generator.setTypesToIgnore(['CustomObject', 'CustomField']);
```
---
## [**mergePackages(packageOrDestructiveFiles, outputFolder)**](#mergepackagespackageordestructivefiles-outputfolder)
Method to merge several package xml files (including destructiveChanges.xml and destructiveChangesPost.xml files) to combine into one file of each type, combine all packages in one file and all detructives in another file.

### **Parameters:**
  - **packageOrDestructiveFiles**: File or list of files to merge (including package and destructive files in the same list)
    - `string` | `string[]`
  - **outputFolder**: Folder to save the created files
    - `string`

### **Return:**
Object with the merge result including the paths of the merged files
- `PackageGeneratorResult`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`DataNotFoundException`**: If not package or destructive files provided
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory

### **Examples:**
You have several options to merge package files: 

**Merge files by Type**

Merge all package XML file into one package XML file, merge all destructive changes pre deployment into one destructiveChanges XML and merge all destructive changes post deployment into one destructiveChangesPost XML.
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;

    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml
```
**Merge all destructive XML files post deployment**

Merge all package XML file into one package XML file and merge all destructive changes pre and post deployment into one destructiveChanges XML post deployment. 

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator();
    generator.setApiVersion('50.0').setMergeDestructives();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // undefined    (By default, create destructives after deploy)
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml
```
**Merge all destructive XML files pre deployment**

Merge all package XML file into one package XML file and merge all destructive changes pre and post deployment into one destructiveChanges XML pre deployment.

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setMergeDestructives().beforeDeploy();
    const result = generator.mergePackages(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // undefined
```
---
## [**mergePackagesFull(packageOrDestructiveFiles, outputFolder)**](#mergepackagesfullpackageordestructivefiles-outputfolder)
Method to merge all provided files into only one file. You can choose if merge all into a package.xml, destructiveChanges.xml or destructiveChangesPost.xml

### **Parameters:**
  - **packageOrDestructiveFiles**: File or list of files to merge (including package and destructive files in the same list)
    - `string` | `string[]` 
  - **outputFolder**: Folder to save the created files
    - `string`

### **Return:**
Object with the merge result including the paths of the merged files
- `PackageGeneratorResult`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`DataNotFoundException`**: If not package or destructive files provided
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory

### **Examples:**
You have several options to merge full package files: 

**Full Merge into Package XML**

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one package XML file.

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    const result = generator.mergePackagesFull(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // [pathFromRoot]/path/to/the/output/folder/package.xml
    console.log(result.destructiveChanges);         // undefined
    console.log(result.destructiveChangesPost);     // undefined
```
**Full Merge into Destructive XML post deployment**

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one destructiveChangesPost XML file.

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setIsDestructive();
    const result = generator.mergePackagesFull(filePaths, outputFolder); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // undefined
    console.log(result.destructiveChanges);         // undefined        (By default, create destructives after deploy)
    console.log(result.destructiveChangesPost);     // [pathFromRoot]/path/to/the/output/folder/destructiveChangesPost.xml
```
**Full Merge into Destructive XML pre deployment**

Merge all package XML, all destructiveChanges XML and all destructiveChangesPost XML files into one destructiveChanges XML file.

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const filePaths = [
        '/test/package/package1.xml',                       // package.xml
        '/test/package/package2.xml',                       // package.xml
        '/test/package/package3.xml',                       // package.xml
        '/test/package/destructiveChanges-dev.xml',         // destructiveChanges.xml
        '/test/package/destructiveChanges-uat.xml',         // destructiveChanges.xml
        '/test/package/destructiveChangesPost1.xml',        // destructiveChangesPost.xml
        '/test/package/destructiveChangesPost-v34.xml'      // destructiveChangesPost.xml
        '/test/package/destructiveChangesPostCustom.xml'    // destructiveChangesPost.xml
    ];
    const outputFolder = 'path/to/the/output/folder';
    const options = {
        apiVersion: '50.0',            // Optional for merge packages
        isDestructive: true,
        beforeDeploy: true
    }
    const generator = new PackageGenerator(50);
    generator.setIsDestructive().setBeforeDeploy();
    const result = generator.mergePackagesFull(filePaths, outputFolder, apiVersion, isDestructive, beforeDeploy); // Return an object with the full path of the created files;
    
    console.log(result.package);                    // undefined
    console.log(result.destructiveChanges);         // [pathFromRoot]/path/to/the/output/folder/destructiveChanges.xml
    console.log(result.destructiveChangesPost);     // undefined

```
---
## [**getPackageContent(metadataOrPath, useIgnoreDestructive)**](#getpackagecontentmetadataorpath)
Method to get the Package XML format content as String to the selected Metadata JSON file or Metadata JSON Object. See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format

### **Parameters:**
  - **metadataOrPath**: Metadata JSON file or Metadata JSON object to get the package or destructive XML content.
    - `string` | `{ [key: string]: MetadataType }`
  - **useIgnoreDestructive**: True to use the ignore destructive file to ignore the package content.
    - `boolean` 

### **Return:**
Returns an String with the XML content
- `string`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory
- **`WrongFormatException`**: If file is not a JSON file or not have the correct Metadata JSON format

### **Examples:**
You have several options to get Package XML Content: 

**Get the package XML Content from Metadata JSON File**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const xmlResultFromFile = generator.getPackageContent(jsonFilePath);

    console.log(xmlResultFromFile);                    // <?xml version="1.0" encoding="UTF-8"?>
                                                       // <Package xmlns="http://soap.sforce.com/2006/04/metadata">
                                                       // ...
```

**Get the package XML Content from Metadata JSON Object**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync(jsonFilePath, 'utf8'));
    const xmlResultFromJSON = generator.getPackageContent(jsonContent);

    console.log(xmlResultFromJSON);                    // <?xml version="1.0" encoding="UTF-8"?>
                                                       // <Package xmlns="http://soap.sforce.com/2006/04/metadata">
                                                       // ...
```
---
## [**createPackage(metadataOrPath, outputFolder)**](#createpackagemetadataorpath-outputfolder)
Method to create a package XML file with the selected Metadata JSON file or Metadata JSON Object. See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format

### **Parameters:**
  - **metadataOrPath**: Metadata JSON file or Metadata JSON object to create the package file.
    - `string` | `{ [key: string]: MetadataType }`
  - **outputFolder**: Folder to save the created file
    - `string`

### **Return:**
Returns the path to the created file
- `string`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory
- **`WrongFormatException`**: If file is not a JSON file or not have the correct Metadata JSON format

### **Examples:**
You have several options to create the XML Package file: 

**Create Package XML from Metadata JSON File**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createPackage(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);            // [rootPath]/path/to/json/package.xml
```
**Create Package XML from Metadata JSON Object**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createPackage(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);        // [rootPath]/path/to/json/package.xml
```
---
## [**createBeforeDeployDestructive(metadataOrPath, outputFolder)**](#createbeforedeploydestructivemetadataorpath-outputfolder)
Method to create a before deploy destructive file with the selected Metadata JSON file or Metadata JSON Object. See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format

### **Parameters:**
  - **metadataOrPath**: Metadata JSON file or Metadata JSON object to create the destructive file.
    - `string` | `{ [key: string]: MetadataType }`
  - **outputFolder**: Folder to save the created file
    - `string`

### **Return:**
Returns the path to the created file
- `string`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory
- **`WrongFormatException`**: If file is not a JSON file or not have the correct Metadata JSON format

### **Examples:**
You have several options to create the XML before destructive file: 

**Create Destructive Changes XML before deploy from Metadata JSON File**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createBeforeDeployDestructive(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);          // [rootPath]/path/to/json/destructiveChanges.xml
```
**Create Destructive Changes XML before deploy from Metadata JSON Object**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createBeforeDeployDestructive(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);          // [rootPath]/path/to/json/destructiveChanges.xml
```
---

## [**createAfterDeployDestructive(metadataOrPath, outputFolder)**](#createafterdeploydestructivemetadataorpath-outputfolder)
Method to create an after deploy destructive file with the selected Metadata JSON file or Metadata JSON Object. See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format

### **Parameters:**
  - **metadataOrPath**: Metadata JSON file or Metadata JSON object to create the destructive file.
    - `string` | `{ [key: string]: MetadataType }`
  - **outputFolder**: Folder to save the created file
    - `string`

### **Return:**
Returns the path to the created file
- `string`

### **Throws:**
This method can throw the next exceptions:

- **`WrongDatatypeException`**: If api version is not a String or number (can be undefined)
- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongDirectoryPathException`**: If the output Folder is not a String or cant convert to absolute path
- **`DirectoryNotFoundException`**: If the directory not exists or not have access to it
- **`InvalidDirectoryPathException`**: If the path is not a directory
- **`WrongFormatException`**: If file is not a JSON file or not have the correct Metadata JSON format

### **Examples:**
You have several options to create the XML after destructive file:

**Create Destructive Changes XML after deploy from Metadata JSON File**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const packageFromFileResult = generator.createAfterDeployDestructive(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);          // [rootPath]/path/to/json/destructiveChangesPost.xml
```
**Create Destructive Changes XML after deploy from Metadata JSON Object**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = generator.createAfterDeployDestructive(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);          // [rootPath]/path/to/json/destructiveChangesPost.xml
```
---
## [**validateJSON(metadataOrPath)**](#validatejsonmetadataorpath)
Static Method to validate a Metadata JSON file or Metadata JSON Object format. If is not valid, throw several exceptions. See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format 

### **Parameters:**
  - **metadataOrPath**: Metadata JSON file or Metadata JSON object to validate.
    - `string` | `any` 

### **Return:**
Returns the Metadata Object Content validated
- `{ [key: string]: MetadataType }`

### **Throws:**
This method can throw the next exceptions:

- **`WrongFilePathException`**: If the package or destructive files path is not a String or cant convert to absolute path
- **`FileNotFoundException`**: If the package or destructive files path not exists or not have access to it
- **`InvalidFilePathException`**: If the package or destructive files path is not a file
- **`WrongFormatException`**: If file is not a JSON file or not have the correct Metadata JSON format

### **Example:**
**Create and Validate your own JSON File**

You can create your own JSON file to create package files and handle metadata types easy with the MetadataType, MetadataObject and MetadataItem classes from [@aurahelper/core](https://github.com/JJLongoria/aura-helper-core). See [Metadata JSON Format](#metadata-file) section to understand the JSON Metadata Format 

```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    import { MetadataType, MetadataObject, MetadataItem } = from '@aurahelper/core';

    // Instance a Metadata Type
    const customObjectType = new MetadataType('CustomObject', checkedOrNot, '.../force-app/main/default/objects', 'object');

    // Add Childs to the Metadata Type
    customObjectType.addChild('Account', new MetadataObject('Account', checkedOrNot, '.../force-app/main/default/objects/Account/Account.object-meta.xml'));
    customObjectType.addChild('Case', new MetadataObject('Case', checkedOrNot, '.../force-app/main/default/objects/Case/Case.object-meta.xml'));
    customObjectType.addChild('CustomObject__c', new MetadataObject('CustomObject__c', checkedOrNot, '.../force-app/main/default/objects/CustomObject__c/CustomObject__c.object-meta.xml'));

    // Instance other Metadata Type
    const customFieldType = new MetadataType('CustomField', checkedOrNot, '.../force-app/main/default/objects', 'field');

    // Add child to the Metadata Type
    customFieldType.addChild('Account', new MetadataObject('Account', checkedOrNot, '.../force-app/main/default/objects/Account'));
    
    // Add childs to the Metadata Object
    customFieldType.getChild('Account').addChild('Name', new MetadataItem('Name', checkedOrNot, '.../force-app/main/default/objects/Account/fields/Name.field-meta.xml'));
    customFieldType.getChild('Account').addChild('CustomField__c', new MetadataItem('CustomField__c', checkedOrNot, '.../force-app/main/default/objects/Account/fields/CustomField__c.field-meta.xml'));

    // Add child to the Metadata Type
    customFieldType.addChild('Case', new MetadataObject('Case', checkedOrNot, '.../force-app/main/default/objects/Case'));

    // Add childs to the Metadata Object
    customFieldType.getChild('Case').addChild('Subject', new MetadataItem('Subject', checkedOrNot, '.../force-app/main/default/objects/Case/fields/Subject.field-meta.xml'));
    customFieldType.getChild('Case').addChild('CustomField__c', new MetadataItem('CustomField__c', checkedOrNot, '.../force-app/main/default/objects/Case/fields/CustomField__c.field-meta.xml'));

    // Add the MetadataTypes to the main Object
    const metadataJSON = {
        CustomObject: customObjectType,
        CustomField: customFieldType
    };

    
    // Now you can create a package XML or validate the created object to ensure that is correct.
    try{
        PackageGenerator.validateJSON(metadataJSON);
    } catch(error){
        // JSON is not valid
        console.log(error.message);     // Description about the error
    }

    // Also you can validate directly a JSON file
    try{
        PackageGenerator.validateJSON('path/to/the/json/metadata');
    } catch(error){
        // JSON is not valid
        console.log(error.message);     // Description about the error
    }
```
# [**Ignore metadata from your package**](#ignore-metadata-from-your-package)
All methods to create or merge package or destructive XML files has two important options to ignore XML files. To ignore files, you need to create a .ahignore.json file (the name can be different) with the format specified on [Ignore File](#ignore-file) section.

### **Examples**:
**Ignore Metadata from a Metadata JSON file when create a package**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    generator.setIgnoreFile('path/to/file' ).setTypesToIgnore(['CustomObject']);
    const packageFromFileResult = generator.createPackage(jsonFilePath, outputFolder);

    console.log(packageFromFileResult);                    // [rootPath]/path/to/json/package.xml
```
**Ignore Metadata from a Metadata JSON Object when create a package**
```javascript
    import { PackageGenerator } from '@aurahelper/package-generator';
    
    const jsonFilePath = 'path/to/json/metadata.json';
    const outputFolder = 'path/to/the/output/folder';

    const generator = new PackageGenerator(50);
    generator.setExplicit();
    generator.setIgnoreFile('path/to/file' ).setTypesToIgnore(['CustomObject']);
    const jsonContent = JSON.parse(fs.readFileSync('jsonFilePath', 'utf8'));
    const packageFromJSONObjectResult = PackageGenerator.createPackage(jsonContent, outputFolder);

    console.log(packageFromJSONObjectResult);                    // [rootPath]/path/to/json/package.xml
```
# [**Metadata JSON Format**](#metadata-file)

The Metadata JSON Format used by Aura Helper Framework and modules have the next structure. Some fields are required and the datatypes checked to ensure the correct file structure. 

```json
    {
        "MetadataAPIName": {
            "name": "MetadataAPIName",                                  // Required (String). Contains the Metadata Type API Name (like object Key)
            "checked": false,                                           // Required (Boolean). Field for include this type on package or not
            "path": "path/to/the/metadata/folder",                      // Optional (String). Path to the Metadata Type folder in local project
            "suffix": "fileSuffix",                                     // Optional (String). Metadata File suffix
            "childs": {                                                 // Object with a collection of childs (Field required (JSON Object) but can be an empty object)
                "MetadataObjectName":{
                    "name": "MetadataObjectName",                       // Required (String). Contains the Metadata Object API Name (like object Key)
                    "checked": false,                                   // Required (Boolean). Field for include this object on package or not
                    "path": "path/to/the/metadata/file/or/folder",      // Optional (String). Path to the object file or folder path
                    "childs": {                                         // Object with a collection of childs (Field required (JSON Object) but can be an empty object)
                        "MetadataItemName": {
                            "name": "MetadataItemName",                 // Required (String). Contains the Metadata Item API Name (like object Key)
                            "checked": false,                           // Required (Boolean). Field for include this object on package or not
                            "path": "path/to/the/metadata/file"
                        },
                        "MetadataItemName2": {
                            ...
                        },
                        ...,
                        ...,
                        ...
                    }
                }
                "MetadataObjectName2":{
                   ...
                },
                ...,
                ...,
                ...
            }
        }
    }

```
### **Example**:

```json
    {
        "CustomObject": {
            "name": "CustomObject",
            "checked": false,
            "path":  "path/to/root/project/force-app/main/default/objects",
            "suffix": "object",
            "childs": {
                "Account": {
                    "name": "Account",
                    "checked": true,            // Add Account Object to the package
                    "path": "path/to/root/project/force-app/main/default/objects/Account/Account.object-meta.xml",
                    "childs": {}
                },
                "Case": {
                    "name": "Case",
                    "checked": true,            // Add Case Object to the package
                    "path": "path/to/root/project/force-app/main/default/objects/Case/Case.object-meta.xml",
                    "childs": {}
                },
                ...,
                ...,
                ...
            }
        },
        "CustomField": {
            "name": "CustomField",
            "checked": false,
            "path":  "path/to/root/project/force-app/main/default/objects",
            "suffix": "field",
            "childs": {
                "Account": {
                    "name": "Account",
                    "checked": false,            
                    "path": "path/to/root/project/force-app/main/default/objects/Account/fields",
                    "childs": {
                        "customField__c": {
                            "name": "customField__c",
                            "checked": true,    // Add customField__c to the package
                            "path": "path/to/root/project/force-app/main/default/objects/Account/fields/customField__c.field-meta.x