Update SetContextLink

Author: jerelmiller

docs/source/api/link/apollo-link-context.mdx

@@ -1,28 +1,55 @@
 ---
-title: Context Link
+title: SetContextLink
 description: Easily set a context on your operation, which is used by other links further down the chain.
 ---
 
-## Overview
+<DocBlock
+  canonicalReference="@apollo/client/link/context!SetContextLink:class"
+  customOrder={["summary", "remarks", "example"]}
+/>
 
-The `setContext` function accepts a function that returns either an object or a promise, which then returns an object to set the new context of a request. It receives two arguments: the GraphQL request being executed, and the previous context. This link makes it easy to perform the asynchronous lookup of things like authentication tokens and more.
+## Constructor signature
 
-```js
-import { setContext } from "@apollo/client/link/context";
-
-const setAuthorizationLink = setContext((request, previousContext) => ({
-  headers: { authorization: "1234" },
-}));
-
-const asyncAuthLink = setContext(
-  (request) =>
-    new Promise((success, fail) => {
-      // do some async lookup here
-      setTimeout(() => {
-        success({ token: "async found token" });
-      }, 10);
-    })
-);
+```ts
+constructor(
+  setter: SetContextLink.ContextSetter
+): SetContextLink
+```
+
+## Usage examples
+
+### Authentication
+
+The most common use case is adding authentication headers to requests:
+
+```ts
+const authLink = new SetContextLink((prevContext, operation) => {
+  const token = getAuthToken();
+
+  return {
+    headers: {
+      ...prevContext.headers,
+      authorization: token ? `Bearer ${token}` : "",
+    },
+  };
+});
+```
+
+### Asynchronous token lookup
+
+You can also perform asynchronous operations to fetch tokens or other data:
+
+```ts
+const asyncAuthLink = new SetContextLink(async (prevContext, operation) => {
+  const token = await fetchAuthToken();
+
+  return {
+    headers: {
+      ...prevContext.headers,
+      authorization: `Bearer ${token}`,
+    },
+  };
+});
 ```
 
 ## Caching lookups
@@ -33,19 +60,30 @@ Take for example a user auth token being found, cached, then removed on a 401 re
 
 ```js
 import { ServerError } from "@apollo/client";
-import { setContext } from "@apollo/client/link/context";
-import { ErrorLink } from "@apollo/client/link/error";
+import { SetContextLink } from "@apollo/client/link/context";
+import { onError } from "@apollo/client/link/error";
 
 // cached storage for the user token
 let token;
-const withToken = setContext(() => {
+const withToken = new SetContextLink(async (prevContext, operation) => {
   // if you have a cached value, return it immediately
-  if (token) return { token };
+  if (token) {
+    return {
+      headers: {
+        ...prevContext.headers,
+        authorization: `Bearer ${token}`,
+      },
+    };
+  }
 
-  return AsyncTokenLookup().then((userToken) => {
-    token = userToken;
-    return { token };
-  });
+  const userToken = await AsyncTokenLookup();
+  token = userToken;
+  return {
+    headers: {
+      ...prevContext.headers,
+      authorization: `Bearer ${token}`,
+    },
+  };
 });
 
 const resetToken = new ErrorLink(({ error }) => {
@@ -57,3 +95,25 @@ const resetToken = new ErrorLink(({ error }) => {
 
 const authFlowLink = withToken.concat(resetToken);
 ```
+
+## Types
+
+<FunctionDetails
+  canonicalReference="@apollo/client/link/context!SetContextLink.SetContextLinkDocumentationTypes.ContextSetter:function(1)"
+  headingLevel={3}
+  result={false}
+  displayName="SetContextLink.ContextSetter"
+/>
+
+### `SetContextLink.SetContextOperation`
+
+<DocBlock canonicalReference="@apollo/client/link/context!SetContextLink.SetContextOperation:type" />
+
+#### Signature
+
+```ts
+type SetContextOperation = Omit<
+  ApolloLink.Operation,
+  "getContext" | "setContext"
+>;
+```

src/link/context/index.ts

@@ -3,6 +3,31 @@ import { Observable } from "rxjs";
 import { ApolloLink } from "@apollo/client/link";
 
 export declare namespace SetContextLink {
+  namespace SetContextLinkDocumentationTypes {
+    /**
+     * A function that returns an updated context object for an Apollo Link
+     * operation.
+     *
+     * The context setter function is called for each operation and allows you to
+     * modify the operation's context before it's passed to the next link in the
+     * chain. The returned context object is shallowly merged with the previous
+     * context object.
+     *
+     * @param prevContext - The previous context of the operation (e.g. the value
+     * of `operation.getContext()`)
+     * @param operation - The GraphQL operation being executed, without the
+     * `getContext` and `setContext` methods
+     * @returns A partial context object or a promise that resolves to a partial context object
+     */
+    export function ContextSetter(
+      prevContext: Readonly<ApolloLink.OperationContext>,
+      operation: SetContextLink.SetContextOperation
+    ):
+      | Promise<Partial<ApolloLink.OperationContext>>
+      | Partial<ApolloLink.OperationContext>;
+  }
+
+  /** {@inheritDoc @apollo/client/link/context!SetContextLink.SetContextLinkDocumentationTypes.ContextSetter:function(1)} */
   export type ContextSetter = (
     prevContext: Readonly<ApolloLink.OperationContext>,
     operation: SetContextLink.SetContextOperation
@@ -22,6 +47,11 @@ export declare namespace SetContextLink {
     | Promise<Partial<ApolloLink.OperationContext>>
     | Partial<ApolloLink.OperationContext>;
 
+  /**
+   * An `ApolloLink.Operation` object without the `getContext` and `setContext`
+   * methods. This prevents context setters from directly manipulating the
+   * context during the setter function execution.
+   */
   export type SetContextOperation = Omit<
     ApolloLink.Operation,
     "getContext" | "setContext"
@@ -45,6 +75,24 @@ export function setContext(setter: SetContextLink.LegacyContextSetter) {
     setter(operation, prevContext)
   );
 }
+/**
+ * `SetContextLink` is a non-terminating link that allows you to modify the
+ * context of GraphQL operations before they're passed to the next link in the
+ * chain. This is commonly used for authentication, adding headers, and other
+ * request-time configuration.
+ *
+ * @example
+ *
+ * ```ts
+ * import { SetContextLink } from "@apollo/client/link/context";
+ *
+ * const link = new SetContextLink((prevContext, operation) => {
+ *   return {
+ *     // ...
+ *   };
+ * });
+ * ```
+ */
 export class SetContextLink extends ApolloLink {
   constructor(setter: SetContextLink.ContextSetter) {
     super((operation, forward) => {