fch 2.0.1 → 3.0.0

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,102 +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),
-    };
-  }
+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);
+    }
 
-  if (!["body", "response"].includes(output)) {
-    const msg = `options.output needs to be either "body" (default) or "response", not "${output}"`;
-    throw new Error(msg);
-  }
+    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";
-  }
+    // 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);
-  }
+    // 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();
+    // It should be cached
+    if (dedupe) {
+      // 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 });
-  }
-});
+      // 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;
+};
 
-// Default values
-fch.method = "get";
-fch.headers = {};
-
-// Default options
-fch.dedupe = true;
-fch.output = "body";
-
-// Interceptors
-fch.before = (request) => request;
-fch.after = (response) => response;
-fch.error = (error) => Promise.reject(error);
-
-const request = (url, opts = {}) => fch(url, { ...opts });
-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.request = request;
-fch.get = get;
-fch.head = head;
-fch.post = post;
-fch.patch = patch;
-fch.put = put;
-fch.del = del;
-
-fch.swear = swear;
-
-export default fch;
-export { request, get, head, post, patch, put, del, swear };
+// 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.1",
+  "version": "3.0.0",
   "description": "Fetch interface with better promises, deduplication, defaults, etc.",
   "homepage": "https://github.com/franciscop/fetch",
   "repository": "https://github.com/franciscop/fetch.git",
@@ -21,15 +21,16 @@
     "async",
     "ajax"
   ],
-  "main": "fetch.js",
-  "files": [],
+  "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,6 +1,6 @@
 # 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";
@@ -8,38 +8,40 @@ const mew = await api("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.
+- 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 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.
-- Easily define shared options straight on the root `fetch.baseUrl = "https://...";`.
+- 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
-
-These are the available options and their defaults:
-
-- `api.baseUrl = null;`: Set an API endpoint
-- `api.method = 'get';`: Default method to use for api()
-- `api.headers = {};`: Merged with the headers on a per-request basis
-- `api.dedupe = true;`: Avoid parallel GET requests to the same path
-- `api.output = 'body';`: Return the body; use 'response' for the full response
-- `api.before = req => req;`: Interceptor executed before sending the request
-- `api.after = res => res;`: Handle the responses before returning them
-- `api.error = err => Promise.reject(err);`: handle any error thrown by fch
-- `api(url, { method, body, headers, ... })`
-- `api.get(url, { headers, ... });`: helper for convenience
-- `api.head(url, { headers, ... });`: helper for convenience
-- `api.post(url, { body, headers, ... });`: helper for convenience
-- `api.patch(url, { body, headers, ... });`: helper for convenience
-- `api.put(url, { body, headers, ... });`: helper for convenience
-- `api.del(url, { body, headers, ... });`: helper for convenience
+
+```js
+// Calls and methods available:
+api(url, { method, body, headers, ...options })
+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 |
 
 ## Getting Started
 
@@ -52,15 +54,24 @@ npm install fch
 Then import it to be able to use it in your code:
 
 ```js
-import api from 'fch';
+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`:
 
-const data = await api.get('/');
+```html
+<!-- Import it as usual -->
+<script src="https://cdn.jsdelivr.net/npm/fch"></script>
+<script>
+  fch('/hello');
+</script>
 ```
 
 ## Options
 
 ```js
-import api, { get, post, put, ... } from 'fch';
+import api from 'fch';
 
 // General options with their defaults; most of these are also parameters:
 api.baseUrl = null;  // Set an API endpoint
@@ -84,12 +95,6 @@ api.get(url, { headers, ... });
 api.post(url, { body, headers, ... });
 api.put(url, { body, headers, ... });
 // ...
-
-// Just import/use the method you need
-get(url, { headers, ... });
-post(url, { body, headers, ... });
-put(url, { body, headers, ... });
-// ...
 ```
 
 ### URL
@@ -120,7 +125,7 @@ api.get('/hello');
 
 ### Body
 
-The `body` can be a string, a FormData instance or a plain object. 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 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';
@@ -250,19 +255,6 @@ fch.error = async err => {
 ```
 
 
-
-### Advanced promise interface
-
-This library uses [the `swear` promise interface](https://www.npmjs.com/swear), which allows you to query operations seamlessly on top of your promise:
-
-```js
-import api from "fch";
-
-// You can keep performing actions like it was sync
-const firstFriendName = await api.get("/friends")[0].name;
-console.log(firstFriendName);
-```
-
 ### Define shared options
 
 You can also define values straight away:
@@ -375,3 +367,54 @@ 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`.
+
+### 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 some more advanced options,