enterprise-fetch 1.0.0-alpha.3 → 1.0.0

package/README.md

@@ -1,7 +1,9 @@
-# Enterprise Fetch
+# Enterprise Fetch [![codecov](https://codecov.io/gh/neilflatley/enterprise-fetch/branch/main/graph/badge.svg?token=48LZ3BDFHL)](https://codecov.io/gh/neilflatley/enterprise-fetch) [![Node.js CI](https://github.com/neilflatley/enterprise-fetch/actions/workflows/node.js.yml/badge.svg)](https://github.com/neilflatley/enterprise-fetch/actions/workflows/node.js.yml) ![npm](https://img.shields.io/npm/v/enterprise-fetch)
 
 A fetch wrapper with some nice enterprise features that are missing from the default fetch implementations, such as request timeout, request proxy, and a fully configurable retry policy. Designed to work in both browser and NodeJS server environments.
 
+ES6 module and CJS available for developers and pre-built minified bundles that can be used straight in the browser
+
 ## Simple usage
 
 The default export provides a fetch wrapper with a default retry policy set
@@ -10,39 +12,42 @@ Use it as a drop-in replacement for your existing fetch implementation
 
 ### Examples
 
-```
+```javascript
 import enterpriseFetch from 'enterprise-fetch';
 
 // enterpriseFetch(url: RequestInfo, init?: FetchInit): Promise<Response>
 
 enterpriseFetch('https://httpbin.org/json')
-    .then((res) => res.json())
-    .then((json) => console.log(json));
+  .then((res) => res.json())
+  .then((json) => console.log(json));
 
 enterpriseFetch('https://httpbin.org/post', {
-        method: 'post',
-        body:    JSON.stringify({ a: 1 }),
-        headers: { 'Content-Type': 'application/json' },
-    })
-    .then(res => res.json())
-    .then(json => console.log(json));
+  method: 'post',
+  body: JSON.stringify({ a: 1 }),
+  headers: { 'Content-Type': 'application/json' },
+})
+  .then((res) => res.json())
+  .then((json) => console.log(json));
 ```
 
 #### Async / await
 
-```
+I prefer writing JavaScript in this way and would be the recommended approach where possible
+
+```javascript
 const res = await enterpriseFetch('https://httpbin.org/post', {
-        method: 'post',
-        body:    JSON.stringify({ a: 1 }),
-        headers: { 'Content-Type': 'application/json' },
-    });
+  method: 'post',
+  body: JSON.stringify({ a: 1 }),
+  headers: { 'Content-Type': 'application/json' },
+});
 const json = await res.json();
 console.log(json);
 ```
 
 ### Default retry policy
 
-```
+```javascript
+const fetchDefaults = {
   // The timeout to apply before sending Abort signal
   // to all requests that do not supply a timeout option
   timeout: 60 * 1000,
@@ -52,45 +57,36 @@ console.log(json);
     minTimeout: 400,
     factor: 2,
   },
-  // Do retry function to examine failures and apply custom 
+  // Do retry function to examine failures and apply custom
   // retry logic return true to retry the fetch call
   doRetry: async (attempt, res, { url, options }) => {
     // Get the retry policy from options or fetchDefaults
     const { retry = fetchDefaults.retry } = options || fetchDefaults;
     if (attempt <= retry.retries) {
-      const counter = `${attempt}/${retry.retries}`;
-
-      if ('message' in res)
-        console.warn(
-          `[fetch] Attempt ${counter} ${
-            res.name || ('type' in res && res.type)
-          }: ${res.message} ${url || ''}`
-        );
-      else
-        console.warn(
-          `[fetch] Attempt ${counter} ${res.status}: ${res.statusText} ${
-            url || ''
-          }`
-        );
-
-      // Retry request on any network error, 
+      // Retry request on any network error,
       // or 4xx or 5xx status codes. No retry on 404
-      if (
-        !res.status ||
-        (res.status >= 400 && res.status !== 404) ||
-        ('name' in res && res.name === 'AbortError') ||
-        ('type' in res && res.type === 'aborted') ||
-        ('code' in res && res.code === 'ECONNRESET') ||
-        ('code' in res && res.code === 'ETIMEDOUT')
-      ) {
+      if (!res.status || (res.status >= 400 && res.status !== 404)) {
+        const counter = `${attempt}/${retry.retries}`;
+        if ('message' in res)
+          console.warn(
+            `[fetch] Attempt ${counter} ${
+              res.name || ('type' in res && res.type)
+            }: ${res.message} ${url || ''}`
+          );
+        else
+          console.warn(
+            `[fetch] Attempt ${counter} ${res.status}: ${res.statusText} ${
+              url || ''
+            }`
+          );
         return true;
       }
     }
     return false;
   },
+};
 ```
 
-
 ## Advanced usage
 
 We can garnish any request `init` object with some additional options as well as the full set of `RequestInit` options supported by the standard fetch implementation
@@ -99,10 +95,10 @@ We can garnish any request `init` object with some additional options as well as
 
 Uses `AbortController` signal instance to terminate the request after a specified timeout duration (in ms).
 
-```
+```javascript
 enterpriseFetch('https://httpbin.org/json', {
-    timeout: 5000,
-  })
+  timeout: 5000,
+})
   .then((res) => res.json())
   .then((json) => console.log(json));
 ```
@@ -115,15 +111,15 @@ e.g. wait 1000ms after first failed request, wait 1500ms between the second and
 
 This is simply the options object from https://www.npmjs.com/package/promise-retry
 
-```
+```javascript
 enterpriseFetch('https://httpbin.org/json', {
-    retry: {
-      retries: 3,
-      minTimeout: 1000,
-      factor: 500,
-    },
-    timeout: 5000,
-  })
+  retry: {
+    retries: 3,
+    minTimeout: 1000,
+    factor: 500,
+  },
+  timeout: 5000,
+})
   .then((res) => res.json())
   .then((json) => console.log(json));
 ```
@@ -134,49 +130,52 @@ Custom retry logic is required to exploit domain specific rules when deciding if
 
 For example, checking the headers for existance of a specific error key, or re-setting use-once headers such as an OAuth 1.0 bearer token for the next request
 
-```
+```javascript
 enterpriseFetch('https://httpbin.org/json', {
-    retry: {
-        retries: 3,
-        minTimeout: 1000,
-        factor: 500,
-    },
-    timeout: 5000,
-    doRetry: async (attempt, response, { options }) => {
-        const { retry } = options;
-        if (attempt <= retry.retries) {
+  retry: {
+    retries: 3,
+    minTimeout: 1000,
+    factor: 500,
+  },
+  timeout: 5000,
+  doRetry: async (attempt, response, { options }) => {
+    const { retry } = options;
+    if (attempt <= retry.retries) {
+      // Retry request on any network error,
+      // or any 4xx or 5xx status codes, except 404
+      if (!res.status || (res.status >= 400 && res.status !== 404)) {
         const counter = `${attempt}/${retry.retries}`;
-        console.warn(
-            `[fetch] Attempt ${counter} ${res.status}: ${res.statusText} ${url || ''}`
-        );
-
-        // Retry request on any network error, 
-        // or any 4xx or 5xx status codes, except 404
-        if (
-            (res.status >= 400 && res.status !== 404) ||
-            ('type' in res && res.type === 'aborted') ||
-            ('name' in res && res.name === 'AbortError') ||
-            ('code' in res && res.code === 'ETIMEDOUT')
-        ) {
-            return true;
-        }
-        }
-        return false;
-    },
-    })
-    .then((res) => res.json())
-    .then((json) => console.log(json));
+        if ('message' in res)
+          console.warn(
+            `[fetch] Attempt ${counter} ${
+              res.name || ('type' in res && res.type)
+            }: ${res.message} ${url || ''}`
+          );
+        else
+          console.warn(
+            `[fetch] Attempt ${counter} ${res.status}: ${res.statusText} ${
+              url || ''
+            }`
+          );
+        return true;
+      }
+    }
+    return false;
+  },
+})
+  .then((res) => res.json())
+  .then((json) => console.log(json));
 ```
 
 ## Application level retry policy
 
-Create a fetch retry policy that can be used throughout your application. 
+Create a fetch retry policy that can be used throughout your application.
 
 Create a configuration file in your app to define fetch defaults that can be applied to all requests using this fetch wrapper.
 
 You can then create an instance of `fetchWithDefaults(fetchDefaults)`, supplying your `fetchDefaults`. Then with this you can either redefine global fetch, or export the created instance of `fetchWithDefaults(fetchDefaults)` to import wherever it is needed in your app.
 
-```
+```javascript
 import { fetchWithDefaults } from 'enterprise-fetch';
 import { FetchInit } from 'enterprise-fetch/dist/models';
 
@@ -234,8 +233,66 @@ const fetch = fetchWithDefaults(fetchDefaults);
 export default fetch;
 ```
 
-## Proxying requests
+## Proxying requests (NodeJS)
 
 NodeJS only, we can leverage the `https-proxy-agent` to send our requests to a proxy server via the `agent` option in `RequestInit`, this is very useful for debugging and tracing fetch requests which is not natively possible with NodeJS.
 
-To activate set process env variable `http_proxy` to a valid http proxy server. e.g. `process.env.http_proxy = http://127.0.0.1:8888`
+To activate set process env variable `http_proxy` to a valid http proxy server. e.g. `process.env.http_proxy = http://127.0.0.1:8888`
+
+## Browser bundles
+
+Browser bundles are available for you to use if you are not using a module bundler for your application.
+
+### Simple example
+
+```html
+<html>
+  <head>
+    <script
+      type="text/javascript"
+      src="https://unpkg.com/enterprise-fetch"
+    ></script>
+    <script>
+      var element = function (id) {
+        return document.getElementById(id);
+      };
+      var goFetch = function () {
+        var uri = element('uri').value;
+        window['enterprise-fetch'].default(uri).then(function (response) {
+          alert(response.status);
+        });
+      };
+    </script>
+  </head>
+  <body>
+    <input type="text" id="uri" value="https://httpbin.org/status/500" />
+    <input type="button" id="fetch" value="Fetch" onclick="goFetch()" />
+  </body>
+</html>
+```
+
+### Legacy browsers
+
+A `cjs` bundle exists in addition to the `esm` bundle loaded by default if you require legacy browser support. The `cjs` bundle is 2x the size of the `esm` bundle due to the syntax transpilation and polyfills.
+
+Polyfills will be required for browsers that do not have native support for
+
+- AbortController
+- fetch
+
+You could use a polyfill service to polyfill missing features by adding a snippet like the below before loading this script
+```html
+<script
+  type="text/javascript"
+  src="https://polyfill.io/v3/polyfill.min.js?features=AbortController%2Cfetch"
+></script>
+```
+
+## Development scripts
+
+- `npm start` builds the library and runs through all tests in command line
+- `npm run build` build the library from source and create an instrumented copy of the build for coverage reporting
+- `npm test` starts a http server and runs through all tests in command line
+- `npm run cy:open` starts a http server and opens cypress testing gui for you to execute test specs interactively in a browser window
+- `npm run report:coverage` checks code coverage and starts a http server rendering the test coverage report for review in a browser
+- `npm run serve` starts a http server with a simple browser testing page available at the `/test` route