feat: refactor core to use Promises instead of callbacks

[dpopp07]

Refactors the entire library to use Promises instead of callbacks. This is a pretty big change but since the SDK is really the only "user", I don't think it will cause any problems.

The generated SDK code should be able to change slightly to achieve no difference in current behavior. The current plan is to start returning Promises first in the generated Watson SDK, with callbacks being an accommodation. We also want to start generating new services using only Promises. This PR enables that route, as it moves all callback handling out of the core and into the generated SDK.

If this is too big of a change to make too late in the game, that's fine, but this work is necessary to move towards a Promise-only approach and doing it this way gives us more flexibility in the generated SDKs to use either approach.

If this is agreeable, I will open a corresponding PR in the generator.

FYI: This PR makes heavy use of the fact that every then and catch block returns a Promise itself and that "returning" or "throwing" inside of these blocks, will resolve and reject in a later chained Promise, respectively. Where we were previously passing one callback around to multiple functions, we are now bubbling up results through chained Promises. Using the other method, we used to lose some error information that is now becoming visible. This required some small changes in the unit tests. On that point, I think the code is improved overall.

[mkistler]

This looks great!

But I am nervous about making such a large change this close to the major release.
I'd like to let @germanattanasio make the call on that.

[germanattanasio]

I don't know about TypeScript but with JS, you need to always wrap the code within a promise in order to catch errors.

public authenticate(options: AuthenticateOptions): Promise<void> { 
  return new Promise((resolve, reject) => {
     const authHeaderString = computeBasicAuthHeader(this.username, this.password); 
     const authHeader = { Authorization: authHeaderString } 
     options.headers = extend(true, {}, options.headers, authHeader);
     resolve();
 });
}

[dpopp07]

Promises work the same in TS as they do JS. That is true, I just wasn't anticipating any errors here and wasn't handling them when I was using callbacks. But I am good with this approach here to be safe.

[germanattanasio]

I'm just trying to anticipate future changes to those methods that today don't return errors

[germanattanasio]

I think this should be wrap in a promise like my example above

[dpopp07]

Since the requestToken method also returns a Promise, I think it is cleaner to chain the Promises together than to create a new Promise altogether.

[germanattanasio]

What happens if this.tokenInfo is undefined?

[dpopp07]

It would throw an error that would not be rejected in the Promise, so the users rejection handling wouldn't catch it. Which would be bad. But we explicitly define the tokenInfo object in the constructor: this.tokenInfo = {};.

I understand what you're saying, I just don't know how much we want to account for a scenario like this that shouldn't ever happen. We were not accounting for any errors happening here before either. The behavior is staying the same. That said, if you think we need to be able to catch errors there, I will change the code

[germanattanasio]

I left some comments around wrapping the entire function as a promise rather than using Promise.resolve() or Promise.reject()

[dpopp07]

In some scenarios I would think that is better but when returning a series of Promises in a row (like authenticate -> getToken -> requestToken -> sendRequest) I think it makes more sense to use Promise chaining and, from each method, return the Promise returned from the method before it, with handlers to do the method-specific processing. Let me know what you think

[germanattanasio]

The latest changes look good. Thanks!