A tiny (~2KB g-zipped) wrapper built around fetch with an intuitive syntax.
f[ETCH] [WR]apper
Wretch 2.8 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
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 => {
});
Wretch does it for you.
wretch("examples/example.json")
.get()
.json(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 => { })
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 => )
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.
const externalApi = wretch("http://external.api")
.auth(`Bearer ${token}`)
.options({ credentials: "include", mode: "cors" })
.resolve((_) => _.forbidden(handle403));
const resource = await externalApi
.headers({ "If-Unmodified-Since": "Wed, 21 Oct 2015 07:28:00 GMT" })
.get("/resource/1")
.json(handleResource);
externalApi
.url("/resource")
.post({ "Shiny new": "resource object" })
.json(handleNewResourceResult);
Installation
Package Manager
npm i wretch
<script> tag
The package contains multiple bundles depending on the format and feature set located under the /dist/bundle
folder.
Bundle variants
π‘ 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 |
<script src="https://unpkg.com/wretch"></script>
<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"
const w = wretch().polyfills({
fetch,
FormData,
});
Globally:
import fetch, { FormData } from "node-fetch";
global.fetch = fetch;
global.FormData = FormData;
wretch.polyfills({
fetch,
FormData,
});
Deno
Works with Deno >=
0.41.0 out of the box.
Types should be imported from /dist/types.d.ts
.
import wretch from "https://cdn.skypack.dev/wretch";
const text = await wretch("https://httpstat.us").get("/200").text();
console.log(text);
Usage
Import
import wretch from "wretch"
const wretch = require("wretch")
window.wretch
Minimal Example
import wretch from "wretch"
const api =
wretch("https://jsonplaceholder.typicode.com", { mode: "cors" })
.errorType("json")
.resolve(r => r.json())
try {
const users = await api.get("/users")
const user = users.find(({ name }) => name === "Nicholas Runolfsdottir V")
const postsByUser = await api.get(`/posts?userId=${user.id}`)
const newPost = await api.url("/posts").post({
title: "New Post",
body: "My shiny new post"
})
await api.url("/posts/" + newPost.id).patch({
title: "Updated Post",
body: "Edited body"
})
await api.get("/posts/" + newPost.id)
} catch (error) {
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.
wretch(baseUrl, baseOptions)
The "request" chain starts here.
.<helper method(s)>()
.<body type>()
.<http method>()
The "response" chain starts here.
Fetch is called after the request chain ends and before the response chain starts.
The request is on the fly and now it is time to chain catchers and finally call a response type handler.
.<catcher(s)>()
.<response type>()
From this point on, wretch returns a standard Promise.
.then(β¦)
.catch(β¦)
π‘ The API documentation is now autogenerated and hosted separately, click the links access it.
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 are used to configure the request and program actions.
w = w
.url("/resource/1")
.headers({ "Cache-Control": no-cache })
.content("text/html")
Specify a body type if uploading data. Can also be added through the HTTP Method argument.
w = w.body("<html><body><div/></body></html>")
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.
wretch().get("/url");
wretch().post({ json: "body" }, "/url");
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 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) => {
const token = await wretch("/renewtoken").get().text();
storeToken(token);
return req.auth(token).get().unauthorized((err) => {
throw err;
}).json();
})
.json()
.then(callback);
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.
wretch("...").get().json().then(json => )
const json = await wretch("...").get().json()
wretch("...").get().json(json => "Hello world!").then(console.log)
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"
const w = wretch().addon(FormDataAddon).addon(QueryStringAddon)
w.formData({ hello: "world" }).query({ check: true })
Typescript should also be fully supported and will provide completions.
https://user-images.githubusercontent.com/3428394/182319457-504a0856-abdd-4c1d-bd04-df5a061e515d.mov
Used to construct and append the query string part of the URL from an object.
import QueryStringAddon from "wretch/addons/queryString"
let w = wretch("http://example.com").addon(QueryStringAddon);
w = w.query({ a: 1, b: 2 });
w = w.query({ c: 3, d: [4, 5] });
w = w.query("five&six&seven=eight");
w = w.query({ reset: true }, true);
Adds a helper method to serialize a multipart/form-data
body from an object.
import FormDataAddon from "wretch/addons/formData"
const form = {
duck: "Muscovy",
duckProperties: {
beak: {
color: "yellow",
},
legs: 2,
},
ignored: {
key: 0,
},
};
wretch("...").addon(FormDataAddon).formData(form, ["ignored"]).post();
Adds a method to serialize a application/x-www-form-urlencoded
body from an object.
import FormUrlAddon from "wretch/addons/formUrl"
const form = { a: 1, b: { c: 2 } };
const alreadyEncodedForm = "a=1&b=%7B%22c%22%3A2%7D";
wretch("...").addon(FormUrlAddon).formUrl(form).post();
wretch("...").addon(FormUrlAddon).formUrl(alreadyEncodedForm).post();
Adds the ability to abort requests and set timeouts using AbortController and signals under the hood.
import AbortAddon from "wretch/addons/abort"
Only compatible with browsers that support
AbortControllers.
Otherwise, you could use a (partial)
polyfill.
Use cases :
const [c, w] = wretch("...")
.addon(AbortAddon())
.get()
.onAbort((_) => console.log("Aborted !"))
.controller();
w.text((_) => console.log("should never be called"));
c.abort();
const controller = new AbortController();
wretch("...")
.addon(AbortAddon())
.signal(controller)
.get()
.onAbort((_) => console.log("Aborted !"))
.text((_) => console.log("should never be called"));
controller.abort();
wretch("...").addon(AbortAddon()).get().setTimeout(1000).json(_ =>
)
Adds the ability to monitor progress when downloading a response.
Compatible with all platforms implementing the TransformStream WebAPI.
import ProgressAddon from "wretch/addons/progress"
wretch("some_url")
.addon(ProgressAddon())
.get()
.progress((loaded, total) => {
console.log(`${(loaded / total * 100).toFixed(0)}%`)
})
.text()
Adds the ability to measure requests using the Performance Timings API.
Uses the Performance API (browsers & Node.js) to expose timings related to the underlying request.
π‘ Make sure to follow the additional instructions in the documentation to setup Node.js if necessary.
Middlewares
Middlewares are functions that can intercept requests before being processed by
Fetch. Wretch includes a helper to help replicate the
middleware style.
import wretch from "wretch"
import { retry, dedupe } from "wretch/middlewares"
const w = wretch().middlewares([retry(), dedupe()])
π‘ The following middlewares were previously provided by the wretch-middlewares
package.
Retries a request multiple times in case of an error (or until a custom condition is true).
π‘ By default, the request will be retried if the response status is not in the 2xx range.
until: (response, error) => response && (response.ok || (response.status >= 400 && response.status < 500))
import wretch from 'wretch'
import { retry } from 'wretch/middlewares'
wretch().middlewares([
retry({
delayTimer: 500,
delayRamp: (delay, nbOfAttempts) => delay * nbOfAttempts,
maxAttempts: 10,
until: (response, error) => response && response.ok,
onRetry: null,
retryOnNetworkError: false,
resolveWithLatestResponse: false
})
]).
wretch().middlewares([
retry({
until: response =>
response.clone().json().then(body =>
body.field === 'something'
)
})
])
Prevents having multiple identical requests on the fly at the same time.
import wretch from 'wretch'
import { dedupe } from 'wretch/middlewares'
wretch().middlewares([
dedupe({
skip: (url, opts) => opts.skipDedupe || opts.method !== 'GET',
key: (url, opts) => opts.method + '@' + url,
resolver: response => response.clone()
})
]).
A throttling cache which stores and serves server responses for a certain amount of time.
import wretch from 'wretch'
import { throttlingCache } from 'wretch/middlewares'
wretch().middlewares([
throttlingCache({
throttle: 1000,
skip: (url, opts) => opts.skipCache || opts.method !== 'GET',
key: (url, opts) => opts.method + '@' + url,
clear: (url, opts) => false,
invalidate: (url, opts) => null,
condition: response => response.ok,
flagResponseOnCacheHit: '__cached'
})
]).
Delays the request by a specific amount of time.
import wretch from 'wretch'
import { delay } from 'wretch/middlewares'
wretch().middlewares([
delay(1000)
]).
Writing a Middleware
Basically a Middleware is a function having the following signature :
type Middleware = (options?: { [key: string]: any }) => ConfiguredMiddleware;
type ConfiguredMiddleware = (next: FetchLike) => FetchLike;
type FetchLike = (
url: string,
opts: WretchOptions,
) => Promise<WretchResponse>;
Context
If you need to manipulate data within your middleware and expose it for later
consumption, a solution could be to pass a named property to the wretch options
(suggested name: context
).
Your middleware can then take advantage of that by mutating the object
reference.
const contextMiddleware = (next) =>
(url, opts) => {
if (opts.context) {
opts.context.property = "anything";
}
return next(url, opts);
};
const context = {};
const res = await wretch("...")
.options({ context })
.middlewares([contextMiddleware])
.get()
.res();
console.log(context.property);
Advanced examples
Β π Show me the code
const delayMiddleware = delay => next => (url, opts) => {
return new Promise(res => setTimeout(() => res(next(url, opts)), delay))
}
const shortCircuitMiddleware = () => next => (url, opts) => {
const response = new Response()
response.text = () => Promise.resolve(opts.method + "@" + url)
response.json = () => Promise.resolve({ url, method: opts.method })
return Promise.resolve(response)
}
const logMiddleware = () => next => (url, opts) => {
console.log(opts.method + "@" + url)
return next(url, opts)
}
const cacheMiddleware = (throttle = 0) => {
const cache = new Map()
const inflight = new Map()
const throttling = new Set()
return next => (url, opts) => {
const key = opts.method + "@" + url
if(!opts.noCache && throttling.has(key)) {
if(cache.has(key))
return Promise.resolve(cache.get(key).clone())
else if(inflight.has(key)) {
return new Promise((resolve, reject) => {
inflight.get(key).push([resolve, reject])
})
}
}
if(!inflight.has(key))
inflight.set(key, [])
if(throttle && !throttling.has(key)) {
throttling.add(key)
setTimeout(() => { throttling.delete(key) }, throttle)
}
return next(url, opts)
.then(_ => {
cache.set(key, _.clone())
inflight.get(key).forEach((([resolve, reject]) => resolve(_.clone()))
inflight.delete(key)
return _
})
.catch(_ => {
inflight.get(key).forEach(([resolve, reject]) => reject(_))
inflight.delete(key)
throw _
})
}
}
const cache = cacheMiddleware(1000)
wretch("...").middlewares([cache]).get()
wretch("...").middlewares([
logMiddleware(),
delayMiddleware(1000),
shortCircuitMiddleware()
}).get().text(_ => console.log(text))
const wretchCache = wretch().middlewares([cacheMiddleware(1000)])
const printResource = (url, timeout = 0) =>
setTimeout(_ => wretchCache.url(url).get().notFound(console.error).text(console.log), timeout)
const resourceUrl = "/"
for(let i = 0; i < 10; i++) {
printResource(resourceUrl)
printResource(resourceUrl, 500)
printResource(resourceUrl, 1500)
}
Limitations
It seems like using wretch
in a Cloudflare Worker environment is not possible out of the box, as the Cloudflare Response
implementation does not implement the type
property and throws an error when trying to access it.
Please check the issue #159 for more information.
Workaround
The following middleware should fix the issue (thanks @jimmed π):
wretch().middlewares([
(next) => async (url, opts) => {
const response = await next(url, opts);
try {
Reflect.get(response, "type", response);
} catch (error) {
Object.defineProperty(response, "type", {
get: () => "default",
});
}
return response;
},
])
The Request
object from the Fetch API uses the Headers
class to store headers under the hood.
This class is case-insensitive, meaning that setting both will actually appends the value to the same key:
const headers = new Headers();
headers.append("Accept", "application/json");
headers.append("accept", "application/json");
headers.forEach((value, key) => console.log(key, value));
When using wretch
, please be mindful of this limitation and avoid setting the same header multiple times with a different case:
wretch(url)
.headers({ "content-type": "application/json" })
.json({ foo: "bar" })
Please check the issue #80 for more information.
Workaround
You can use the following middleware to deduplicate headers (thanks @jimmed π):
export const manipulateHeaders =
callback => next => (url, { headers, ...opts }) => {
const nextHeaders = callback(new Headers(headers))
return next(url, { ...opts, headers: nextHeaders })
}
export const dedupeHeaders = (dedupeHeaderLogic = {}) => {
const deduperMap = new Map(
Object.entries(dedupeHeaderLogic).map(([k, v]) => [k.toLowerCase(), v]),
)
const dedupe = key =>
deduperMap.get(key.toLowerCase()) ?? (values => new Set(values))
return manipulateHeaders((headers) => {
Object.entries(headers.raw()).forEach(([key, values]) => {
const deduped = Array.from(dedupe(key)(values))
headers.delete(key)
deduped.forEach((value, index) =>
headers[index ? 'append' : 'set'](key.toLowerCase(), value),
)
})
return headers
})
}
wretch().middlewares([dedupeHeaders()])
wretch().middlewares([
dedupeHeaders({
Accept: (values) => values.filter(v => v !== '*/*')
})
])
Migration from v1
Philosophy
Wretch has been completely rewritten with the following goals in mind:
- reduce its size by making it modular
- preserve the typescript type coverage
- improve the API by removing several awkward choices
Compatibility
wretch@1
was transpiled to es5, wretch@2
is now transpiled to es2018.
Any "modern" browser and Node.js versions >= 14 should parse the library without issues.
If you need compatibility with older browsers/nodejs versions then either stick with v1, use poyfills
or configure @babel
to make it transpile wretch.
Addons
Some features that were part of wretch
v1 are now split apart and must be imported through addons.
It is now needed to pass the Addon to the .addon
method to register it.
Please refer to the Addons documentation.
import wretch from "wretch"
wretch.formData({ hello: "world" }).query({ check: true })
import FormDataAddon from "wretch/addons/formData"
import QueryStringAddon from "wretch/addons/queryString"
import baseWretch from "wretch"
const wretch = baseWretch().addon(FormDataAddon).addon(QueryStringAddon)
wretch.formData({ hello: "world" }).query({ check: true })
Typescript
Types have been renamed and refactored, please update your imports accordingly and refer to the typescript api documentation.
API Changes
Replace / Mixin arguments
Some functions used to have a mixin = true
argument that could be used to merge the value, others a replace = false
argument performing the opposite.
In v2 there are only replace = false
arguments but the default behaviour should be preserved.
wretch.options({ credentials: "same-origin" }, false)
wretch.options({ credentials: "same-origin" })
wretch.options({ credentials: "same-origin" }, true)
wretch.options({ credentials: "same-origin" })
In v1 it was possible to set fetch options while calling the http methods to end the request chain.
wretch("...").get({ my: "option" })
This was a rarely used feature and the extra argument now appends a string to the base url.
wretch("https://base.com").get("/resource/1")
Replay function
The .replay
function has been renamed to .fetch
.
License
MIT