✨ add axios CancelToken support

change last parameter accessToken to be a requestOptions object which lets us add cancelToken

Author: Crhistian Ramirez

README.md

@@ -176,7 +176,7 @@ Me.As().ListProducts()
   .then(impersonatedProductList => console.log(impersonatedProductList))
 ```
 
-As you can see this method makes it very easy to toggle between impersonated calls and non-impersonated calls. But what if you have more than two tokens to toggle between? To address that scenario we recommend using the optional `accessToken` parameter available as the last parameter on all sdk methods.
+As you can see this method makes it very easy to toggle between impersonated calls and non-impersonated calls. But what if you have more than two tokens to toggle between? To address that scenario we recommend using the optional `requestOptions.accessToken` parameter. `requestOptions` is available as the last parameter on all sdk methods.
 
 ```javascript
 import { Me } from 'ordercloud-javascript-sdk';
@@ -186,18 +186,41 @@ var token2 = 'USER2_TOKEN';
 var token3 = 'USER3_TOKEN';
 
 // Get products for user 1
-Me.ListProducts(null, token1)
+Me.ListProducts(null, { accessToken: token1 })
   .then(user1ProductList => console.log(user1ProductList))
 
 // Get products for user 2
-Me.ListProducts(null, token2)
+Me.ListProducts(null, { accessToken: token2 })
   .then(user2ProductList => console.log(user2ProductList))
 
 // Get products for user 3
-Me.ListProducts(null, token3)
+Me.ListProducts(null, { accessToken: token3 })
   .then(user3ProductList => console.log(user3ProductList))
 ```
 
+## Cancelling Requests
+
+In addition to `requestOptions.accessToken` the sdk provides `requestOptions.cancelToken` which enables [axios request cancellation](https://github.com/axios/axios#cancellation). This option is useful for cleaning up outstanding requests when changes in your user experience no longer require the data requested. For instance, you could use the cancel token to clean up outstanding requests [when your react component unmounts](https://reactjs.org/docs/hooks-effect.html#effects-with-cleanup).
+
+```ts
+import axios from 'axios';
+import { Products } from 'ordercloud-javascript-sdk';
+
+const signal = axios.CancelToken.source();
+
+Products.List({search: 'Tennis balls'}, {cancelToken: signal.token})
+  .catch(ex => {
+    if (axios.isCancel(ex)) {
+      console.log(ex) // 'This request was cancelled!'
+    } else {
+      console.log(ex) // Normal ordercloud exception
+    }
+  })
+
+// Oops! I don't want to resolve this request anymore
+signal.cancel('This request was cancelled!')
+```
+
 ## Typescript Support
 
 While typescript is not required to use this project (we compile it down to javascript for you), it does mean there are some added benefits for our typescript users.

codegen/templates/api/Auth.ts

@@ -1,4 +1,4 @@
-import axios, { AxiosInstance } from 'axios'
+import axios, { AxiosInstance, CancelToken } from 'axios'
 import { AccessToken } from '../models/AccessToken'
 import Configuration from '../Configuration'
 import { SecurityProfile } from '../models/SecurityProfile'
@@ -43,7 +43,10 @@ class Auth {
     username: string,
     password: string,
     clientID: string,
-    scope: Array<SecurityProfile['Roles']>
+    scope: Array<SecurityProfile['Roles']>,
+    options: {
+      cancelToken?: CancelToken
+    } = {}
   ): Promise<RequiredDeep<AccessToken>> {
     if (!Array.isArray(scope)) {
       throw new Error('scope must be a string array')
@@ -62,6 +65,7 @@ class Auth {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
         },
+        ...options,
       })
       .catch(e => {
         if (e.response) {
@@ -88,7 +92,10 @@ class Auth {
     username: string,
     password: string,
     clientID: string,
-    scope: Array<SecurityProfile['Roles']>
+    scope: Array<SecurityProfile['Roles']>,
+    options: {
+      cancelToken?: CancelToken
+    } = {}
   ): Promise<RequiredDeep<AccessToken>> {
     if (!Array.isArray(scope)) {
       throw new Error('scope must be a string array')
@@ -108,6 +115,7 @@ class Auth {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
         },
+        ...options,
       })
       .catch(e => {
         if (e.response) {
@@ -130,7 +138,10 @@ class Auth {
   public async ClientCredentials(
     clientSecret: string,
     clientID: string,
-    scope: Array<SecurityProfile['Roles']>
+    scope: Array<SecurityProfile['Roles']>,
+    options: {
+      cancelToken?: CancelToken
+    } = {}
   ): Promise<RequiredDeep<AccessToken>> {
     if (!Array.isArray(scope)) {
       throw new Error('scope must be a string array')
@@ -148,6 +159,7 @@ class Auth {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
         },
+        ...options,
       })
       .catch(e => {
         if (e.response) {
@@ -168,7 +180,10 @@ class Auth {
    */
   public async RefreshToken(
     refreshToken: string,
-    clientID: string
+    clientID: string,
+    options: {
+      cancelToken?: CancelToken
+    } = {}
   ): Promise<RequiredDeep<AccessToken>> {
     const body = {
       grant_type: 'refresh_token',
@@ -182,6 +197,7 @@ class Auth {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
         },
+        ...options,
       })
       .catch(e => {
         if (e.response) {
@@ -202,7 +218,10 @@ class Auth {
    */
   public async Anonymous(
     clientID: string,
-    scope: Array<SecurityProfile['Roles']>
+    scope: Array<SecurityProfile['Roles']>,
+    options: {
+      cancelToken?: CancelToken
+    } = {}
   ): Promise<RequiredDeep<AccessToken>> {
     if (!Array.isArray(scope)) {
       throw new Error('scope must be a string array')
@@ -219,6 +238,7 @@ class Auth {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
         },
+        ...options,
       })
       .catch(e => {
         if (e.response) {

codegen/templates/api/_RESOURCE_.ts.hbs

@@ -4,6 +4,7 @@ import { {{this}} } from '../models/{{this}}';
 import { PartialDeep } from '../models/PartialDeep';
 import { RequiredDeep } from '../models/RequiredDeep';
 import { Filters } from '../models/Filters';
+import { RequestOptions } from '../models/RequestOptions';
 import httpClient from '../utils/HttpClient';
 import OrderCloudError from '../utils/OrderCloudError';
 
@@ -22,13 +23,14 @@ class {{resource.id}} {
 
     {{#resource.operations}}
    /**{{#allParams}}
-    * @param {{#if isQueryParam}}options.{{name}} {{description}}{{else}}{{name}} {{description}}{{#if isBodyParam}}{{#if hasRequiredFields}}Required fields: {{commaSeparate requiredFields}}{{/if}}{{/if}}{{/if}}{{/allParams}}
-    * @param accessToken Provide an alternative token to the one stored in the sdk instance (useful for impersonation).
+    * @param {{#if isQueryParam}}listOptions.{{name}} {{description}}{{else}}{{name}} {{description}}{{#if isBodyParam}}{{#if hasRequiredFields}}Required fields: {{commaSeparate requiredFields}}{{/if}}{{/if}}{{/if}}{{/allParams}}
+    * @param requestOptions.accessToken Provide an alternative token to the one stored in the sdk instance (useful for impersonation).
+    * @param requestOptions.cancelToken Provide an [axios cancelToken](https://github.com/axios/axios#cancellation) that can be used to cancel the request.
     */
-    public async {{name}}{{#if hasReturnType}}{{#if isList}}<T{{baseType}} extends {{baseType}}>{{else}}<T{{returnType}} extends {{returnType}}>{{/if}}{{/if}}({{#allParams}}{{#unless isQueryParam}}{{#if isBodyParam}}{{#if ../isPatch}}{{name}}: PartialDeep<{{typescriptType}}>, {{else}}{{name}}: {{typescriptType}},{{/if}}{{else}}{{name}}: {{typescriptType}}, {{/if}}{{/unless}}{{/allParams}} {{#if hasQueryParams}}options: { {{#queryParams}}{{name}}?: {{typescriptType}}{{#unless @last}}, {{/unless}}{{/queryParams}} } = {}, {{/if}}accessToken?: string ): Promise<{{#if hasReturnType}}RequiredDeep<{{#if isList}}{{#if isFacetList}}ListPageFacet<T{{baseType}}>{{else}}ListPage<T{{baseType}}>{{/if}}{{else}}T{{returnType}}{{/if}}>{{else}}void{{/if}}> {
+    public async {{name}}{{#if hasReturnType}}{{#if isList}}<T{{baseType}} extends {{baseType}}>{{else}}<T{{returnType}} extends {{returnType}}>{{/if}}{{/if}}({{#allParams}}{{#unless isQueryParam}}{{#if isBodyParam}}{{#if ../isPatch}}{{name}}: PartialDeep<{{typescriptType}}>, {{else}}{{name}}: {{typescriptType}},{{/if}}{{else}}{{name}}: {{typescriptType}}, {{/if}}{{/unless}}{{/allParams}} {{#if hasQueryParams}}options: { {{#queryParams}}{{name}}?: {{typescriptType}}{{#unless @last}}, {{/unless}}{{/queryParams}} } = {}, {{/if}}requestOptions: RequestOptions = {} ): Promise<{{#if hasReturnType}}RequiredDeep<{{#if isList}}{{#if isFacetList}}ListPageFacet<T{{baseType}}>{{else}}ListPage<T{{baseType}}>{{/if}}{{else}}T{{returnType}}{{/if}}>{{else}}void{{/if}}> {
         const impersonating = this.impersonating;
         this.impersonating = false;
-        return await httpClient.{{verb}}(`{{parameterizePath path}}`{{#if hasBodyParam}}, {{bodyParam.name}}{{/if}}, { params: { {{#if hasQueryParams}}...options, {{/if}} {{#if hasFilters}}filters: options.filters, {{/if}}accessToken, impersonating } } )
+        return await httpClient.{{verb}}(`{{parameterizePath path}}`{{#if hasBodyParam}}, {{bodyParam.name}}{{/if}}, { params: { {{#if hasQueryParams}}...options, {{/if}} {{#if hasFilters}}filters: options.filters, {{/if}}...requestOptions, impersonating } } )
         .catch(ex => {
             if(ex.response) {
                 throw new OrderCloudError(ex)

codegen/templates/models/RequestOptions.ts

@@ -0,0 +1,6 @@
+import { CancelToken } from 'axios'
+
+export interface RequestOptions {
+  accessToken?: string
+  cancellationToken?: CancelToken
+}

codegen/templates/models/index.ts.hbs

@@ -4,6 +4,8 @@ export * from './{{this.name}}';
 export * from './DecodedToken';
 export * from './SdkConfiguration';
 export * from './PartialDeep';
+export * from './RequiredDeep';
 export * from './ListPage';
 export * from './ListPageFacet';
-export * from './Filters';
+export * from './Filters';
+export * from './RequestOptions';