Interface Wretch<Self, Chain, Resolver>

Sets the request body with any content.

wretch("...").body("hello").put();
// Note that calling put/post methods with a non-object argument is equivalent:
wretch("...").put("hello");
Copy

Sets the "Content-Type" header, stringifies an object and sets the request body.

const jsonObject = { a: 1, b: 2, c: 3 };
wretch("...").json(jsonObject).post();
// Note that calling an 'http verb' method with an object argument is equivalent:
wretch("...").post(jsonObject);
Copy

Performs a DELETE request.

wretch("...").delete();
Copy

Sends the request using the accumulated fetch options.

Can be used to replay requests.

const reAuthOn401 = wretch()
.catcher(401, async (error, request) => {
  // Renew credentials
  const token = await wretch("/renewtoken").get().text();
  storeToken(token);
  // Replay the original request with new credentials
  return request.auth(token).fetch().unauthorized((err) => {
    throw err;
  }).json();
});

reAuthOn401
.get("/resource")
.json() // <- Will only be called for the original promise
.then(callback); // <- Will be called for the original OR the replayed promise result
Copy

Performs a GET request.

wretch("...").get();
Copy

Performs a HEAD request.

wretch("...").head();
Copy

Performs an OPTIONS request.

wretch("...").opts();
Copy

Performs a PATCH request.

wretch("...").json({...}).patch()
Copy

Performs a POST request.

wretch("...").json({...}).post()
Copy

Performs a PUT request.

wretch("...").json({...}).put()
Copy

Shortcut to set the "Accept" header.

wretch("...").accept("application/json");
Copy

Register an Addon to enhance the wretch or response objects.

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 })
Copy

Shortcut to set the "Authorization" header.

wretch("...").auth("Basic d3JldGNoOnJvY2tz");
Copy

Adds a catcher which will be called on every subsequent request error.

Very useful when you need to perform a repetitive action on a specific error code.

const w = wretch()
  .catcher(404, err => redirect("/routes/notfound", err.message))
  .catcher(500, err => flashMessage("internal.server.error"))

// No need to catch the 404 or 500 codes, they are already taken care of.
w.get("http://myapi.com/get/something").json()

// Default catchers can be overridden if needed.
w
.get("http://myapi.com/get/something")
.notFound(err =>
  // overrides the default 'redirect' catcher
 )
.json()
Copy

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

const reAuthOn401 = wretch()
.catcher(401, async (error, request) => {
  // Renew credentials
  const token = await wretch("/renewtoken").get().text();
  storeToken(token);
  // Replay the original request with new credentials
  return request.auth(token).fetch().unauthorized((err) => {
    throw err;
  }).json();
});

reAuthOn401
.get("/resource")
.json() // <- Will only be called for the original promise
.then(callback); // <- Will be called for the original OR the replayed promise result
Copy

A fallback catcher that will be called for any error thrown - if uncaught by other means.

wretch(url)
  .catcher(404, err => redirect("/routes/notfound", err.message))
  .catcher(500, err => flashMessage("internal.server.error"))
  // this fallback will trigger for any error except the ones caught above (404 and 505)
  .catcherFallback(err => {
    log("Uncaught error:", err)
    throw err
  })
Copy

See

Wretch.catcher for more details.

Shortcut to set the "Content-Type" header.

wretch("...").content("application/json");
Copy

Defer one or multiple request chain methods that will get called just before the request is sent.

// Small fictional example: deferred authentication

// If you cannot retrieve the auth token while configuring the wretch object you can use .defer to postpone the call
const api = wretch("http://some-domain.com").defer((w, url, options) => {
  // If we are hitting the route /user…
  if (//user/.test(url)) {
    const { token } = options.context;
    return w.auth(token);
  }
  return w;
});

// ... //

const token = await getToken(request.session.user);

// .auth gets called here automatically
api.options({
  context: { token },
}).get("/user/1").res();
Copy

Sets the method (text, json ...) used to parse the data contained in the response body in case of an HTTP error is returned.

Note: if the response Content-Type header is set to "application/json", the body will be parsed as json regardless of the errorType.

wretch("http://server/which/returns/an/error/with/a/json/body")
  .errorType("json")
  .get()
  .res()
  .catch(error => {
    // error[errorType] (here, json) contains the parsed body
    console.log(error.json)
  })
Copy

Sets the request headers.

wretch("...")
  .headers({ "Content-Type": "text/plain", Accept: "application/json" })
  .post("my text")
  .json();
Copy

Add middlewares to intercept a request before being sent.

// A simple delay middleware.
const delayMiddleware = delay => next => (url, opts) => {
  return new Promise(res => setTimeout(() => res(next(url, opts)), delay))
}

// The request will be delayed by 1 second.
wretch("...").middlewares([
  delayMiddleware(1000)
]).get().res()
Copy

Sets the fetch options.

wretch("...").options({ credentials: "same-origin" });
Copy

Wretch being immutable, you can store the object for later use.

const corsWretch = wretch().options({ credentials: "include", mode: "cors" });

corsWretch.get("http://endpoint1");
corsWretch.get("http://endpoint2");
Copy

You can override instead of mixing in the existing options by passing a boolean flag.

// By default options are mixed in :
let w = wretch()
  .options({ headers: { "Accept": "application/json" } })
  .options({ encoding: "same-origin", headers: { "X-Custom": "Header" } });
console.log(JSON.stringify(w._options))
// => {"encoding":"same-origin", "headers":{"Accept":"application/json","X-Custom":"Header"}}

// With the flag, options are overridden :
w = wretch()
  .options({ headers: { "Accept": "application/json" } })
  .options(
    { encoding: "same-origin", headers: { "X-Custom": "Header" } },
    true,
  );
console.log(JSON.stringify(w._options))
// => {"encoding":"same-origin","headers":{"X-Custom":"Header"}}
Copy

Sets non-global polyfills - for instance in browserless environments.

Needed for libraries like fetch-ponyfill.

const fetch = require("node-fetch");
const FormData = require("form-data");

wretch("http://domain.com")
  .polyfills({
    fetch: fetch,
    FormData: FormData,
    URLSearchParams: require("url").URLSearchParams,
  })
  .get()
Copy

Programs a resolver to perform response chain tasks automatically.

Very useful when you need to perform repetitive actions on the wretch response.

The clear argument, if set to true, removes previously defined resolvers.

// Program "response" chain actions early on
const w = wretch()
  .addon(PerfsAddon())
  .resolve(resolver => resolver
    // monitor every request…
    .perfs(console.log)
    // automatically parse and return json…
    .json()
  )

 const myJson = await w.url("http://a.com").get()
 // Equivalent to:
 // w.url("http://a.com")
 //  .get()
 //  <- the resolver chain is automatically injected here !
 //  .perfs(console.log)
 //  .json()
Copy

Appends or replaces the url.

wretch("/root").url("/sub").get().json();

// Can be used to set a base url

// Subsequent requests made using the 'blogs' object will be prefixed with "http://domain.com/api/blogs"
const blogs = wretch("http://domain.com/api/blogs");

// Perfect for CRUD apis
const id = await blogs.post({ name: "my blog" }).json(blog => blog.id);
const blog = await blogs.get(`/${id}`).json();
console.log(blog.name);

await blogs.url(`/${id}`).delete().res();

// And to replace the base url if needed :
const noMoreBlogs = blogs.url("http://domain2.com/", true);
Copy