fch 3.0.0 → 3.0.1

package/fetch.js

@@ -145,8 +145,8 @@ const create = (defaults = {}) => {
       request = before(request);
     }
 
-    // It should be cached
-    if (dedupe) {
+    // It should be cached and it's not being manually manipulated
+    if (dedupe && !request.signal) {
       // It's already cached! Just return it
       if (dedupe.get()) return dedupe.get();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fch",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Fetch interface with better promises, deduplication, defaults, etc.",
   "homepage": "https://github.com/franciscop/fetch",
   "repository": "https://github.com/franciscop/fetch.git",

package/readme.md

@@ -4,7 +4,7 @@ A tiny library to make API calls easier. Similar to Axios, but tiny size and sim
 
 ```js
 import api from "fch";
-const mew = await api("https://pokeapi.co/pokemon/150");
+const mew = await api.get("https://pokeapi.co/pokemon/150");
 console.log(mew);
 ```
 
@@ -19,29 +19,30 @@ console.log(mew);
 - Configurable to return either just the body, or the full response.
 
 ```js
-// Calls and methods available:
-api(url, { method, body, headers, ...options })
+import api from 'fch';
+
 api.get(url, { headers, ...options })
 api.head(url, { headers, ...options })
 api.post(url, { body, headers, ...options })
 api.patch(url, { body, headers, ...options })
 api.put(url, { body, headers, ...options })
 api.del(url, { body, headers, ...options })
-fch.create({ url, body, headers, ...options})
-```
-
-|Options/variables |Default        |Description                                |
-|------------------|---------------|-------------------------------------------|
-|`url`             |`null`         |The path or full url for the request       |
-|`api.baseUrl`     |`null`         |The shared base of the API                 |
-|`api.method`      |`"get"`        |Default method to use for the call         |
-|`api.query`       |`{}`           |Add query parameters to the URL            |
-|`api.headers`     |`{}`           |Shared headers across all requests         |
-|`api.dedupe`      |`true`         |Reuse GET requests made concurrently       |
-|`api.output`      |`"body"`       |The return value of the API call           |
-|`api.before`      |`req => req`   |Process the request before sending it      |
-|`api.after`       |`res => res`   |Process the response before receiving it   |
-|`api.error`       |`err => reject(err)` |Process errors before returning them |
+
+api.create({ url, body, headers, ...options})
+```
+
+| Options   | Default            | Description                                 |
+|-----------|--------------------|---------------------------------------------|
+| `url`     | `null`             | The path or full url for the request        |
+| `baseUrl` | `null`             | The shared base of the API                  |
+| `method`  | `"get"`            | Default method to use for the call          |
+| `query`   | `{}`               | Add query parameters to the URL             |
+| `headers` | `{}`               | Shared headers across all requests          |
+| `dedupe`  | `true`             | Reuse GET requests made concurrently        |
+| `output`  | `"body"`           | The return value of the API call            |
+| `before`  | `req => req`       | Process the request before sending it       |
+| `after`   | `res => res`       | Process the response before returning it    |
+| `error`   | `err => throw err` | Process errors before returning them        |
 
 ## Getting Started
 
@@ -73,9 +74,10 @@ On the browser you can add it with a script and it will be available as `fch`:
 ```js
 import api from 'fch';
 
-// General options with their defaults; most of these are also parameters:
-api.baseUrl = null;  // Set an API endpoint
+// General options with their defaults; all of these are also parameters:
+api.baseUrl = null;  // Set an API base URL reused all across requests
 api.method = 'get';  // Default method to use for api()
+api.query = {};      // Is merged with the query parameters passed manually
 api.headers = {};    // Is merged with the headers on a per-request basis
 
 // Control simple variables
@@ -97,18 +99,54 @@ api.put(url, { body, headers, ... });
 // ...
 ```
 
-### URL
+### Method
+
+The HTTP method to make the request. When using the shorthand, it defaults to `GET`. We recommend using the method syntax:
+
+```js
+import api from 'fch';
+
+api.get('/cats');
+api.post('/cats', { body: { name: 'snowball' } });
+api.put(`/cats/3`, { body: { name: 'snowball' }});
+```
+
+You can use it with the plain function as an option parameter. The methods are all lowercase but the option as a parameter is case insensitive; it can be either uppercase or lowercase:
+
+```js
+// Recommended way of dealing with methods:
+api.get(...);
+
+// INVALID; won't work
+api.GET(...);
+
+// Both of these are valid:
+api({ method; 'GET' })
+api({ method; 'get'})
+```
+
+Example: adding a new cat and fixing a typo:
+
+```js
+import api from 'fch';
+
+const cats = await api.get('/cats');
+console.log(cats);
+const { id } = await api.post('/cats', { body: { name: 'snowbll' } });
+await api.put(`/cats/${id}`, { body: { name: 'snowball' }})
+```
+
+### Url
 
-This is normally the first argument, though technically you can use both styles:
+Specify where to send the request to. It's normally the first argument, though technically you can use both styles:
 
 ```js
-// All of these methods are valid
 import api from 'fch';
 
-// We strongly recommend using this style for your normal code:
+// Recommended way of specifying the Url
 await api.post('/hello', { body: '...', headers: {} })
 
-// Try to avoid these, but they are also valid:
+// These are also valid if you prefer their style; we won't judge
 await api('/hello', { method: 'post', body: '...', headers: {} });
 await api({ url: '/hello', method: 'post', headers: {}, body: '...' });
 await api.post({ url: '/hello', headers: {}, body: '...' });
@@ -123,9 +161,11 @@ api.get('/hello');
 // Called https//api.filemon.io/hello
 ```
 
+> Note: with Node.js you need to either set an absolute baseUrl or make the URL absolute
+
 ### Body
 
-The `body` can be a string, a plain object|array or a FormData instance. If it's an object, it'll be stringified and the header `application/json` will be added. Otherwise it'll be sent as plain text:
+The `body` can be a string, a plain object|array or a FormData instance. If it's an array or object, it'll be stringified and the header `application/json` will be added. Otherwise it'll be sent as plain text:
 
 ```js
 import api from 'api';
@@ -142,6 +182,46 @@ form.onsubmit = e => {
 };
 ```
 
+The methods `GET` and `HEAD` do not accept a body and it'll be ignored.
+
+The **response body** will be returned by default as the output of the call:
+
+```js
+const body = await api.get('/cats');
+console.log(body);
+// [{ id: 1, }, ...]
+```
+
+When the server specifies the header `Content-Type` as `application/json`, then we'll attempt to parse the response body and return that as the variable. Otherwise, the plain text will be returned.
+
+When the function returns the response (if you set `output: "response"` as an option), then the body can be accessed as `response.body`:
+
+```js
+const response = await api.get('/cats', { output: 'response' });
+console.log(response.body);
+// [{ id: 1, }, ...]
+```
+
+
+### Query
+
+You can easily pass GET query parameters by using the option `query`:
+
+```js
+api.get('/cats', { query: { limit: 3 } });
+// /cats?limit=3
+```
+
+While rare, some times you might want to persist a query parameter across requests and always include it; in that case, you can define it globally and it'll be added to every request:
+
+```js
+import api from 'fch';
+api.query.myparam = 'abc';
+
+api.get('/cats', { query: { limit: 3 } });
+// /cats?limit=3&myparam=abc
+```
+
 
 ### Headers
 
@@ -150,13 +230,28 @@ You can define headers globally, in which case they'll be added to every request
 
 ```js
 import api from 'fch';
-api.headers.abc = 'def';
 
-api.get('/helle', { headers: { ghi: 'jkl' } });
+// Globally, so they are reused across all requests
+api.headers.a = 'b';
+
+// With an interceptor, in case you need dynamic headers per-request
+api.before = req => {
+  req.headers.c = 'd';
+  return req;
+};
+
+// Set them for this single request:
+api.get('/hello', { headers: { e: 'f' } });
 // Total headers on the request:
-// { abc: 'def', ghi: 'jkl' }
+// { a: 'b', c: 'd', e: 'f' }
 ```
 
+When to use each?
+
+- If you need headers shared across all requests, like an API key, then the global one is the best place.
+- When you need to extract them dynamically from somewhere it's better to use the .before() interceptor. An example would be the user Authorization token.
+- When it changes on each request, it's not consistent or it's an one-off, use the option argument.
+
 
 ### Output
 
@@ -203,7 +298,7 @@ fch('/a', { dedupe: true });  // [DEFAULT] Dedupes GET requests
 fch('/a', { dedupe: false })  // All fetch() calls trigger a network call
 ```
 
-> We do not support deduping other methods right now besides `GET` right now
+> We do not support deduping other methods besides `GET` right now
 
 Note that opting out of deduping a request will _also_ make that request not be reusable, see this test for details:
 
@@ -387,6 +482,24 @@ fch.get('/hello');   // Gets http://localhost:3000/hello (or wherever you are)
 
 Note: for server-side (Node.js) usage, you always want to set `baseUrl`.
 
+### How to cancel an ongoing request?
+
+You can cancel ongoing requests [similarly to native fetch()](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort#examples), by passing it a signal:
+
+```js
+import api from 'fch';
+
+const controller = new AbortController();
+const signal = controller.signal;
+
+abortButton.addEventListener('click', () => {
+  controller.abort();
+  console.log('Download aborted');
+});
+
+api.get(url, { signal });
+```
+
 ### What are the differences in Node.js vs Browser?
 
 First, we use the native Node.js' fetch() and the browser's native fetch(), so any difference between those also applies to this library. For example, if you were to call `"/"` in the browser it'd refer to the current URL, while in Node.js it'd fail since you need to specify the full URL. Some other places where you might find differences: CORS, cache, etc.
@@ -417,4 +530,4 @@ API size is also strikingly different, with **7.8kb** for Axios and **1.9kb** fo
 As disadvantages, I can think of two major ones for `fch`:
 
 - Requires Node.js 18+, which is the version that includes `fetch()` by default.
-- Does not support some more advanced options,
+- Does not support many of the more advanced options, like `onUploadProgress` nor `onDownloadProgress`.