fch 3.0.0 → 3.0.3

package/fetch.js

@@ -118,7 +118,7 @@ const create = (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 || "/", query, baseUrl);
+    request.url = createUrl(request.url ?? fch.url, query, baseUrl);
     request.method = (request.method ?? fch.method).toLowerCase();
     request.headers = createHeaders(request.headers, fch.headers);
 
@@ -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();
 
@@ -161,6 +161,7 @@ const create = (defaults = {}) => {
   };
 
   // Default values
+  fch.url = defaults.url ?? "/";
   fch.method = defaults.method ?? "get";
   fch.query = defaults.query ?? {};
   fch.headers = defaults.headers ?? {};
@@ -189,18 +190,11 @@ const create = (defaults = {}) => {
   fch.put = put;
   fch.del = del;
 
+  fch.create = create;
+
   return fch;
 };
 
-// Need to export it globally with `global`, since if we use export default then
-// we cannot load it in the browser as a normal <script>, and if we load it in
-// the browser as a <script module> then we cannot run a normal script after it
-// since the modules are deferred by default. Basically this is a big mess and
-// I wish I could just do if `(typeof window !== 'undefined') window.fch = fch`,
-// but unfortunately that's not possible now and I need this as a traditionally
-// global definition, and then another file to import it as ESM. UGHHH
-let glob = {};
-if (typeof global !== "undefined") glob = global;
-if (typeof window !== "undefined") glob = window;
-glob.fch = create();
-glob.fch.create = create;
+const fch = create();
+
+export default fch;

package/index.js

@@ -0,0 +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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fch",
-  "version": "3.0.0",
+  "version": "3.0.3",
   "description": "Fetch interface with better promises, deduplication, defaults, etc.",
   "homepage": "https://github.com/franciscop/fetch",
   "repository": "https://github.com/franciscop/fetch.git",
@@ -9,6 +9,7 @@
   "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' > ./index.js",
     "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"
@@ -21,19 +22,20 @@
     "async",
     "ajax"
   ],
-  "main": "./index.js",
-  "browser": "./fetch.js",
+  "main": "./fetch.js",
+  "browser": "./index.js",
   "files": [
+    "index.js",
     "fetch.js"
   ],
   "type": "module",
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "jest": "^28.0.1",
-    "jest-fetch-mock": "^3.0.3"
+    "jest-fetch-mock": "^3.0.3",
+    "terser": "^5.13.1"
   },
   "jest": {
     "testEnvironment": "jest-environment-node",

package/readme.md

@@ -1,47 +1,49 @@
-# Fch [![npm install fch](https://img.shields.io/badge/npm%20install-fch-blue.svg)](https://www.npmjs.com/package/fch) [![gzip size](https://img.badgesize.io/franciscop/fetch/master/fetch.js.svg?compression=gzip)](https://github.com/franciscop/fetch/blob/master/fetch.js)
+# Fch [![npm install fch](https://img.shields.io/badge/npm%20install-fch-blue.svg)](https://www.npmjs.com/package/fch) [![gzip size](https://img.badgesize.io/franciscop/fetch/master/index.js.svg?compression=gzip)](https://github.com/franciscop/fetch/blob/master/index.js)
 
 A tiny library to make API calls easier. Similar to Axios, but tiny size and simpler API:
 
 ```js
 import api from "fch";
-const mew = await api("https://pokeapi.co/pokemon/150");
+api.baseUrl = "https://pokeapi.co/";
+const mew = await api.get("/pokemon/150");
 console.log(mew);
 ```
 
-- Automatically `JSON.stringify()` and `Content-Type: 'application/json'` for objects.
-- Automatically parse server response taking into account the headers.
-- Works the same way in Node.js and the browser.
-- Await/Async Promises. `>= 400 and <= 100` will _reject_ the promise and throw an error.
-- No dependencies; include it with a simple `<script>`
-- Easily define shared options straight on the root `fch.baseUrl = "https://...";`.
-- Interceptors: `before` (the request), `after` (the response) and `error` (it fails).
+- 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.
+- Interceptors: `before` the request, `after` the response and catch with `error`.
 - Deduplicates parallel GET requests.
-- Configurable to return either just the body, or the full response.
+- Works the same way in Node.js and the browser.
+- No dependencies; include it with a simple `<script>` on the browser.
 
 ```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                        |
+| ----------------------| ----------| -----------------------------------|
+| [`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     |
 
 ## Getting Started
 
@@ -70,45 +72,78 @@ On the browser you can add it with a script and it will be available as `fch`:
 
 ## Options
 
+These are all available options and their defaults:
+
 ```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.method = 'get';  // Default method to use for api()
-api.headers = {};    // Is merged with the headers on a per-request basis
+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.dedupe = true;   // Avoid parallel GET requests to the same path
 api.output = 'body'; // Return the body; use 'response' for the full response
+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);
+```
+
+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).
+
+### Method
+
+The HTTP method to make the request. When using the shorthand, it defaults to `GET`. We recommend using the method syntax:
 
-// Similar API to fetch()
-api(url, { method, body, headers, ... });
+```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';
 
-// Our highly recommended style:
-api.get(url, { headers, ... });
-api.post(url, { body, headers, ... });
-api.put(url, { body, headers, ... });
-// ...
+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
+### 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 +158,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 +179,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 +227,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 +295,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:
 
@@ -255,32 +347,6 @@ fch.error = async err => {
 ```
 
 
-### Define shared options
-
-You can also define values straight away:
-
-```js
-import api from "fch";
-
-api.baseUrl = "https://pokeapi.co/";
-
-const mew = await api.get("/pokemon/150");
-console.log(mew);
-```
-
-If you prefer Axios' style of outputting the whole response, you can do:
-
-```js
-// Default, already only returns the data on a successful call
-api.output = "data";
-const name = await api.get("/users/1").name;
-
-// Axios-like
-api.output = "response";
-const name = await api.get("/users/1").data.name;
-```
-
-
 ## How to
 
 ### Stop errors from throwing
@@ -332,7 +398,7 @@ const body = await fch.get('/blabla');
 ```
 
 
-### Set the authorization headers
+### Set authorization headers
 
 You can set that globally as a header:
 
@@ -387,14 +453,54 @@ 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`.
 
-### What are the differences in Node.js vs Browser?
+
+
+### 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';
+
+const controller = new AbortController();
+const signal = controller.signal;
+
+abortButton.addEventListener('click', () => {
+  controller.abort();
+  console.log('Download aborted');
+});
+
+api.get(url, { signal });
+```
+
+
+
+### Define shared options
+
+You can also define values straight away:
+
+```js
+import api from "fch";
+
+api.baseUrl = "https://pokeapi.co/";
+
+const mew = await api.get("/pokemon/150");
+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.
 
 
-### What are the differences with Axios?
+
+### Differences with Axios
 
 The main difference is that things are simplified with fch:
 
@@ -412,9 +518,9 @@ axios.interceptors.request.use(fn);
 fch.before = fn;
 ```
 
-API size is also strikingly different, with **7.8kb** for Axios and **1.9kb** for fch.
+API size is also strikingly different, with **7.8kb** for Axios and **1.1kb** for fch.
 
 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`.