@selkirk-systems/fetch 0.1.6 → 1.0.2

package/README.md

@@ -1,61 +1,17 @@
-# Selkirk Fetch 
+# `Fetch`
 
-This is a wrapper for [isomorphic-fetch](https://github.com/matthew-andrews/isomorphic-fetch).
-All options provided by isomorphic-fetch are available by default. 
+Abortable Fetch Library
 
-
-### Notes
-This wrapper abstracts some additional config that selkirk would use 90% of the time.
-All config options can be overridden if needed
-
-Config
-- All Data sent and received assumed to be JSON
-- Anything set to the body property is automatically JSON.stringify
-- Method "GET" is assumed if not provided
-- Responses from the server are processed into JSON objects automatically.
-- Errors in responses are also processed and will cause a "catch" to fire based on httpResponseCodes
-
-
-### Component Example
-
-```
-const Fetch = require('selkirk-fetch');
-
-Fetch('/api', {
-        method: 'put',
-        body  : user
-    })
-   .then((response)=> {
-        //response is already processed into a valid obj and can be used as such
-        
-       Dispatcher.handleViewAction({
-           actionType: Constants.USER_SUBMITTED,
-           item      : response
-       })
-   })
-   .catch((err)=> {
-        //valid httpResponseCodes that are considered errors will trigger a catch (500,401) etc.
-        
-       _onError(err);
-       Dispatcher.handleViewAction({
-           actionType: Constants.USER_SUBMIT_FAILED,
-       })
-   })
+## Usage
 
 ```
+import { Fetch } from "@selkirk-systems/fetch";
 
-#### Boilerplate
-
-The package is based on [react-npm-boilerplate](https://github.com/juliancwirko/react-npm-boilerplate). This one is prepared to be used as a starter point for React components which needs to be published on Npm.
+export const fetchAgreementsByFiscalYear = ( year ) => {
 
-It includes linting with [ESLint](http://eslint.org/) and testing with [Mocha](https://mochajs.org/), [Enzyme](http://airbnb.io/enzyme/) and [JSDOM](https://github.com/tmpvar/jsdom).
+    dispatch( FETCH_AGREEMENTS );
 
-Also there is of course ES6 transpilation.
+    return Fetch( AGREEMENTS_LOOKUP_BY_FISCAL_YEAR_URL( { fiscalYear: year } ) ).then( respondWith( FETCHED_AGREEMENTS ) );
 
-#### Basic Usage
-
-1. Clone this repo
-2. Inside cloned repo run `npm install`
-3. If you want to run tests: `npm test` or `npm run testonly` or `npm run test-watch`. You need to write tests in `__tests__` folder. You need at least Node 4 on your machine to run tests.
-4. If you want to run linting: `npm test` or `npm run lint`. Fix bugs: `npm run lint-fix`. You can adjust your `.eslintrc` config file.
-5. If you want to run transpilation to ES5 in `dist` folder: `npm run prepublish` (standard npm hook).
+}
+```

package/dist/Download.js

@@ -0,0 +1,183 @@
+/* eslint-disable */
+
+//download.js v4.21, by dandavis; 2008-2018. [MIT] see http://danml.com/download.html for tests/usage
+// v1 landed a FF+Chrome compatible way of downloading strings to local un-named files, upgraded to use a hidden frame and optional mime
+// v2 added named files via a[download], msSaveBlob, IE (10+) support, and window.URL support for larger+faster saves than dataURLs
+// v3 added dataURL and Blob Input, bind-toggle arity, and legacy dataURL fallback was improved with force-download mime and base64 support. 3.1 improved safari handling.
+// v4 adds AMD/UMD, commonJS, and plain browser support
+// v4.1 adds url download capability via solo URL argument (same domain/CORS only)
+// v4.2 adds semantic variable names, long (over 2MB) dataURL support, and hidden by default temp anchors
+// https://github.com/rndme/download
+
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) {
+    // AMD. Register as an anonymous module.
+    define([], factory);
+  } else if (typeof exports === 'object') {
+    // Node. Does not work with strict CommonJS, but
+    // only CommonJS-like environments that support module.exports,
+    // like Node.
+    module.exports = factory();
+  } else {
+    // Browser globals (root is window)
+    root.download = factory();
+  }
+})(this, function () {
+  return function download(data, strFileName, strMimeType) {
+    var self = window,
+      // this script is only for browsers anyway...
+      defaultMime = "application/octet-stream",
+      // this default mime also triggers iframe downloads
+      mimeType = strMimeType || defaultMime,
+      payload = data,
+      url = !strFileName && !strMimeType && payload,
+      anchor = document.createElement("a"),
+      toString = function (a) {
+        return String(a);
+      },
+      myBlob = self.Blob || self.MozBlob || self.WebKitBlob || toString,
+      fileName = strFileName || "download",
+      blob,
+      reader;
+    myBlob = myBlob.call ? myBlob.bind(self) : Blob;
+    if (String(this) === "true") {
+      //reverse arguments, allowing download.bind(true, "text/xml", "export.xml") to act as a callback
+      payload = [payload, mimeType];
+      mimeType = payload[0];
+      payload = payload[1];
+    }
+    if (url && url.length < 2048) {
+      // if no filename and no mime, assume a url was passed as the only argument
+      fileName = url.split("/").pop().split("?")[0];
+      anchor.href = url; // assign href prop to temp anchor
+      if (anchor.href.indexOf(url) !== -1) {
+        // if the browser determines that it's a potentially valid url path:
+        var ajax = new XMLHttpRequest();
+        ajax.open("GET", url, true);
+        ajax.responseType = 'blob';
+        ajax.onload = function (e) {
+          download(e.target.response, fileName, defaultMime);
+        };
+        setTimeout(function () {
+          ajax.send();
+        }, 0); // allows setting custom ajax headers using the return:
+        return ajax;
+      } // end if valid url?
+    } // end if url?
+
+    //go ahead and download dataURLs right away
+    if (/^data:([\w+-]+\/[\w+.-]+)?[,;]/.test(payload)) {
+      if (payload.length > 1024 * 1024 * 1.999 && myBlob !== toString) {
+        payload = dataUrlToBlob(payload);
+        mimeType = payload.type || defaultMime;
+      } else {
+        return navigator.msSaveBlob ?
+        // IE10 can't do a[download], only Blobs:
+        navigator.msSaveBlob(dataUrlToBlob(payload), fileName) : saver(payload); // everyone else can save dataURLs un-processed
+      }
+    } else {
+      //not data url, is it a string with special needs?
+      if (/([\x80-\xff])/.test(payload)) {
+        var i = 0,
+          tempUiArr = new Uint8Array(payload.length),
+          mx = tempUiArr.length;
+        for (i; i < mx; ++i) tempUiArr[i] = payload.charCodeAt(i);
+        payload = new myBlob([tempUiArr], {
+          type: mimeType
+        });
+      }
+    }
+    blob = payload instanceof myBlob ? payload : new myBlob([payload], {
+      type: mimeType
+    });
+    function dataUrlToBlob(strUrl) {
+      var parts = strUrl.split(/[:;,]/),
+        type = parts[1],
+        indexDecoder = strUrl.indexOf("charset") > 0 ? 3 : 2,
+        decoder = parts[indexDecoder] == "base64" ? atob : decodeURIComponent,
+        binData = decoder(parts.pop()),
+        mx = binData.length,
+        i = 0,
+        uiArr = new Uint8Array(mx);
+      for (i; i < mx; ++i) uiArr[i] = binData.charCodeAt(i);
+      return new myBlob([uiArr], {
+        type: type
+      });
+    }
+    function saver(url, winMode) {
+      if ('download' in anchor) {
+        //html5 A[download]
+        anchor.href = url;
+        anchor.setAttribute("download", fileName);
+        anchor.className = "download-js-link";
+        anchor.innerHTML = "downloading...";
+        anchor.style.display = "none";
+        anchor.addEventListener('click', function (e) {
+          e.stopPropagation();
+          this.removeEventListener('click', arguments.callee);
+        });
+        document.body.appendChild(anchor);
+        setTimeout(function () {
+          anchor.click();
+          document.body.removeChild(anchor);
+          if (winMode === true) {
+            setTimeout(function () {
+              self.URL.revokeObjectURL(anchor.href);
+            }, 250);
+          }
+        }, 66);
+        return true;
+      }
+
+      // handle non-a[download] safari as best we can:
+      if (/(Version)\/(\d+)\.(\d+)(?:\.(\d+))?.*Safari\//.test(navigator.userAgent)) {
+        if (/^data:/.test(url)) url = "data:" + url.replace(/^data:([\w\/\-\+]+)/, defaultMime);
+        if (!window.open(url)) {
+          // popup blocked, offer direct download:
+          if (confirm("Displaying New Document\n\nUse Save As... to download, then click back to return to this page.")) {
+            location.href = url;
+          }
+        }
+        return true;
+      }
+
+      //do iframe dataURL download (old ch+FF):
+      var f = document.createElement("iframe");
+      document.body.appendChild(f);
+      if (!winMode && /^data:/.test(url)) {
+        // force a mime that will download:
+        url = "data:" + url.replace(/^data:([\w\/\-\+]+)/, defaultMime);
+      }
+      f.src = url;
+      setTimeout(function () {
+        document.body.removeChild(f);
+      }, 333);
+    } //end saver
+
+    if (navigator.msSaveBlob) {
+      // IE10+ : (has Blob, but not a[download] or URL)
+      return navigator.msSaveBlob(blob, fileName);
+    }
+    if (self.URL) {
+      // simple fast and modern way using Blob and URL:
+      saver(self.URL.createObjectURL(blob), true);
+    } else {
+      // handle non-Blob()+non-URL browsers:
+      if (typeof blob === "string" || blob.constructor === toString) {
+        try {
+          return saver("data:" + mimeType + ";base64," + self.btoa(blob));
+        } catch (y) {
+          return saver("data:" + mimeType + "," + encodeURIComponent(blob));
+        }
+      }
+
+      // Blob but not URL support:
+      reader = new FileReader();
+      reader.onload = function (e) {
+        saver(this.result);
+      };
+      reader.readAsDataURL(blob);
+    }
+    return true;
+  }; /* end download() */
+});

package/dist/FetchWrapper.js

@@ -0,0 +1,389 @@
+//Inspired by https://www.bennadel.com/blog/4180-canceling-api-requests-using-fetch-and-abortcontroller-in-javascript.htm
+
+import Download from './Download';
+import FetchErrorHandler from './middleware/FetchErrorHandler';
+
+// Regular expression patterns for testing content-type response headers.
+const RE_CONTENT_TYPE_JSON = /^application\/(x-)?json/i;
+const RE_CONTENT_TYPE_TEXT = /"^text\/"/i;
+const RE_QUERY_STRING = /\/.+\?/;
+const UNEXPECTED_ERROR_MESSAGE = "An unexpected error occurred while processing your request.";
+const CONTENT_TYPE_DOWNLOADS = {
+  'application/pdf': true,
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': true
+};
+//We store the original promise.catch so we can override it in some
+//scenarios when we want to swallow errors vs bubble them up.
+const ORIGINAL_CATCH_FN = Promise.prototype.catch;
+
+//Auto applied middleware that dispatches all errors so any UI's can respond.
+let _middlewares = [FetchErrorHandler];
+
+//Cache of request AbortController signals for auto request aborting.
+let _requests = {};
+
+/**
+ * PUBLIC: Apply custom middleware to act on any fetch responses and errors.
+ * 
+ * NOTE: Middleware can handle errors and swallow them by passing back a new error object.
+ * 
+ * @param {array} middleware 
+ */
+export function applyMiddleware(middleware = []) {
+  _middlewares = middleware;
+  _middlewares.push(FetchErrorHandler);
+}
+
+/**
+* Make the fetch request with the given configuration options.
+* 
+* GUARANTEE: All errors produced by this method will have consistent structure, even
+* if they are low-level networking errors. At a minimum, every Promise rejection will
+* have the following properties:
+*
+* TODO: Add support for multi-form uploads (images, files etc)
+* 
+* - data.type
+* - data.message
+* - status.code
+* - status.text
+* - status.isAbort
+*/
+export default function Fetch(url, options = {}) {
+  const config = {
+    downloadFileName: null,
+    contentType: "application/json",
+    headers: {
+      accept: "*/*"
+    },
+    credentials: "same-origin",
+    url: url || "",
+    urlTemplateData: {},
+    method: "GET",
+    params: {},
+    form: null,
+    json: null,
+    body: null,
+    signal: new AbortController(),
+    ...options,
+    _hasCatch: false,
+    _promiseChain: null,
+    _userSignal: Boolean(options.signal)
+  };
+  let finalHeaders, finalMethod, finalUrl, finalBody, finalSignal, request;
+  try {
+    finalHeaders = buildHeaders(config.headers);
+    finalMethod = config.method;
+    finalUrl = buildURL(config.url, config.urlTemplateData, config.params);
+    finalBody = config.body;
+    finalSignal = config.signal;
+
+    // Bail out early if url contains url params, 
+    //these should be set via the options.params object.
+    if (!config.url.href && RE_QUERY_STRING.test(config.url)) {
+      return Promise.reject(normalizeError({
+        type: "INVALID_URL",
+        message: `${config.url} contains query parameters: please use options.params object for this purpose.`
+      }, {}, {}, config));
+    }
+    if (CONTENT_TYPE_DOWNLOADS[config.contentType] && finalMethod === "GET") {
+      finalHeaders.credentials = "same-origin";
+      finalHeaders.accept = "*/*";
+    }
+    if (config.form) {
+      // For form data posts, we want the browser to build the Content-
+      // Type for us so that it puts in both the "multipart/form-data" plus the
+      // correct, auto-generated field delimiter.
+      delete finalHeaders["content-type"];
+      finalMethod = "POST";
+      finalBody = buildFormData(config.form);
+    } else if (config.json) {
+      finalHeaders["content-type"] = config.contentType || "application/x-json";
+      finalBody = JSON.stringify(config.json);
+    } else if (config.body) {
+      finalHeaders["content-type"] = config.contentType || "application/octet-stream";
+    } else {
+      finalHeaders["content-type"] = config.contentType;
+    }
+    request = new window.Request(finalUrl, {
+      headers: finalHeaders,
+      method: finalMethod,
+      body: finalBody,
+      signal: finalSignal.signal
+    });
+
+    //Check if a pending request is in-flight, if so and it is the exact same url abort it.
+    if (_requests[finalUrl]) {
+      _requests[finalUrl].abort();
+    }
+
+    //Cache requests abort signal by url
+    cacheRequestSignal(finalUrl, finalSignal);
+    config._promiseChain = Promise.resolve(window.fetch(request)).then(async response => {
+      deleteCachedRequestSignal(finalUrl);
+      const data = await unwrapResponseData(response);
+      if (response.ok) {
+        //Run response through middleware
+        const nextResp = _applyMiddleware(null, response, config);
+        if (config.downloadFileName) {
+          presetBrowserDownloadDialog(data, config);
+        }
+        return [{
+          request: request,
+          response: nextResp || response,
+          data: data
+        }, false];
+      }
+      return handleError(normalizeError(data, request, response, config), config);
+    }).catch(err => {
+      deleteCachedRequestSignal(finalUrl);
+      const error = isNormalizedError(err) ? err : normalizeTransportError(err);
+      return handleError(error, config);
+    });
+  } catch (err) {
+    deleteCachedRequestSignal(finalUrl);
+    return handleError(normalizeTransportError(err), config);
+  }
+  if (config._promiseChain) {
+    //If catch is added outside, then assume they want to handle errors and 
+    //not have them swallowed
+
+    config._promiseChain.catch = function (...args) {
+      config._hasCatch = true;
+      return ORIGINAL_CATCH_FN.apply(this, args);
+    };
+  }
+  return config._promiseChain;
+}
+
+/**
+ * Shows the browser download dialog
+ * @param {response.blob} blob 
+ * @param {object} config 
+ * @returns 
+ */
+function presetBrowserDownloadDialog(blob, config) {
+  return Download(blob, config.downloadFileName, config.contentType);
+}
+
+/**
+ * Stores a ref to the abort signal
+ * @param {string} url 
+ * @param {AbortController.signal} signal 
+ */
+function cacheRequestSignal(url, signal) {
+  _requests[url] = signal;
+}
+
+/**
+ * Deletes a req from the cached requests
+ * @param {string} url 
+ */
+function deleteCachedRequestSignal(url) {
+  delete _requests[url];
+}
+
+/**
+ * Checks if the error structure mimics ours and has already been normalized.
+ * @param {Object} err 
+ * @returns 
+ */
+function isNormalizedError(err) {
+  return err.hasOwnProperty("status") && err.hasOwnProperty("data");
+}
+
+/**
+ * Handles errors by passing them through any middleware and finally throwing them or swallowing them.
+ * @param {object} normalizedError 
+ * @param {object} config 
+ * @returns 
+ */
+function handleError(normalizedError, config) {
+  const hasCatch = config._hasCatch;
+  const promiseChain = config._promiseChain;
+  const nextErr = _applyMiddleware(normalizedError, null, config);
+
+  //Only swallow errors if they have been handled by middleware AND they have not 
+  //Added a catch outside
+  if (!hasCatch && !nextErr) {
+    if (promiseChain && promiseChain.cancel) promiseChain.cancel();
+    //In the case of aborted requests etc, we treat them as success and let the initial fetch chain 
+    //handle them.
+    return Promise.resolve([normalizedError, true]);
+  }
+
+  // The request failed in a critical way; the content of this error will be
+  // entirely unpredictable.
+  return Promise.reject(nextErr || normalizedError);
+}
+
+/**
+ * Passes any errors, responses through configured middleware
+ * 
+ * @param {ErrorEvent} err  the error.
+ * @param {Object} response the network response.
+ * @param {Object} options  the request options.
+ * @returns null
+ */
+function _applyMiddleware(err, response, options) {
+  let i = -1;
+  const next = function (nextErr, nextState) {
+    i++;
+    const middleware = _middlewares[i];
+    if (!middleware) return nextErr || nextState;
+    return middleware(nextErr)(nextState)(options)(next);
+  };
+  return next(err, response);
+}
+
+/**
+* Unwrap the response payload from the given response based on the reported
+* content-type.
+*/
+async function unwrapResponseData(response) {
+  var contentType = response.headers.has("content-type") ? response.headers.get("content-type") : "";
+  if (RE_CONTENT_TYPE_JSON.test(contentType)) {
+    return response.json();
+  } else if (RE_CONTENT_TYPE_TEXT.test(contentType)) {
+    return response.text();
+  } else {
+    return response.blob();
+  }
+}
+
+/**
+* FormData instance from the given object.
+* 
+* NOTE: At this time, only simple values (ie, no files) are supported.
+*/
+function buildFormData(form) {
+  var formData = new FormData();
+  Object.entries(form).forEach(([key, value]) => {
+    formData.append(key, value);
+  });
+  return formData;
+}
+
+/**
+ * Supports url or url with template identifiers,creates a url with optional query parameters.
+ * @param {string} url 
+ * @param {object} templateData 
+ * @param {object} params 
+ * @returns 
+ */
+function buildURL(url, templateData, params) {
+  if (url.href) return url;
+  const formattedUrl = buildURLTemplate(url, templateData);
+  const finalUrl = new URL(formattedUrl, `${window.location.origin}${window.baseUrl || ""}`);
+  const searchParams = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const e = value[i];
+        searchParams.append(key, e);
+      }
+      return;
+    }
+    searchParams.append(key, value);
+  });
+  finalUrl.search = searchParams;
+  return finalUrl;
+}
+
+/**
+ * Builds a urls tring using template identifiers.
+ * @param {string} url 
+ * @param {object} templateData 
+ */
+function buildURLTemplate(url, templateData) {
+  Object.entries(templateData).forEach(([key, value]) => {
+    url = url.replace(new RegExp(`{${key}}`, "ig"), value.toString());
+  });
+  return url;
+}
+
+/**
+* Transform the collection of HTTP headers into a like collection wherein the names
+* of the headers have been lower-cased. This way, if we need to manipulate the
+* collection prior to transport, we'll know what key-casing to use.
+*/
+function buildHeaders(headers) {
+  var lowercaseHeaders = {};
+  Object.entries(headers).forEach(([key, value]) => {
+    lowercaseHeaders[key.toLowerCase()] = value;
+  });
+  return lowercaseHeaders;
+}
+
+/**
+* At a minimum, we want every error to have the following properties:
+* 
+* - data.type
+* - data.message
+* - status.code
+* - status.text
+* - status.isAbort
+* 
+* These are the keys that the calling context will depend on; and, are the minimum
+* keys that the server is expected to return when it throws domain errors.
+*/
+function normalizeError(data, request, response, config) {
+  var error = {
+    data: {
+      type: "ServerError",
+      message: UNEXPECTED_ERROR_MESSAGE
+    },
+    status: {
+      code: response.status,
+      text: response.statusText,
+      isAbort: false
+    },
+    // The following data is being provided to make debugging AJAX errors easier.
+    request: request,
+    response: response,
+    config: config || {}
+  };
+
+  // If the error data is an Object (which it should be if the server responded
+  // with a domain-based error), then it should have "type" and "message"
+  // properties within it. That said, just because this isn't a transport error, it
+  // doesn't mean that this error is actually being returned by our application.
+  if (typeof data?.type === "string" && typeof data?.message === "string") {
+    Object.assign(error.data, data);
+
+    // If the error data has any other shape, it means that an unexpected error
+    // occurred on the server (or somewhere in transit). Let's pass that raw error
+    // through as the rootCause, using the default error structure.
+  } else {
+    error.data.rootCause = data;
+  }
+  return error;
+}
+
+/**
+* If our request never makes it to the server (or the round-trip is interrupted
+* somehow), we still want the error response to have a consistent structure with the
+* application errors returned by the server. At a minimum, we want every error to
+* have the following properties:
+* 
+* - data.type
+* - data.message
+* - status.code
+* - status.text
+* - status.isAbort
+*/
+function normalizeTransportError(transportError) {
+  const isAbort = transportError.name === "AbortError";
+  return {
+    data: {
+      type: "TransportError",
+      message: isAbort ? "Network Request Aborted" : UNEXPECTED_ERROR_MESSAGE,
+      rootCause: transportError
+    },
+    status: {
+      code: 0,
+      text: "Unknown",
+      isAbort: isAbort
+    }
+  };
+}

package/dist/constants/ErrorConstants.js

@@ -0,0 +1 @@
+export const ADD_ERROR = "ADD_ERROR";

package/dist/index.d.ts

@@ -0,0 +1 @@
+declare module '@selkirk-systems/fetch';