Wretch

A tiny wrapper built around fetch with an intuitive syntax.

HTTP client • Fetch • AJAX
elbywan/wretchwretch

README

wretch-logo

Wretch

github-badge npm-badge npm-downloads-badge Coverage Status license-badge

A tiny (~1.9KB g-zipped) wrapper built around fetch with an intuitive syntax.

f[ETCH] [WR]apper

Wretch 2.1 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](#motivation)
- [Installation](#installation)
- [Compatibility](#compatibility)
- [Usage](#usage)
- [Api](#api-)
- [Addons](#addons)
- [Middlewares](#middlewares)
- [Migration from v1](#migration-from-v1)
- [License](#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.

  1. ``` js
  2. fetch("examples/example.json")
  3.   .then(response => response.json())
  4.   .then(json => {
  5.     //Do stuff with the parsed json
  6.   });
  7. ```

Wretch does it for you.

  1. ``` js
  2. // Use .res for the raw response, .text for raw text, .json for json, .blob for a blob ...
  3. wretch("examples/example.json")
  4.   .get()
  5.   .json(json => {
  6.     // Do stuff with the parsed json
  7.   });
  8. ```

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


Fetch won’t reject on HTTP error status.

  1. ``` js
  2. fetch("anything")
  3.   .then(response => {
  4.     if(!response.ok) {
  5.       if(response.status === 404) throw new Error("Not found")
  6.       else if(response.status === 401) throw new Error("Unauthorized")
  7.       else if(response.status === 418) throw new Error("I'm a teapot !")
  8.       else throw new Error("Other error")
  9.     }
  10.     else // ...
  11.   })
  12.   .then(data => /* ... */)
  13.   .catch(error => { /* ... */ })
  14. ```

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

  1. ``` js
  2. wretch("anything")
  3.   .get()
  4.   .notFound(error => { /* ... */ })
  5.   .unauthorized(error => { /* ... */ })
  6.   .error(418, error => { /* ... */ })
  7.   .res(response => /* ... */)
  8.   .catch(error => { /* uncaught errors */ })
  9. ```

Because sending a json object should be easy.


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

  1. ``` js
  2. fetch("endpoint", {
  3.   method: "POST",
  4.   headers: { "Content-Type": "application/json" },
  5.   body: JSON.stringify({ "hello": "world" })
  6. }).then(response => /* ... */)
  7. // Omitting the data retrieval and error management parts…
  8. ```

With wretch, you have shorthands at your disposal.

  1. ``` js
  2. wretch("endpoint")
  3.   .post({ "hello": "world" })
  4.   .res(response => /* ... */)
  5. ```

Because configuration should not rhyme with repetition.


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

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

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

  18. // Post a resource
  19. externalApi
  20.   .url("/resource")
  21.   .post({ "Shiny new": "resource object" })
  22.   .json(handleNewResourceResult);
  23. ```

Installation


Package Manager


  1. ```sh
  2. npm i wretch # or yarn/pnpm add wretch
  3. ```

<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


FeatureFile
-------------------------------------
Core`wretch.min.js`
Core`wretch.all.min.js`

FormatExtension
------------------
ESM`.min.mjs`
CommonJS`.min.cjs`
UMD`.min.js`


  1. ``` html
  2. <!--
  3.   Pick your favourite CDN:
  4.     - https://unpkg.com/wretch
  5.     - https://cdn.jsdelivr.net/npm/wretch/
  6.     - https://www.skypack.dev/view/wretch
  7.     - https://cdnjs.com/libraries/wretch
  8.     - …
  9. -->
  10. <script src="https://unpkg.com/wretch"></script>
  11. <script type="module">
  12.   import wretch from 'https://cdn.skypack.dev/wretch/dist/bundle/wretch.all.min.mjs'
  14.   // ... //
  15. </script>
  16. ```

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.

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

>

For older versions of Node.js, Wretch requires installing FormData and fetch polyfills.


Polyfills


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

_The non-global way (preferred):_

  1. ``` js
  2. // w is a reusable wretch instance
  3. const w = wretch().polyfills({
  4.   fetch: require("node-fetch"),
  5.   FormData: require("form-data"),
  6.   URLSearchParams: require("url").URLSearchParams,
  7. });
  8. ```

_Globally:_

  1. ``` js
  2. // Either mutate the global object…
  3. global.fetch = require("node-fetch");
  4. global.FormData = require("form-data");
  5. global.URLSearchParams = require("url").URLSearchParams;

  7. // …or use the static wretch.polyfills method to impact every wretch instance created afterwards.
  8. wretch.polyfills({
  9.   fetch: require("node-fetch"),
  10.   FormData: require("form-data"),
  11.   URLSearchParams: require("url").URLSearchParams,
  12. });
  13. ```

Deno


Works with Deno >=
0.41.0 out of the box.

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

  1. ```ts
  2. // You can import wretch from any CDN that serve ESModules.
  3. import wretch from "https://cdn.skypack.dev/wretch";

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

Usage


Import


  1. ```typescript
  2. // ECMAScript modules
  3. import wretch from "wretch"
  4. // CommonJS
  5. const wretch = require("wretch")
  6. // Global variable (script tag)
  7. window.wretch
  8. ```

Minimal Example


  1. ``` js
  2. import wretch from "wretch"

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

  10. try {
  11.   // Fetch users
  12.   const users = await api.get("/users")
  13.   // Find all posts from a given user
  14.   const user = users.find(({ name }) => name === "Nicholas Runolfsdottir V")
  15.   const postsByUser = await api.get(`/posts?userId=${user.id}`)
  16.   // Create a new post
  17.   const newPost = await api.url("/posts").post({
  18.     title: "New Post",
  19.     body: "My shiny new post"
  20.   })
  21.   // Patch it
  22.   await api.url("/posts/" + newPost.id).patch({
  23.     title: "Updated Post",
  24.     body: "Edited body"
  25.   })
  26.   // Fetch it
  27.   await api.get("/posts/" + newPost.id)
  28. } catch (error) {
  29.   // The API could return an empty object - in which case the status text is logged instead.
  30.   const message =
  31.     typeof error.message === "object" && Object.keys(error.message).length > 0
  32.       ? JSON.stringify(error.message)
  33.       : error.response.statusText
  34.   console.error(`${error.status}: ${message}`)
  35. }
  36. ```

Chaining


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

  1. ```ts
  2. // First, instantiate wretch
  3. wretch(baseUrl, baseOptions)
  4. ```

_The "request" chain starts here._

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

_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._

  1. ```ts
  2.   // Optional - You can chain error handlers here
  3.   .<catcher(s)>()
  4.   // Required - Specify the data type you need, which will be parsed and handed to you
  5.   .<response type>()
  6.   // >> Ends the response chain.
  7. ```

_From this point on, wretch returns a standard Promise._

  1. ```ts
  2.   .then(…)
  3.   .catch(…)
  4. ```

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.

  1. ``` js
  2. import wretch from "wretch"

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

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

Helper Methods 🔗


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

  1. ``` js
  2. w = w
  3.   .url("/resource/1")
  4.   .headers({ "Cache-Control": no-cache })
  5.   .content("text/html")
  6. ```

Body Types 🔗


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

  1. ``` js
  2. w = w.body("<html><body><div/></body></html>")
  3. ```

HTTP Methods 🔗


Setus 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.

  1. ``` js
  2. // These shorthands:
  3. wretch().get("/url");
  4. wretch().post({ json: "body" }, "/url");
  5. // Are equivalent to:
  6. wretch().url("/url").get();
  7. wretch().json({ json: "body" }).url("/url").post();
  8. ```

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.

  1. ``` js
  2. wretch("...")
  3.   .get()
  4.   .badRequest((err) => console.log(err.status))
  5.   .unauthorized((err) => console.log(err.status))
  6.   .forbidden((err) => console.log(err.status))
  7.   .notFound((err) => console.log(err.status))
  8.   .timeout((err) => console.log(err.status))
  9.   .internalError((err) => console.log(err.status))
  10.   .error(418, (err) => console.log(err.status))
  11.   .fetchError((err) => console.log(err))
  12.   .res();
  13. ```

The error passed to catchers is enhanced with additional properties.

  1. ```ts
  2. type WretchError = Error & {
  3.   status: number;
  4.   response: WretchResponse;
  5.   text?: string;
  6.   json?: Object;
  7. };
  8. ```

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

  1. ``` js
  2. wretch("/resource")
  3.   .get()
  4.   .unauthorized(async (error, req) => {
  5.     // Renew credentials
  6.     const token = await wretch("/renewtoken").get().text();
  7.     storeToken(token);
  8.     // Replay the original request with new credentials
  9.     return req.auth(token).get().unauthorized((err) => {
  10.       throw err;
  11.     }).json();
  12.   })
  13.   .json()
  14.   // The promise chain is preserved as expected
  15.   // ".then" will be performed on the result of the original request
  16.   // or the replayed one (if a 401 error was thrown)
  17.   .then(callback);
  18. ```

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.

  1. ``` js
  2. // Without a callback
  3. wretch("...").get().json().then(json => /* json is the parsed json of the response body */)
  4. // Without a callback using await
  5. const json = await wretch("...").get().json()
  6. // With a callback the value returned is passed to the Promise
  7. wretch("...").get().json(json => "Hello world!").then(console.log) // => Hello world!
  8. ```

_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.

  1. ``` js
  2. import FormDataAddon from "wretch/addons/formData"
  3. import QueryStringAddon from "wretch/addons/queryString"

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

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

Typescript should also be fully supported and will provide completions.

https://user-images.githubusercontent.com/3428394/182319457-504a0856-abdd-4c1d-bd04-df5a061e515d.mov

QueryString 🔗


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

  1. ``` js
  2. import QueryStringAddon from "wretch/addons/queryString"
  3. ```

FormData 🔗


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

  1. ``` js
  2. import FormDataAddon from "wretch/addons/formData"
  3. ```

FormUrl 🔗


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

  1. ``` js
  2. import FormUrlAddon from "wretch/addons/formUrl"
  3. ```

Abort 🔗


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

  1. ``` js
  2. import AbortAddon from "wretch/addons/abort"
  3. ```

_Only compatible with browsers that support
AbortControllers.
Otherwise, you could use a (partial)
polyfill._

Use cases :

  1. ``` js
  2. const [c, w] = wretch("...")
  3.   .addon(AbortAddon())
  4.   .get()
  5.   .onAbort((_) => console.log("Aborted !"))
  6.   .controller();

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

  11. // Or :

  13. const controller = new AbortController();

  15. wretch("...")
  16.   .addon(AbortAddon())
  17.   .signal(controller)
  18.   .get()
  19.   .onAbort((_) => console.log("Aborted !"))
  20.   .text((_) => console.log("should never be called"));

  22. controller.abort();
  23. ```

  1. ``` js
  2. // 1 second timeout
  3. wretch("...").addon(AbortAddon()).get().setTimeout(1000).json(_ =>
  4.   // will not be called if the request timeouts
  5. )
  6. ```

Performance 🔗


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.

  1. ``` js
  2. import wretch from "wretch"
  3. import { retry, dedupe } from "wretch/middlewares"

  5. const w = wretch().middlewares([retry(), dedupe()])
  6. ```

💡 The following middlewares were previously provided by the [wretch-middlewares](https://github.com/elbywan/wretch-middlewares/) package.


Retry 🔗


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

  1. ``` js
  2. import wretch from 'wretch'
  3. import { retry } from 'wretch/middlewares'

  5. wretch().middlewares([
  6.   retry({
  7.     /* Options - defaults below */
  8.     delayTimer: 500,
  9.     delayRamp: (delay, nbOfAttempts) => delay * nbOfAttempts,
  10.     maxAttempts: 10,
  11.     until: (response, error) => response && response.ok,
  12.     onRetry: null,
  13.     retryOnNetworkError: false,
  14.     resolveWithLatestResponse: false
  15.   })
  16. ])./* ... */

  18. // You can also return a Promise, which is useful if you want to inspect the body:
  19. wretch().middlewares([
  20.   retry({
  21.     until: response =>
  22.       response.clone().json().then(body =>
  23.         body.field === 'something'
  24.       )
  25.   })
  26. ])
  27. ```

Dedupe 🔗


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

  1. ``` js
  2. import wretch from 'wretch'
  3. import { dedupe } from 'wretch/middlewares'

  5. wretch().middlewares([
  6.   dedupe({
  7.     /* Options - defaults below */
  8.     skip: (url, opts) => opts.skipDedupe || opts.method !== 'GET',
  9.     key: (url, opts) => opts.method + '@' + url,
  10.     resolver: response => response.clone()
  11.   })
  12. ])./* ... */
  13. ```

Throttling Cache 🔗


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

  1. ``` js
  2. import wretch from 'wretch'
  3. import { throttlingCache } from 'wretch/middlewares'

  5. wretch().middlewares([
  6.   throttlingCache({
  7.     /* Options - defaults below */
  8.     throttle: 1000,
  9.     skip: (url, opts) => opts.skipCache || opts.method !== 'GET',
  10.     key: (url, opts) => opts.method + '@' + url,
  11.     clear: (url, opts) => false,
  12.     invalidate: (url, opts) => null,
  13.     condition: response => response.ok,
  14.     flagResponseOnCacheHit: '__cached'
  15.   })
  16. ])./* ... */
  17. ```

Delay 🔗


Delays the request by a specific amount of time.

  1. ``` js
  2. import wretch from 'wretch'
  3. import { delay } from 'wretch/middlewares'

  5. wretch().middlewares([
  6.   delay(1000)
  7. ])./* ... */
  8. ```

Writing a Middleware


Basically a Middleware is a function having the following signature :

  1. ```ts
  2. // A middleware accepts options and returns a configured version
  3. type Middleware = (options?: { [key: string]: any }) => ConfiguredMiddleware;
  4. // A configured middleware (with options curried)
  5. type ConfiguredMiddleware = (next: FetchLike) => FetchLike;
  6. // A "fetch like" function, accepting an url and fetch options and returning a response promise
  7. type FetchLike = (
  8.   url: string,
  9.   opts: WretchOptions,
  10. ) => Promise<WretchResponse>;
  11. ```

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.

  1. ``` js
  2. const contextMiddleware = (next) =>
  3.   (url, opts) => {
  4.     if (opts.context) {
  5.       // Mutate "context"
  6.       opts.context.property = "anything";
  7.     }
  8.     return next(url, opts);
  9.   };

  11. // Provide the reference to a "context" object
  12. const context = {};
  13. const res = await wretch("...")
  14.   // Pass "context" by reference as an option
  15.   .options({ context })
  16.   .middlewares([contextMiddleware])
  17.   .get()
  18.   .res();

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

Advanced examples


 👀 Show me the code

  1. ``` js
  2. /* A simple delay middleware. */
  3. const delayMiddleware = delay => next => (url, opts) => {
  4.   return new Promise(res => setTimeout(() => res(next(url, opts)), delay))
  5. }

  7. /* Returns the url and method without performing an actual request. */
  8. const shortCircuitMiddleware = () => next => (url, opts) => {
  9.   // We create a new Response object to comply because wretch expects that from fetch.
  10.   const response = new Response()
  11.   response.text = () => Promise.resolve(opts.method + "@" + url)
  12.   response.json = () => Promise.resolve({ url, method: opts.method })
  13.   // Instead of calling next(), returning a Response Promise bypasses the rest of the chain.
  14.   return Promise.resolve(response)
  15. }

  17. /* Logs all requests passing through. */
  18. const logMiddleware = () => next => (url, opts) => {
  19.   console.log(opts.method + "@" + url)
  20.   return next(url, opts)
  21. }

  23. /* A throttling cache. */
  24. const cacheMiddleware = (throttle = 0) => {

  26.   const cache = new Map()
  27.   const inflight = new Map()
  28.   const throttling = new Set()

  30.   return next => (url, opts) => {
  31.     const key = opts.method + "@" + url

  33.     if(!opts.noCache && throttling.has(key)) {
  34.       // If the cache contains a previous response and we are throttling, serve it and bypass the chain.
  35.       if(cache.has(key))
  36.         return Promise.resolve(cache.get(key).clone())
  37.       // If the request in already in-flight, wait until it is resolved
  38.       else if(inflight.has(key)) {
  39.         return new Promise((resolve, reject) => {
  40.           inflight.get(key).push([resolve, reject])
  41.         })
  42.       }
  43.     }

  45.     // Init. the pending promises Map
  46.     if(!inflight.has(key))
  47.       inflight.set(key, [])

  49.     // If we are not throttling, activate the throttle for X milliseconds
  50.     if(throttle && !throttling.has(key)) {
  51.       throttling.add(key)
  52.       setTimeout(() => { throttling.delete(key) }, throttle)
  53.     }

  55.     // We call the next middleware in the chain.
  56.     return next(url, opts)
  57.       .then(_ => {
  58.         // Add a cloned response to the cache
  59.         cache.set(key, _.clone())
  60.         // Resolve pending promises
  61.         inflight.get(key).forEach((([resolve, reject]) => resolve(_.clone()))
  62.         // Remove the inflight pending promises
  63.         inflight.delete(key)
  64.         // Return the original response
  65.         return _
  66.       })
  67.       .catch(_ => {
  68.         // Reject pending promises on error
  69.         inflight.get(key).forEach(([resolve, reject]) => reject(_))
  70.         inflight.delete(key)
  71.         throw _
  72.       })
  73.   }
  74. }

  76. // To call a single middleware
  77. const cache = cacheMiddleware(1000)
  78. wretch("...").middlewares([cache]).get()

  80. // To chain middlewares
  81. wretch("...").middlewares([
  82.   logMiddleware(),
  83.   delayMiddleware(1000),
  84.   shortCircuitMiddleware()
  85. }).get().text(_ => console.log(text))

  87. // To test the cache middleware more thoroughly
  88. const wretchCache = wretch().middlewares([cacheMiddleware(1000)])
  89. const printResource = (url, timeout = 0) =>
  90.   setTimeout(_ => wretchCache.url(url).get().notFound(console.error).text(console.log), timeout)
  91. // The resource url, change it to an invalid route to check the error handling
  92. const resourceUrl = "/"
  93. // Only two actual requests are made here even though there are 30 calls
  94. for(let i = 0; i < 10; i++) {
  95.   printResource(resourceUrl)
  96.   printResource(resourceUrl, 500)
  97.   printResource(resourceUrl, 1500)
  98. }
  99. ```


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](#addonaddon-wretchaddon) method to register it.

Please refer to the Addons documentation.

  1. ``` js
  2. /* Previously (wretch@1) */
  3. import wretch from "wretch"

  5. wretch.formData({ hello: "world" }).query({ check: true })

  7. /* Now (wretch@2) */
  8. import FormDataAddon from "wretch/addons/formData"
  9. import QueryStringAddon from "wretch/addons/queryString"
  10. import wretch as baseWretch from "wretch"

  12. // Add both addons
  13. const wretch = baseWretch().addon(FormDataAddon).addon(QueryStringAddon)

  15. // Additional features are now available
  16. wretch.formData({ hello: "world" }).query({ check: true })
  17. ```

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.

  1. ``` js
  2. /* Previously (wretch@1) */
  3. wretch.options({ credentials: "same-origin" }, false) // false: do not merge the value
  4. wretch.options({ credentials: "same-origin" }) // Default behaviour stays the same

  6. /* Now (wretch@2) */
  7. wretch.options({ credentials: "same-origin" }, true) // true: replace the existing value
  8. wretch.options({ credentials: "same-origin" }) // Default behaviour stays the same
  9. ```

HTTP methods extra argument


In v1 it was possible to set fetch options while calling the http methods to end the request chain.

  1. ``` js
  2. /* Previously (wretch@1) */
  3. wretch("...").get({ my: "option" })
  4. ```

This was a rarely used feature and the extra argument now appends a string to the base url.

  1. ``` js
  2. /* Now (wretch@2) */
  3. wretch("https://base.com").get("/resource/1")
  4. ```

Replay function


The .replay function has been renamed to [.fetch](https://elbywan.github.io/wretch/api/interfaces/index.Wretch.html#fetch).

License


MIT