feat: ✨ added compare and merge functionality for branches with unit test cases [CS-36688]

A new branch is created for the feature as the prev branch `CS-36487-branch-compare-merge` encountered many merge conflicts.

Author: nadeem-cs

lib/entity.js

@@ -267,3 +267,25 @@ export function parseData (response, stackHeaders, contentTypeUID) {
   }
   return data
 }
+
+export async function get (http, url, params, data) {
+  const headers = {
+    params: {
+      ...cloneDeep(data.branches),
+      ...cloneDeep(params)
+    },
+    headers: {
+      ...cloneDeep(this.stackHeaders)
+    }
+  } || {}
+  try {
+    const response = await http.get(url, headers)
+    if (response.data) {
+      return response.data
+    } else {
+      throw error(response)
+    }
+  } catch (err) {
+    throw error(err)
+  }
+}

lib/stack/branch/compare.js

@@ -0,0 +1,78 @@
+import { get } from '../../entity'
+
+/**
+ *
+ * @namespace Branch
+ */
+export function Compare (http, data = {}) {
+  this.stackHeaders = data.stackHeaders
+  this.urlPath = `/stacks/branches/compare`
+
+  /**
+     * @description List of content types and global fields that exist in only one branch or are different between the two branches.
+     * @memberof Compare
+     * @func all
+     * @returns {Promise<Response>} Promise for response.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch('branch_uid').compare('compare_branch_uid').all({skip: 0, limit: 100})
+     * .then(response)
+     * .catch(error)
+     *
+   */
+  this.all = async (params = {}) => {
+    return await get(http, this.urlPath, params, data)
+  }
+
+  /**
+     * @description List of all or specific content types that exist in only one branch or are different between the two branches.
+     * @memberof Compare
+     * @func contentTypes
+     * @param {string} params.uid Optional uid for Content Type to compare.
+     * @returns {Promise<Response>} Promise for response.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch('branch_uid').compare().all({skip: 0, limit: 100})
+     * .then(response)
+     * .catch(error)
+     *
+   */
+  this.contentTypes = async (params = {}) => {
+    let url = `${this.urlPath}/content_types`
+    if (params.uid) {
+      url = `${url}/${params.uid}`
+      delete params.uid
+    }
+    return await get(http, url, params, data)
+  }
+
+  /**
+     * @description Compare allows you compare any or specific ContentType or GlobalFields.
+     * @memberof Compare
+     * @func globalFields
+     * @param {string} params.uid Optional uid for Global Field to compare.
+     * @returns {Promise<Response>} Promise for response.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch('branch_uid').compare().all({skip: 0, limit: 100})
+     * .then(response)
+     * .catch(error)
+     *
+   */
+  this.globalFields = async (params = {}) => {
+    let url = `${this.urlPath}/global_fields`
+    if (params.uid) {
+      url = `${url}/${params.uid}`
+      delete params.uid
+    }
+    return await get(http, url, params, data)
+  }
+
+  return this
+}

lib/stack/branch/index.js

@@ -1,5 +1,8 @@
 import cloneDeep from 'lodash/cloneDeep'
 import { create, query, fetch, deleteEntity } from '../../entity'
+import { Compare } from './compare'
+import { MergeQueue } from './mergeQueue'
+import error from '../../core/contentstackError'
 
 /**
  *
@@ -44,6 +47,29 @@ export function Branch (http, data = {}) {
      *
      */
     this.fetch = fetch(http, 'branch')
+
+    /**
+     * @description Compare allows you compare any or specific ContentType or GlobalFields.
+     * @memberof Branch
+     * @func compare
+     * @returns {Compare} Instance of Compare.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch('branch_uid').compare()
+     *
+     */
+    this.compare = (compareBranchUid) => {
+      const compareData = { stackHeaders: this.stackHeaders }
+      if (compareBranchUid) {
+        compareData.branches = {
+          base_branch: this.uid,
+          compare_branch: compareBranchUid
+        }
+      }
+      return new Compare(http, compareData)
+    }
   } else {
     /**
      * @description The Create a Branch call creates a new branch in a particular stack of your Contentstack account.
@@ -54,7 +80,7 @@ export function Branch (http, data = {}) {
      * @example
      * import * as contentstack from '@contentstack/management'
      * const client = contentstack.client()
-     * const branch = {
+     * const branch =   {
      *      name: 'branch_name',
      *      source: 'master'
      * }
@@ -77,6 +103,63 @@ export function Branch (http, data = {}) {
      * .then((collection) => { console.log(collection) })
      */
     this.query = query({ http, wrapperCollection: BranchCollection })
+
+    /**
+     * @description Merge allows user to merge branches in a Stack.
+     * @memberof Branch
+     * @func merge
+     * @returns {Object} Response Object
+     *
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch().merge({
+     *   base_branch: "main",
+     *   compare_branch: "dev",
+     *   default_merge_strategy: "merge_prefer_base",
+     *   item_merge_strategies: [ 
+     *     {
+     *       uid: "global_field_uid", 
+     *       type: "global_field", 
+     *       merge_strategy: "merge_prefer_base"
+     *     }
+     *   ],
+     *   merge_comment: "Merging dev into main", 
+     *   no_revert: true
+     * })
+     */
+    this.merge = async (mergeObj) => {
+      const url = '/stacks/branches/merge';
+      const header = { 
+        headers: { ...cloneDeep(this.stackHeaders)},
+      }
+      try {
+        const response = await http.post(url, mergeObj, header);
+        if (response.data) return response.data;
+        else throw error(response)
+      } catch (e) {
+        throw error(e);
+      }
+    }
+
+    /**
+     * @description Merge Queue provides list of all recent merge jobs in a Stack.
+     * @memberof Branch
+     * @func mergeQueue
+     * @returns {MergeQueue} Instance of MergeQueue 
+     *
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch().mergeQueue()
+     *    
+     */
+    this.mergeQueue = (uid) => {
+      const mergeData = { stackHeaders: this.stackHeaders, uid }
+      return new MergeQueue(http, mergeData)
+    }
   }
   return this
 }
@@ -86,4 +169,4 @@ export function BranchCollection (http, data) {
   return obj.map((branchData) => {
     return new Branch(http, { branch: branchData, stackHeaders: data.stackHeaders })
   })
-}
+}

lib/stack/branch/mergeQueue.js

@@ -0,0 +1,47 @@
+import { get } from '../../entity'
+
+export function MergeQueue (http, data = {}) {
+  this.stackHeaders = data.stackHeaders
+  this.urlPath = `/stacks/branches/merge-queue`
+
+  if (data.uid) {
+    /**
+     * @description Fetch function gets the status of a merge job and it's configuration details.
+     * @memberof MergeQueue
+     * @func fetch
+     * @returns {Promise<Response>} Promise for response.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch().mergeQueue('UID').fetch()
+     * .then(response)
+     * .catch(error)
+     *
+    */
+    this.fetch = async () => {
+      const url = `${this.urlPath}/${data.uid}`
+      return await get(http, url, {}, data)
+    }
+  } else {
+    /**
+     * @description Find function lists all recent merge jobs.
+     * @memberof MergeQueue
+     * @func find
+     * @returns {Promise<Response>} Promise for response.
+     * @example
+     * import * as contentstack from '@contentstack/management'
+     * const client = contentstack.client()
+     *
+     * client.stack({ api_key: 'api_key'}).branch().mergeQueue().find()
+     * .then(response)
+     * .catch(error)
+     *
+    */
+    this.find = async (params = {}) => {
+      return await get(http, this.urlPath, params, data)
+    }
+  }
+
+  return this
+}