fch 3.0.4 → 4.0.0

package/fetch.min.js

@@ -1 +1 @@
-const hasPlainBody=e=>{if(!e.headers["content-type"]&&["object","array"].includes(typeof e.body)&&!(e.body instanceof FormData))return!0},createUrl=(e,t,r)=>{let[o,a={}]=e.split("?");const s=new URLSearchParams({...Object.fromEntries(new URLSearchParams(t)),...Object.fromEntries(new URLSearchParams(a))}).toString();if(s&&(o=o+"?"+s),!r)return o;return new URL(o,r).href},createHeaders=(e,t)=>{const r={...t,...e};for(let e in r){const t=r[e];delete r[e],r[e.toLowerCase()]=t}return r},createDedupe=(e,t)=>({save:r=>(e.set(t,r),r),get:()=>e.get(t),clear:()=>e.delete(t)}),createFetch=(e,{after:t,dedupe:r,error:o,output:a})=>fetch(e.url,e).then((async e=>{r&&r.clear();let s={status:e.status,statusText:e.statusText,headers:{}};for(let t of e.headers.keys())s.headers[t.toLowerCase()]=e.headers.get(t);if(!e.ok){const t=new Error(e.statusText);return t.response=s,o(t)}const d=e.headers.get("content-type").includes("application/json");return s.body=await(d?e.json():e.text()),t&&(s=t(s)),"body"===a?s.body:s})),create=(e={})=>{const t=new Map,r=async(e,o={})=>{"object"!=typeof o&&(o={}),o="string"==typeof e?{url:e,...o}:e||{};let{dedupe:a=r.dedupe,output:s=r.output,baseURL:d=r.baseURL,baseUrl:n=d||r.baseUrl,query:u={},before:c=r.before,after:h=r.after,error:p=r.error,...l}=o;if(u={...r.query,...u},l.url=createUrl(l.url??r.url,u,n),l.method=(l.method??r.method).toLowerCase(),l.headers=createHeaders(l.headers,r.headers),"get"!==l.method&&(a=!1),a&&(a=createDedupe(t,l.url)),!["body","response"].includes(s)){throw new Error(`options.output needs to be either "body" (default) or "response", not "${s}"`)}return hasPlainBody(l)&&(l.body=JSON.stringify(l.body),l.headers["content-type"]="application/json; charset=utf-8"),c&&(l=c(l)),a&&!l.signal?a.get()?a.get():a.save(createFetch(l,{dedupe:a,output:s,error:p,after:h})):createFetch(l,{output:s,error:p,after:h})};r.url=e.url??"/",r.method=e.method??"get",r.query=e.query??{},r.headers=e.headers??{},r.dedupe=e.dedupe??!0,r.output=e.output??"body",r.credentials=e.credentials??"include",r.before=e.before??(e=>e),r.after=e.after??(e=>e),r.error=e.error??(e=>Promise.reject(e));return r.get=(e,t={})=>r(e,{...t}),r.head=(e,t={})=>r(e,{...t,method:"head"}),r.post=(e,t={})=>r(e,{...t,method:"post"}),r.patch=(e,t={})=>r(e,{...t,method:"patch"}),r.put=(e,t={})=>r(e,{...t,method:"put"}),r.del=(e,t={})=>r(e,{...t,method:"delete"}),r.create=create,r},fch=create();window.fch=fch;
+const e=(e,{after:t,cache:r,error:o,output:a})=>fetch(e.url,e).then((async e=>{r&&r.clear();let s={status:e.status,statusText:e.statusText,headers:{}};for(let t of e.headers.keys())s.headers[t.toLowerCase()]=e.headers.get(t);if(!e.ok){const t=new Error(e.statusText);return t.response=s,o(t)}if(s=t(s),"stream"===a)return e.body;if(e[a]&&"function"==typeof e[a])return e[a]();const n=e.headers.get("content-type"),u=n&&n.includes("application/json");if(s.body=s.body||await(u?e.json():e.text()),"body"===a)return s.body;if("response"===a)return s;throw new Error(`Invalid option output="${a}"`)})),t=(r={})=>{const o=(()=>{const e=new Map;return t=>({save:r=>(e.set(t,r),r),get:()=>e.get(t),clear:()=>e.delete(t)})})(),a=async(t="/",r={})=>{"object"!=typeof r&&(r={}),r="string"==typeof t?{url:t,...r}:t;let{dedupe:s,output:n,before:u,after:d,error:c,...f}={...a,...r};f.url=((e,t,r)=>{let[o,a={}]=e.split("?");const s=new URLSearchParams({...Object.fromEntries(new URLSearchParams(t)),...Object.fromEntries(new URLSearchParams(a))}).toString();return s&&(o=o+"?"+s),r?new URL(o,r).href:o})(f.url,{...a.query,...r.query},f.baseUrl??f.baseURL),f.method=f.method.toLowerCase(),f.headers=(e=>{const t={};for(let[r,o]of Object.entries(e))t[r.toLowerCase()]=o;return t})({...a.headers,...r.headers});const p=!(!s||"get"!==f.method)&&o(f.url);var i;return"object"!=typeof(i=f.body)||i instanceof FormData||i.pipe||(f.body=JSON.stringify(f.body),f.headers["content-type"]="application/json"),f=u(f),p&&!f.signal?p.get()?p.get():p.save(e(f,{cache:p,output:n,error:c,after:d})):e(f,{output:n,error:c,after:d})};return a.url=r.url??"/",a.method=r.method??"get",a.query=r.query??{},a.headers=r.headers??{},a.baseUrl=r.baseUrl??r.baseURL??null,a.dedupe=r.dedupe??!0,a.output=r.output??"body",a.credentials=r.credentials??"include",a.before=r.before??(e=>e),a.after=r.after??(e=>e),a.error=r.error??(e=>{throw e}),["get","head","post","patch","put","delete"].map((e=>{a[e]=(t,r={})=>a(t,{...r,method:e})})),a.create=t,a};"undefined"!=typeof window&&(window.fch=t());export default t();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fch",
-  "version": "3.0.4",
+  "version": "4.0.0",
   "description": "Fetch interface with better promises, deduplication, defaults, etc.",
   "homepage": "https://github.com/franciscop/fetch",
   "repository": "https://github.com/franciscop/fetch.git",
@@ -9,7 +9,8 @@
   "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
   "license": "MIT",
   "scripts": {
-    "build": "terser --compress --mangle -- ./fetch.js | sed 's/export default fch;/window.fch=fch;/g' > ./fetch.min.js",
+    "build": "terser --compress --mangle --toplevel -o ./fetch.min.js -- ./fetch.js",
+    "size": "echo $(gzip -c fetch.min.js | wc -c) bytes",
     "start": "npm run watch # Start ~= Start dev",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --detectOpenHandles",
     "watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch --coverage --detectOpenHandles"
@@ -22,11 +23,8 @@
     "async",
     "ajax"
   ],
-  "main": "./fetch.js",
-  "module": "./fetch.js",
-  "browser": "./fetch.min.js",
+  "main": "./fetch.min.js",
   "files": [
-    "fetch.js",
     "fetch.min.js"
   ],
   "type": "module",

package/readme.md

@@ -3,47 +3,53 @@
 A tiny library to make API calls easier. Similar to Axios, but tiny size and simpler API:
 
 ```js
-import api from "fch";
-api.baseUrl = "https://pokeapi.co/";
-const mew = await api.get("/pokemon/150");
+// Plain usage
+import fch from "fch";
+const mew = await fch("https://pokeapi.co/pokemon/150");
 console.log(mew);
+
+// As an API abstraction
+const api = fch.create({ baseUrl: "https://pokeapi.co/" });
+const mew = await api.get("/pokemon/150");
+await api.patch("/pokemon/150", { body: { type: "psychic" } });
 ```
 
 - Create instances with shared options across requests.
 - Automatically encode object and array bodies as JSON.
 - Automatically decode JSON responses based on the headers.
 - Await/Async Promises; `>= 400 and <= 100` will _reject_ with an error.
+- Credentials: "include" by default
 - Interceptors: `before` the request, `after` the response and catch with `error`.
 - Deduplicates parallel GET requests.
 - Works the same way in Node.js and the browser.
 - No dependencies; include it with a simple `<script>` on the browser.
 
 ```js
-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 })
-
-api.create({ url, body, headers, ...options})
-```
+import api from "fch";
 
-| Options               | Default   | Description                        |
-| ----------------------| ----------| -----------------------------------|
-| [`method`](#method)   | `"get"`   | Default method to use for the call |
-| [`url`](#url)         | `null`    | The path or url for the request    |
-| [`baseUrl`](#url)     | `null`    | The shared base of the API         |
-| [`body`](#body)       | `null`    | The body to send with the request  |
-| [`query`](#query)     | `{}`      | Add query parameters to the URL    |
-| [`headers`](#headers) | `{}`      | Shared headers across all requests |
-| [`output`](#output)   | `"body"`  | The return value of the API call   |
-| [`dedupe`](#dedupe)   | `true`    | Reuse concurrently GET requests    |
-| [`before`](#interceptors) |`req => req`       |Process the request before sending it    |
-| [`after`](#interceptors)  |`res => res`       |Process the response before returning it |
-| [`error`](#interceptors)  |`err => throw err` |Process errors before returning them     |
+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.delete(url, { body, headers, ...options });
+
+api.create({ url, body, headers, ...options });
+```
+
+| Options                   | Default            | Description                              |
+| ------------------------- | ------------------ | ---------------------------------------- |
+| [`method`](#method)       | `"get"`            | Default method to use for the call       |
+| [`url`](#url)             | `"/"`              | The path or url for the request          |
+| [`baseUrl`](#url)         | `null`             | The shared base of the API               |
+| [`body`](#body)           | `null`             | The body to send with the request        |
+| [`query`](#query)         | `{}`               | Add query parameters to the URL          |
+| [`headers`](#headers)     | `{}`               | Shared headers across all requests       |
+| [`output`](#output)       | `"body"`           | The return value of the API call         |
+| [`dedupe`](#dedupe)       | `true`             | Reuse concurrently GET requests          |
+| [`before`](#interceptors) | `req => req`       | Process the request before sending it    |
+| [`after`](#interceptors)  | `res => res`       | Process the response before returning it |
+| [`error`](#interceptors)  | `err => throw err` | Process errors before returning them     |
 
 ## Getting Started
 
@@ -56,17 +62,17 @@ npm install fch
 Then import it to be able to use it in your code:
 
 ```js
-import fch from 'fch';
-const body = await fch.get('/');
+import fch from "fch";
+const body = await fch.get("/");
 ```
 
 On the browser you can add it with a script and it will be available as `fch`:
 
 ```html
 <!-- Import it as usual -->
-<script src="https://cdn.jsdelivr.net/npm/fch"></script>
-<script>
-  fch('/hello');
+<script src="https://cdn.jsdelivr.net/npm/fch" type="module"></script>
+<script type="module">
+  fch("/hello");
 </script>
 ```
 
@@ -75,23 +81,23 @@ On the browser you can add it with a script and it will be available as `fch`:
 These are all available options and their defaults:
 
 ```js
-import api from 'fch';
+import api from "fch";
 
 // General options with their defaults; all of these are also parameters:
-api.method = 'get';  // Default method to use for api()
-api.url = '/';       // Relative or absolute url where the request is sent
-api.baseUrl = null;  // Set an API base URL reused all across requests
-api.query = {};      // Merged with the query parameters passed manually
-api.headers = {};    // Merged with the headers on a per-request basis
+api.method = "get"; // Default method to use for api()
+api.url = "/"; // Relative or absolute url where the request is sent
+api.baseUrl = null; // Set an API base URL reused all across requests
+api.query = {}; // Merged with the query parameters passed manually
+api.headers = {}; // Merged with the headers on a per-request basis
 
 // Control simple variables
-api.output = 'body'; // Return the body; use 'response' for the full response
-api.dedupe = true;   // Avoid sending concurrent GET requests to the same path
+api.output = "body"; // Return the parsed body; use 'response' or 'stream' otherwise
+api.dedupe = true; // Avoid sending concurrent GET requests to the same path
 
 // Interceptors
-api.before = req => req;
-api.after = res => res;
-api.error = err => Promise.reject(err);
+api.before = (req) => req;
+api.after = (res) => res;
+api.error = (err) => Promise.reject(err);
 ```
 
 They can all be defined globally as shown above, passed manually as the options argument, or be used when [creating a new instance](#create-an-instance).
@@ -101,11 +107,11 @@ They can all be defined globally as shown above, passed manually as the options
 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';
+import api from "fch";
 
-api.get('/cats');
-api.post('/cats', { body: { name: 'snowball' } });
-api.put(`/cats/3`, { body: { name: 'snowball' }});
+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:
@@ -125,12 +131,12 @@ api({ method; 'get'})
 Example: adding a new cat and fixing a typo:
 
 ```js
-import api from 'fch';
+import api from "fch";
 
-const cats = await api.get('/cats');
+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' }})
+const { id } = await api.post("/cats", { body: { name: "snowbll" } });
+await api.put(`/cats/${id}`, { body: { name: "snowball" } });
 ```
 
 ### Url
@@ -138,23 +144,23 @@ await api.put(`/cats/${id}`, { body: { name: 'snowball' }})
 Specify where to send the request to. It's normally the first argument, though technically you can use both styles:
 
 ```js
-import api from 'fch';
+import api from "fch";
 
 // Recommended way of specifying the Url
-await api.post('/hello', { body: '...', headers: {} })
+await api.post("/hello", { body: "...", headers: {} });
 
 // 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: '...' });
+await api("/hello", { method: "post", body: "...", headers: {} });
+await api({ url: "/hello", method: "post", headers: {}, body: "..." });
+await api.post({ url: "/hello", headers: {}, body: "..." });
 ```
 
 It can be either absolute or relative, in which case it'll use the local one in the page. It's recommending to set `baseUrl`:
 
 ```js
-import api from 'fch';
-api.baseUrl = 'https//api.filemon.io/';
-api.get('/hello');
+import api from "fch";
+api.baseUrl = "https//api.filemon.io/";
+api.get("/hello");
 // Called https//api.filemon.io/hello
 ```
 
@@ -183,8 +189,10 @@ 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:
 
+> See more info in [**Output**](#output)
+
 ```js
-const body = await api.get('/cats');
+const body = await api.get("/cats");
 console.log(body);
 // [{ id: 1, }, ...]
 ```
@@ -194,51 +202,48 @@ When the server specifies the header `Content-Type` as `application/json`, then
 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' });
+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 } });
+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';
+import api from "fch";
+api.query.myparam = "abc";
 
-api.get('/cats', { query: { limit: 3 } });
+api.get("/cats", { query: { limit: 3 } });
 // /cats?limit=3&myparam=abc
 ```
 
-
 ### Headers
 
 You can define headers globally, in which case they'll be added to every request, or locally, so that they are only added to the current request. You can also add them in the `before` callback:
 
-
 ```js
-import api from 'fch';
+import api from "fch";
 
 // Globally, so they are reused across all requests
-api.headers.a = 'b';
+api.headers.a = "b";
 
 // With an interceptor, in case you need dynamic headers per-request
-api.before = req => {
-  req.headers.c = 'd';
+api.before = (req) => {
+  req.headers.c = "d";
   return req;
 };
 
 // Set them for this single request:
-api.get('/hello', { headers: { e: 'f' } });
+api.get("/hello", { headers: { e: "f" } });
 // Total headers on the request:
 // { a: 'b', c: 'd', e: 'f' }
 ```
@@ -249,31 +254,49 @@ When to use each?
 - 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
 
 This controls whether the call returns just the body (default), or the whole response. It can be controlled globally or on a per-request basis:
 
 ```js
-import api from 'fch';
-
-// "body" (default) or "response"
-api.output = 'body';
-
-// Return only the body, this is the default
-const body = await api.get('/data');
+// Return only the body (default)
+const body = await api.get("/data");
 
 // Return the whole response (with .body):
-const response = await api.get('/data', { output: 'response' });
+const response = await api.get("/data", { output: "response" });
+
+// Return a plain body stream
+const stream = await api.get("/data", { output: "stream" });
+stream.pipeTo(outStream);
 
-// Throws error
-const invalid = await api.get('/data', { output: 'invalid' });
+// Return a blob, since `response.blob()` is available:
+const blob = await api.get("/data", { output: "blob" });
 ```
 
+There are few options that can be specified:
+
+- `output: "body"` (default): returns the body, parsed as JSON or plain TEXT depending on the headers.
+- `output: "response"`: return the full response with the properties `body`, `headers`, `status`, etc. The body will be parsed as JSON or plain TEXT depending on the headers. If you want the raw `response`, use `raw` or `clone` instead (see below in "raw" or "METHODS").
+- `output: "stream"`: return a [web ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) of the body as the result of the promise.
+- Any of [the valid methods](https://developer.mozilla.org/en-US/docs/Web/API/Response#methods):
+  - `output: "arrayBuffer"`: returns an arrayBuffer of the response body.
+  - `output: "blob"`: returns an arrayBuffer of the response body.
+  - `output: "clone"`: returns the raw Response, with the raw body. See also `raw` below.
+  - `output: formData`: returns an instance of FormData with all the parsed data.
+  - `output: json`: attempts to parse the response as JSON.
+  - `output: text`: puts the response body as plain text.
+- `output: "raw"`: an alias for `clone`, returning the raw response (after passing through `after`).
+
+For example, return the raw body as a `ReadableStream` with the option `stream`:
+
+```js
+const stream = await api.get('/cats', { output: 'stream' });
+stream.pipeTo(...);
+```
 
 ### Dedupe
 
-When you perform a GET request to a given URL, but another GET request *to the same* URL is ongoing, it'll **not** create a new request and instead reuse the response when the first one is finished:
+When you perform a GET request to a given URL, but another GET request _to the same_ URL is ongoing, it'll **not** create a new request and instead reuse the response when the first one is finished:
 
 ```js
 fetch.mockOnce("a").mockOnce("b");
@@ -287,12 +310,12 @@ You can disable this by setting either the global `fch.dedupe` option to `false`
 
 ```js
 // Globally set it for all calls
-fch.dedupe = true;  // [DEFAULT] Dedupes GET requests
+fch.dedupe = true; // [DEFAULT] Dedupes GET requests
 fch.dedupe = false; // All fetch() calls trigger a network call
 
 // Set it on a per-call basis
-fch('/a', { dedupe: true });  // [DEFAULT] Dedupes GET requests
-fch('/a', { dedupe: false })  // All fetch() calls trigger a network call
+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 besides `GET` right now
@@ -305,7 +328,7 @@ it("can opt out locally", async () => {
   const res = await Promise.all([
     fch("/a"),
     fch("/a", { dedupe: false }),
-    fch("/a"),  // Reuses the 1st response, not the 2nd one
+    fch("/a"), // Reuses the 1st response, not the 2nd one
   ]);
 
   expect(res).toEqual(["a", "b", "a"]);
@@ -317,6 +340,12 @@ it("can opt out locally", async () => {
 
 You can also easily add the interceptors `before`, `after` and `error`:
 
+- `before`: Called when the request is fully formed, but before actually launching it.
+- `before`: Called just after the response is created and if there was no error, but before parsing anything else.
+- `error`: When the response is not okay, if possible it'll include the `response` object.
+
+> Note: interceptors are never deduped/cached and always execute once per call, even if the main async fetch() has been deduped.
+
 ```js
 // Perform an action or request transformation before the request is sent
 fch.before = async req => {
@@ -346,7 +375,6 @@ fch.error = async err => {
 };
 ```
 
-
 ## How to
 
 ### Stop errors from throwing
@@ -354,10 +382,11 @@ fch.error = async err => {
 While you can handle this on a per-request basis, if you want to overwrite the global behavior you can write a interceptor:
 
 ```js
-import fch from 'fch';
-fch.error = error => error.response;
+import fch from "fch";
+fch.output = "response";
+fch.error = (error) => error.response;
 
-const res = await fch('/notfound');
+const res = await fch("/notfound");
 expect(res.status).toBe(404);
 ```
 
@@ -366,75 +395,83 @@ expect(res.status).toBe(404);
 By default a successful request will just return the data. However this one is configurable on a global level:
 
 ```js
-import fch from 'fch';
-fch.output = 'response';  // Valid values are 'body' (default) or 'response'
+import fch from "fch";
+fch.output = "response";
 
-const res = await fch('/hello');
+const res = await fch("/hello");
+console.log(res.status);
 ```
 
 Or on a per-request level:
 
 ```js
-import fch from 'fch';
+import fch from "fch";
 
 // Valid values are 'body' (default) or 'response'
-const res = await fch('/hello', { output: 'response' });
+const res = await fch("/hello", { output: "response" });
 
 // Does not affect others
-const body = await fch('/hello');
+const body = await fch("/hello");
 ```
 
+It does perform some basic parsing of the `body`, if you don't want any of that you can retrieve the very raw response:
+
+```js
+import fch from "fch";
+
+// Valid values are 'body' (default) or 'response'
+const res = await fch("/hello", { output: "raw" });
+console.log(res.body); // ReadableStream
+```
 
 ### Set a base URL
 
 There's a configuration parameter for that:
 
 ```js
-import fch from 'fch';
-fch.baseUrl = 'https://api.filemon.io/';
+import fch from "fch";
+fch.baseUrl = "https://api.filemon.io/";
 
 // Calls "https://api.filemon.io/blabla"
-const body = await fch.get('/blabla');
+const body = await fch.get("/blabla");
 ```
 
-
 ### Set authorization headers
 
 You can set that globally as a header:
 
 ```js
-import fch from 'fch';
-fch.headers.Authorization = 'bearer abc';
+import fch from "fch";
+fch.headers.Authorization = "bearer abc";
 
-const me = await fch('/users/me');
+const me = await fch("/users/me");
 ```
 
 Or globally on a per-request basis, for example if you take the value from localStorage:
 
 ```js
-import fch from 'fch';
+import fch from "fch";
 
 // All the requests will add the Authorization header when the token is
 // in localStorage
-fch.before = req => {
-  if (localStorage.get('token')) {
-    req.headers.Authorization = 'bearer ' + localStorage.get('token');
+fch.before = (req) => {
+  if (localStorage.get("token")) {
+    req.headers.Authorization = "bearer " + localStorage.get("token");
   }
   return req;
 };
 
-const me = await fch('/users/me');
+const me = await fch("/users/me");
 ```
 
 Or on a per-request basis, though we wouldn't recommend this:
 
 ```js
-import fch from 'fch';
+import fch from "fch";
 
-const me = await fch('/users/me', { headers: { Authorization: 'bearer abc' } });
+const me = await fch("/users/me", { headers: { Authorization: "bearer abc" } });
 ```
 
-
 ### Create an instance
 
 You can create an instance with its own defaults and global options easily. It's common when writing an API that you want to encapsulate away:
@@ -453,28 +490,47 @@ 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`.
 
+### Streaming a response body
+
+To stream the body, you need to use the `output: "stream"` option so that it returns a [WebStream ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream):
+
+```js
+import fch from "fch";
+
+// Valid values are 'body' (default) or 'response'
+const stream = await fch("/data", { output: "stream" });
+stream.pipeTo(outStream);
+```
 
+You might want to convert it to a Node.js ReadStream:
+
+```js
+import fch from "fch";
+import { Readable } from "node:stream";
+
+const stream = await fch("/data", { output: "stream" });
+const readableNodeStream = Readable.fromWeb(stream);
+// ...
+```
 
 ### Cancel ongoing requests
 
 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';
+import api from "fch";
 
 const controller = new AbortController();
 const signal = controller.signal;
 
-abortButton.addEventListener('click', () => {
+abortButton.addEventListener("click", () => {
   controller.abort();
-  console.log('Download aborted');
+  console.log("Download aborted");
 });
 
 api.get(url, { signal });
 ```
 
-
-
 ### Define shared options
 
 You can also define values straight away:
@@ -490,28 +546,24 @@ console.log(mew);
 
 You can also [create an instance](#create-an-instance) that will have the same options for all requests made with that instance.
 
-
-
 ### 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.
 
 In the library itself there's nothing different between the browser and Node.js, but it might be interesting to note that (if/when implemented) things like cache, etc. in Node.js are normally long-lived and shared, while in a browser request it'd bound to the request itself.
 
-
-
 ### Differences with Axios
 
 The main difference is that things are simplified with fch:
 
 ```js
 // Modify headers
-axios.defaults.headers.Authorization = '...';
-fch.headers.Authorization = '...';
+axios.defaults.headers.Authorization = "...";
+fch.headers.Authorization = "...";
 
 // Set a base URL
-axios.defaults.baseURL = '...';
-fch.baseUrl = '...';
+axios.defaults.baseURL = "...";
+fch.baseUrl = "...";
 
 // Add an interceptor
 axios.interceptors.request.use(fn);
@@ -524,3 +576,17 @@ 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 many of the more advanced options, like `onUploadProgress` nor `onDownloadProgress`.
+
+## Releases
+
+### V4
+
+Breaking changes:
+
+- Only ESM exports. Meaning, if you use it in a browser you'll need the `<script type="module">`.
+- The method `fch.del()` (and derivates with fch.create()) have been renamed to `fch.delete()`.
+
+Changes:
+
+- Added `output` options: `raw`, `stream`, `arrayBuffer`, `blob`, `clone`, `formData`, `json`, `text`
+- Gone from 1.2kb down to 1.0kb

package/fetch.js

@@ -1,200 +0,0 @@
-// Plain-ish object
-const hasPlainBody = (options) => {
-  if (options.headers["content-type"]) return;
-  if (!["object", "array"].includes(typeof options.body)) return;
-  if (options.body instanceof FormData) return;
-  return true;
-};
-
-const createUrl = (url, query, base) => {
-  let [path, urlQuery = {}] = url.split("?");
-
-  // Merge global params with passed params with url params
-  const entries = new URLSearchParams({
-    ...Object.fromEntries(new URLSearchParams(query)),
-    ...Object.fromEntries(new URLSearchParams(urlQuery)),
-  }).toString();
-  if (entries) {
-    path = path + "?" + entries;
-  }
-
-  if (!base) return path;
-  const fullUrl = new URL(path, base);
-  return fullUrl.href;
-};
-
-const createHeaders = (user, base) => {
-  // User-set headers overwrite the base headers
-  const headers = { ...base, ...user };
-
-  // Make the headers lowercase
-  for (let key in headers) {
-    const value = headers[key];
-    delete headers[key];
-    headers[key.toLowerCase()] = value;
-  }
-
-  return headers;
-};
-
-const createDedupe = (ongoing, url) => ({
-  save: (prom) => {
-    ongoing.set(url, prom);
-    return prom;
-  },
-  get: () => ongoing.get(url),
-  clear: () => ongoing.delete(url),
-});
-
-const createFetch = (request, { after, dedupe, error, output }) => {
-  return fetch(request.url, request).then(async (res) => {
-    // No longer ongoing at this point
-    if (dedupe) dedupe.clear();
-
-    // Need to manually create it to set some things like the proper response
-    let response = {
-      status: res.status,
-      statusText: res.statusText,
-      headers: {},
-    };
-    for (let key of res.headers.keys()) {
-      response.headers[key.toLowerCase()] = res.headers.get(key);
-    }
-
-    // Oops, throw it
-    if (!res.ok) {
-      const err = new Error(res.statusText);
-      err.response = response;
-      return error(err);
-    }
-
-    // Automatically parse the response
-    const isJson = res.headers.get("content-type").includes("application/json");
-    response.body = await (isJson ? res.json() : res.text());
-
-    // Hijack the response and modify it
-    if (after) {
-      response = after(response);
-    }
-
-    if (output === "body") {
-      return response.body;
-    } else {
-      return response;
-    }
-  });
-};
-
-const create = (defaults = {}) => {
-  // DEDUPLICATION is created on a per-instance basis
-  // To avoid making parallel requests to the same url if one is ongoing
-  const ongoing = new Map();
-
-  const fch = async (url, options = {}) => {
-    // Second parameter always has to be an object, even when it defaults
-    if (typeof options !== "object") options = {};
-
-    // Accept either fch(options) or fch(url, options)
-    options = typeof url === "string" ? { url, ...options } : url || {};
-
-    // Exctract the options
-    let {
-      dedupe = fch.dedupe,
-      output = fch.output,
-      baseURL = fch.baseURL, // DO NOT USE; it's here only for user friendliness
-      baseUrl = baseURL || fch.baseUrl,
-
-      // Extract it since it should not be part of fetch()
-      query = {},
-
-      // Interceptors can also be passed as parameters
-      before = fch.before,
-      after = fch.after,
-      error = fch.error,
-
-      ...request
-    } = options; // Local option OR global value (including defaults)
-
-    // Merge it, first the global and then the local
-    query = { ...fch.query, ...query };
-    // Absolute URL if possible; Default method; merge the default headers
-    request.url = createUrl(request.url ?? fch.url, query, baseUrl);
-    request.method = (request.method ?? fch.method).toLowerCase();
-    request.headers = createHeaders(request.headers, fch.headers);
-
-    if (request.method !== "get") {
-      dedupe = false;
-    }
-    if (dedupe) {
-      dedupe = createDedupe(ongoing, request.url);
-    }
-
-    if (!["body", "response"].includes(output)) {
-      const msg = `options.output needs to be either "body" (default) or "response", not "${output}"`;
-      throw new Error(msg);
-    }
-
-    // JSON-encode plain objects
-    if (hasPlainBody(request)) {
-      request.body = JSON.stringify(request.body);
-      request.headers["content-type"] = "application/json; charset=utf-8";
-    }
-
-    // Hijack the requeset and modify it
-    if (before) {
-      request = before(request);
-    }
-
-    // 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();
-
-      // Otherwise, save it in the cache and return the promise
-      return dedupe.save(
-        createFetch(request, { dedupe, output, error, after })
-      );
-    } else {
-      // PUT, POST, etc should never dedupe and just return the plain request
-      return createFetch(request, { output, error, after });
-    }
-  };
-
-  // Default values
-  fch.url = defaults.url ?? "/";
-  fch.method = defaults.method ?? "get";
-  fch.query = defaults.query ?? {};
-  fch.headers = defaults.headers ?? {};
-
-  // Default options
-  fch.dedupe = defaults.dedupe ?? true;
-  fch.output = defaults.output ?? "body";
-  fch.credentials = defaults.credentials ?? "include";
-
-  // Interceptors
-  fch.before = defaults.before ?? ((request) => request);
-  fch.after = defaults.after ?? ((response) => response);
-  fch.error = defaults.error ?? ((error) => Promise.reject(error));
-
-  const get = (url, opts = {}) => fch(url, { ...opts });
-  const head = (url, opts = {}) => fch(url, { ...opts, method: "head" });
-  const post = (url, opts = {}) => fch(url, { ...opts, method: "post" });
-  const patch = (url, opts = {}) => fch(url, { ...opts, method: "patch" });
-  const put = (url, opts = {}) => fch(url, { ...opts, method: "put" });
-  const del = (url, opts = {}) => fch(url, { ...opts, method: "delete" });
-
-  fch.get = get;
-  fch.head = head;
-  fch.post = post;
-  fch.patch = patch;
-  fch.put = put;
-  fch.del = del;
-
-  fch.create = create;
-
-  return fch;
-};
-
-const fch = create();
-
-export default fch;