feat(client): enable startFirst as extra option in service upgrade

fix #52

Author: lgaticaq

index.js

@@ -1,14 +1,17 @@
 'use strict'
 
-/* eslint-disable require-jsdoc */
-
 const axios = require('axios')
 const merge = require('lodash.merge')
 const pWhilst = require('p-whilst')
 
 /**
  * @typedef {import('./types').Validate} Validate
  * @typedef {import('./types').ErrorCode} ErrorCode
+ * @typedef {import('./types').Service} Service
+ * @typedef {import('./types').Stack} Stack
+ * @typedef {import('./types').ServiceUpgrade} ServiceUpgrade
+ * @typedef {import('./types').Upgrade} Upgrade
+ * @typedef {import('./types').Options} Options
  * @typedef {import('axios').AxiosInstance} AxiosInstance
  */
 
@@ -36,36 +39,77 @@ const validate = async client => {
   }
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @returns {Promise<Array<Stack>>} -
+ * @example
+ * const stacks = getStacks(client)
+ */
 const getStacks = async client => {
   return (await client.get('environments/')).data.data
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @returns {Promise<Array<Service>>} -
+ * @example
+ * const services = getServices(client)
+ */
 const getServices = async client => {
   return (await client.get('services/')).data.data
 }
 
+/**
+ * @param {Array<Stack>} stacks -
+ * @param {string} name -
+ * @returns {Stack} -
+ * @example
+ * const stack = fetchStackByName(stacks, 'MyStack')
+ */
 const fetchStackByName = (stacks, name) => {
   return stacks.filter(stack => stack.name === name).pop()
 }
 
+/**
+ * @param {Array<Service>} services -
+ * @param {string} name -
+ * @param {string} [stackId=null] -
+ * @returns {Service} -
+ * @example
+ * const service = fetchServiceByName(services, 'MyService')
+ */
 const fetchServiceByName = (services, name, stackId = null) => {
   return services
     .filter(s => s.name === name)
     .filter(s => !stackId || s.environmentId === stackId)
     .pop()
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @param {string} name -
+ * @returns {Promise<Stack>} -
+ * @example
+ * const stack = findStackByName(client, 'MyStack')
+ */
 const findStackByName = async (client, name) => {
   const stacks = await getStacks(client)
   const stack = await fetchStackByName(stacks, name)
 
   if (!stack) {
-    throw new Error(`Unable to locate stack '${stack}'`)
+    throw new Error(`Unable to locate stack '${name}'`)
   }
 
   return stack
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @param {string} name -
+ * @returns {Promise<Service>} -
+ * @example
+ * const service = findServiceByName(client, 'MyStack/MyService')
+ */
 const findServiceByName = async (client, name) => {
   const [service, stack] = name
     .toLowerCase()
@@ -83,7 +127,15 @@ const findServiceByName = async (client, name) => {
   return locatedService
 }
 
-const buildUpgradeInstructions = (service, newVersion) => {
+/**
+ * @param {Service} service -
+ * @param {string} newVersion -
+ * @param {boolean} [startFirst=true] -
+ * @returns {ServiceUpgrade} -
+ * @example
+ * const upgrade = await buildUpgradeInstructions(service, '1.0.0')
+ */
+const buildUpgradeInstructions = (service, newVersion, startFirst = true) => {
   const {
     launchConfig,
     launchConfig: { imageUuid }
@@ -97,26 +149,50 @@ const buildUpgradeInstructions = (service, newVersion) => {
     {
       inServiceStrategy: {
         launchConfig: { imageUuid: image },
-        startFirst: true
+        startFirst
       }
     }
   )
 }
 
+/**
+ * @param {ServiceUpgrade} instruction -
+ * @param {string} variable -
+ * @param {string} value -
+ * @returns {ServiceUpgrade} -
+ * @example
+ * upgrade = withAdditionalEnvVar(upgrade, 'MY_VAR', 'myValue')
+ */
 const withAdditionalEnvVar = (instruction, variable, value) => {
   const launchConfig = { environment: { [variable]: value } }
 
   return merge(instruction, { inServiceStrategy: { launchConfig } })
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @param {string} id -
+ * @param {ServiceUpgrade} upgrade -
+ * @returns {Promise<*>} -
+ * @example
+ * const response = upgradeService(client, 'stackId', upgrade)
+ */
 const upgradeService = async (client, id, upgrade) => {
   return (await client.post(`services/${id}/?action=upgrade`, upgrade)).data
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @param {string} id -
+ * @returns {Promise<*>} -
+ * @example
+ * response = checkUpgradeService(client, 'stackId')
+ */
 const checkUpgradeService = (client, id) => {
   let attempts = 0
   let service = {}
   const upgradeTimeout = 5 * 60
+  // eslint-disable-next-line require-jsdoc
   const sleep = timeout =>
     new Promise(resolve => setTimeout(() => resolve(), timeout))
   return pWhilst(
@@ -143,12 +219,27 @@ const checkUpgradeService = (client, id) => {
   )
 }
 
+/**
+ * @param {AxiosInstance} client -
+ * @param {string} id -
+ * @returns {Promise<*>} -
+ * @example
+ * response = finishUpgradeService(client, 'stackId')
+ */
 const finishUpgradeService = async (client, id) => {
   return (await client.post(`services/${id}/?action=finishupgrade`)).data
 }
 
+/**
+ * @class
+ */
 class Rancher {
+  // eslint-disable-next-line jsdoc/require-example
+  /**
+   * @param {Options} options -
+   */
   constructor (options) {
+    /** @type {Options} */
     this.config = Object.assign(
       {
         dryRun: false,
@@ -161,6 +252,7 @@ class Rancher {
       options
     )
 
+    /** @type {AxiosInstance} */
     // @ts-ignore
     this.client = axios.create({
       auth: {
@@ -182,17 +274,26 @@ class Rancher {
     return { isValid, errorCode }
   }
 
-  async upgrade (name, version, commit) {
+  /**
+   * @param {string} name -
+   * @param {string} version -
+   * @param {string} [commit] -
+   * @param {boolean} [startFirst=true] -
+   * @returns {Promise<Upgrade>} -
+   * @example
+   * const { isValid, errorCode } = client.upgrade('MyStack/MyService', '1.0.0')
+   */
+  async upgrade (name, version, commit, startFirst = true) {
     const { commitVariable, dryRun, releaseVariable } = this.config
     const service = await findServiceByName(this.client, name)
-    let upgrade = await buildUpgradeInstructions(service, version)
+    let upgrade = buildUpgradeInstructions(service, version, startFirst)
 
     if (commitVariable && commit) {
-      upgrade = await withAdditionalEnvVar(upgrade, commitVariable, commit)
+      upgrade = withAdditionalEnvVar(upgrade, commitVariable, commit)
     }
 
     if (releaseVariable) {
-      upgrade = await withAdditionalEnvVar(upgrade, releaseVariable, version)
+      upgrade = withAdditionalEnvVar(upgrade, releaseVariable, version)
     }
 
     let response = !dryRun
@@ -209,6 +310,4 @@ class Rancher {
   }
 }
 
-/* eslint-enable require-jsdoc */
-
 module.exports = Rancher

package-lock.json

@@ -33,6 +33,7 @@
     "@semantic-release/changelog": "5.0.1",
     "@semantic-release/git": "9.0.0",
     "@types/axios": "0.14.0",
+    "@types/lodash.merge": "4.6.6",
     "eslint": "6.8.0",
     "eslint-plugin-array-func": "3.1.5",
     "eslint-plugin-eslint-comments": "3.1.2",