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");
The body contents
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);
An object which will be serialized into a JSON
Optional
contentType: stringA custom content type.
Performs a DELETE request.
wretch("...").delete();
Optional
url: stringSends 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
Optional
method: stringThe HTTP method to use
Optional
url: stringSome url to append
Optional
body: anySet the body. Behaviour varies depending on the argument type, an object is considered as json.
Performs a GET request.
wretch("...").get();
Optional
url: stringPerforms a HEAD request.
wretch("...").head();
Optional
url: stringPerforms an OPTIONS request.
wretch("...").opts();
Optional
url: stringPerforms a PATCH request.
wretch("...").json({...}).patch()
Optional
body: anyOptional
url: stringPerforms a POST request.
wretch("...").json({...}).post()
Optional
body: anyOptional
url: stringPerforms a PUT request.
wretch("...").json({...}).put()
Optional
body: anyOptional
url: stringShortcut to set the "Accept" header.
wretch("...").accept("application/json");
Header value
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 })
A Wretch addon to register
Shortcut to set the "Authorization" header.
wretch("...").auth("Basic d3JldGNoOnJvY2tz");
Header value
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()
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
Error code or name
The catcher method
Shortcut to set the "Content-Type" header.
wretch("...").content("application/json");
Header value
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();
Exposes the wretch instance, url and options to program deferred methods.
Optional
clear: ClearReplace the existing deferred methods if true instead of pushing to the existing list.
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)
})
The method to call on the Fetch response to read the body and use it as the Error message
Sets the request headers.
wretch("...")
.headers({ "Content-Type": "text/plain", Accept: "application/json" })
.post("my text")
.json();
An object containing header keys and values
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()
Optional
clear: booleanSets the fetch options.
wretch("...").options({ credentials: "same-origin" });
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");
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"}}
New options
Optional
replace: booleanIf true, replaces the existing options
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()
An object containing the polyfills
Optional
replace: booleanIf true, replaces the current polyfills instead of mixing in
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()
Resolver callback
Optional
clear: ClearAppends 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);
Url segment
Optional
replace: booleanIf true, replaces the current url instead of appending
Generated using TypeDoc
The Wretch object used to perform easy fetch requests.
Immutability : almost every method of this class return a fresh Wretch object.