<h1 align="center"> <a href="https://elbywan.github.io/wretch"><img src="assets/wretch.svg" alt="wretch-logo" width="220px"></a><br> <br> <a href="https://elbywan.github.io/wretch">Wretch</a><br> <br> <a href="https://github.com/elbywan/wretch/actions/workflows/node.yml"><img alt="github-badge" src="https://github.com/elbywan/wretch/actions/workflows/node.yml/badge.svg"></a> <a href="https://www.npmjs.com/package/wretch"><img alt="npm-badge" src="https://img.shields.io/npm/v/wretch.svg?colorB=ff733e" height="20"></a> <a href="https://www.npmjs.com/package/wretch"><img alt="npm-downloads-badge" src="https://img.shields.io/npm/dm/wretch.svg?colorB=53aabb" height="20"></a> <a href="https://coveralls.io/github/elbywan/wretch?branch=master"><img src="https://coveralls.io/repos/github/elbywan/wretch/badge.svg?branch=master" alt="Coverage Status"></a> <a href="https://bundlejs.com/?q=wretch#sharing"><img src='https://deno.bundlejs.com/badge?q=wretch'/></a> <a href="https://github.com/elbywan/wretch/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license-badge" height="20"></a> </h1> <h4 align="center"> A tiny (~2KB g-zipped) wrapper built around <a href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch">fetch</a> with an intuitive syntax. </h4> <h5 align="center"> <i>f[ETCH] [WR]apper</i> </h6> <br>

Wretch 2.9 is now live 🎉 ! Please have a look at the releases and the changelog after each update for new features and breaking changes. If you want to try out the hot stuff, please look into the dev branch.

And if you like the library please consider becoming a sponsor ❤️.

Features

wretch is a small wrapper around fetch designed to simplify the way to perform network requests and handle responses.

• 🪶 Small - core is less than 2KB g-zipped
• 💡 Intuitive - lean API, handles errors, headers and (de)serialization
• 🧊 Immutable - every call creates a cloned instance that can then be reused safely
• 🔌 Modular - plug addons to add new features, and middlewares to intercept requests
• 🧩 Isomorphic - compatible with modern browsers, Node.js 14+ and Deno
• 🦺 Type safe - strongly typed, written in TypeScript
• ✅ Proven - fully covered by unit tests and widely used
• 💓 Maintained - alive and well for many years

Table of Contents

• Motivation
• Installation
• Compatibility
• Usage
• Api
• Addons
• Middlewares
• Migration from v1
• License

Motivation

Because having to write a second callback to process a response body feels awkward.

Fetch needs a second callback to process the response body.

fetch("examples/example.json")
  .then(response => response.json())
  .then(json => {
    //Do stuff with the parsed json
  });

Wretch does it for you.

// Use .res for the raw response, .text for raw text, .json for json, .blob for a blob ...
wretch("examples/example.json")
  .get()
  .json(json => {
    // Do stuff with the parsed json
  });

Because manually checking and throwing every request error code is tedious.

Fetch won’t reject on HTTP error status.

fetch("anything")
  .then(response => {
    if(!response.ok) {
      if(response.status === 404) throw new Error("Not found")
      else if(response.status === 401) throw new Error("Unauthorized")
      else if(response.status === 418) throw new Error("I'm a teapot !")
      else throw new Error("Other error")
    }
    else // ...
  })
  .then(data => /* ... */)
  .catch(error => { /* ... */ })

Wretch throws when the response is not successful and contains helper methods to handle common codes.

wretch("anything")
  .get()
  .notFound(error => { /* ... */ })
  .unauthorized(error => { /* ... */ })
  .error(418, error => { /* ... */ })
  .res(response => /* ... */)
  .catch(error => { /* uncaught errors */ })

Because sending a json object should be easy.

With fetch you have to set the header, the method and the body manually.

fetch("endpoint", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ "hello": "world" })
}).then(response => /* ... */)
// Omitting the data retrieval and error management parts…

With wretch, you have shorthands at your disposal.

wretch("endpoint")
  .post({ "hello": "world" })
  .res(response => /* ... */)

Because configuration should not rhyme with repetition.

A Wretch object is immutable which means that you can reuse previous instances safely.

// Cross origin authenticated requests on an external API
const externalApi = wretch("http://external.api") // Base url
  // Authorization header
  .auth(`Bearer ${token}`)
  // Cors fetch options
  .options({ credentials: "include", mode: "cors" })
  // Handle 403 errors
  .resolve((_) => _.forbidden(handle403));

// Fetch a resource
const resource = await externalApi
  // Add a custom header for this request
  .headers({ "If-Unmodified-Since": "Wed, 21 Oct 2015 07:28:00 GMT" })
  .get("/resource/1")
  .json(handleResource);

// Post a resource
externalApi
  .url("/resource")
  .post({ "Shiny new": "resource object" })
  .json(handleNewResourceResult);

Installation

Package Manager

npm i wretch # or yarn/pnpm add wretch

<script> tag

The package contains multiple bundles depending on the format and feature set located under the /dist/bundle folder.

<details> <summary>Bundle variants</summary> <br>

💡 If you pick the core bundle, then to plug addons you must import them separately from /dist/bundle/addons/[addonName].min.js

Feature set	File Name
Core features only	wretch.min.js
Core + all addons	wretch.all.min.js

Format	Extension
ESM	.min.mjs
CommonJS	.min.cjs
UMD	.min.js

</details>

<!--
  Pick your favourite CDN:
    - https://unpkg.com/wretch
    - https://cdn.jsdelivr.net/npm/wretch/
    - https://www.skypack.dev/view/wretch
    - https://cdnjs.com/libraries/wretch
    - …
-->

<!-- UMD import as window.wretch -->
<script src="https://unpkg.com/wretch"></script>

<!-- Modern import -->
<script type="module">
  import wretch from 'https://cdn.skypack.dev/wretch/dist/bundle/wretch.all.min.mjs'

  // ... //
</script>

Compatibility

Browsers

wretch@^2 is compatible with modern browsers only. For older browsers please use wretch@^1.

Node.js

Wretch is compatible with and tested in Node.js >= 14. Older versions of node may work but it is not guaranteed.

Polyfills (Node.js < 18)

Starting from Node.js 18, node includes experimental fetch support. Wretch will work without installing any polyfill.

For older versions, the Node.js standard library does not provide a native implementation of fetch (and other Browsers-only APIs) and polyfilling is mandatory.

The non-global way (preferred):

import fetch, { FormData } from "node-fetch"

// w is a reusable wretch instance
const w = wretch().polyfills({
  fetch,
  FormData,
});

Globally:

import fetch, { FormData } from "node-fetch";

// Either mutate the global object…
global.fetch = fetch;
global.FormData = FormData;

// …or use the static wretch.polyfills method to impact every wretch instance created afterwards.
wretch.polyfills({
  fetch,
  FormData,
});

Deno

Works with Deno >= 0.41.0 out of the box.

Types should be imported from /dist/types.d.ts.

// You can import wretch from any CDN that serve ESModules.
import wretch from "https://cdn.skypack.dev/wretch";

const text = await wretch("https://httpstat.us").get("/200").text();
console.log(text); // -> 200 OK

Usage

Import

// ECMAScript modules
import wretch from "wretch"
// CommonJS
const wretch = require("wretch")
// Global variable (script tag)
window.wretch

Minimal Example

import wretch from "wretch"

// Instantiate and configure wretch
const api =
  wretch("https://jsonplaceholder.typicode.com", { mode: "cors" })
    .errorType("json")
    .resolve(r => r.json())

try {
  // Fetch users
  const users = await api.get("/users")
  // Find all posts from a given user
  const user = users.find(({ name }) => name === "Nicholas Runolfsdottir V")
  const postsByUser = await api.get(`/posts?userId=${user.id}`)
  // Create a new post
  const newPost = await api.url("/posts").post({
    title: "New Post",
    body: "My shiny new post"
  })
  // Patch it
  await api.url("/posts/" + newPost.id).patch({
    title: "Updated Post",
    body: "Edited body"
  })
  // Fetch it
  await api.get("/posts/" + newPost.id)
} catch (error) {
  // The API could return an empty object - in which case the status text is logged instead.
  const message =
    typeof error.message === "object" && Object.keys(error.message).length > 0
      ? JSON.stringify(error.message)
      : error.response.statusText
  console.error(`${error.status}: ${message}`)
}

Chaining

A high level overview of the successive steps that can be chained to perform a request and parse the result.

// First, instantiate wretch
wretch(baseUrl, baseOptions)

The "request" chain starts here.

  // Optional - A set of helper methods to set the default options, set accept header, change the current url…
  .<helper method(s)>()
  // Optional - Serialize an object to json or FormData formats and sets the body & header field if needed
  .<body type>()
    // Required - Sends the get/put/post/delete/patch request.
  .<http method>()

The "response" chain starts here.

Fetch is called after the request chain ends and before the response chain starts.<br> The request is on the fly and now it is time to chain catchers and finally call a response type handler.

  // Optional - You can chain error handlers here
  .<catcher(s)>()
  // Required - Specify the data type you need, which will be parsed and handed to you
  .<response type>()
  // >> Ends the response chain.

From this point on, wretch returns a standard Promise.

  .then(…)
  .catch(…)

API 🔗

💡 The API documentation is now autogenerated and hosted separately, click the links access it.

Static Methods 🔗

These methods are available from the main default export and can be used to instantiate wretch and configure it globally.

import wretch from "wretch"

wretch.options({ mode: "cors" })

let w = wretch("http://domain.com/", { cache: "default" })

Helper Methods 🔗

Helper Methods are used to configure the request and program actions.

w = w
  .url("/resource/1")
  .headers({ "Cache-Control": no-cache })
  .content("text/html")

Body Types 🔗

Specify a body type if uploading data. Can also be added through the HTTP Method argument.

w = w.body("<html><body><div/></body></html>")

HTTP Methods 🔗

Sets the HTTP method and sends the request.

Calling an HTTP method ends the request chain and returns a response chain. You can pass optional url and body arguments to these methods.

// These shorthands:
wretch().get("/url");
wretch().post({ json: "body" }, "/url");
// Are equivalent to:
wretch().url("/url").get();
wretch().json({ json: "body" }).url("/url").post();

NOTE: if the body argument is an Object it is assumed that it is a JSON payload and it will have the same behaviour as calling .json(body) unless the Content-Type header has been set to something else beforehand.

Catchers 🔗

Catchers are optional, but if none are provided an error will still be thrown for http error codes and it will be up to you to catch it.

wretch("...")
  .get()
  .badRequest((err) => console.log(err.status))
  .unauthorized((err) => console.log(err.status))
  .forbidden((err) => console.log(err.status))
  .notFound((err) => console.log(err.status))
  .timeout((err) => console.log(err.status))
  .internalError((err) => console.log(err.status))
  .error(418, (err) => console.log(err.status))
  .fetchError((err) => console.log(err))
  .res();

The error passed to catchers is enhanced with additional properties.

type WretchError = Error & {
  status: number;
  response: WretchResponse;
  text?: string;
  json?: Object;
};

The original request is passed along the error and can be used in order to perform an additional request.

wretch("/resource")
  .get()
  .unauthorized(async (error, req) => {
    // Renew credentials
    const token = await wretch("/renewtoken").get().text();
    storeToken(token);
    // Replay the original request with new credentials
    return req.auth(token).get().unauthorized((err) => {
      throw err;
    }).json();
  })
  .json()
  // The promise chain is preserved as expected
  // ".then" will be performed on the result of the original request
  // or the replayed one (if a 401 error was thrown)
  .then(callback);

Response Types 🔗

Setting the final response body type ends the chain and returns a regular promise.

All these methods accept an optional callback, and will return a Promise resolved with either the return value of the provided callback or the expected type.

// Without a callback
wretch("...").get().json().then(json => /* json is the parsed json of the response body */)
// Without a callback using await
const json = await wretch("...").get().json()
// With a callback the value returned is passed to the Promise
wretch("...").get().json(json => "Hello world!").then(console.log) // => Hello world!

If an error is caught by catchers, the response type handler will not be called.

Addons

Addons are separate pieces of code that you can import and plug into wretch to add new features.

import FormDataAddon from "wretch/addons/formData"
import QueryStringAddon from "wretch/addons/queryString"

// Add both addons
const w = wretch().addon(FormDataAddon).addon(QueryStringAddon)

// Additional features are now available
w.formData({ hello: "world" }).query({ check: true })

Typescript should also be fully supported and will provide