@selkirk-systems/fetch 0.1.6 → 1.0.2

package/lib/FetchWrapper.js

@@ -0,0 +1,515 @@
+//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/lib/constants/ErrorConstants.js

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

package/lib/index.js

@@ -0,0 +1,3 @@
+export { default as Download } from './Download';
+export { default as fetch, applyMiddleware } from './FetchWrapper';
+export { ADD_ERROR } from "./constants/ErrorConstants";

package/lib/middleware/FetchErrorHandler.js

@@ -0,0 +1,42 @@
+import { dispatch } from "@selkirk-systems/state-management";
+import { ADD_ERROR } from "../constants/ErrorConstants";
+
+const handler = ( err ) => ( response ) => ( options ) => ( next ) => {
+    if ( err ) {
+        dispatch( ADD_ERROR, err );
+
+        return;
+    }
+
+    return next( null, response );
+};
+
+// NOTE: event name is all lower case as per DOM convention
+window.addEventListener( "unhandledrejection", function ( e ) {
+    // NOTE: e.preventDefault() must be manually called to prevent the default
+    // action which is currently to log the stack trace to console.warn
+    e.preventDefault();
+    // NOTE: parameters are properties of the event detail property
+    var reason = e.reason || e.detail.reason;
+    //var promise = e.detail.promise;
+    // See Promise.onPossiblyUnhandledRejection for parameter documentation
+    console.groupEnd();
+    console.groupEnd();
+    console.groupEnd();
+    throw reason;
+} );
+
+// NOTE: event name is all lower case as per DOM convention
+window.addEventListener( "rejectionhandled", function ( e ) {
+    // NOTE: e.preventDefault() must be manually called prevent the default
+    // action which is currently unset (but might be set to something in the future)
+    e.preventDefault();
+    // NOTE: parameters are properties of the event detail property
+    var promise = e.reason || e.detail.promise;
+    // See Promise.onUnhandledRejectionHandled for parameter documentation
+    console.groupEnd();
+    console.log( "REJECTION HANDLED", promise );
+} );
+
+export default handler;
+

package/lib/middleware/FetchLogger.js

@@ -0,0 +1,38 @@
+function getStatusCode(err) {
+    return err && err.response && err.response.statusCode ? err.response.statusCode : 500;
+}
+
+const FetchLogger = err => response => options => next => {
+    //Only log outputs for 'development' environment
+    if (process.env.NODE_ENV !== "development") return next(err, response);
+
+    const headerCSS = ['color:gray;font-weight:lighter'];
+    const bodyCSS = 'color:gray;font-weight:lighter';
+    const successCSS = 'color: green; font-weight:bold';
+    const errorCSS = 'color:red;font-weight:bold';
+    const responseCSS = 'color:#87A7DB;font-weight:bold';
+    const paramsCSS = 'color:orange;font-weight:bold';
+
+    if (err) {
+        headerCSS.push(errorCSS);
+        headerCSS.push(bodyCSS);
+
+        console.groupCollapsed(`%cfetch %cFAIL (${getStatusCode(err)}) %c${options.url}`, ...headerCSS);
+        console.log("error", err.response);
+    }
+    else {
+        headerCSS.push(successCSS);
+        headerCSS.push(bodyCSS);
+
+        console.groupCollapsed(`%cfetch %cSUCCESS %c${options.url}`, ...headerCSS);
+        console.log("%cerror", errorCSS, err);
+    }
+
+    console.log("%cresponse", responseCSS, response);
+    console.log("%cparams", paramsCSS, options);
+
+    console.groupEnd();
+
+    return next(err, response);
+}
+export default FetchLogger;

package/package.json

@@ -1,69 +1,39 @@
 {
   "name": "@selkirk-systems/fetch",
-  "version": "0.1.6",
-  "description": "A wrapper on fetch-polyfill that will work for server and client environments",
-  "selkirk": {
-    "bambooDeploy": "npm",
-    "bambooKey": "EDF",
-    "bambooUrl": [
-      "http://bamboo5.selkirksystems.com/browse/RCB-EDFDEF",
-      "http://bamboo5.selkirksystems.com/browse/RCB-EDFPUB"
-    ]
+  "version": "1.0.2",
+  "description": "Abortable fetch library",
+  "keywords": [],
+  "author": "Marcos Bernal <mbernal@selkirksystems.com>",
+  "license": "ISC",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "directories": {
+    "dist": "dist",
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "dist/**",
+    "lib/**"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://bitbucket.org/selkirk/selkirk-fetch.git"
+    "url": "git+https://galderak@bitbucket.org/selkirk/web-component-library.git"
   },
-  "author": "Marcos Bernal <mbernal@selkirksystems.com>",
-  "contributors": [
-    {
-      "name": "Marcos Bernal",
-      "email": "mbernal@selkirksystems.com"
-    }
-  ],
-  "homepage": "https://bitbucket.org/selkirk/selkirk-fetch/wiki/Home",
-  "keywords": [
-    "react-component",
-    "react",
-    "utility"
-  ],
   "scripts": {
-    "prepublish": "babel src --ignore __tests__ --out-dir ./dist",
-    "lint": "eslint ./src",
-    "lintfix": "eslint ./src --fix",
-    "testonly": "mocha --require scripts/mocha_runner src/**/__tests__/**/*.js",
-    "test": "npm run lint && npm run testonly",
-    "test-watch": "npm run testonly -- --watch --watch-extensions js"
+    "test": "node ./__tests__/**",
+    "docs": "jsdoc --configure ../../jsdoc.json -r ./lib -d docs",
+    "build": "del dist && cross-env CI=false NODE_ENV=production babel lib --out-dir dist --copy-files --ignore __tests__,spec.js,test.js,__snapshots__"
+  },
+  "bugs": {
+    "url": "https://bitbucket.org/selkirk/web-component-library/issues"
   },
-  "devDependencies": {
-    "babel-cli": "^6.6.4",
-    "babel-core": "^6.7.4",
-    "babel-eslint": "^6.0.2",
-    "babel-plugin-transform-es2015-modules-umd": "^6.6.5",
-    "babel-polyfill": "^6.7.4",
-    "babel-preset-es2015": "^6.6.0",
-    "babel-preset-react": "^6.5.0",
-    "babel-preset-stage-2": "^6.5.0",
-    "babelify": "^7.3.0",
-    "@selkirk-systems/bamboo-util": "~1.2.0",
-    "chai": "^3.5.0",
-    "enzyme": "^2.2.0",
-    "eslint": "^2.7.0",
-    "eslint-plugin-babel": "^3.1.0",
-    "eslint-plugin-react": "^4.2.3",
-    "gulp": "^3.9.1",
-    "gulp-concat": "^2.6.0",
-    "jsdom": "^8.1.0",
-    "mocha": "^2.4.5",
-    "nodemon": "^1.9.1",
-    "react-addons-test-utils": "^15.0.0",
-    "sinon": "^1.17.3"
+  "homepage": "https://bitbucket.org/selkirk/web-component-library#readme",
+  "peerDependencies": {
+    "@selkirk-systems/state-management": "^1.0.0"
   },
-  "dependencies": {
-    "babel-runtime": "^6.6.1",
-    "bluebird": "^3.4.6",
-    "es6-promise": "^4.2.2",
-    "isomorphic-fetch": "^2.2.1",
-    "object-assign": "^4.1.0"
-  }
-}
+  "gitHead": "5c983164ac8e9ba82f7029463483fe5635987802"
+}