README.md edits

Author: codeclown

Diff for: COMPARISON.md

@@ -0,0 +1,27 @@
+# Comparison to other AJAX libraries/solutions
+
+Explanations on why this library was made despite there being many libraries already out there.
+
+
+## Why not use fetch?
+
+[Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) is sometimes cumbersome:
+
+- Must set `Content-Type` header and encode body manually when sending JSON
+- Must call `response.json()` always when retrieving JSON
+- Forces proper CORS always
+- Does not reject on 4xx or 5xx responses status codes, only on network errors
+
+
+## Why not use axios?
+
+[Axios](https://github.com/axios/axios) has a history of issues related to global defaults and side-effects (some [severe](https://github.com/axios/axios/issues/385)). Some have been [fixed](https://github.com/axios/axios/pull/1395) but [more](https://github.com/axios/axios/pull/2207) still arise.
+
+It is cumbersome and error-prone to set request configuration with a (nested) object. Also, this design sometimes leads to cumbersome workarounds (e.g. [unsetting a header value](https://github.com/axios/axios/issues/382)).
+
+
+## Why not use jQuery.ajax?
+
+If you have it in your project, sure. Not that common anymore.
+
+Worth noting that older versions of jQuery, still widely in use, implement a [broken Promise implementation](https://stackoverflow.com/questions/23951745/is-any-jquery-version-compliant-to-promise-a-specifications/23958233#23958233).

Diff for: README.md

@@ -13,10 +13,13 @@
 - Understands Content-Type
   - Decodes JSON responses by default
 - [Works on modern browsers](#browser-support)
-  - No external dependencies
-  - See [polyfills](#polyfills) for a list of polyfills you might need for older browsers
+  - See [polyfills](#polyfills) for a list of polyfills if you target very old browsers
+- No external dependencies
+- Quite small (<2.5KB minified)
 - [Fully tested](/test/specs)
 
+Why not use fetch, axios, jQuery, etc..? See [COMPARISON.md](COMPARISON.md).
+
 
 ## Installation
 
@@ -158,6 +161,29 @@ console.log(req.toObject().url);
 
 The following methods are available.
 
+- [.get(url)](#get)
+- [.post(url)](#post)
+- [.method(method)](#method)
+- [.url(url)](#url)
+- [.baseUrl(url)](#baseurl)
+- [.query(object | string)](#query)
+- [.headers(object)](#headers)
+- [.amendHeaders(object)](#amendheaders)
+- [.header(key, value)](#header)
+- [.unsetHeader(name)](#unsetheader)
+- [.body(data)](#body)
+- [.json(value)](#json)
+- [.urlencoded(value)](#urlencoded)
+- [.timeout(milliseconds)](#timeout)
+- [.unsetTimeout()](#unsettimeout)
+- [.send([body])](#send)
+- [.sendUrlencoded(data)](#sendurlencoded)
+- [.sendJson(data)](#sendjson)
+- [.setResponseTransformers([])](#setresponsetransformers)
+- [.setAllowedStatusCode(allowed)](#setallowedstatuscode)
+- [.polyfills(polyfills)](#polyfills)
+- [.toObject() / .config() / .debug()](#toobject)
+
 ### get
 
 ```js
@@ -222,7 +248,7 @@ request.baseUrl('https://example.com/nested/foo').url('accounts')  // => https:/
 Sets query parameters from an object. Overwrites existing query.
 
 ```js
-.query(object)
+.query(object | string)
 ```
 
 Where `object` is key-value object of query parameters to set (will be encoded using `URLSearchParams#toString`), or a valid query string.
@@ -437,6 +463,15 @@ request.setResponseTransformers([
 ]);
 ```
 
+Reference to the original array is lost:
+
+```js
+const array = [];
+const req = request.setResponseTransformers(array);
+array.push(someFunction);
+req.toObject().responseTransformers; // not affected by the push, still []
+```
+
 ### setAllowedStatusCode
 
 By default any 2XX status code resolves the Promise and other status codes will reject it. This can be customized using `setAllowedStatusCode`.