Available methods: .get() · .post() · .put() · .patch() · .delete() · .head() · .opts()


`js
const api = wretch("http://jsonplaceholder.typicode.com")

// These shorthands:
api.get("/posts");
api.post({ json: "body" }, "/posts");
// Are equivalent to:
api.url("/posts").get();
api.json({ json: "body" }).url("/posts").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.

$3

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.

Available methods: .badRequest() · .unauthorized() · .forbidden() · .notFound() · .timeout() · .internalError() · .error() · .fetchError()


`js
wretch("http://domain.com/resource")
.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.


`ts
type WretchError = Error & {
status: number;
response: WretchResponse;
url: string;
};
`

By default, error.message is set to the response body text (or statusText if body parsing fails).

#### Request Replay

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


`js
await wretch("https://httpbingo.org/basic-auth/user/pass")
.addon(BasicAuthAddon)
.basicAuth("user", "wrongpass")
.get()
.unauthorized(async (error, req) => {
// Renew credentials
const password = await wretch("https://httpbingo.org/base64/decode/cGFzcw==").get().text();
// Replay the original request with new credentials
return req
.basicAuth("user", password)
.fetch()
.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(() => { / … / });
`

$3

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.

Available methods: .res() · .json() · .text() · .blob() · .arrayBuffer() · .formData()


`js
const ENDPOINT = "https://jsonplaceholder.typicode.com/posts/1"

// Without a callback
wretch(ENDPOINT)
.get()
.json()
.then(json => {
/ the json argument is the parsed json of the response body /
})
// Without a callback using await
const json = await wretch(ENDPOINT).get().json()
// With a callback the value returned is passed to the Promise
wretch(ENDPOINT).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.


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

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

// Additional features are now available
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

$3

Used to construct and append the query string part of the URL from an object.


`js
import QueryStringAddon from "wretch/addons/queryString"

let w = wretch("http://example.com").addon(QueryStringAddon);
// url is http://example.com
w = w.query({ a: 1, b: 2 });
// url is now http://example.com?a=1&b=2
w = w.query({ c: 3, d: [4, 5] });
// url is now http://example.com?a=1&b=2c=3&d=4&d=5
w = w.query("five&six&seven=eight");
// url is now http://example.com?a=1&b=2c=3&d=4&d=5&five&six&seven=eight
w = w.query({ reset: true }, { replace: true });
// url is now http://example.com?reset=true
`

$3

Adds a helper method to serialize a multipart/form-data body from an object.


`js
import FormDataAddon from "wretch/addons/formData"

const form = {
duck: "Muscovy",
duckProperties: {
beak: {
color: "yellow",
},
legs: 2,
},
ignored: {
key: 0,
},
};

// Will append the following keys to the FormData payload:
// "duck", "duckProperties[beak][color]", "duckProperties[legs]"
wretch("https://httpbingo.org/post").addon(FormDataAddon).formData(form, { recursive: ["ignored"] }).post();
`

$3

Adds a method to serialize a application/x-www-form-urlencoded body from an object.


`js
import FormUrlAddon from "wretch/addons/formUrl"

const form = { a: 1, b: { c: 2 } };
const alreadyEncodedForm = "a=1&b=%7B%22c%22%3A2%7D";

// Automatically sets the content-type header to "application/x-www-form-urlencoded"
wretch("https://httpbingo.org/post").addon(FormUrlAddon).formUrl(form).post();
wretch("https://httpbingo.org/post").addon(FormUrlAddon).formUrl(alreadyEncodedForm).post();
`

$3

Adds the ability to abort requests and set timeouts using AbortController and signals under the hood.


`js
import AbortAddon from "wretch/addons/abort"
`

Use cases :


`js
const [c, w] = wretch("https://httpbingo.org/get")
.addon(AbortAddon())
.get()
.onAbort((_) => console.log("Aborted !"))
.controller();

w.text((_) => console.log("should never be called"));
c.abort();

// Or :

const controller = new AbortController();

wretch("https://httpbingo.org/get")
.addon(AbortAddon())
.signal(controller)
.get()
.onAbort((_) => console.log("Aborted !"))
.text((_) => console.log("should never be called"));

controller.abort();
`


`js
await wretch("https://httpbingo.org/delay/2")
.addon(AbortAddon())
.get()
// 1 second timeout
.setTimeout(1000)
.onAbort(_ => {
console.log("Request timed out")
})
.json(_ => {
console.log("Response received in time")
})
`

$3

Adds the ability to set the Authorization header for the basic authentication scheme without the need to manually encode the username/password.

Also, allows using URLs with wretch that contain credentials, which would otherwise throw an error.


`js
import BasicAuthAddon from "wretch/addons/basicAuth"

const user = "user"
const pass = "pass"

// Automatically sets the Authorization header to "Basic " +
wretch("https://httpbingo.org/get")
.addon(BasicAuthAddon)
.basicAuth(user, pass)
.get()

// Allows using URLs with credentials in them
wretch(https://${user}:${pass}@httpbingo.org/basic-auth/${user}/${pass})
.addon(BasicAuthAddon)
.get()
`

$3

Adds the ability to monitor progress when downloading or uploading.

_Compatible with all platforms implementing the TransformStream WebAPI._

Download progress:


`js
import ProgressAddon from "wretch/addons/progress"

await wretch("https://httpbingo.org/bytes/5000")
.addon(ProgressAddon())
.get()
// Called with the number of bytes loaded and the total number of bytes to load
.progress((loaded, total) => {
console.log(Download: ${(loaded / total * 100).toFixed(0)}%)
})
.blob()
`

Upload progress:


`js
import ProgressAddon from "wretch/addons/progress"
import FormDataAddon from "wretch/addons/formData"

const formData = new FormData()
formData.append('file', file)

wretch("https://httpbingo.org/post")
.addon([ProgressAddon(), FormDataAddon])
.onUpload((loaded, total) => {
console.log(Upload: ${(loaded / total * 100).toFixed(0)}%)
})
.post(formData)
.res()
`

> Note for browsers: Upload progress requires HTTPS (HTTP/2) in Chrome/Chromium and doesn't work in Firefox due to streaming limitations. Works fully in Node.js.

$3

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.


`js
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.

$3

Retries a request multiple times in case of an error (or until a custom condition is true).

> 💡 By default, the request will be retried only for server errors (5xx) and other non-successful responses, but not for client errors (4xx).
>
> `js
> // To retry on all non-2xx responses (including 4xx):
> until: (response, error) => !!response && response.ok
> `


`js
import wretch from 'wretch'
import { retry } from 'wretch/middlewares'

wretch().middlewares([
retry({
/ Options - defaults below /
delayTimer: 500,
delayRamp: (delay, nbOfAttempts) => delay * nbOfAttempts,
maxAttempts: 10,
until: (response, error) => !!response && (response.ok || (response.status >= 400 && response.status < 500)),
onRetry: undefined,
retryOnNetworkError: false,
resolveWithLatestResponse: false
})
])

// You can also return a Promise, which is useful if you want to inspect the body:
wretch().middlewares([
retry({
until: response =>
response?.clone().json().then(body =>
body.field === 'something'
) || false
})
])
`

$3

Prevents having multiple identical requests on the fly at the same time.


`js
import wretch from 'wretch'
import { dedupe } from 'wretch/middlewares'

wretch().middlewares([
dedupe({
/ Options - defaults below /
skip: (url, opts) => opts.skipDedupe || opts.method !== 'GET',
key: (url, opts) => opts.method + '@' + url,
resolver: response => response.clone()
})
])
`

$3

A throttling cache which stores and serves server responses for a certain amount of time.


`js
import wretch from 'wretch'
import { throttlingCache } from 'wretch/middlewares'

wretch().middlewares([
throttlingCache({
/ Options - defaults below /
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'
})
])
`

$3

Delays the request by a specific amount of time.


`js
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 :


`ts
// A middleware accepts options and returns a configured version
type Middleware = (options?: { [key: string]: any }) => ConfiguredMiddleware;
// A configured middleware (with options curried)
type ConfiguredMiddleware = (next: FetchLike) => FetchLike;
// A "fetch like" function, accepting an url and fetch options and returning a response promise
type FetchLike = (
url: string,
opts: WretchOptions,
) => Promise;
`

$3

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.


`js
const contextMiddleware = (next) =>
(url, opts) => {
if (opts.context) {
// Mutate "context"
opts.context.property = "anything";
}
return next(url, opts);
};

// Provide the reference to a "context" object
const context = {};
const res = await wretch("https://httpbingo.org/get")
// Pass "context" by reference as an option
.options({ context })
.middlewares([contextMiddleware])
.get()
.res();

console.log(context.property); // prints "anything"
`

$3

Limitations

Cloudflare Workers

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.

$3

The following middleware should fix the issue (thanks @jimmed 🙇):


`js
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;
},
])
`

Headers Case Sensitivity

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:


`js
const headers = new Headers();
headers.append("Accept", "application/json");
headers.append("accept", "application/json");
headers.forEach((value, key) => console.log(key, value));
// prints: accept application/json, application/json
`

When using wretch, please be mindful of this limitation and avoid setting the same header multiple times with a different case:


`js
wretch("https://httpbingo.org/post")
.headers({ "content-type": "application/json" })
// .json is a shortcut for .headers("Content-Type": "application/json").post().json()
.json({ foo: "bar" })
// Wretch stores the headers inside a plain javascript object and will not deduplicate them.
// Later on when fetch builds the Headers object the content type header will be set twice
// and its value will be "application/json, application/json".
// Ultimately this is certainly not what you want.
`

#### Please check the issue #80 for more information.

$3

You can use the following middleware to deduplicate headers (thanks @jimmed 🙇):


`js
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) =>
headersindex ? 'append' : 'set', value),
)
})
return headers
})
}

// By default, it will deduplicate identical values for a given header. This can be used as follows:
wretch().middlewares([dedupeHeaders()])
// If there is a specific header for which the defaults cause problems, then you can provide a callback to handle deduplication yourself:
wretch().middlewares([
dedupeHeaders({
Accept: (values) => values.filter(v => v !== '/')
})
])
``

Migration Guides

Comprehensive migration guides are available for upgrading between major versions:

- Migration Guide: v2 to v3
- Migration Guide: v1 to v2

License

MIT