refactor(auth): Implement new initializer function API (#3012)

.changeset/perfect-lobsters-kiss.md

···
+---
+'@urql/exchange-auth': major
+---
+
+Implement new `authExchange` API, which removes the need for an `authState` (i.e. an internal authentication state) and removes `getAuth`, replacing it with a separate `refreshAuth` flow.
+
+The new API requires you to now pass an initializer function. This function receives a `utils`
+object with `utils.mutate` and `utils.appendHeaders` utility methods.
+It must return the configuration object, wrapped in a promise, and this configuration is similar to
+what we had before, if you're migrating to this. Its `refreshAuth` method is now only called after
+authentication errors occur and not on initialization. Instead, it's now recommended that you write
+your initialization logic in-line.
+
+```js
+authExchange(async utils => {
+  let token = localStorage.getItem('token');
+  let refreshToken = localStorage.getItem('refreshToken');
+  return {
+    addAuthToOperation(operation) {
+      return utils.appendHeaders(operation, {
+        Authorization: `Bearer ${token}`,
+      });
+    },
+    didAuthError(error) {
+      return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
+    },
+    async refreshAuth() {
+      const result = await utils.mutate(REFRESH, { token });
+      if (result.data?.refreshLogin) {
+        token = result.data.refreshLogin.token;
+        refreshToken = result.data.refreshLogin.refreshToken;
+        localStorage.setItem('token', token);
+        localStorage.setItem('refreshToken', refreshToken);
+      }
+    },
+  };
+});
+```

docs/advanced/authentication.md

···
   exchanges: [
     dedupExchange,
     cacheExchange,
-    authExchange({
-      /* config */
+    authExchange(async utils => {
+      return {
+        /* config... */
+      };
     }),
     fetchExchange,
   ],
 });
 ```
 
+You pass an initialization function to the `authExchange`. This function is called by the exchange
+when it first initializes. It'll let you receive an object of utilities and you must return
+a (promisified) object of configuration options.
+
 Let's discuss each of the [configuration options](../api/auth-exchange.md#options) and how to use them in turn.
 
-### Configuring `getAuth` (initial load, fetch from storage)
+### Configuring the initializer function (initial load)
 
-The `getAuth` option is used to fetch the auth state. This is how to configure it for fetching the tokens at initial launch in React:
+The initializer function must return a promise of a configuration object and hence also gives you an
+opportunity to fetch your authentication state from storage.
 
 ```js
-const getAuth = async ({ authState }) => {
-  if (!authState) {
-    const token = localStorage.getItem('token');
-    const refreshToken = localStorage.getItem('refreshToken');
-    if (token && refreshToken) {
-      return { token, refreshToken };
-    }
-    return null;
-  }
+async function initializeAuthState() {
+  const token = localStorage.getItem('token');
+  const refreshToken = localStorage.getItem('refreshToken');
+  return { token, refreshToken };
+}
 
-  return null;
-};
+authExchange(async utils => {
+  let { token, refreshToken } = initializeAuthState();
+  return {
+    /* config... */
+  };
+});
 ```
 
-We check that the `authState` doesn't already exist (this indicates that it is the first time this exchange is executed and not an auth failure) and fetch the auth state from
-storage. The structure of this particular `authState` is an object with keys for `token` and
-`refreshToken`, but this format is not required. We can use different keys or store any additional
-auth related information here. For example, we could decode and store the token expiry date, which
-would save us from decoding the JWT every time we want to check whether it has expired.
+The first step here is to retrieve our tokens from a kind of storage, which may be asynchronous as
+well, as illustrated by `initializeAuthState`.
 
-In React Native, this is very similar, but because persisted storage in React Native is always asynchronous, so is this function:
+In React Native, this is very similar, but because persisted storage in React Native is always
+asynchronous and promisified, we would await our tokens. This works because the
+function that `authExchange` is async, i.e. must return a `Promise`.
 
 ```js
-const getAuth = async ({ authState, mutate }) => {
-  if (!authState) {
-    const token = await AsyncStorage.getItem(TOKEN_KEY, {});
-    const refreshToken = await AsyncStorage.getItem(REFRESH_TOKEN_KEY, {});
-    if (token && refreshToken) {
-      return { token, refreshToken };
-    }
-    return null;
-  }
+async function initializeAuthState() {
+  const token = await AsyncStorage.getItem(TOKEN_KEY);
+  const refreshToken = await AyncStorage.getItem(REFRESH_KEY);
+  return { token, refreshToken };
+}
 
-  return null;
-};
+authExchange(async utils => {
+  let { token, refreshToken } = initializeAuthState();
+  return {
+    /* config... */
+  };
+});
 ```
 
 ### Configuring `addAuthToOperation`
 
-The purpose of `addAuthToOperation` is to apply an auth state to each request. Note that the format
-of the `authState` will be whatever we've returned from `getAuth` and not constrained by the exchange:
-
-```js
-import { makeOperation } from '@urql/core';
+The purpose of `addAuthToOperation` is to apply an auth state to each request. Here, we'll use the
+tokens we retrieved from storage and add them to our operations.
 
-const addAuthToOperation = ({ authState, operation }) => {
-  if (!authState || !authState.token) {
-    return operation;
-  }
+In this example, we're using a utility we're passed, `appendHeaders`. This utility is a simply
+shortcut to quickly add HTTP headers via `fetchOptions` to an `Operation`, however, we may as well
+be editing the `Operation` context here using `makeOperation`.
 
-  const fetchOptions =
-    typeof operation.context.fetchOptions === 'function'
-      ? operation.context.fetchOptions()
-      : operation.context.fetchOptions || {};
+```js
+authExchange(async utils => {
+  let token = await AsyncStorage.getItem(TOKEN_KEY);
+  let refreshToken = await AyncStorage.getItem(REFRESH_KEY);
 
-  return makeOperation(operation.kind, operation, {
-    ...operation.context,
-    fetchOptions: {
-      ...fetchOptions,
-      headers: {
-        ...fetchOptions.headers,
-        Authorization: authState.token,
-      },
+  return {
+    addAuthToOperation(operation) {
+      if (!token) return operation;
+      return utils.appendHeaders(operation, {
+        Authorization: `Bearer ${token}`,
+      });
     },
-  });
-};
+    // ...
+  };
+});
 ```
 
-First, we check that we have an `authState` and a `token`. Then we apply it to the request
-`fetchOptions` as an `Authorization` header. The header format can vary based on the API (e.g. using
-`Bearer ${token}` instead of just `token`) which is why it'll be up to us to add the header
-in the expected format for our API.
+First, we check that we have a non-null `token`. Then we apply it to the request using the
+`appendHeaders` utility as an `Authorization` header.
+
+We could also be using `makeOperation` here to update the context in any other way, such as:
+
+```js
+import { makeOperation } from '@urql/core';
+
+makeOperation(operation.kind, operation, {
+  ...operation.context,
+  someAuthThing: token,
+});
+```
 
 ### Configuring `didAuthError`
 
-This function lets the exchange know what is defined to be an API error for your API. `didAuthError` receives an `error` which is of type
-[`CombinedError`](../api/core.md#combinederror), and we can use the `graphQLErrors` array in `CombinedError` to determine if an auth error has occurred.
+This function lets the `authExchange` know what is defined to be an API error for your API.
+`didAuthError` is called by `authExchange` when it receives an `error` on an `OperationResult`, which
+is of type [`CombinedError`](../api/core.md#combinederror).
 
-The GraphQL error looks like something like this:
+We can for example check the error's `graphQLErrors` array in `CombinedError` to determine if an auth
+error has occurred. While your API may implement this differently, an authentication error on an
+execution result may look a little like this if your API uses `extensions.code` on errors:
 
 ```js
 {
···
       extensions: {
         code: 'FORBIDDEN'
       },
-      response: {
-        status: 200
-      }
     }
   ]
 }
 ```
 
-Most GraphQL APIs will communicate auth errors via the [error code
-extension](https://www.apollographql.com/docs/apollo-server/data/errors/#codes), which
-is the recommended approach. We'll be able to determine whether any of the GraphQL errors were due
+If you're building a new API, using `extensions` on errors is the recommended approach to add
+metadata to your errors. We'll be able to determine whether any of the GraphQL errors were due
 to an unauthorized error code, which would indicate an auth failure:
 
 ```js
-const didAuthError = ({ error }) => {
-  return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
-};
-```
-
-For some GraphQL APIs, the auth error is communicated via an 401 HTTP response as is common in RESTful APIs:
-
-```js
-{
-  data: null,
-  errors: [
-    {
-      message: 'Unauthorized: Token has expired',
-      response: {
-        status: 401
-      }
-    }
-  ]
-}
+authExchange(async utils => {
+  // ...
+  return {
+    // ...
+    didAuthError(error, _operation) {
+      return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
+    },
+  };
+});
 ```
 
-In this case we can determine the auth error based on the status code of the request:
+For some GraphQL APIs, the authentication error is only communicated via a 401 HTTP status as is
+common in RESTful APIs, which is suboptimal, but which we can still write a check for.
 
 ```js
-const didAuthError = ({ error }) => {
-  return error.graphQLErrors.some(
-    e => e.response.status === 401,
-  );
-},
+authExchange(async utils => {
+  // ...
+  return {
+    // ...
+    didAuthError(error, _operation) {
+      return error.response.status === 401;
+    },
+  };
+});
 ```
 
-If `didAuthError` returns `true`, it will trigger the exchange to trigger the logic for asking for re-authentication via `getAuth`.
+If `didAuthError` returns `true`, it will trigger the `authExchange` to trigger the logic for asking
+for re-authentication via `refreshAuth`.
 
-### Configuring `getAuth` (triggered after an auth error has occurred)
+### Configuring `refershAuth` (triggered after an auth error has occurred)
 
 If the API doesn't support any sort of token refresh, this is where we could simply log the user out.
 
 ```js
-const getAuth = async ({ authState }) => {
-  if (!authState) {
-    const token = localStorage.getItem('token');
-    const refreshToken = localStorage.getItem('refreshToken');
-    if (token && refreshToken) {
-      return { token, refreshToken };
-    }
-    return null;
-  }
-
-  logout();
-
-  return null;
-};
+authExchange(async utils => {
+  // ...
+  return {
+    // ...
+    async refreshAuth() {
+      logout();
+    },
+  };
+});
 ```
 
 Here, `logout()` is a placeholder that is called when we got an error, so that we can redirect to a
···
 user first:
 
 ```js
-const getAuth = async ({ authState, mutate }) => {
-  if (!authState) {
-    const token = localStorage.getItem('token');
-    const refreshToken = localStorage.getItem('refreshToken');
-    if (token && refreshToken) {
-      return { token, refreshToken };
-    }
-    return null;
-  }
-
-  const result = await mutate(refreshMutation, {
-    token: authState!.refreshToken,
-  });
+authExchange(async utils => {
+  let token = localStorage.getItem('token');
+  let refreshToken = localStorage.getItem('refreshToken');
 
-  if (result.data?.refreshLogin) {
-    localStorage.setItem('token', result.data.refreshLogin.token);
-    localStorage.setItem('refreshToken', result.data.refreshLogin.refreshToken);
+  return {
+    // ...
+    async refreshAuth() {
+      const result = await utils.mutate(REFRESH, { refreshToken });
 
-    return {
-      token: result.data.refreshLogin.token,
-      refreshToken: result.data.refreshLogin.refreshToken,
-    };
-  }
+      if (result.data?.refreshLogin) {
+        // Update our local variables and write to our storage
+        token = result.data.refreshLogin.token;
+        refreshToken = result.data.refreshLogin.refreshToken;
+        localStorage.setItem('token', token);
+        localStorage.setItem('refreshToken', refreshToken);
+      } else {
+        // This is where auth has gone wrong and we need to clean up and redirect to a login page
+        localStorage.clear();
+        logout();
+      }
+    },
+  };
+});
+```
 
-  // This is where auth has gone wrong and we need to clean up and redirect to a login page
-  localStorage.clear();
-  logout();
+Here we use the special `mutate` utility method provided by the `authExchange` to do the token
+refresh. This is a useful method to use if your GraphQL API expects you to make a GraphQL mutation
+to update your authentication state. It will send the mutation and bypass all authentication and
+prior exchanges.
 
-  return null;
-}
-```
+If your authentication is not handled via GraphQL but a REST endpoint, you can use the `fetch` API
+here however instead of a mutation.
 
-Here we use the special mutate function provided by the auth exchange to do the token refresh. If your auth is not handled via GraphQL but a REST endpoint, you can
-use `fetch` in this function instead of a mutation. All other requests will be paused while `getAuth` returns, so we never have to handle multiple auth failures
-at the same time.
+All other requests will be paused while `refreshAuth` runs, so we won't have to deal with multiple
+authentication errors or refreshes at once.
 
 ### Configuring `willAuthError`
 
-`willAuthError` is an optional parameter and is run _before_ a network request is made. We can use it to trigger the logic in
-`getAuth` without the need to send a request and get a GraphQL Error back. For example, we can use this to predict that the authentication will fail because our JWT is invalid already:
+`willAuthError` is an optional parameter and is run _before_ a request is made.
+
+We can use it to trigger an authentication error and let the `authExchange` run our `refreshAuth`
+function without the need to first let a request fail with an authentication error. For example, we
+can use this to predict an authentication error, for instance, because of expired JWT tokens.
 
 ```js
-const willAuthError = ({ authState }) => {
-  if (!authState || /* JWT is expired */) return true;
-  return false;
-}
+authExchange(async utils => {
+  // ...
+  return {
+    // ...
+    willAuthError(_operation) {
+      // Check whether `token` JWT is expired
+      return false;
+    },
+  };
+});
 ```
 
 This can be really useful when we know when our authentication state is invalid and want to prevent
-even sending any operation that we know will fail with an authentication error. However, if we were
-to use this and are logging in our users with a login _mutation_ then the above code will
-unfortunately never let this login mutation through to our GraphQL API.
+even sending any operation that we know will fail with an authentication error.
 
-If we have such a mutation we may need to write a more sophisticated `willAuthError` function like
-the following:
+However, we have to be careful on how we define this function, if some queries or login mutations
+are sent to our API without being logged in. In these cases, it's better to either detect the
+mutations we'd like to allow or return `false` when a token isn't set in storage yet.
 
-```js
-const willAuthError = ({ operation, authState }) => {
-  if (!authState) {
-    // Detect our login mutation and let this operation through:
-    return !(
-      operation.kind === 'mutation' &&
-      // Here we find any mutation definition with the "login" field
-      operation.query.definitions.some(definition => {
-        return (
-          definition.kind === 'OperationDefinition' &&
-          definition.selectionSet.selections.some(node => {
-            // The field name is just an example, since signup may also be an exception
-            return node.kind === 'Field' && node.name.value === 'login';
-          })
-        );
-      })
-    );
-  } else if (false /* JWT is expired */) {
-    return true;
-  }
+If we'd like to detect a mutation that will never fail with an authentication error, we could for
+instance write the following logic:
 
-  return false;
-};
+```js
+authExchange(async utils => {
+  // ...
+  return {
+    // ...
+    willAuthError(operation) {
+      if (
+        operation.kind === 'mutation' &&
+        // Here we find any mutation definition with the "login" field
+        operation.query.definitions.some(definition => {
+          return (
+            definition.kind === 'OperationDefinition' &&
+            definition.selectionSet.selections.some(node => {
+              // The field name is just an example, since signup may also be an exception
+              return node.kind === 'Field' && node.name.value === 'login';
+            })
+          );
+        })
+      ) {
+        return false;
+      } else if (false /* is JWT expired? */) {
+        return true;
+      } else {
+        return false;
+      }
+    },
+  };
+});
 ```
 
-Alternatively, you may decide to let all operations through if `authState` isn't defined or to allow
-all mutations through. In an application that allows unauthenticated users to perform various
-actions, it's a good idea for us to return `false` when `!authState` applies.
-
-[Read more about `@urql/exchange-auth`'s API in our API docs.](../api/auth-exchange.md)
+Alternatively, you may decide to let all operations through if your token isn't set in storage, i.e.
+if you have no prior authentication state.
 
 ## Handling Logout by reacting to Errors
 
···
         }
       },
     }),
-    authExchange({
-      /* config */
+    authExchange(async utils => {
+      return {
+        /* config */
+      };
     }),
     fetchExchange,
   ],
···
 
 ## Cache Invalidation on Logout
 
-If we're dealing with multiple authentication states at the same time, e.g. logouts, we need to ensure that the `Client` is reinitialized whenever the authentication state changes. Here's an example of how we may do this in React if necessary:
+If we're dealing with multiple authentication states at the same time, e.g. logouts, we need to
+ensure that the `Client` is reinitialized whenever the authentication state changes.
+Here's an example of how we may do this in React if necessary:
 
 ```jsx
 import { createClient, Provider } from 'urql';
···
 }
 ```
 
-When the application launches, the first thing we do is check whether the user has any auth tokens in persisted storage. This will tell us
-whether to show the user the logged in or logged out view.
+When the application launches, the first thing we do is check whether the user has any authentication
+tokens in persisted storage. This will tell us whether to show the user the logged in or logged out view.
 
 The `isLoggedIn` prop should always be updated based on authentication state change. For instance, we may set it to
 `true` after the user has authenticated and their tokens have been added to storage, and set it to
 `false` once the user has been logged out and their tokens have been cleared. It's important to clear
 or add tokens to a storage _before_ updating the prop in order for the auth exchange to work
 correctly.
+
+This pattern of creating a new `Client` when changing authentication states is especially useful
+since it will also recreate our client-side cache and invalidate all cached data.

docs/api/auth-exchange.md

···
   exchanges: [
     dedupExchange,
     cacheExchange,
-    authExchange({
-      /* config */
+    authExchange(async utils => {
+      return {
+        /* config... */
+      };
     }),
     fetchExchange,
   ],
 });
 ```
 
-The `authExchange` accepts an object of options, which are used to configure how your
-authentication method works. Internally, the `authExchange` keeps an authentication state, whose
-shape is determined by the functions passed to the exchange's options:
+The `authExchange` accepts an initialization function. This function is called when your exchange
+and `Client` first start up, and must return an object of options wrapped in a `Promise`, which is
+used to configure how your authentication method works.
+
+You can use this function to first retrieve your authentication state from a kind
+of local storage, or to call your API to validate your authentication state first.
+
+The relevant configuration options, returned to the `authExchange`, then determine
+how the `authExchange` behaves:
 
 - `addAuthToOperation` must be provided to tell `authExchange` how to add authentication information
   to an operation, e.g. how to add the authentication state to an operation's fetch headers.
-- `getAuth` must be provided to let the `authExchange` handle the authentication flow, including
-  token refreshes and other reauthentication. It may send mutations to the GraphQL API or make
-  out-of-band API requests using `fetch`.
-- `didAuthError` may be provided to let the `authExchange` detect authentication errors from the API
-  to trigger the `getAuth` method and reauthentication flow.
 - `willAuthError` may be provided to detect expired tokens or tell whether an operation will likely
-  fail due to an authentication error, which may trigger the `getAuth` method and reauthentication
-  flow early.
-
-## Options
-
-| Option               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `addAuthToOperation` | Receives a parameter object with the current `authState` (`null \| T`) and an error ([See `CombinedError`](./core.md#combinederror)). It should return the same operation to which the authentication state has been added, e.g. as an authentication header.                                                                                                                                                                                                                          |
-| `getAuth`            | This provided method receives the `authState` (`null \| T`). It should then refresh the authentication state using either a `fetch`call or [the`mutate`method, which is similar to`client.mutation`](./core.md#clientmutation) and return a new `authState`object. In case it receives`null` it should return a stored authentication state, e.g. from local storage. It's allowed to throw an error, which will interrupt the auth flow and let the authentication error fallthrough. |
-| `didAuthError`       | May be provided and return a `boolean` that indicates whether an error is an authentication error, given `error: CombinedError` and `authState: T \| null` as parameters.                                                                                                                                                                                                                                                                                                              |
-| `willAuthError`      | May be provided and return a `boolean` that indicates whether an operation is likely to fail, e.g. due to an expired token, to trigger the authentication flow early, and is given `operation: Operation` and `authState: T \| null` as parameters.                                                                                                                                                                                                                                    |
-
-## Examples
-
-The `addAuthToOperation` method is frequently populated with a function that adds the `authState` to
-the operation's fetch headers.
-
-```js
-function addAuthToOperation: ({
-  authState,
-  operation,
-}) {
-  // the token isn't in the auth state, return the operation without changes
-  if (!authState || !authState.token) {
-    return operation;
-  }
+  fail due to an authentication error.
+- `didAuthError` may be provided to let the `authExchange` detect authentication errors from the
+  API on results.
+- `refreshAuth` is called when an authentication error occurs and gives you an opportunity to update
+  your authentication state. Afterwards, the `authExchange` will retry your operation.
 
-  // fetchOptions can be a function (See Client API) but you can simplify this based on usage
-  const fetchOptions =
-    typeof operation.context.fetchOptions === 'function'
-      ? operation.context.fetchOptions()
-      : operation.context.fetchOptions || {};
-
-  return {
-    ...operation,
-    context: {
-      ...operation.context,
-      fetchOptions: {
-        ...fetchOptions,
-        headers: {
-          ...fetchOptions.headers,
-          "Authorization": authState.token,
-        },
-      },
-    },
-  };
-}
-```
-
-[Read more examples in the documentation given here.](https://github.com/urql-graphql/urql/tree/main/exchanges/auth#quick-start-guide)
+[Read more examples in the documentation given here.](../advanced/authentication.md)

exchanges/auth/README.md

···
   exchanges: [
     dedupExchange,
     cacheExchange,
-    authExchange({
-      addAuthToOperation: ({ authState, operation }) => {
-        // the token isn't in the auth state, return the operation without changes
-        if (!authState || !authState.token) {
+    authExchange(async utils => {
+      // called on initial launch,
+      // fetch the auth state from storage (local storage, async storage etc)
+      let token = localStorage.getItem('token');
+      let refreshToken = localStorage.getItem('refreshToken');
+
+      return {
+        addAuthToOperation(operation) {
+          if (token) {
+            return utils.appendHeaders(operation, {
+              Authorization: `Bearer ${token}`,
+            });
+          }
           return operation;
-        }
+        },
+        willAuthError(_operation) {
+          // e.g. check for expiration, existence of auth etc
+          return !token;
+        },
+        didAuthError(error, _operation) {
+          // check if the error was an auth error
+          // this can be implemented in various ways, e.g. 401 or a special error code
+          return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
+        },
+        async refreshAuth() {
+          // called when auth error has occurred
+          // we should refresh the token with a GraphQL mutation or a fetch call,
+          // depending on what the API supports
+          const result = await mutate(refreshMutation, {
+            token: authState?.refreshToken,
+          });
 
-        // fetchOptions can be a function (See Client API) but you can simplify this based on usage
-        const fetchOptions =
-          typeof operation.context.fetchOptions === 'function'
-            ? operation.context.fetchOptions()
-            : operation.context.fetchOptions || {};
-
-        return makeOperation(operation.kind, operation, {
-          ...operation.context,
-          fetchOptions: {
-            ...fetchOptions,
-            headers: {
-              ...fetchOptions.headers,
-              Authorization: authState.token,
-            },
-          },
-        });
-      },
-      willAuthError: ({ authState }) => {
-        if (!authState) return true;
-        // e.g. check for expiration, existence of auth etc
-        return false;
-      },
-      didAuthError: ({ error }) => {
-        // check if the error was an auth error (this can be implemented in various ways, e.g. 401 or a special error code)
-        return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
-      },
-      getAuth: async ({ authState, mutate }) => {
-        // for initial launch, fetch the auth state from storage (local storage, async storage etc)
-        if (!authState) {
-          const token = localStorage.getItem('token');
-          const refreshToken = localStorage.getItem('refreshToken');
-          if (token && refreshToken) {
-            return { token, refreshToken };
+          if (result.data?.refreshLogin) {
+            // save the new tokens in storage for next restart
+            token = result.data.refreshLogin.token;
+            refreshToken = result.data.refreshLogin.refreshToken;
+            localStorage.setItem('token', token);
+            localStorage.setItem('refreshToken', refreshToken);
+          } else {
+            // otherwise, if refresh fails, log clear storage and log out
+            localStorage.clear();
+            logout();
           }
-          return null;
-        }
-
-        /**
-         * the following code gets executed when an auth error has occurred
-         * we should refresh the token if possible and return a new auth state
-         * If refresh fails, we should log out
-         **/
-
-        // if your refresh logic is in graphQL, you must use this mutate function to call it
-        // if your refresh logic is a separate RESTful endpoint, use fetch or similar
-        const result = await mutate(refreshMutation, {
-          token: authState?.refreshToken,
-        });
-
-        if (result.data?.refreshLogin) {
-          // save the new tokens in storage for next restart
-          localStorage.setItem('token', result.data.refreshLogin.token);
-          localStorage.setItem('refreshToken', result.data.refreshLogin.refreshToken);
-
-          // return the new tokens
-          return {
-            token: result.data.refreshLogin.token,
-            refreshToken: result.data.refreshLogin.refreshToken,
-          };
-        }
-
-        // otherwise, if refresh fails, log clear storage and log out
-        localStorage.clear();
-
-        // your app logout logic should trigger here
-        logout();
-
-        return null;
-      },
+        },
+      };
     }),
     fetchExchange,
   ],
···
 
 ## Handling Errors via the errorExchange
 
-Handling the logout logic in `getAuth` is the easiest way to get started, but it means the errors will always get swallowed by the `authExchange`.
-If you want to handle errors globally, this can be done using the `errorExchange`:
+Handling the logout logic in `refreshAuth` is the easiest way to get started,
+but it means the errors will always get swallowed by the `authExchange`.
+If you want to handle errors globally, this can be done using the `mapExchange`:
 
 ```js
-import { errorExchange } from 'urql';
+import { mapExchange } from 'urql';
 
-// this needs to be placed ABOVE the authExchange in the exchanges array, otherwise the auth error will show up hear before the auth exchange has had the chance to handle it
-errorExchange({
-  onError: (error) => {
-    // we only get an auth error here when the auth exchange had attempted to refresh auth and getting an auth error again for the second time
+// this needs to be placed ABOVE the authExchange in the exchanges array, otherwise the auth error
+// will show up hear before the auth exchange has had the chance to handle it
+mapExchange({
+  onError(error) {
+    // we only get an auth error here when the auth exchange had attempted to refresh auth and
+    // getting an auth error again for the second time
     const isAuthError = error.graphQLErrors.some(
       e => e.extensions?.code === 'FORBIDDEN',
     );
-
     if (isAuthError) {
       // clear storage, log the user out etc
     }

exchanges/auth/src/authExchange.test.ts

···
   take,
   makeSubject,
   publish,
+  scan,
   tap,
   map,
 } from 'wonka';
-import { vi, expect, it } from 'vitest';
 
-import { print } from 'graphql';
-import { authExchange } from './authExchange';
 import {
   makeOperation,
   CombinedError,
···
   Operation,
   OperationResult,
 } from '@urql/core';
+
+import { vi, expect, it } from 'vitest';
+import { print } from 'graphql';
 import { queryOperation } from '../../../packages/core/src/test-utils';
+import { authExchange } from './authExchange';
 
 const makeExchangeArgs = () => {
   const operations: Operation[] = [];
···
   };
 };
 
-const withAuthHeader = (operation, token) => {
-  const fetchOptions =
-    typeof operation.context.fetchOptions === 'function'
-      ? operation.context.fetchOptions()
-      : operation.context.fetchOptions || {};
-
-  return makeOperation(operation.kind, operation, {
-    ...operation.context,
-    fetchOptions: {
-      ...fetchOptions,
-      headers: {
-        ...fetchOptions.headers,
-        Authorization: token,
-      },
-    },
-  });
-};
-
 it('adds the auth header correctly', async () => {
   const { exchangeArgs } = makeExchangeArgs();
 
   const res = await pipe(
     fromValue(queryOperation),
-    authExchange({
-      getAuth: async () => ({ token: 'my-token' }),
-      willAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState!.token);
-      },
+    authExchange(async utils => {
+      const token = 'my-token';
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        didAuthError: () => false,
+        async refreshAuth() {
+          /*noop*/
+        },
+      };
     })(exchangeArgs),
     take(1),
     toPromise
···
   });
 });
 
-it('adds the auth header correctly when it is fetched asynchronously', async () => {
+it('adds the auth header correctly when intialized asynchronously', async () => {
   const { exchangeArgs } = makeExchangeArgs();
 
   const res = await pipe(
     fromValue(queryOperation),
-    authExchange<{ token: string }>({
-      getAuth: async () => {
-        await Promise.resolve();
-        return { token: 'async-token' };
-      },
-      willAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState!.token);
-      },
+    authExchange(async utils => {
+      // delayed initial auth
+      await Promise.resolve();
+      const token = 'async-token';
+
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        didAuthError: () => false,
+        async refreshAuth() {
+          /*noop*/
+        },
+      };
     })(exchangeArgs),
     take(1),
     toPromise
···
   });
 });
 
-it('supports calls to the mutate() method in getAuth()', async () => {
+it('supports calls to the mutate() method in refreshAuth()', async () => {
   const { exchangeArgs } = makeExchangeArgs();
 
-  const res = await pipe(
+  const willAuthError = vi
+    .fn()
+    .mockReturnValueOnce(true)
+    .mockReturnValue(false);
+
+  const [mutateRes, res] = await pipe(
     fromValue(queryOperation),
-    authExchange<{ token: string }>({
-      getAuth: async ({ mutate }) => {
-        const result = await mutate('mutation { auth }');
-        expect(print(result.operation.query)).toBe('mutation {\n  auth\n}');
-        return { token: 'async-token' };
-      },
-      willAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState?.token);
-      },
+    authExchange(async utils => {
+      const token = 'async-token';
+
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        willAuthError,
+        didAuthError: () => false,
+        async refreshAuth() {
+          const result = await utils.mutate('mutation { auth }', undefined);
+          expect(print(result.operation.query)).toBe('mutation {\n  auth\n}');
+        },
+      };
     })(exchangeArgs),
     take(2),
+    scan((acc, res) => [...acc, res], [] as OperationResult[]),
     toPromise
   );
 
+  expect(mutateRes.operation.context.fetchOptions).toEqual({
+    headers: {
+      Authorization: 'async-token',
+    },
+  });
+
   expect(res.operation.context.authAttempt).toBe(false);
   expect(res.operation.context.fetchOptions).toEqual({
-    ...(queryOperation.context.fetchOptions || {}),
+    method: 'POST',
     headers: {
       Authorization: 'async-token',
     },
···
   const result = vi.fn();
   const auth$ = pipe(
     source,
-    authExchange({
-      getAuth: async () => {
-        await Promise.resolve();
-        return { token: 'my-token' };
-      },
-      willAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState!.token);
-      },
+    authExchange(async utils => {
+      const token = 'my-token';
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        didAuthError: () => false,
+        async refreshAuth() {
+          /*noop*/
+        },
+      };
     })(exchangeArgs),
     tap(result),
     take(2),
···
   const { exchangeArgs, result, operations } = makeExchangeArgs();
   const { source, next } = makeSubject<any>();
 
-  let initialAuth;
-  let afterErrorAuth;
-
   const didAuthError = vi.fn().mockReturnValueOnce(true);
 
-  const getAuth = vi
-    .fn()
-    .mockImplementationOnce(() => {
-      initialAuth = Promise.resolve({ token: 'initial-token' });
-      return initialAuth;
-    })
-    .mockImplementationOnce(() => {
-      afterErrorAuth = Promise.resolve({ token: 'final-token' });
-      return afterErrorAuth;
-    });
-
   pipe(
     source,
-    authExchange<{ token: string }>({
-      getAuth,
-      didAuthError,
-      willAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState?.token);
-      },
+    authExchange(async utils => {
+      let token = 'initial-token';
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        didAuthError,
+        async refreshAuth() {
+          token = 'final-token';
+        },
+      };
     })(exchangeArgs),
     publish
   );
 
-  await Promise.resolve();
-  expect(getAuth).toHaveBeenCalledTimes(1);
-  await initialAuth;
-  await new Promise(res => {
-    setTimeout(() => {
-      res(null);
-    });
-  });
+  await new Promise(resolve => setTimeout(resolve));
 
   result.mockReturnValueOnce({
     operation: queryOperation,
···
   next(queryOperation);
   expect(result).toHaveBeenCalledTimes(1);
   expect(didAuthError).toHaveBeenCalledTimes(1);
-  expect(getAuth).toHaveBeenCalledTimes(2);
 
-  await afterErrorAuth;
-  await new Promise(res => {
-    setTimeout(() => {
-      res(null);
-    });
-  });
+  await new Promise(resolve => setTimeout(resolve));
 
   expect(result).toHaveBeenCalledTimes(2);
   expect(operations.length).toBe(2);
···
   const { exchangeArgs, result, operations } = makeExchangeArgs();
   const { source, next } = makeSubject<any>();
 
-  let initialAuth;
-  let afterErrorAuth;
-
-  vi.useRealTimers();
   const willAuthError = vi
     .fn()
     .mockReturnValueOnce(true)
     .mockReturnValue(false);
 
-  const getAuth = vi
-    .fn()
-    .mockImplementationOnce(async () => {
-      initialAuth = Promise.resolve({ token: 'initial-token' });
-      return await initialAuth;
-    })
-    .mockImplementationOnce(() => {
-      afterErrorAuth = Promise.resolve({ token: 'final-token' });
-      return afterErrorAuth;
-    });
-
   pipe(
     source,
-    authExchange<{ token: string }>({
-      getAuth,
-      willAuthError,
-      didAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState?.token);
-      },
+    authExchange(async utils => {
+      let token = 'initial-token';
+      return {
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        willAuthError,
+        didAuthError: () => false,
+        async refreshAuth() {
+          token = 'final-token';
+        },
+      };
     })(exchangeArgs),
     publish
   );
 
-  await Promise.resolve();
-  expect(getAuth).toHaveBeenCalledTimes(1);
-  await initialAuth;
-  await new Promise(res => {
-    setTimeout(() => {
-      res(null);
-    });
-  });
+  await new Promise(resolve => setTimeout(resolve));
 
   next(queryOperation);
   expect(result).toHaveBeenCalledTimes(0);
   expect(willAuthError).toHaveBeenCalledTimes(1);
-  expect(getAuth).toHaveBeenCalledTimes(2);
 
-  await afterErrorAuth;
-
-  await new Promise(res => {
-    setTimeout(() => {
-      res(null);
-    });
-  });
+  await new Promise(resolve => setTimeout(resolve));
 
   expect(result).toHaveBeenCalledTimes(1);
   expect(operations.length).toBe(1);
···
 
   let initialAuthResolve: ((_?: any) => void) | undefined;
 
-  const willAuthError = vi.fn().mockReturnValue(false);
+  const willAuthError = vi
+    .fn()
+    .mockReturnValueOnce(true)
+    .mockReturnValue(false);
 
   pipe(
     source,
-    authExchange<{ token: string }>({
-      async getAuth() {
-        await new Promise(resolve => {
-          initialAuthResolve = resolve;
-        });
+    authExchange(async utils => {
+      await new Promise(resolve => {
+        initialAuthResolve = resolve;
+      });
 
-        return { token: 'token' };
-      },
-      willAuthError,
-      didAuthError: () => false,
-      addAuthToOperation: ({ authState, operation }) => {
-        return withAuthHeader(operation, authState?.token);
-      },
+      let token = 'token';
+      return {
+        willAuthError,
+        didAuthError: () => false,
+        addAuthToOperation(operation) {
+          return utils.appendHeaders(operation, {
+            Authorization: token,
+          });
+        },
+        async refreshAuth() {
+          token = 'final-token';
+        },
+      };
     })(exchangeArgs),
     publish
   );
 
   await Promise.resolve();
 
-  next(queryOperation);
+  next({ ...queryOperation, key: 1 });
+  next({ ...queryOperation, key: 2 });
+
   expect(result).toHaveBeenCalledTimes(0);
   expect(willAuthError).toHaveBeenCalledTimes(0);
 
···
 
   await new Promise(resolve => setTimeout(resolve));
 
-  expect(willAuthError).toHaveBeenCalledTimes(1);
-  expect(result).toHaveBeenCalledTimes(1);
+  expect(willAuthError).toHaveBeenCalledTimes(2);
+  expect(result).toHaveBeenCalledTimes(2);
 
-  expect(operations.length).toBe(1);
+  expect(operations.length).toBe(2);
   expect(operations[0]).toHaveProperty(
     'context.fetchOptions.headers.Authorization',
-    'token'
+    'final-token'
+  );
+
+  expect(operations[1]).toHaveProperty(
+    'context.fetchOptions.headers.Authorization',
+    'final-token'
   );
 });

exchanges/auth/src/authExchange.ts

···
 } from 'wonka';
 
 import {
+  createRequest,
+  makeOperation,
   Operation,
   OperationContext,
   OperationResult,
   CombinedError,
   Exchange,
-  createRequest,
-  makeOperation,
   TypedDocumentNode,
+  AnyVariables,
 } from '@urql/core';
 
 import { DocumentNode } from 'graphql';
 
-export interface AuthConfig<T> {
-  /** addAuthToOperation() must be provided to add the custom `authState` to an Operation's context, so that it may be picked up by the `fetchExchange`. */
-  addAuthToOperation(params: {
-    authState: T | null;
-    operation: Operation;
-  }): Operation;
+/** Utilities to use while refreshing authentication tokens. */
+export interface AuthUtilities {
+  /** Sends a mutation to your GraphQL API, bypassing earlier exchanges and authentication.
+   *
+   * @param query - a GraphQL document containing the mutation operation that will be executed.
+   * @param variables - the variables used to execute the operation.
+   * @param context - {@link OperationContext} options that'll be used in future exchanges.
+   * @returns A `Promise` of an {@link OperationResult} for the GraphQL mutation.
+   *
+   * @remarks
+   * The `mutation()` utility method is useful when your authentication requires you to make a GraphQL mutation
+   * request to update your authentication tokens. In these cases, you likely wish to bypass prior exchanges and
+   * the authentication in the `authExchange` itself.
+   *
+   * This method bypasses the usual mutation flow of the `Client` and instead issues the mutation as directly
+   * as possible. This also means that it doesn’t carry your `Client`'s default {@link OperationContext}
+   * options, so you may have to pass them again, if needed.
+   */
+  mutate<Data = any, Variables extends AnyVariables = AnyVariables>(
+    query: DocumentNode | TypedDocumentNode<Data, Variables> | string,
+    variables: Variables,
+    context?: Partial<OperationContext>
+  ): Promise<OperationResult<Data>>;
 
-  /** didAuthError() may be provided to tweak the detection of an authentication error that this exchange should handle. */
-  didAuthError?(params: { error: CombinedError; authState: T | null }): boolean;
+  /** Adds additional HTTP headers to an `Operation`.
+   *
+   * @param operation - An {@link Operation} to add headers to.
+   * @param headers - The HTTP headers to add to the `Operation`.
+   * @returns The passed {@link Operation} with the headers added to it.
+   *
+   * @remarks
+   * The `appendHeaders()` utility method is useful to add additional HTTP headers
+   * to an {@link Operation}. It’s a simple convenience function that takes
+   * `operation.context.fetchOptions` into account, since adding headers for
+   * authentication is common.
+   */
+  appendHeaders(
+    operation: Operation,
+    headers: Record<string, string>
+  ): Operation;
+}
 
-  /** willAuthError() may be provided to detect a potential operation that'll receive authentication error so that getAuth() can be run proactively. */
-  willAuthError?(params: {
-    authState: T | null;
-    operation: Operation;
-  }): boolean;
+/** Configuration for the `authExchange` returned by the initializer function you write. */
+export interface AuthConfig {
+  /** Called for every operation to add authentication data to your operation.
+   *
+   * @param operation - An {@link Operation} that needs authentication tokens added.
+   * @returns a new {@link Operation} with added authentication tokens.
+   *
+   * @remarks
+   * The {@link authExchange} will call this function you provide and expects that you
+   * add your authentication tokens to your operation here, on the {@link Operation}
+   * that is returned.
+   *
+   * Hint: You likely want to modify your `fetchOptions.headers` here, for instance to
+   * add an `Authorization` header.
+   */
+  addAuthToOperation(operation: Operation): Operation;
 
-  /** getAuth() handles how the application refreshes or reauthenticates given a stale `authState` and should return a new `authState` or `null`. */
-  getAuth(params: {
-    authState: T | null;
-    /** The mutate() method may be used to send one-off mutations to the GraphQL API for the purpose of authentication. */
-    mutate<Data = any, Variables extends object = {}>(
-      query: DocumentNode | TypedDocumentNode<Data, Variables> | string,
-      variables?: Variables,
-      context?: Partial<OperationContext>
-    ): Promise<OperationResult<Data>>;
-  }): Promise<T | null>;
+  /** Called before an operation is forwaded onwards to make a request.
+   *
+   * @param operation - An {@link Operation} that needs authentication tokens added.
+   * @returns a boolean, if true, authentication must be refreshed.
+   *
+   * @remarks
+   * The {@link authExchange} will call this function before an {@link Operation} is
+   * forwarded onwards to your following exchanges.
+   *
+   * When this function returns `true`, the `authExchange` will call
+   * {@link AuthConfig.refreshAuth} before forwarding more operations
+   * to prompt you to update your authentication tokens.
+   *
+   * Hint: If you define this function, you can use it to check whether your authentication
+   * tokens have expired.
+   */
+  willAuthError?(operation: Operation): boolean;
+
+  /** Called after receiving an operation result to check whether it has failed with an authentication error.
+   *
+   * @param error - A {@link CombinedError} that a result has come back with.
+   * @param operation - The {@link Operation} of that has failed.
+   * @returns a boolean, if true, authentication must be refreshed.
+   *
+   * @remarks
+   * The {@link authExchange} will call this function if it sees an {@link OperationResult}
+   * with a {@link CombinedError} on it, implying that it may have failed due to an authentication
+   * error.
+   *
+   * When this function returns `true`, the `authExchange` will call
+   * {@link AuthConfig.refreshAuth} before forwarding more operations
+   * to prompt you to update your authentication tokens.
+   * Afterwards, this operation will be retried once.
+   *
+   * Hint: You should define a function that detects your API’s authentication
+   * errors, e.g. using `result.extensions`.
+   */
+  didAuthError(error: CombinedError, operation: Operation): boolean;
+
+  /** Called to refresh the authentication state.
+   *
+   * @remarks
+   * The {@link authExchange} will call this function if either {@link AuthConfig.willAuthError}
+   * or {@link AuthConfig.didAuthError} have returned `true` prior, which indicates that the
+   * authentication state you hold has expired or is out-of-date.
+   *
+   * When this function is called, you should refresh your authentication state.
+   * For instance, if you have a refresh token and an access token, you should rotate
+   * these tokens with your API by sending the refresh token.
+   *
+   * Hint: You can use the {@link fetch} API here, or use {@link AuthUtilities.mutate}
+   * if your API requires a GraphQL mutation to refresh your authentication state.
+   */
+  refreshAuth(): Promise<void>;
 }
 
 const addAuthAttemptToOperation = (
   operation: Operation,
-  hasAttempted: boolean
+  authAttempt: boolean
 ) =>
   makeOperation(operation.kind, operation, {
     ...operation.context,
-    authAttempt: hasAttempted,
+    authAttempt,
   });
 
-export function authExchange<T>({
-  addAuthToOperation,
-  getAuth,
-  didAuthError,
-  willAuthError,
-}: AuthConfig<T>): Exchange {
+/** Creates an `Exchange` handling control flow for authentication.
+ *
+ * @param init - An initializer function that returns an {@link AuthConfig} wrapped in a `Promise`.
+ * @returns the created authentication {@link Exchange}.
+ *
+ * @remarks
+ * The `authExchange` is used to create an exchange handling authentication and
+ * the control flow of refresh authentication.
+ *
+ * You must pass an initializer function, which receives {@link AuthUtilities} and
+ * must return an {@link AuthConfig} wrapped in a `Promise`.
+ * When this exchange is used in your `Client`, it will first call your initializer
+ * function, which gives you an opportunity to get your authentication state, e.g.
+ * from local storage.
+ *
+ * You may then choose to validate this authentication state and update it, and must
+ * then return an {@link AuthConfig}.
+ *
+ * This configuration defines how you add authentication state to {@link Operation | Operations},
+ * when your authentication state expires, when an {@link OperationResult} has errored
+ * with an authentication error, and how to refresh your authentication state.
+ *
+ * @example
+ * ```ts
+ * authExchange(async (utils) => {
+ *   let token = localStorage.getItem('token');
+ *   let refreshToken = localStorage.getItem('refreshToken');
+ *   return {
+ *     addAuthToOperation(operation) {
+ *       return utils.appendHeaders(operation, {
+ *         Authorization: `Bearer ${token}`,
+ *       });
+ *     },
+ *     didAuthError(error) {
+ *       return error.graphQLErrors.some(e => e.extensions?.code === 'FORBIDDEN');
+ *     },
+ *     async refreshAuth() {
+ *       const result = await utils.mutate(REFRESH, { token });
+ *       if (result.data?.refreshLogin) {
+ *         token = result.data.refreshLogin.token;
+ *         refreshToken = result.data.refreshLogin.refreshToken;
+ *         localStorage.setItem('token', token);
+ *         localStorage.setItem('refreshToken', refreshToken);
+ *       }
+ *     },
+ *   };
+ * });
+ * ```
+ */
+export function authExchange(
+  init: (utilities: AuthUtilities) => Promise<AuthConfig>
+): Exchange {
   return ({ client, forward }) => {
-    const bypassQueue: WeakSet<Operation> = new WeakSet();
-    const retryQueue: Map<number, Operation> = new Map();
+    const bypassQueue = new WeakSet<Operation>();
+    const retries = makeSubject<Operation>();
 
-    const {
-      source: retrySource$,
-      next: retryOperation,
-    } = makeSubject<Operation>();
+    let retryQueue = new Map<number, Operation>();
 
-    let authState: T | null = null;
+    function flushQueue(_config?: AuthConfig | undefined) {
+      if (_config) config = _config;
+      authPromise = undefined;
+      const queue = retryQueue;
+      retryQueue = new Map();
+      queue.forEach(retries.next);
+    }
+
+    let authPromise: Promise<void> | void;
+    let config: AuthConfig | null = null;
 
     return operations$ => {
-      function mutate<Data = any, Variables extends object = {}>(
-        query: DocumentNode | string,
-        variables?: Variables,
-        context?: Partial<OperationContext>
-      ): Promise<OperationResult<Data>> {
-        const operation = client.createRequestOperation(
-          'mutation',
-          createRequest(query, variables),
-          context
-        );
+      authPromise = Promise.resolve()
+        .then(() =>
+          init({
+            mutate<Data = any, Variables extends AnyVariables = AnyVariables>(
+              query: DocumentNode | string,
+              variables: Variables,
+              context?: Partial<OperationContext>
+            ): Promise<OperationResult<Data>> {
+              const baseOperation = client.createRequestOperation(
+                'mutation',
+                createRequest(query, variables),
+                context
+              );
+              return pipe(
+                result$,
+                onStart(() => {
+                  const operation = addAuthToOperation(baseOperation);
+                  bypassQueue.add(operation);
+                  retries.next(operation);
+                }),
+                filter(result => result.operation.key === baseOperation.key),
+                take(1),
+                toPromise
+              );
+            },
+            appendHeaders(
+              operation: Operation,
+              headers: Record<string, string>
+            ) {
+              const fetchOptions =
+                typeof operation.context.fetchOptions === 'function'
+                  ? operation.context.fetchOptions()
+                  : operation.context.fetchOptions || {};
+              return makeOperation(operation.kind, operation, {
+                ...operation.context,
+                fetchOptions: {
+                  ...fetchOptions,
+                  headers: {
+                    ...fetchOptions.headers,
+                    ...headers,
+                  },
+                },
+              });
+            },
+          })
+        )
+        .then(flushQueue);
 
-        return pipe(
-          result$,
-          onStart(() => {
-            bypassQueue.add(operation);
-            retryOperation(operation);
-          }),
-          filter(result => result.operation.key === operation.key),
-          take(1),
-          toPromise
+      function refreshAuth(operation: Operation) {
+        // add to retry queue to try again later
+        retryQueue.set(
+          operation.key,
+          addAuthAttemptToOperation(operation, true)
         );
+        // check that another operation isn't already doing refresh
+        if (config && !authPromise) {
+          authPromise = config.refreshAuth().finally(flushQueue);
+        }
       }
 
-      const updateAuthState = (newAuthState: T | null) => {
-        authState = newAuthState;
-        authPromise = undefined;
-        retryQueue.forEach(retryOperation);
-        retryQueue.clear();
-      };
+      function willAuthError(operation: Operation) {
+        return (
+          !operation.context.authAttempt &&
+          config &&
+          config.willAuthError &&
+          config.willAuthError(operation)
+        );
+      }
 
-      let authPromise: Promise<any> | void = Promise.resolve()
-        .then(() => getAuth({ authState, mutate }))
-        .then(updateAuthState);
+      function didAuthError(result: OperationResult) {
+        return (
+          config &&
+          config.didAuthError &&
+          config.didAuthError(result.error!, result.operation)
+        );
+      }
 
-      const refreshAuth = (operation: Operation): void => {
-        // add to retry queue to try again later
-        operation = addAuthAttemptToOperation(operation, true);
-        retryQueue.set(operation.key, operation);
-
-        // check that another operation isn't already doing refresh
-        if (!authPromise) {
-          authPromise = getAuth({ authState, mutate })
-            .then(updateAuthState)
-            .catch(() => updateAuthState(null));
-        }
-      };
+      function addAuthToOperation(operation: Operation) {
+        return config ? config.addAuthToOperation(operation) : operation;
+      }
 
       const sharedOps$ = pipe(operations$, share);
 
       const teardownOps$ = pipe(
         sharedOps$,
-        filter((operation: Operation) => {
-          return operation.kind === 'teardown';
-        })
+        filter(operation => operation.kind === 'teardown')
       );
 
       const pendingOps$ = pipe(
         sharedOps$,
-        filter((operation: Operation) => {
-          return operation.kind !== 'teardown';
-        })
+        filter(operation => operation.kind !== 'teardown')
       );
 
       const opsWithAuth$ = pipe(
-        merge([retrySource$, pendingOps$]),
+        merge([retries.source, pendingOps$]),
         map(operation => {
           if (bypassQueue.has(operation)) {
             return operation;
           } else if (authPromise) {
-            operation = addAuthAttemptToOperation(operation, false);
-            retryQueue.set(
-              operation.key,
-              addAuthAttemptToOperation(operation, false)
-            );
+            if (!retryQueue.has(operation.key)) {
+              retryQueue.set(
+                operation.key,
+                addAuthAttemptToOperation(operation, false)
+              );
+            }
             return null;
-          } else if (
-            !operation.context.authAttempt &&
-            willAuthError &&
-            willAuthError({ operation, authState })
-          ) {
+          } else if (willAuthError(operation)) {
             refreshAuth(operation);
             return null;
           }
 
-          operation = addAuthAttemptToOperation(operation, false);
-          return addAuthToOperation({ operation, authState });
+          return addAuthToOperation(
+            addAuthAttemptToOperation(operation, false)
+          );
         }),
         filter(Boolean)
       ) as Source<Operation>;
···
 
       return pipe(
         result$,
-        filter(({ error, operation }) => {
-          if (error && didAuthError && didAuthError({ error, authState })) {
-            if (!operation.context.authAttempt) {
-              refreshAuth(operation);
-              return false;
-            }
+        filter(result => {
+          if (
+            result.error &&
+            didAuthError(result) &&
+            !result.operation.context.authAttempt
+          ) {
+            refreshAuth(result.operation);
+            return false;
           }
 
           return true;

exchanges/auth/src/index.ts

···
 export { authExchange } from './authExchange';
-export type { AuthConfig } from './authExchange';
+export type { AuthUtilities, AuthConfig } from './authExchange';