René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Enhancement] Configure additional options passed to the Fetch API","articleBody":"## Do you want to request a *feature* or report a *bug*?\r\n\r\n__Feature__\r\n\r\nPatch v1: [contentstack-javascript-issue-5-patch-v1.diff.txt](https://github.com/builtio-contentstack/contentstack-javascript/files/1754381/contentstack-javascript-issue-5-patch-v1.diff.txt) to apply on 6abdf0a (the currently last master commit).\r\n\r\n## What is the current behavior?\r\n\r\nCurrently, the [Request](https://github.com/builtio-contentstack/contentstack-javascript/blob/6abdf0a7aeb12bf557ae7f76d31946914b5896cd/src/core/lib/request.js) function is used (in [Query](https://github.com/builtio-contentstack/contentstack-javascript/blob/master/src/core/modules/query.js), [Entry](https://github.com/builtio-contentstack/contentstack-javascript/blob/master/src/core/modules/entry.js) and [Assets](https://github.com/builtio-contentstack/contentstack-javascript/blob/master/src/core/modules/assets.js) modules) to make the HTTP requests to the [Contentstack's Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).\r\n\r\nUnder the hood, [Request used the Fetch API](https://github.com/builtio-contentstack/contentstack-javascript/blob/6abdf0a7aeb12bf557ae7f76d31946914b5896cd/src/core/lib/request.js#L43) (polyfilled at runtime with [isomorphic-fetch](https://github.com/matthew-andrews/isomorphic-fetch) if needed) to process the HTTP requests.\r\n\r\n```javascript\r\n// File: src/core/lib/request.js\r\n// Version: 6abdf0a (on Jan 2, 2018, 10:08 AM GMT+1)\r\n// Lines: 43-46\r\n\r\nfetch(url + '?' + queryParams, {\r\n  method: 'GET',\r\n  headers: headers\r\n})\r\n```\r\nAs we can see: __there is a no way to configure additional options into the `init` parameter__ ([the second parameter of the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Syntax) which currently contains `method` and `headers` options only).\r\n\r\n## What is the expected behavior?\r\n\r\n__Allowing to configure additional options passed to the Fetch API's `init` parameter.__\r\n\r\nIdeally, we should be allowed to passed that additional options in two levels:\r\n\r\n* Defaults additional options used for __every__ HTTP queries ;\r\n* Additional options use for __some__ HTTP queries (merged to the defaults additional options).\r\n\r\n### Use case example\r\n\r\nIn Node.js: using an [http(s).Agent](https://nodejs.org/api/http.html#http_class_http_agent) instance to allows custom proxy.\r\n\r\nIt's a frequent use case when the Node.js process is running behind a corporate/security/policy proxy.\r\n\r\nIf we can't configure the agent, we won't be able to request the [Contentstack's Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) with the [JavaScript SDK for Contentstack](https://www.contentstack.com/docs/platforms/javascript-browser/api-reference/index.html) (package [contentstack-javascript](https://github.com/builtio-contentstack/contentstack-javascript/)).\r\n\r\n\r\n```javascript\r\nconst HttpProxyAgent = require(\"http-proxy-agent\");\r\n\r\nconst proxyAgent = new HttpProxyAgent(\"http://corporate-proxy.local/\");\r\n\r\n// +-----------\r\n// | \u003e Scenario A: START\r\n// | \u003e Configure the agent to be used for every HTTP queries.\r\n// |\r\n\r\nconst Stack = Contentstack.Stack(\"api_key\", \"access_token\", \"environment_name\", {\r\n  agent: proxyAgent\r\n});\r\n\r\nconst Query = Stack.ContentType('blog').Entry(\"blt123something\");\r\n\r\n// |\r\n// | \u003e\u003e Schenario A.1:\r\n// | \u003e\u003e Execute the query through the default  agent\r\n// |\r\n\r\nQuery.fetch().then(/* ... */);\r\n\r\n// |\r\n// | \u003e\u003e Schenario A.2:\r\n// | \u003e\u003e Execute the query through another agent than the default one.\r\n// |\r\n\r\nconst anotherProxyAgent = new HttpProxyAgent(\"http://another-corporate-proxy.local/\");\r\n\r\nQuery.fetch({ agent: anotherProxyAgent }).then(/* ... */);\r\n\r\n// |\r\n// | \u003e Scenario A: END\r\n// +-----------\r\n\r\n// +-----------\r\n// | \u003e Scenario B: START\r\n// | \u003e No agent is configure by default. The agent is configure \r\n// | \u003e for a specific request execution.\r\n\r\nconst Stack = Contentstack.Stack(\"api_key\", \"access_token\", \"environment_name\", { agent: proxyAgent });\r\n\r\nconst Query = Stack.ContentType('blog').Entry(\"blt123something\");\r\n\r\nQuery.fetch({ agent: proxyAgent }).then(/* ... */);\r\n\r\n// |\r\n// | \u003e Scenario B: END\r\n// +-----------\r\n```\r\n\r\n### Implementation suggested\r\n\r\nThat can be achieved by extending some functions' interface:\r\n\r\n* [`Stack()`](https://www.contentstack.com/docs/platforms/javascript-browser/api-reference/global.html#Stack)\r\n    ```javascript\r\n    var Stack = Contentstack.Stack('api_key', 'access_token', 'environment', {\r\n      // default additional fetch's init options\r\n    });\r\n    // OR\r\n    var Stack = Contentstack.Stack({\r\n        'api_key':'bltsomethingapikey',\r\n        'access_token':'bltsomethongtoken',\r\n        'environment':'environment_name',\r\n        'fetchOptions': {\r\n          // default additional fetch's init options\r\n        }\r\n      });\r\n    ```\r\n* [`fetch()`](https://www.contentstack.com/docs/platforms/javascript-browser/api-reference/global.html#fetch)\r\n    ```javascript\r\n    /**\r\n     * @method fetch\r\n     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n     */\r\n    fetch(fetchOptions?: Object) {}\r\n    ```\r\n* [`find()`](https://www.contentstack.com/docs/platforms/javascript-browser/api-reference/global.html#find)\r\n    ```javascript\r\n    /**\r\n     * @method find\r\n     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n     */\r\n    find(fetchOptions?: Object) {}\r\n    ```\r\n* [`findOne()`](https://www.contentstack.com/docs/platforms/javascript-browser/api-reference/global.html#findOne)\r\n    ```javascript\r\n    /**\r\n     * @method findOne\r\n     * @deprecated since verion 3.3.0\r\n     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n     */\r\n    findOne(fetchOptions?: Object) {}\r\n    ```\r\n* [`Request` (src/core/lib/requests.js)](https://github.com/builtio-contentstack/contentstack-javascript/blob/master/src/core/lib/request.js)\r\n    ```javascript\r\n    /**\r\n     * @method Request\r\n     * @param {Object} requestParams Query instance's request params.\r\n     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n     */\r\n    function Request(requestParams: Object, fetchOptions?: Object) {}\r\n    ```\r\n* [`sendRequest` (src/core/lib/utils.js)](https://github.com/builtio-contentstack/contentstack-javascript/blob/master/src/core/lib/utils.js)\r\n    ```javascript\r\n    /**\r\n     * @method sendRequest\r\n     * @param {Object} queryObject Query instance.\r\n     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n     */\r\n    function sendRequest(queryObject: Query. fetchOptions?: Object) {}\r\n    ```\r\n\r\n### Patch\r\n\r\nPatch v1: [contentstack-javascript-issue-5-patch-v1.diff.txt](https://github.com/builtio-contentstack/contentstack-javascript/files/1754381/contentstack-javascript-issue-5-patch-v1.diff.txt) to apply on 6abdf0a (the currently last master commit).\r\n\r\n\u003cdetails\u003e\r\n \u003csummary\u003eClick to toggle contents of contentstack-javascript-issue-5-patch-v1.diff\u003c/summary\u003e\r\n\r\n```js\r\ndiff --git a/src/core/lib/request.js b/src/core/lib/request.js\r\nindex 9255650..4b58a13 100644\r\n--- a/src/core/lib/request.js\r\n+++ b/src/core/lib/request.js\r\n@@ -4,7 +4,7 @@ import fetch from \"runtime/http.js\";\r\n //JS SDK version\r\n let version = '{{VERSION}}';\r\n \r\n-export default function Request(options) {\r\n+export default function Request(options, fetchOptions) {\r\n     return new Promise(function(resolve, reject) {\r\n         let queryParams;\r\n         let serialize = function(obj, prefix) {\r\n@@ -40,10 +40,14 @@ export default function Request(options) {\r\n             queryParams = serialize(options.body);\r\n         }\r\n \r\n-        fetch(url + '?' + queryParams, {\r\n-                method: 'GET',\r\n-                headers: headers\r\n-            })\r\n+        const _fetchOptions = Utils.mergeDeep.call(Utils, {}, fetchOptions);\r\n+\r\n+        Utils.mergeDeep.call(Utils, _fetchOptions, {\r\n+            method: 'GET',\r\n+            headers: headers\r\n+        });\r\n+\r\n+        fetch(url + '?' + queryParams, _fetchOptions)\r\n             .then(function(response) {\r\n                 if (response.ok \u0026\u0026 response.status === 200) {\r\n                     let data = response.json();\r\ndiff --git a/src/core/lib/utils.js b/src/core/lib/utils.js\r\nindex 7e59d35..982b89a 100644\r\n--- a/src/core/lib/utils.js\r\n+++ b/src/core/lib/utils.js\r\n@@ -186,7 +186,9 @@ export function spreadResult(result) {\r\n     return _results;\r\n };\r\n \r\n-export function sendRequest(queryObject) {\r\n+export function sendRequest(queryObject, fetchOptions) {\r\n+    let _utils = this;\r\n+\r\n     let env_uid = queryObject.environment_uid;\r\n     if (env_uid) {\r\n         queryObject._query.environment_uid = env_uid;\r\n@@ -235,7 +237,9 @@ export function sendRequest(queryObject) {\r\n \r\n     let callback = function(continueFlag, resolve, reject) {\r\n         if (continueFlag) {\r\n-            Request(queryObject.requestParams)\r\n+            const _fetchOptions = mergeDeep.call(_utils, queryObject.fetchOptions, fetchOptions);\r\n+\r\n+            Request(queryObject.requestParams, _fetchOptions)\r\n                 .then(function(data) {\r\n                     try {\r\n                         self.entry_uid = self.asset_uid = self.tojson = self.queryCachePolicy = undefined;\r\ndiff --git a/src/core/modules/assets.js b/src/core/modules/assets.js\r\nindex 16c1cfd..5c3d96f 100644\r\n--- a/src/core/modules/assets.js\r\n+++ b/src/core/modules/assets.js\r\n@@ -68,11 +68,12 @@ export default class Assets {\r\n \r\n     /**\r\n      * @method fetch\r\n+     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n      * @description fetch asset obhect of requested Asset uid of defined query if present.\r\n      * @example\r\n      * Stack.Assets('bltsomething123').fetch()\r\n      */\r\n-    fetch() {\r\n+    fetch(fetchOptions) {\r\n         if (this.asset_uid) {\r\n             this.requestParams = {\r\n                 method: 'POST',\r\n@@ -84,7 +85,7 @@ export default class Assets {\r\n                 }\r\n             }\r\n \r\n-            return Utils.sendRequest(this);\r\n+            return Utils.sendRequest(this, fetchOptions);\r\n         } else {\r\n             console.error(\"Kindly provide an asset uid. e.g. .Assets('bltsomething123')\");\r\n         }\r\ndiff --git a/src/core/modules/entry.js b/src/core/modules/entry.js\r\nindex 992077c..29f9d3d 100644\r\n--- a/src/core/modules/entry.js\r\n+++ b/src/core/modules/entry.js\r\n@@ -208,11 +208,12 @@ export default class Entry {\r\n \r\n     /**\r\n      * @method fetch\r\n+     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n      * @description fetch entry of requested content_type of defined query if present.\r\n      * @example\r\n      * blogEntry.fetch()\r\n      */\r\n-    fetch() {\r\n+    fetch(fetchOptions) {\r\n         if (this.entry_uid) {\r\n             this.requestParams = {\r\n                 method: 'POST',\r\n@@ -223,7 +224,7 @@ export default class Entry {\r\n                     query: this._query\r\n                 }\r\n             };\r\n-            return Utils.sendRequest(this);\r\n+            return Utils.sendRequest(this, fetchOptions);\r\n         } else {\r\n             console.error(\"Kindly provide an entry uid. e.g. .Entry('bltsomething123')\");\r\n         }\r\ndiff --git a/src/core/modules/query.js b/src/core/modules/query.js\r\nindex 0ff9a05..3a86161 100644\r\n--- a/src/core/modules/query.js\r\n+++ b/src/core/modules/query.js\r\n@@ -436,11 +436,12 @@ export default class Query extends Entry {\r\n \r\n     /**\r\n      * @method find\r\n+     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n      * @description Provides all the entries which satisfied the query specified.\r\n      * @example\r\n      * blogQuery.find()\r\n      */\r\n-    find() {\r\n+    find(fetchOptions) {\r\n         const host = this.config.protocol + \"://\" + this.config.host + ':' + this.config.port + '/' + this.config.version,\r\n             url = (this.type \u0026\u0026 this.type === 'asset') ? host + this.config.urls.assets : host + this.config.urls.content_types + this.content_type_uid + this.config.urls.entries;\r\n         this.requestParams = {\r\n@@ -452,17 +453,18 @@ export default class Query extends Entry {\r\n                 query: this._query\r\n             }\r\n         };\r\n-        return Utils.sendRequest(this);\r\n+        return Utils.sendRequest(this, fetchOptions);\r\n     }\r\n \r\n     /**\r\n      * @method findOne\r\n      * @deprecated since verion 3.3.0\r\n+     * @param {Object} [fetchOptions] Any custom settings that you want to apply to the request.\r\n      * @description Provides the single entry from the resultset.\r\n      * @example\r\n      * blogQuery.findOne()\r\n      */\r\n-    findOne() {\r\n+    findOne(fetchOptions) {\r\n         const host = this.config.protocol + \"://\" + this.config.host + ':' + this.config.port + '/' + this.config.version,\r\n             url = (this.type \u0026\u0026 this.type === 'asset') ? host + this.config.urls.assets : host + this.config.urls.content_types + this.content_type_uid + this.config.urls.entries;\r\n         this.singleEntry = true;\r\n@@ -476,7 +478,7 @@ export default class Query extends Entry {\r\n                 query: this._query\r\n             }\r\n         };\r\n-        return Utils.sendRequest(this);\r\n+        return Utils.sendRequest(this, fetchOptions);\r\n     }\r\n \r\n }\r\n\\ No newline at end of file\r\ndiff --git a/src/core/stack.js b/src/core/stack.js\r\nindex 33a1530..76a5f78 100644\r\n--- a/src/core/stack.js\r\n+++ b/src/core/stack.js\r\n@@ -24,17 +24,20 @@ export default class Stack {\r\n                         access_token: stack_arguments[0].access_token\r\n                     };\r\n                     this.environment = stack_arguments[0].environment;\r\n+                    this.fetchOptions = stack_arguments[0].fetchOptions || {};\r\n                     return this;\r\n                 } else {\r\n                     console.error(\"Kindly provide valid object parameters.\");\r\n                 }\r\n             case 3:\r\n+            case 4:\r\n                 if (typeof stack_arguments[0] === \"string\" \u0026\u0026 typeof stack_arguments[1] === \"string\" \u0026\u0026 typeof stack_arguments[2] === \"string\") {\r\n                     this.headers = {\r\n                         api_key: stack_arguments[0],\r\n                         access_token: stack_arguments[1]\r\n                     };\r\n                     this.environment = stack_arguments[2];\r\n+                    this.fetchOptions = stack_arguments[3] || {};\r\n                     return this;\r\n                 } else {\r\n                     console.error(\"Kindly provide valid string parameters.\");\r\n\r\n```\r\n\u003c/details\u003e","author":{"url":"https://github.com/enten","@type":"Person","name":"enten"},"datePublished":"2018-02-24T13:14:59.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/5/contentstack-javascript/issues/5"}