Merge pull request #130 from jmeas/2.0.0

2.0.0

Author: jamesplease

.eslintrc

@@ -9,13 +9,16 @@
     }
   },
   "rules": {
-    "no-unused-vars": "error"
+    "no-unused-vars": "error",
+    "react/jsx-uses-react": "error",
+    "react/jsx-uses-vars": "error"
   },
   "env": {
     "browser": true,
     "node": true
   },
   "globals": {
     "Promise": true
-  }
+  },
+  "plugins": ["react"]
 }

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+### v2.0.0 (2018/2/17)
+
+**Breaking**
+
+* `transformResponse` has been renamed to be `transformData`
+* `fetchPolicy` is now determined by the method that you pass in. This change was made to support using
+  POST methods for read requests, and is unlikely to break your code.
+* A new prop, `cacheResponse`, is used to determine if a response is added to the cache or
+  not. This is to support using POST methods for read requests, and is unlikely to break your code.
+
+**New Features**
+
+* A new `failed` property is passed to you in the render prop callback. This allows you to
+  quickly determine if a request failed for any reason (be it network errors or "error" status
+  codes).
+
 ### v1.1.0 (2018/2/7)
 
 **New Features**

README.md

@@ -198,8 +198,10 @@ The [render prop](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce)
 It is called with one argument, `result`, an object with the following keys:
 
 * `fetching`: A Boolean representing whether or not a request is currently in flight for this component
-* `error`: A Boolean representing if a network error occurred. Note that HTTP "error" status codes do not
-  cause `error` to be `true`; only failed or aborted network requests do. For more, see the
+* `failed`: A Boolean representing whether or not the request failed for any reason. This includes network
+  errors and status codes that are greater than or equal to`400`.
+* `error`: An error object representing a network error occurred. Note that HTTP "error" status codes do not
+  cause errors; only failed or aborted network requests do. For more, see the
   ["Using Fetch" MDN guide](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful).
 * `response`: An instance of [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). The
   [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Body) will already be read, and made
@@ -299,15 +301,15 @@ response is from the cache or from a network request. Receives two arguments:
 </Fetch>
 ```
 
-##### `transformResponse`
+##### `transformData`
 
 A function that is called with the data returned from the response. You can use this
 hook to transform the data before it is passed into `children`.
 
 ```jsx
 <Fetch
   url="/posts/2"
-  transformResponse={data => data.post>
+  transformData={data => data.post>
   {({ fetching, error, response, data }) => {
     <div>
       {fetching && ('Loading...')}
@@ -323,7 +325,7 @@ hook to transform the data before it is passed into `children`.
 </Fetch>
 ```
 
-> Note: `transformResponse` does not modify the value of `response.data`. The transformed data is
+> Note: `transformData` does not modify the value of `response.data`. The transformed data is
 > made available to you in the render prop argument under the `data` key.
 
 ##### `responseType`
@@ -395,11 +397,30 @@ This determines how the request interacts with the cache. Valid options are:
 * `"network-only"`
 * `"cache-only"`
 
-For documentation on this prop, refer to the [response caching guide](./docs/guides/response-caching.md).
+For documentation on what each of these values do, refer to the [response caching guide](./docs/guides/response-caching.md).
+
+The default value of this prop is based on the value of the `method` prop that you pass to `<Fetch/>`.
+
+| Method                   | Default value    |
+| ------------------------ | ---------------- |
+| GET, HEAD, OPTIONS       | `"cache-first"`  |
+| POST, PUT, PATCH, DELETE | `"network-only"` |
 
 > This prop behaves identically to the Apollo prop
 > [with the same name](https://www.apollographql.com/docs/react/basics/queries.html#graphql-config-options-fetchPolicy).
 
+##### `cacheResponse`
+
+Whether or not the response will be cached. The default value is based on the value of the `method` prop that you pass
+to `<Fetch/>`.
+
+| Method                   | Default value |
+| ------------------------ | ------------- |
+| GET, HEAD, OPTIONS       | `true`        |
+| POST, PUT, PATCH, DELETE | `false`       |
+
+For documentation on this prop, refer to the [response caching guide](./docs/guides/response-caching.md).
+
 ##### `dedupe`
 
 A Boolean value representing whether or not the request should be

docs/guides/best-practices.md

@@ -4,41 +4,56 @@ Here are some tips that may help you when using React Request.
 
 ### Handling errors
 
-It may seem like handling errors is as simple as checking for an `error` object
-within the render callback, but the `error` object is only included as an
-argument in the following situations:
+The `failed` Boolean is passed to the `children` callback, which
+represents whether _any_ error occurred with the request. This includes
+network requests or status codes greater than or equal to 400.
 
-1. A network error occurred, such as a timeout or a loss of network connection
-2. A new request "aborted" the previous one (meaning that the component
-   will ignore the response of the earlier request)
+This Boolean is convenient for a coarse understanding that the network
+failed, but using this Boolean alone is typically not enough to provide
+a great user experience. A user may want to know why the request
+failed. Was the resource not found? Did the user submit bad information?
+Was there a network error? Was the user logged out?
 
-There are other situations when most developers typically the component
-to be in an error state, such as when a 404 is returned.
+We encourage you to dig into the `error` and `response` objects
+to provide your users with a more detailed explanation of what went wrong,
+rather than displaying a generic "There was an error" message.
 
-The best way to cover all situations is by _also_ looking at the `response.ok` value.
-This is a Boolean that is `false` anytime that the `status` of the response
-is `>= 400`. So this will catch other errors such as Not Found errors, Unauthorized errors,
-and other client and server errors.
-
-Together, checking for `error` and `response.ok` should cover all possible
-situations when a request is "unsuccessful." The following example demonstrates
-this.
+Here is an example that shows the different kinds of ways that a response
+can error.
 
 ```js
 <Fetch {...fetchProps}>
-  {({ error, response }) => {
-    if (error || (response && !response.ok)) {
-      console.log('There was some kind of error.');
-    } else {
-      console.log('The request is either loading or it succeeded');
+  {({ failed, error, response }) => {
+    if (failed) {
+      console.log('There was _some_ kind of error. What happened?');
+    }
+
+    if (error) {
+      console.log('There was a network error');
+
+      if (navigation.onLine) {
+        console.log('The user lost internet connection.');
+      } else {
+        // You can look at the Error to learn more.
+        console.log('The request was aborted, or it timed out');
+      }
+    }
+
+    const status = response && response.status;
+
+    if (status === 404) {
+      console.log('The resource was not found.');
+    } else if (status === 401) {
+      console.log('You user have been logged out.');
+    } else if (status === 400) {
+      console.log('Invalid data was submitted');
+    } else if (status === 500) {
+      console.log('Something went wrong on the server.');
     }
   }}
 </Fetch>
 ```
 
-> Note: you can explain what has gone wrong to the user in greater detail by looking
-> at properties on the `error` object or the `response` object.
-
 ### Making "fetch components"
 
 HTTP requests require a lot of configuration, which can make your

docs/guides/response-caching.md

@@ -1,14 +1,23 @@
 # Response Caching
 
 React Request has a built-in response caching system. Interactions with the
-cache are configurable with the `fetchPolicy` prop.
+cache are configurable with the `fetchPolicy` and `cacheResponse` prop.
 
 The way the cache works is like this: any time a response from the server is received,
 it will be cached using the request's [request key](./request-keys.md). Subsequent
 requests are matched with existing cached server responses using _their_ request key.
 
+The `cacheResponse` prop determines if server responses will be cached. Typically,
+you only want to cache responses for "read" requests. Accordingly, the default
+value is based on the value of the `method` prop:
+
+| Method                   | Default value |
+| ------------------------ | ------------- |
+| GET, HEAD, OPTIONS       | `true`        |
+| POST, PUT, PATCH, DELETE | `false`       |
+
 There are four ways that a `<Fetch/>` component can interact with the
-cache.
+cached responses, which are configurable with the `fetchPolicy` prop:
 
 ### `cache-first`
 
@@ -34,3 +43,31 @@ The cache is ignored, and a network request is always made.
 
 If a response exists in the cache, then it will be returned. If no response
 exists in the cache, then an error will be passed into the render prop function.
+
+---
+
+Like `cacheResponse`, the default value of `fetchPolicy` is based on the method that you pass.
+
+| Method                   | Default value    |
+| ------------------------ | ---------------- |
+| GET, HEAD, OPTIONS       | `"cache-first"`  |
+| POST, PUT, PATCH, DELETE | `"network-only"` |
+
+### Using `POST` for read requests
+
+Some APIs use the `POST` method for read requests. React Request supports this, but you will
+need to manually configure the cache. This may look something like this:
+
+```jsx
+<Fetch
+  method="post"
+  url="/books/2"
+  cacheResponse
+  fetchPolicy="cache-first"
+  lazy={false}
+/>
+```
+
+With the above configuration, responses will be stored in the cache, and requests will
+only be made when the cache is empty. Also note that the [lazy prop](./using-the-lazy-prop.md)
+is set to `false` so that the request fires when the component mounts.

package.json

@@ -1,14 +1,14 @@
 {
   "name": "react-request",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Declarative HTTP requests with React.",
   "main": "lib/index.js",
   "module": "es/index.js",
   "scripts": {
     "clean": "rimraf dist es tmp lib",
     "test": "npm run lint && npm run test:unit",
     "test:unit": "jest",
-    "lint": "eslint src",
+    "lint": "eslint src test",
     "prepublish": "in-publish && npm run build || not-in-publish",
     "build": "npm run clean && npm run build:umd && npm run build:umd:min && npm run build:es && npm run build:commonjs",
     "build:commonjs": "cross-env BABEL_ENV=commonjs babel src --out-dir lib",
@@ -66,6 +66,7 @@
     "enzyme": "^3.3.0",
     "enzyme-adapter-react-16": "^1.1.1",
     "eslint": "^4.17.0",
+    "eslint-plugin-react": "^7.6.1",
     "fetch-mock": "^6.0.0",
     "in-publish": "^2.0.0",
     "jest": "^22.1.4",