fch 2.0.0 → 3.0.1

package/fetch.js

@@ -1,20 +1,26 @@
-import swear from "swear";
-
-// To avoid making parallel requests to the same url if one is ongoing
-const ongoing = new Map();
-
 // Plain-ish object
 const hasPlainBody = (options) => {
   if (options.headers["content-type"]) return;
-  if (typeof options.body !== "object") return;
+  if (!["object", "array"].includes(typeof options.body)) return;
   if (options.body instanceof FormData) return;
   return true;
 };
 
-const createUrl = (path, base) => {
+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 url = new URL(path, base);
-  return url.href;
+  const fullUrl = new URL(path, base);
+  return fullUrl.href;
 };
 
 const createHeaders = (user, base) => {
@@ -31,6 +37,15 @@ const createHeaders = (user, base) => {
   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
@@ -70,90 +85,122 @@ const createFetch = (request, { after, dedupe, error, output }) => {
   });
 };
 
-const fch = swear((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;
-
-  // Absolute URL if possible; Default method; merge the default headers
-  options.url = createUrl(options.url, fch.baseUrl);
-  options.method = (options.method ?? fch.method).toLowerCase();
-  options.headers = createHeaders(options.headers, fch.headers);
-
-  let {
-    dedupe = fch.dedupe,
-    output = fch.output,
-
-    before = fch.before,
-    after = fch.after,
-    error = fch.error,
-
-    ...request
-  } = options; // Local option OR global value (including defaults)
-
-  if (request.method !== "get") {
-    dedupe = false;
-  }
-  if (dedupe) {
-    dedupe = {
-      save: (prom) => {
-        ongoing.set(request.url, prom);
-        return prom;
-      },
-      get: () => ongoing.get(request.url),
-      clear: () => ongoing.delete(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
-  if (dedupe) {
-    // It's already cached! Just return it
-    if (dedupe.get()) return dedupe.get();
+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 || "/", 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);
+    }
 
-    // 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 });
-  }
-});
+    if (!["body", "response"].includes(output)) {
+      const msg = `options.output needs to be either "body" (default) or "response", not "${output}"`;
+      throw new Error(msg);
+    }
 
-fch.get = (url, options = {}) => fch(url, { ...options, method: "get" });
-fch.head = (url, options = {}) => fch(url, { ...options, method: "head" });
-fch.post = (url, options = {}) => fch(url, { ...options, method: "post" });
-fch.patch = (url, options = {}) => fch(url, { ...options, method: "patch" });
-fch.put = (url, options = {}) => fch(url, { ...options, method: "put" });
-fch.del = (url, options = {}) => fch(url, { ...options, method: "delete" });
+    // JSON-encode plain objects
+    if (hasPlainBody(request)) {
+      request.body = JSON.stringify(request.body);
+      request.headers["content-type"] = "application/json; charset=utf-8";
+    }
 
-// Default values
-fch.method = "get";
-fch.headers = {};
+    // Hijack the requeset and modify it
+    if (before) {
+      request = before(request);
+    }
 
-// Default options
-fch.dedupe = true;
-fch.output = "body";
+    // 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();
 
-// Interceptors
-fch.before = (request) => request;
-fch.after = (response) => response;
-fch.error = (error) => Promise.reject(error);
+      // 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.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;
+
+  return fch;
+};
 
-export default 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fch",
-  "version": "2.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",
@@ -21,14 +21,16 @@
     "async",
     "ajax"
   ],
-  "main": "fetch.js",
+  "main": "./index.js",
+  "browser": "./fetch.js",
+  "files": [
+    "fetch.js"
+  ],
   "type": "module",
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {
-    "swear": "^1.1.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "jest": "^28.0.1",
     "jest-fetch-mock": "^3.0.3"

package/readme.md

@@ -1,31 +1,48 @@
 # 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)
 
-A library to make API calls easier. Similar to Axios, but tiny size and simpler API:
+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("/pokemon/150");
+const mew = await api.get("https://pokeapi.co/pokemon/150");
 console.log(mew);
 ```
 
-`fch` is a better `fetch()`:
-
-- Automatically `JSON.stringify()` and `Content-Type: 'application/json'` for plain objects.
-- Automatically parse server response as json if it includes the headers, or text otherwise.
-- Isomorphic fetch(); it works the same way in the browser and server.
-- Await/Async Promise interface works as you know and love.
-- Better error handling. `>= 400 and <= 100` will _reject_ the promise with an error instance.
-- Advanced [Promise interface](https://www.npmjs.com/swear) for better scripting.
-- Import with the shorthand for tighter syntax. `import { get, post } from 'fch';`.
-- Easily define shared options straight on the root `fetch.baseUrl = "https://...";`.
+- 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).
 - Deduplicates parallel GET requests.
 - Configurable to return either just the body, or the full response.
-- [TODO]: cache engine with "highs" and "lows", great for scrapping
-- [TODO]: rate-limiting of requests (N-second, or N-parallel), great for scrapping
+
+```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})
+```
+
+| 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
 
@@ -37,85 +54,227 @@ 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('/');
+```
+
+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>
+```
+
+## Options
+
 ```js
 import api from 'fch';
 
-const data = await api.get('/');
+// 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
+api.dedupe = true;   // Avoid parallel GET requests to the same path
+api.output = 'body'; // Return the body; use 'response' for the full response
+
+// Interceptors
+api.before = req => req;
+api.after = res => res;
+api.error = err => Promise.reject(err);
+
+// Similar API to fetch()
+api(url, { method, body, headers, ... });
+
+// Our highly recommended style:
+api.get(url, { headers, ... });
+api.post(url, { body, headers, ... });
+api.put(url, { body, headers, ... });
+// ...
 ```
 
+### Method
 
-### Advanced promise interface
+The HTTP method to make the request. When using the shorthand, it defaults to `GET`. We recommend using the method syntax:
 
-This library has a couple of aces up its sleeve. First, it [has a better Promise interface](https://www.npmjs.com/swear):
+```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
-import api from "fch";
+// Recommended way of dealing with methods:
+api.get(...);
+
+// INVALID; won't work
+api.GET(...);
 
-// You can keep performing actions like it was sync
-const firstFriendName = await api.get("/friends")[0].name;
-console.log(firstFriendName);
+// Both of these are valid:
+api({ method; 'GET' })
+api({ method; 'get'})
 ```
 
-### Define shared options
+Example: adding a new cat and fixing a typo:
 
-You can also define values straight away:
+```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
+
+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';
 
-api.baseUrl = "https://pokeapi.co/";
+// Recommended way of specifying the Url
+await api.post('/hello', { body: '...', headers: {} })
 
-const mew = await api.get("/pokemon/150");
-console.log(mew);
+// 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: '...' });
 ```
 
-If you prefer Axios' style of outputting the whole response, you can do:
+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
-// Default, already only returns the data on a successful call
-api.output = "data";
-const name = await api.get("/users/1").name;
+import api from 'fch';
+api.baseUrl = 'https//api.filemon.io/';
+api.get('/hello');
+// Called https//api.filemon.io/hello
+```
 
-// Axios-like
-api.output = "response";
-const name = await api.get("/users/1").data.name;
+> 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 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';
+
+// Sending plain text
+await api.post('/houses', { body: 'plain text' });
+
+// Will JSON.stringify it internally, and add the JSON headers
+await api.post('/houses', { body: { id: 1, name: 'Cute Cottage' } });
+
+// Send it as FormData
+form.onsubmit = e => {
+  await api.post('/houses', { body: new FormData(e.target) });
+};
 ```
 
-### Interceptors
+The methods `GET` and `HEAD` do not accept a body and it'll be ignored.
 
-You can also easily add the interceptors `before`, `after` and `error`:
+The **response body** will be returned by default as the output of the call:
 
 ```js
-// Perform an action or request transformation before the request is sent
-fch.before = async req => {
-  // Normalized request ready to be sent
-  ...
+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
+
+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';
+
+// 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;
 };
 
-// Perform an action or data transformation after the request is finished
-fch.after = async res => {
-  // Full response as just after the request is made
-  ...
-  return res;
-};
+// Set them for this single request:
+api.get('/hello', { headers: { e: 'f' } });
+// Total headers on the request:
+// { a: 'b', c: 'd', e: 'f' }
+```
 
-// Perform an action or data transformation when an error is thrown
-fch.error = async err => {
-  // Need to re-throw if we want to throw on error
-  ...
-  throw err;
+When to use each?
 
-  // OR, resolve it as if it didn't fail
-  return err.response;
+- 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.
 
-  // OR, resolve it with a custom value
-  return { message: 'Request failed with a code ' + err.response.status };
-};
+
+### 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 the whole response (with .body):
+const response = await api.get('/data', { output: 'response' });
+
+// Throws error
+const invalid = await api.get('/data', { output: 'invalid' });
 ```
 
 
-## Dedupe
+### 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:
 
@@ -139,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:
 
@@ -157,28 +316,77 @@ it("can opt out locally", async () => {
 });
 ```
 
+### Interceptors
 
-## How to
+You can also easily add the interceptors `before`, `after` and `error`:
 
-### Stop errors from throwing
+```js
+// Perform an action or request transformation before the request is sent
+fch.before = async req => {
+  // Normalized request ready to be sent
+  ...
+  return req;
+};
 
-While you can handle this on a per-request basis, if you want to overwrite the global behavior you can just do:
+// Perform an action or data transformation after the request is finished
+fch.after = async res => {
+  // Full response as just after the request is made
+  ...
+  return res;
+};
+
+// Perform an action or data transformation when an error is thrown
+fch.error = async err => {
+  // Need to re-throw if we want to throw on error
+  ...
+  throw err;
+
+  // OR, resolve it as if it didn't fail
+  return err.response;
+
+  // OR, resolve it with a custom value
+  return { message: 'Request failed with a code ' + err.response.status };
+};
+```
+
+
+### Define shared options
+
+You can also define values straight away:
 
 ```js
-import fch from 'fch';
-fch.error = error => error.response;
+import api from "fch";
 
-const res = fch('/notfound');
-expect(res.status).toBe(404);
+api.baseUrl = "https://pokeapi.co/";
+
+const mew = await api.get("/pokemon/150");
+console.log(mew);
 ```
 
-Just that, then when there's an error it'll just return as usual, e.g.:
+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
+
+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;
 
-const res = fch('/notfound');
+const res = await fch('/notfound');
 expect(res.status).toBe(404);
 ```
 
@@ -214,8 +422,8 @@ There's a configuration parameter for that:
 import fch from 'fch';
 fch.baseUrl = 'https://api.filemon.io/';
 
-// Calls "https://api.filemon.io/blabla/"
-const body = await fch.get('/blabla/');
+// Calls "https://api.filemon.io/blabla"
+const body = await fch.get('/blabla');
 ```
 
 
@@ -230,7 +438,7 @@ fch.headers.Authorization = 'bearer abc';
 const me = await fch('/users/me');
 ```
 
-Globally on a per-request basis, for example if you take the value from localStorage:
+Or globally on a per-request basis, for example if you take the value from localStorage:
 
 ```js
 import fch from 'fch';
@@ -254,3 +462,72 @@ import fch from 'fch';
 
 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:
+
+```js
+import fch from 'fch';
+
+const api = fch.create({
+  baseUrl: 'https://api.filemon.io/',
+  ...
+});
+
+api.get('/hello');   // Gets https://api.filemon.io/hello
+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.
+
+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?
+
+The main difference is that things are simplified with fch:
+
+```js
+// Modify headers
+axios.defaults.headers.Authorization = '...';
+fch.headers.Authorization = '...';
+
+// Set a base URL
+axios.defaults.baseURL = '...';
+fch.baseUrl = '...';
+
+// Add an interceptor
+axios.interceptors.request.use(fn);
+fch.before = fn;
+```
+
+API size is also strikingly different, with **7.8kb** for Axios and **1.9kb** 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 many of the more advanced options, like `onUploadProgress` nor `onDownloadProgress`.

package/fetch.test.js

@@ -1,370 +0,0 @@
-import fch from "./fetch.js";
-import mock from "jest-fetch-mock";
-
-mock.enableMocks();
-
-const jsonHeaders = { headers: { "Content-Type": "application/json" } };
-
-describe("fetch()", () => {
-  beforeEach(() => {
-    fetch.resetMocks();
-  });
-
-  it("can create a basic request", async () => {
-    fetch.once("hello");
-    const data = await fch("/");
-
-    expect(data).toEqual("hello");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-  });
-
-  it("accepts Axios syntax as well", async () => {
-    fetch.once("hello");
-    const data = await fch({ url: "/" });
-
-    expect(data).toEqual("hello");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-  });
-
-  it("can receive a full response", async () => {
-    fetch.once("hello", { status: 200, headers: { hello: "world" } });
-    const res = await fch("/", { output: "response" });
-
-    expect(res.body).toEqual("hello");
-    expect(res.status).toEqual(200);
-    expect(res.statusText).toEqual("OK");
-    expect(res.headers.hello).toEqual("world");
-    expect(fetch.mock.calls.length).toEqual(1);
-  });
-
-  it("works with JSON", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const data = await fch("https://google.com/");
-
-    expect(data).toEqual({ secret: "12345" });
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("https://google.com/");
-  });
-
-  it("can use the swear interface", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const hello = await fch("/").secret;
-    expect(hello).toEqual("12345");
-  });
-
-  it("can use the baseUrl", async () => {
-    fetch.once("hi");
-    fch.baseUrl = "https://google.com/";
-    const data = await fch.get("/hello");
-    expect(data).toBe("hi");
-    expect(fetch.mock.calls[0][0]).toBe("https://google.com/hello");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-    fch.baseUrl = null;
-  });
-
-  it("can use the `fetch.get()` shorthand", async () => {
-    fetch.once("my-data");
-    const data = await fch.get("/");
-    expect(data).toBe("my-data");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-  });
-
-  it("can use the `fetch.patch()` shorthand", async () => {
-    fetch.once("my-data");
-    expect(await fch.patch("/")).toBe("my-data");
-    expect(fetch.mock.calls[0][1].method).toEqual("patch");
-  });
-
-  it("can use the `fetch.put()` shorthand", async () => {
-    fetch.once("my-data");
-    expect(await fch.put("/")).toBe("my-data");
-    expect(fetch.mock.calls[0][1].method).toEqual("put");
-  });
-
-  it("can use the `fetch.post()` shorthand", async () => {
-    fetch.once("my-data");
-    expect(await fch.post("/")).toBe("my-data");
-    expect(fetch.mock.calls[0][1].method).toEqual("post");
-  });
-
-  it("can use the `fetch.del()` shorthand", async () => {
-    fetch.once("my-data");
-    expect(await fch.del("/")).toBe("my-data");
-    expect(fetch.mock.calls[0][1].method).toEqual("delete");
-  });
-
-  it("ignores invalid options", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const res = await fch("https://google.com/", 10);
-
-    expect(res).toEqual({ secret: "12345" });
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("https://google.com/");
-  });
-
-  it("will not overwrite if it is FormData", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const res = await fch("/", { method: "post", body: new FormData() });
-
-    expect(res).toEqual({ secret: "12345" });
-    expect(fetch.mock.calls.length).toEqual(1);
-    const [url, opts] = fetch.mock.calls[0];
-    expect(opts).toMatchObject({ body: expect.any(FormData) });
-  });
-
-  it("will not overwrite if content-type is set", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const res = await fch("/", {
-      method: "POST",
-      body: { a: "b" },
-      headers: { "Content-Type": "xxx" },
-    });
-
-    expect(res).toEqual({ secret: "12345" });
-    expect(fetch.mock.calls.length).toEqual(1);
-    const [url, opts] = fetch.mock.calls[0];
-    expect(url).toEqual("/");
-    expect(opts).toMatchObject({
-      method: "post",
-      body: { a: "b" },
-      headers: { "content-type": "xxx" },
-    });
-  });
-
-  it("will send JSON", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const res = await fch("/", { method: "POST", body: { a: "b" } });
-
-    expect(res).toEqual({ secret: "12345" });
-    expect(fetch.mock.calls.length).toEqual(1);
-    const [url, opts] = fetch.mock.calls[0];
-    expect(url).toEqual("/");
-    expect(opts).toMatchObject({
-      method: "post",
-      body: '{"a":"b"}',
-      headers: { "content-type": "application/json; charset=utf-8" },
-    });
-  });
-
-  it("can run in parallel", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch("/a"), fch("/b")]);
-
-    expect(res).toEqual(["a", "b"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("can set `accepts` insensitively", async () => {
-    fetch.once(JSON.stringify({ secret: "12345" }), jsonHeaders);
-    const res = await fch("/", { headers: { Accepts: "text/xml" } });
-
-    expect(fetch.mock.calls[0][1].headers).toEqual({ accepts: "text/xml" });
-  });
-
-  it("can accept network rejections", async () => {
-    fetch.mockResponseOnce(JSON.stringify("unauthorized"), {
-      status: 401,
-      ok: false,
-    });
-    await expect(fch("/")).rejects.toMatchObject({
-      message: "Unauthorized",
-    });
-  });
-
-  it("throws with the wrong 'output' option", async () => {
-    fetch.once("hello");
-    await expect(fch("/", { output: "abc" })).rejects.toMatchObject({
-      message: `options.output needs to be either "body" (default) or "response", not "abc"`,
-    });
-  });
-
-  it("can accept rejections", async () => {
-    fetch.mockRejectOnce(new Error("fake error message"));
-    await expect(fch("/error")).rejects.toMatchObject({
-      message: "fake error message",
-    });
-  });
-});
-
-describe("interceptors", () => {
-  beforeEach(() => {
-    fetch.resetMocks();
-  });
-  afterEach(() => {
-    fetch.resetMocks();
-    delete fch.before;
-    delete fch.after;
-  });
-
-  it("can create a before interceptor", async () => {
-    fetch.once("hello");
-    const data = await fch("/", {
-      before: (req) => {
-        req.url = "/hello";
-        req.method = "put";
-        return req;
-      },
-    });
-
-    expect(data).toEqual("hello");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/hello");
-    expect(fetch.mock.calls[0][1].method).toEqual("put");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-  });
-
-  it("can create a global before interceptor", async () => {
-    fetch.once("hello");
-    fch.before = (req) => {
-      req.url = "/hello";
-      req.method = "put";
-      return req;
-    };
-    const data = await fch("/");
-
-    expect(data).toEqual("hello");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/hello");
-    expect(fetch.mock.calls[0][1].method).toEqual("put");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-
-    delete fch.before;
-  });
-
-  it("can create an after interceptor", async () => {
-    fetch.once("hello", { status: 201, headers: { hello: "world" } });
-    const res = await fch("/", {
-      output: "response",
-      after: (res) => {
-        res.body = "bye";
-        res.status = 200;
-        res.headers.hello = "world";
-        return res;
-      },
-    });
-
-    expect(res.body).toEqual("bye");
-    expect(res.status).toEqual(200);
-    expect(res.statusText).toEqual("Created");
-    expect(res.headers.hello).toEqual("world");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-  });
-
-  it("can create a global after interceptor", async () => {
-    fetch.once("hello", { status: 201, headers: { hello: "world" } });
-    fch.after = (res) => {
-      res.body = "bye";
-      res.status = 200;
-      res.headers.hello = "world";
-      return res;
-    };
-    const res = await fch("/", { output: "response" });
-
-    expect(res.body).toEqual("bye");
-    expect(res.status).toEqual(200);
-    expect(res.statusText).toEqual("Created");
-    expect(res.headers.hello).toEqual("world");
-    expect(fetch.mock.calls.length).toEqual(1);
-    expect(fetch.mock.calls[0][0]).toEqual("/");
-    expect(fetch.mock.calls[0][1].method).toEqual("get");
-    expect(fetch.mock.calls[0][1].headers).toEqual({});
-  });
-});
-
-describe("dedupe network calls", () => {
-  beforeEach(() => {
-    fetch.resetMocks();
-  });
-
-  it("dedupes ongoing/parallel calls", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch("/a"), fch("/a")]);
-
-    expect(res).toEqual(["a", "a"]);
-    expect(fetch.mock.calls.length).toEqual(1);
-  });
-
-  it("dedupes named calls", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch.get("/a"), fch.get("/a")]);
-
-    expect(res).toEqual(["a", "a"]);
-    expect(fetch.mock.calls.length).toEqual(1);
-  });
-
-  it("can opt out locally", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch("/a"), fch("/a", { dedupe: false })]);
-
-    expect(res).toEqual(["a", "b"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("cannot reuse an opted out call", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch("/a", { dedupe: false }), fch("/a")]);
-
-    expect(res).toEqual(["a", "b"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("will reuse the last opt-in call", async () => {
-    fetch.once("a").once("b").once("c");
-    const res = await Promise.all([
-      fch("/a"),
-      fch("/a", { dedupe: false }),
-      fch("/a"),
-    ]);
-
-    expect(res).toEqual(["a", "b", "a"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("can opt out globally", async () => {
-    fetch.once("a").once("b").once("c");
-    fch.dedupe = false;
-    const res = await Promise.all([fch("/a"), fch("/a"), fch("/a")]);
-
-    expect(res).toEqual(["a", "b", "c"]);
-    expect(fetch.mock.calls.length).toEqual(3);
-    fch.dedupe = true;
-  });
-
-  it("does NOT dedupe/cache serial requests", async () => {
-    fetch.once("a").once("b");
-    const resa = await fch("/a");
-    const resb = await fch("/a");
-
-    expect([resa, resb]).toEqual(["a", "b"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("does NOT dedupe/cache other request types", async () => {
-    fetch.once("a").once("b");
-    const res = await Promise.all([fch.get("/a"), fch.post("/a")]);
-
-    expect(res).toEqual(["a", "b"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-
-  it("NOT deduping are invisible for other request", async () => {
-    fetch.once("a").once("b").once("c");
-    const res = await Promise.all([
-      fch.get("/a"),
-      fch.post("/a"),
-      fch.get("/a"),
-    ]);
-
-    expect(res).toEqual(["a", "b", "a"]);
-    expect(fetch.mock.calls.length).toEqual(2);
-  });
-});