fetch-xl

Fluent, interceptable and configurable fetch wrapper

Installation

npm install fetch-xl --save

Depending on your browser support, you will also need the fetch polyfill and a promise polyfill. See fetch polyfill for more details.

Key Concepts

RequestBuilder

• goal: fluent api to build a fetch Request (e.g. url, headers, body, etc.)

RequestBuilderXL

• goal: Enhanced fluent api RequestBuilder that also allows the configuration of request/response/error interceptors and some debug logging.

Interceptor

• goal:
  • to intercept the request before it's executed/fetched, or to intercept the response or error that's returned by the fetch action
  • multiple interceptors form an interceptorChain and pass the 'intercepted' request/response/error to the next interceptor
• config:
  • priority {number} : determines the order of the executed interceptors
  • intercept generator functions (see also below):
    • interceptRequest {generator} : to intercept the RequestBuilder before the actual Request is fetched
    • interceptResponse {generator} : to intercept a success response
    • interceptErrorResponse {generator} : to intercept an error response
• intercept generator functions:
  • use the power of generators (es6) and have a similar concept as redux-sagas:
    • fetch-xl takes care of some logic (like async/promise) behind the scenes
    • just yield the different steps the intercept method has to do
    • end the intercept by yielding (or returning) one of the possible propagateActions at the end
      • this yielded propagateAction determines the input of the next step in the interceptorChain
      • e.g. 'interceptRequest' can propagate the request (success flow) or can prohibit the execution of the actual fetch call by propagating a response or an error
    • you can use effectActions prior to yielding/returning a propagateAction
• propagateActions:
  • propagateRequest : to pass a (un)modified RequestBuilder down the interceptorChain
  • propagateResponse : to pass a success response back up the interceptorChain
  • propagateError : to pass an error response back up the interceptorChain
• effectActions:
  • awaitCall: if you need to call an asynchronous function (that returns a promise) during the intercept function. Yielding awaitCall will stop the intercept function until its promise is resolved. Surround it with a try-catch block if you want to handle the promise rejection.
  • you can add your own effectAction
• provided interceptors:
  • interceptRequest-interceptors:
    • jsonRequestInterceptor: to automatically stringify the 'body' to JSON
  • interceptResponse-interceptors:
    • jsonResponseInterceptor: to return the response as a JSON object
    • rejectHttpErrorStatusResponseInterceptor: to override the default fetch behaviour where HTTP error statusses do not result in a rejected promise
    • textResponseInterceptor: to return the response as text
  • ... list is still growing ... but you can easily add your own!

InterceptorBuilder

• goal: fluent api to build an interceptor

apiConfigurator

• goal:
  • fluent api to configure your fetch api/resources
  • api configurations can be done on multiple configuration levels - defaults, resource, action - where each level is in itself a RequestBuilder
    • the configurations are passed on to the lower level(s) so that e.g. the interceptors and baseUrl configured on the 'defaults' level will automatically be active on each 'lower' resource and action levels
  • multiple api's (with different baseUrl's) can be configured if needed, just call another apiConfigurator
• multiple configuration levels:
  • defaults: for the default configuration of the api, e.g. the baseUrl and interceptors and/or headers that have to be applied for all resources/actions
  • resource: for the configuration of a particular resource (a group of resource actions all sharing the same base url)
  • action: for the configuration of a specific action
  • Example - a typical use case could be:
    • defaults - http://some.site.com/rest/api
      • resource A - /users
        • action A1 - GET = to get all the users
        • action A2 - GET /:userId = to get a single user
      • resource B - /orders
        • action B1 - POST = to place an order (create)
        • action B2 - PUT /:orderId = to update an order

Usage

fetch-xl is still a 'Work In Progress' ... examples will follow

License

The MIT License