From 1be5134f70b101932b5c4a3ef47b214e252b7567 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 15:05:01 -0600 Subject: [PATCH 01/53] Update docs for HttpLink types --- docs/source/api/link/apollo-link-http.mdx | 392 ++-------------------- src/link/http/HttpLink.ts | 181 ++++++---- 2 files changed, 143 insertions(+), 430 deletions(-) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 2b554ab61d0..72de89e65b8 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -3,374 +3,10 @@ title: HTTP Link description: Get GraphQL results over a network using HTTP fetch. --- -> We recommend reading [Apollo Link overview](./introduction/) before learning about individual links. - -`HttpLink` is a terminating link that sends a GraphQL operation to a remote endpoint over HTTP. Apollo Client uses `HttpLink` by default when you provide the `uri` option to the `ApolloClient` constructor. - -`HttpLink` supports both POST and GET requests, and you can configure HTTP options on a per-operation basis. You can use these options for authentication, persisted queries, dynamic URIs, and other granular updates. - -## Usage - -Import the `HttpLink` class and initialize a link like so: - -```js -import { HttpLink } from "@apollo/client"; - -const link = new HttpLink({ - uri: "http://localhost:4000/graphql", - // Additional options -}); -``` - -## `HttpLink` constructor options - -The `HttpLink` constructor takes an options object that can include the fields below. Note that you can also override some of these options on a per-operation basis using the [operation context](#context-options). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `uri` - -`String` or `Function` - - - -The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an `Operation` object and returns the string URL to use for that operation. - -The default value is `/graphql`. - -
- -###### `includeExtensions` - -`Boolean` - - - -If true, includes the `extensions` field in operations sent to your GraphQL endpoint. - -The default value is `false`. - -
- -###### `fetch` - -`Function` - - - -A function to use instead of calling the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) directly when sending HTTP requests to your GraphQL endpoint. The function must conform to the signature of `fetch`. - -By default, the Fetch API is used unless it isn't available in your runtime environment. - -See [Customizing `fetch`](#customizing-fetch). - -
- -###### `headers` - -`Object` - - - -An object representing headers to include in every HTTP request, such as `{Authorization: 'Bearer abc123'}`. - -
- -###### `preserveHeaderCase` - -`Boolean` - - - -If set to true, header names won't be automatically normalized to lowercase. This allows for non-http-spec-compliant servers that might expect capitalized header names. - -The default value is `false`. - -
- -###### `credentials` - -`String` - - - -The credentials policy to use for each `fetch` call. Can be `omit`, `include`, or `same-origin`. - -
- -###### `fetchOptions` - -`Object` - - - -An object containing options to use for each call to `fetch`. If a particular option is not included in this object, the default value of that option is used. - -Note that if you set `fetchOptions.method` to `GET`, `HttpLink` follows [standard GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). - -[See available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) - -
- -###### `useGETForQueries` - -`Boolean` - - - -If `true`, the link uses an HTTP GET request when sending query operations to your GraphQL endpoint. Mutation operations continue to use `POST` requests. If you want _all_ operations to use `GET` requests, set [`fetchOptions.method`](#fetchoptions) instead. - -The default value is `false`. - -
- -###### `print` - -`Function` - - - -An optional function to use when transforming a query or mutation `DocumentNode` into a string. It accepts an `ASTNode` (typically a `DocumentNode`) and the original `print` function as arguments, and is expected to return a string. This option can be used with `stripIgnoredCharacters` to remove whitespace from queries. - -```js -import { stripIgnoredCharacters } from "graphql"; - -const httpLink = new HttpLink({ - uri: "/graphql", - print: (ast, originalPrint) => stripIgnoredCharacters(originalPrint(ast)), -}); -``` - -By default the bare [GraphQL `print` function](https://graphql.org/graphql-js/language/#print) is used. - -
- -## Context options - -`HttpLink` checks the [current operation's `context`](./introduction/#managing-context) for certain values before sending its request to your GraphQL endpoint. Previous links in the link chain can set these values to customize the behavior of `HttpLink` for each operation. - -> Some of these values can also be provided as options to [the `HttpLink` constructor](#httplink-constructor-options). If a value is provided to both, the value in the `context` takes precedence. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `uri` - -`String` or `Function` - - - -The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an `Operation` object and returns the string URL to use for that operation. - -The default value is `/graphql`. - -
- -###### `headers` - -`Object` - - - -An object representing headers to include in the HTTP request, such as `{Authorization: 'Bearer abc123'}`. - -
- -###### `credentials` - -`String` - - - -The credentials policy to use for this `fetch` call. Can be `omit`, `include`, or `same-origin`. - -
- -###### `fetchOptions` - -`Object` - - - -An object containing options to use for this call to `fetch`. If a particular option is not included in this object, the default value of that option is used. - -Note that if you set `fetchOptions.method` to `GET`, `HttpLink` follows [standard GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). - -[See available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) - -
- -###### `http` - -`Object` - - - -An object that configures advanced `HttpLink` functionality, such as support for persisted queries. Options are listed in [`http` option fields](#http-option-fields). - -
- -### `http` option fields - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `includeExtensions` - -`Boolean` - - - -If true, includes the `extensions` field in operations sent to your GraphQL endpoint. - -The default value is `false`. - -
- -###### `includeQuery` - -`Boolean` - - - -If `false`, the GraphQL query string is _not_ included in the request. Set this option if you're sending a request that uses a [persisted query](./persisted-queries/). - -The default value is `true`. - -
- -###### `preserveHeaderCase` - -`Boolean` - - - -If set to true, header names won't be automatically normalized to lowercase. This allows for non-http-spec-compliant servers that might expect capitalized header names. - -The default value is `false`. - -
+ ## Operation results @@ -451,3 +87,23 @@ const customFetch = (uri, options) => { const link = new HttpLink({ fetch: customFetch }); ``` + +## Types + + + + + + diff --git a/src/link/http/HttpLink.ts b/src/link/http/HttpLink.ts index 09a563e3781..5792a7b6e23 100644 --- a/src/link/http/HttpLink.ts +++ b/src/link/http/HttpLink.ts @@ -8,36 +8,25 @@ import { BaseHttpLink } from "./BaseHttpLink.js"; export declare namespace HttpLink { /** - * Options passed to `HttpLink` through request context. + * Options passed to `HttpLink` through [request context](https://apollographql.com/docs/react/api/link/introduction#managing-context). Previous + * non-terminating links in the link chain also can set these values to + * customize the behavior of `HttpLink` for each operation. + * + * > [!NOTE] + * > Some of these values can also be provided to the `HttpLink` constructor. + * > If a value is provided to both, the value in `context` takes precedence. */ interface ContextOptions { - /** - * The URL of the GraphQL endpoint to send requests to. Can also be a - * function that accepts an `Operation` object and returns the string URL to - * use for that operation. - */ - uri?: string | UriFunction; + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#uri:member} */ + uri?: string | HttpLink.UriFunction; - /** - * An object representing headers to include in the HTTP request, such as - * `{Authorization: 'Bearer abc123'}`. - */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#headers:member} */ headers?: Record; - /** - * The credentials policy to use for this fetch call. Can be `omit`, `include`, - * or `same-origin`. - */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#credentials:member} */ credentials?: RequestCredentials; - /** - * An object containing options to use for this call to `fetch`. If a - * particular option is not included in this object, the default value of - * that option is used. - * - * Note that if you set `fetchOptions.method` to `GET`, `HttpLink` follows - * [standard GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). - */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetchOptions:member} */ fetchOptions?: RequestInit; /** @@ -48,16 +37,11 @@ export declare namespace HttpLink { } /** - * Options passed to `HttpLink` through the `http` constructor option - * or the `http` property of a request context. + * Options passed to `HttpLink` through the `http` property of a request + * context. */ export interface HttpOptions { - /** - * If `true`, includes the `extensions` field in operations sent to your - * GraphQL endpoint. - * - * @defaultValue true - */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeExtensions:member} */ includeExtensions?: boolean; /** @@ -68,19 +52,12 @@ export declare namespace HttpLink { */ includeQuery?: boolean; - /** - * If set to true, header names won't be automatically normalized to - * lowercase. This allows for non-http-spec-compliant servers that might - * expect capitalized header names. - * - * @defaultValue false - */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ preserveHeaderCase?: boolean; /** * A list of additional `accept` headers to include in the request, - * as defined in - * https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.2 + * as defined in https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.2 * * @example * @@ -92,72 +69,130 @@ export declare namespace HttpLink { } /** - * Options for the `HttpLink` constructor. + * Options provided to the `HttpLink` constructor. + * + * > [!NOTE] + * > Some of these options are also available to override in [request context](https://apollographql.com/docs/react/api/link/introduction#managing-context). + * > Context options override the options passed to the constructor. Treat + * > these options as default values that are used when the request context + * > does not override the value. */ export interface Options { /** - * The URI to use when fetching operations. + * The URL of the GraphQL endpoint to send requests to. Can also be a + * function that accepts an `ApolloLink.Operation` object and returns the + * string URL to use for that operation. * - * Defaults to '/graphql'. + * @defaultValue "/graphql" */ - uri?: string | UriFunction; + uri?: string | HttpLink.UriFunction; /** - * Passes the extensions field to your graphql server. + * If `true`, includes the `extensions` field in operations sent to your + * GraphQL endpoint. * - * Defaults to true. + * @defaultValue true */ includeExtensions?: boolean; /** - * A `fetch`-compatible API to use when making requests. + * A function to use instead of calling the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) directly + * when sending HTTP requests to your GraphQL endpoint. The function must + * conform to the signature of `fetch`. + * + * By default, the Fetch API is used unless it isn't available in your + * runtime environment. + * + * See [Customizing `fetch`](https://apollographql.com/docs/react/api/link/introduction#customizing-fetch). */ fetch?: typeof fetch; /** - * An object representing values to be sent as headers on the request. + * An object representing headers to include in every HTTP request. + * + * @example + * + * ```json + * { + * "Authorization": "Bearer 1234" + * } + * ``` */ headers?: Record; /** - * If set to true, header names won't be automatically normalized to - * lowercase. This allows for non-http-spec-compliant servers that might - * expect capitalized header names. + * If `true`, header names won't be automatically normalized to lowercase. + * This allows for non-http-spec-compliant servers that might expect + * capitalized header names. + * + * @defaultValue false */ preserveHeaderCase?: boolean; /** - * The credentials policy you want to use for the fetch call. + * The credentials policy to use for each `fetch` call. */ credentials?: RequestCredentials; /** * Any overrides of the fetch options argument to pass to the fetch call. + * + * An object containing options to use for each call to `fetch`. If a + * particular option is not included in this object, the default value of + * that option is used. + * + * > [!NOTE] + * > If you set `fetchOptions.method` to `GET`, `HttpLink` follows [standard + * > GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). + * + * See [available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) */ fetchOptions?: RequestInit; /** - * If set to true, use the HTTP GET method for query operations. Mutations - * will still use the method specified in fetchOptions.method (which defaults - * to POST). + * If `true`, the link uses an HTTP `GET` request when sending query + * operations to your GraphQL endpoint. Mutation operations continue to use + * `POST` requests. If you want all operations to use `GET` requests, + * set `fetchOptions.method` instead. + * + * @defaultValue false */ useGETForQueries?: boolean; /** - * If set to true, the default behavior of stripping unused variables - * from the request will be disabled. + * If `true`, unused variables from the operation will not be stripped from + * the request and will instead be sent to the GraphQL endpoint. * + * @remarks * Unused variables are likely to trigger server-side validation errors, - * per https://spec.graphql.org/draft/#sec-All-Variables-Used, but this - * includeUnusedVariables option can be useful if your server deviates + * per https://spec.graphql.org/draft/#sec-All-Variables-Used. + * `includeUnusedVariables` can be useful if your server deviates * from the GraphQL specification by not strictly enforcing that rule. + * + * @defaultValue false */ includeUnusedVariables?: boolean; /** - * A function to substitute for the default query print function. Can be - * used to apply changes to the results of the print function. + * A function to use when transforming a GraphQL document into a string. It + * accepts an `ASTNode` (typically a `DocumentNode`) and the original `print` + * function as arguments, and is expected to return a string. This option + * enables you to, for example, use `stripIgnoredCharacters` to remove + * whitespace from queries. + * + * By default the [GraphQL `print` function](https://graphql.org/graphql-js/language/#print) is used. + * + * @example + * + * ```ts + * import { stripIgnoredCharacters } from "graphql"; + * + * const httpLink = new HttpLink({ + * uri: "/graphql", + * print: (ast, originalPrint) => stripIgnoredCharacters(originalPrint(ast)), + * }); + * ``` */ - print?: Printer; + print?: HttpLink.Printer; } interface Body { @@ -171,6 +206,28 @@ export declare namespace HttpLink { type UriFunction = (operation: ApolloLink.Operation) => string; } +/** + * `HttpLink` is a terminating link that sends a GraphQL operation to a remote + * endpoint over HTTP. Apollo Client uses `HttpLink` by default when you provide + * the `uri` option to the `ApolloClient` constructor. + * + * @remarks + * + * `HttpLink` supports both POST and GET requests, and you can configure HTTP + * options on a per-operation basis. You can use these options for + * authentication, persisted queries, dynamic URIs, and other granular updates. + * + * @example + * + * ```ts + * import { HttpLink } from "@apollo/client"; + * + * const link = new HttpLink({ + * uri: "http://localhost:4000/graphql", + * // Additional options + * }); + * ``` + */ export class HttpLink extends ApolloLink { constructor(options: HttpLink.Options & ClientAwarenessLink.Options = {}) { const { left, right, request } = ApolloLink.from([ From ef010e5bf676426f17b1fbc26178727061594f54 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 15:23:24 -0600 Subject: [PATCH 02/53] Update more httplink docs --- docs/source/api/link/apollo-link-http.mdx | 47 ++++++----------------- 1 file changed, 12 insertions(+), 35 deletions(-) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 72de89e65b8..c3532affed3 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -8,52 +8,29 @@ description: Get GraphQL results over a network using HTTP fetch. customOrder={["summary", "remarks", "example"]} /> -## Operation results - -After your GraphQL endpoint (successfully) responds with the result of the sent operation, `HttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. - ## Handling errors -`HttpLink` distinguishes between client errors, server errors, and GraphQL errors. You can add the [`onError` link](./apollo-link-error) to your link chain to handle these errors via a [callback](./apollo-link-error#options). +`HttpLink` distinguishes between client errors, server errors, and GraphQL errors. You can add the [`ErrorLink`](./apollo-link-error) to your link chain to handle these errors via a [callback](./apollo-link-error#options). The following types of errors can occur: -| Error | Description | Callback | Error Type | -| -------------- | ---------------------------------------------------------------------------------------------------------------------- | :------: | ------------------ | -| Client Parse | The request body is not serializable, for example due to a circular reference. | `error` | `ClientParseError` | -| Server Parse | The server's response cannot be parsed ([response.json()](https://developer.mozilla.org/en-US/docs/Web/API/Body/json)) | `error` | `ServerParseError` | -| Server Network | The server responded with a non-2xx HTTP code. | `error` | `ServerError` | -| Server Data | The server's response didn't contain `data` or `errors`. | `error` | `ServerError` | -| GraphQL Error | Resolving the GraphQL operation resulted in at least one error, which is present in the `errors` field. | `next` | `Object` | +| Error | Description | Callback | Error Type | +| -------------- | ---------------------------------------------------------------------------------------------------------------------- | :------: | ---------------------------------------------------------- | +| Client Parse | The request body is not serializable, for example due to a circular reference. | `error` | `ClientParseError` | +| Server Parse | The server's response cannot be parsed ([response.json()](https://developer.mozilla.org/en-US/docs/Web/API/Body/json)) | `error` | [`ServerParseError`](../errors/ServerParseError) | +| Server Network | The server responded with a non-2xx HTTP code. | `error` | [`ServerError`](../errors/ServerError) | +| Server Data | The server's response didn't contain `data` or `errors`. | `error` | [`ServerError`](../errors/ServerError) | +| GraphQL Error | Resolving the GraphQL operation resulted in at least one error, which is present in the `errors` field. | `next` | [`CombinedGraphQLErrors`](../errors/CombinedGraphQLErrors) | -Because many server implementations can return a valid GraphQL result on a server network error, the thrown `Error` object contains the parsed server result. A server data error also receives the parsed result. +See the documentation on [Identifying error types](../../data/error-handling#identifying-error-types) to learn how to distinguish between the different error types. -All error types inherit the `name`, `message`, and nullable `stack` properties from the generic javascript [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error): - -```js -//type ClientParseError -{ - parseError: Error; // Error returned from response.json() -}; - -//type ServerParseError -{ - response: Response; // Object returned from fetch() - statusCode: number; // HTTP status code - bodyText: string // text that was returned from server -}; +## Operation results -//type ServerError -{ - result: Record; // Parsed object from server response - response: Response; // Object returned from fetch() - statusCode: number; // HTTP status code -}; -``` +After your GraphQL endpoint (successfully) responds with the result of the sent operation, `HttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. ## Customizing `fetch` -You can provide the [`fetch` option](#fetch) to the `HttpLink` constructor to enable many custom networking needs. For example, you can modify the request based on calculated headers or calculate the endpoint URI based on the operation's details. +You can provide a custom [`fetch` option](#options-fetch) to the `HttpLink` constructor to enable many custom networking needs. For example, you can modify the request based on calculated headers or calculate the endpoint URI based on the operation's details. If you're targeting an environment that doesn't provide the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) (such as older browsers or the server) you can provide a different implementation of `fetch`. We recommend [`unfetch`](https://github.com/developit/unfetch) for older browsers and [`node-fetch`](https://github.com/bitinn/node-fetch) for running in Node. From 9bb27dd0b6b0168981003b1ba06559d5fcb1c9ee Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 15:23:31 -0600 Subject: [PATCH 03/53] Remove outdated info --- src/link/http/HttpLink.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/link/http/HttpLink.ts b/src/link/http/HttpLink.ts index 5792a7b6e23..c7010645f51 100644 --- a/src/link/http/HttpLink.ts +++ b/src/link/http/HttpLink.ts @@ -208,8 +208,7 @@ export declare namespace HttpLink { /** * `HttpLink` is a terminating link that sends a GraphQL operation to a remote - * endpoint over HTTP. Apollo Client uses `HttpLink` by default when you provide - * the `uri` option to the `ApolloClient` constructor. + * endpoint over HTTP. * * @remarks * From 1ce39c0cd3d8ec064fa8881226637ee977ea24e0 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 15:29:40 -0600 Subject: [PATCH 04/53] Add constructor signature and include information about client awareness --- docs/source/api/link/apollo-link-http.mdx | 14 ++++++++++++++ src/link/http/HttpLink.ts | 4 ++++ 2 files changed, 18 insertions(+) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index c3532affed3..c69dd0ec346 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -8,6 +8,14 @@ description: Get GraphQL results over a network using HTTP fetch. customOrder={["summary", "remarks", "example"]} /> +{/* TODO: Remove the custom signature once documentation supports rendering constructor functions */} + +```ts +constructor( + options: HttpLink.Options & ClientAwarenessLink.Options = {} +): HttpLink +``` + ## Handling errors `HttpLink` distinguishes between client errors, server errors, and GraphQL errors. You can add the [`ErrorLink`](./apollo-link-error) to your link chain to handle these errors via a [callback](./apollo-link-error#options). @@ -84,3 +92,9 @@ const link = new HttpLink({ fetch: customFetch }); headingLevel={3} displayName="HttpLink.HttpOptions" /> + + diff --git a/src/link/http/HttpLink.ts b/src/link/http/HttpLink.ts index c7010645f51..8e8f2c85c6b 100644 --- a/src/link/http/HttpLink.ts +++ b/src/link/http/HttpLink.ts @@ -216,6 +216,10 @@ export declare namespace HttpLink { * options on a per-operation basis. You can use these options for * authentication, persisted queries, dynamic URIs, and other granular updates. * + * `HttpLink` combines the functionality of `BaseHttpLink` and + * `ClientAwarenessLink` into a single link. If you prefer to use `HttpLink` + * without the `ClientAwarenessLink` functionality, use `BaseHttpLink` instead. + * * @example * * ```ts From bcbba2d96638aa3c8fd151a3ce5bf9bd604c4c67 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 15:30:18 -0600 Subject: [PATCH 05/53] Update title of doc --- docs/source/api/link/apollo-link-http.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index c69dd0ec346..5326eb65a43 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -1,5 +1,5 @@ --- -title: HTTP Link +title: HttpLink description: Get GraphQL results over a network using HTTP fetch. --- From 3451f7e0a8af3c3a799f0e3fba5152b49c1a1afe Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:03:52 -0600 Subject: [PATCH 06/53] Add client awareness link doc --- docs/source/_sidebar.yaml | 2 + .../api/link/apollo-link-client-awareness.mdx | 100 ++++++++++++++++++ .../client-awareness/ClientAwarenessLink.ts | 35 +++++- 3 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 docs/source/api/link/apollo-link-client-awareness.mdx diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index 610eb3453ae..f39b046930c 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -197,6 +197,8 @@ items: href: ./api/link/apollo-link-context - label: ErrorLink href: ./api/link/apollo-link-error + - label: ClientAwarenessLink + href: ./api/link/apollo-link-client-awareness - label: PersistedQueryLink href: ./api/link/persisted-queries - label: RemoveTypenameFromVariablesLink diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx new file mode 100644 index 00000000000..17426dc8381 --- /dev/null +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -0,0 +1,100 @@ +--- +title: ClientAwarenessLink +description: API reference +--- + + + +## Configuring with Apollo Client + +You can configure client awareness when initializing your Apollo Client instance using the `clientAwareness` and `enhancedClientAwareness` options. Options configured with the `ClientAwarenessLink` constructor, `HttpLink` constructor, or [request context](./introduction#managing-context) take precedence. + +```ts +import { ApolloClient } from "@apollo/client"; + +new ApolloClient({ + clientAwareness: { + name: "My Client", + version: "my_client_version", + }, + enhancedClientAwareness: { + transport: "extensions", + }, +}); +``` + +## Configuring with `HttpLink` + +You can configure client awareness when initializing an `HttpLink` using the `clientAwareness` and `enhancedClientAwareness` options. These options take precedence over options provided to the `ApolloClient` constructor but can be overridden by [request context](./introduction#managing-context). + +```ts +import { ApolloClient, HttpLink } from "@apollo/client"; + +const link = new HttpLink({ + clientAwareness: { + name: "My Client", + version: "my_client_version", + }, + enhancedClientAwareness: { + transport: "extensions", + }, +}); + +const client = new ApolloClient({ + link, + // additional options +}); +``` + + + +If you are using `BaseHttpLink` and want client awareness functionality, you will need to add `ClientAwarenessLink` to your link chain manually. `HttpLink` includes `ClientAwarenessLink` by default. + + + +## Configuring with request context + +You can configure client awareness using request context. Provide the `clientAwareness` and `enhancedClientAwareness` fields in `context`. These values take precedence over all other configurations. + +```ts +const client = new ApolloClient(/* ... */); + +function MyComponent() { + const { data } = useQuery(query, { + context: { + clientAwareness: { + name: "My Client", + version: "my_client_version", + }, + enhancedClientAwareness: { + transport: "extensions", + }, + }, + }); + + // ... +} +``` + +## Types + + + + + + diff --git a/src/link/client-awareness/ClientAwarenessLink.ts b/src/link/client-awareness/ClientAwarenessLink.ts index e862d32a760..498b258fbc1 100644 --- a/src/link/client-awareness/ClientAwarenessLink.ts +++ b/src/link/client-awareness/ClientAwarenessLink.ts @@ -49,17 +49,48 @@ export declare namespace ClientAwarenessLink { * and Apollo Server logs (and other monitoring or analytics tools) by adding * information about the your application to outgoing requests. */ - clientAwareness?: ClientAwarenessOptions; + clientAwareness?: ClientAwarenessLink.ClientAwarenessOptions; /** * Configures the "enhanced client awareness" feature. * This feature allows you to identify the version of the Apollo Client library * used in your application in Apollo Studio (and other monitoring or analytics tools) * by adding information about the Apollo Client library to outgoing requests. */ - enhancedClientAwareness?: EnhancedClientAwarenessOptions; + enhancedClientAwareness?: ClientAwarenessLink.EnhancedClientAwarenessOptions; } } +/** + * `ClientAwarenessLink` provides support for providing client awareness + * features. + * + * @remarks + * + * Client awareness adds identifying information about the client to HTTP + * requests for use with metrics reporting tools, such as the [Apollo GraphOS](https://apollographql.com/docs/graphos/platform). + * It is included in the functionality of [`HttpLink`](https://apollographql.com/docs/react/api/link/apollo-link-http) by default. + * + * Client awareness distinguishes between user-provided client awareness + * (provided by the `clientAwareness` option) and enhanced client awareness + * (provided by the `enhancedClientAwareness` option). User-provided client + * awareness enables you to set a customized client name and version for + * identification in metrics reporting tools. Enhanced client awareness enables + * the identification of the Apollo Client package name and version. + * + * @example + * + * ```ts + * const link = new ClientAwarenessLink({ + * clientAwareness: { + * name: "My Client", + * version: "1", + * }, + * enhancedClientAwareness: { + * transport: "extensions", + * }, + * }); + * ``` + */ export class ClientAwarenessLink extends ApolloLink { constructor(constructorOptions: ClientAwarenessLink.Options = {}) { super((operation, forward) => { From fc6ac0cb762ecef4a9193e69d9254717ead7d2b8 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:04:55 -0600 Subject: [PATCH 07/53] Tweak HttpLink description --- src/link/http/HttpLink.ts | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/link/http/HttpLink.ts b/src/link/http/HttpLink.ts index 8e8f2c85c6b..774a2e4b570 100644 --- a/src/link/http/HttpLink.ts +++ b/src/link/http/HttpLink.ts @@ -208,7 +208,8 @@ export declare namespace HttpLink { /** * `HttpLink` is a terminating link that sends a GraphQL operation to a remote - * endpoint over HTTP. + * endpoint over HTTP. It combines the functionality of `BaseHttpLink` and + * `ClientAwarenessLink` into a single link. * * @remarks * @@ -216,10 +217,6 @@ export declare namespace HttpLink { * options on a per-operation basis. You can use these options for * authentication, persisted queries, dynamic URIs, and other granular updates. * - * `HttpLink` combines the functionality of `BaseHttpLink` and - * `ClientAwarenessLink` into a single link. If you prefer to use `HttpLink` - * without the `ClientAwarenessLink` functionality, use `BaseHttpLink` instead. - * * @example * * ```ts From e5f7a505efa8efcdc2c7cd83dfd492dd745080c8 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:08:37 -0600 Subject: [PATCH 08/53] Alphabetize links in sidebar --- docs/source/_sidebar.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index f39b046930c..18cbd6b8341 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -189,16 +189,16 @@ items: href: ./api/link/introduction - label: ApolloLink href: ./api/link/apollo-link - - label: HttpLink - href: ./api/link/apollo-link-http - label: BatchHttpLink href: ./api/link/apollo-link-batch-http - - label: SetContextLink - href: ./api/link/apollo-link-context - - label: ErrorLink - href: ./api/link/apollo-link-error - label: ClientAwarenessLink href: ./api/link/apollo-link-client-awareness + - label: ErrorLink + href: ./api/link/apollo-link-error + - label: GraphQLWsLink (newer protocol) + href: ./api/link/apollo-link-subscriptions + - label: HttpLink + href: ./api/link/apollo-link-http - label: PersistedQueryLink href: ./api/link/persisted-queries - label: RemoveTypenameFromVariablesLink @@ -209,8 +209,8 @@ items: href: ./api/link/apollo-link-retry - label: SchemaLink href: ./api/link/apollo-link-schema - - label: GraphQLWsLink (newer protocol) - href: ./api/link/apollo-link-subscriptions + - label: SetContextLink + href: ./api/link/apollo-link-context - label: WebSocketLink (older protocol) href: ./api/link/apollo-link-ws - label: Community links From 192bf6790917dbbb5bea7046574240ca5d357861 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:14:57 -0600 Subject: [PATCH 09/53] Use interface for batchHttpLink options. Add doc blocks --- src/link/batch-http/batchHttpLink.ts | 49 +++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/src/link/batch-http/batchHttpLink.ts b/src/link/batch-http/batchHttpLink.ts index 42affb2233b..87d9d2c31c3 100644 --- a/src/link/batch-http/batchHttpLink.ts +++ b/src/link/batch-http/batchHttpLink.ts @@ -18,20 +18,53 @@ import { compact } from "@apollo/client/utilities/internal"; import { maybe } from "@apollo/client/utilities/internal/globals"; export declare namespace BatchHttpLink { - export type Options = Pick< - BatchLink.Options, - "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" - > & - Omit; - + /** + * Options provided to the `BatchHttpLink` constructor. + */ + export interface Options + extends Pick< + BatchLink.Options, + "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" + >, + Omit {} + + /** + * Options passed to `BatchHttpLink` through [request context](https://apollographql.com/docs/react/api/link/introduction#managing-context). Previous + * non-terminating links in the link chain also can set these values to + * customize the behavior of `BatchHttpLink` for each operation. + * + * > [!NOTE] + * > Some of these values can also be provided to the `BatchHttpLink` constructor. + * > If a value is provided to both, the value in `context` takes precedence. + */ export type ContextOptions = HttpLink.ContextOptions; } const backupFetch = maybe(() => fetch); /** - * Transforms Operation for into HTTP results. - * context can include the headers property, which will be passed to the fetch function + * `BatchHttpLink` is a terminating link that batches array of individual + * GraphQL operations into a single HTTP request that's sent to a single GraphQL + * endpoint. It combines the functionality of `BaseBatchHttpLink` and + * `ClientAwarenessLink` into a single link. + * + * @remarks + * + * If you use `BatchHttpLink` instead of `HttpLink` as your terminating link, + * Apollo Client automatically batches executed GraphQL operations and transmits + * them to your server according to the batching options you provide. + * + * @example + * + * ```ts + * import { BatchHttpLink } from "@apollo/client/link/batch-http"; + * + * const link = new BatchHttpLink({ + * uri: "http://localhost:4000/graphql", + * batchMax: 5, // No more than 5 operations per batch + * batchInterval: 20, // Wait no more than 20ms after first batched operation + * }); + * ``` */ export class BatchHttpLink extends ApolloLink { constructor( From 87bd4942b2d41b1b859a9c2e9cd63ad045fe3f95 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:21:34 -0600 Subject: [PATCH 10/53] Use interface instead of type alias --- src/link/batch-http/batchHttpLink.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/batch-http/batchHttpLink.ts b/src/link/batch-http/batchHttpLink.ts index 87d9d2c31c3..991d357f42d 100644 --- a/src/link/batch-http/batchHttpLink.ts +++ b/src/link/batch-http/batchHttpLink.ts @@ -37,7 +37,7 @@ export declare namespace BatchHttpLink { * > Some of these values can also be provided to the `BatchHttpLink` constructor. * > If a value is provided to both, the value in `context` takes precedence. */ - export type ContextOptions = HttpLink.ContextOptions; + export interface ContextOptions extends HttpLink.ContextOptions {} } const backupFetch = maybe(() => fetch); From 48f5530cabe7ba0ccc173de1c744b30851ac78c7 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 16:23:21 -0600 Subject: [PATCH 11/53] Revert back to type --- src/link/batch-http/batchHttpLink.ts | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/link/batch-http/batchHttpLink.ts b/src/link/batch-http/batchHttpLink.ts index 991d357f42d..a5355c122c4 100644 --- a/src/link/batch-http/batchHttpLink.ts +++ b/src/link/batch-http/batchHttpLink.ts @@ -21,12 +21,11 @@ export declare namespace BatchHttpLink { /** * Options provided to the `BatchHttpLink` constructor. */ - export interface Options - extends Pick< - BatchLink.Options, - "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" - >, - Omit {} + export type Options = Pick< + BatchLink.Options, + "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" + > & + Omit; /** * Options passed to `BatchHttpLink` through [request context](https://apollographql.com/docs/react/api/link/introduction#managing-context). Previous From b35849986a83026f442b97346751cd2cabf303d6 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:13:20 -0600 Subject: [PATCH 12/53] Update doc blocks for batchHttpLink --- src/link/batch-http/batchHttpLink.ts | 50 ++++++++++++++++++++++++++-- src/link/batch/batchLink.ts | 21 ++++++++---- 2 files changed, 61 insertions(+), 10 deletions(-) diff --git a/src/link/batch-http/batchHttpLink.ts b/src/link/batch-http/batchHttpLink.ts index a5355c122c4..fb469f6c552 100644 --- a/src/link/batch-http/batchHttpLink.ts +++ b/src/link/batch-http/batchHttpLink.ts @@ -18,9 +18,53 @@ import { compact } from "@apollo/client/utilities/internal"; import { maybe } from "@apollo/client/utilities/internal/globals"; export declare namespace BatchHttpLink { - /** - * Options provided to the `BatchHttpLink` constructor. - */ + export namespace DocumentationTypes { + /** + * Options provided to the `BatchHttpLink` constructor. + */ + interface Options { + /** {@inheritDoc @apollo/client/link/batch!BatchLink.Options#batchDebounce:member} */ + batchDebounce?: boolean; + + /** {@inheritDoc @apollo/client/link/batch!BatchLink.Options#batchInterval:member} */ + batchInterval?: number; + + /** {@inheritDoc @apollo/client/link/batch!BatchLink.Options#batchKey:member} */ + batchKey?: (operation: ApolloLink.Operation) => string; + + /** {@inheritDoc @apollo/client/link/batch!BatchLink.DocumentationTypes.Options#batchMax:member {"defaultValue": 10}} */ + batchMax?: number; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#uri:member} */ + uri?: string | HttpLink.UriFunction; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeExtensions:member} */ + includeExtensions?: boolean; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetch:member} */ + fetch?: typeof fetch; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#headers:member} */ + headers?: Record; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ + preserveHeaderCase?: boolean; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ + credentials?: string; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetchOptions:member} */ + fetchOptions?: any; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeUnusedVariables:member} */ + includeUnusedVariables?: boolean; + + /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#print:member} */ + print?: HttpLink.Printer; + } + } + + /** {@inheritDoc @apollo/client/link/batch-http!BatchHttpLink.DocumentationTypes.Options:interface} */ export type Options = Pick< BatchLink.Options, "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" diff --git a/src/link/batch/batchLink.ts b/src/link/batch/batchLink.ts index ff782d7617d..9ffdbf3795d 100644 --- a/src/link/batch/batchLink.ts +++ b/src/link/batch/batchLink.ts @@ -6,6 +6,17 @@ import { ApolloLink } from "@apollo/client/link"; import { OperationBatcher } from "./batching.js"; export declare namespace BatchLink { + export namespace DocumentationTypes { + interface Options { + /** + * The maximum number of operations to include in a single batch. + * + * @defaultValue {{defaultValue}} + */ + batchMax?: number; + } + } + export type BatchHandler = ( operations: ApolloLink.Operation[], forward: ApolloLink.ForwardFunction[] @@ -15,7 +26,7 @@ export declare namespace BatchLink { /** * The interval at which to batch, in milliseconds. * - * Defaults to 10. + * @defaultValue 10 */ batchInterval?: number; @@ -26,11 +37,7 @@ export declare namespace BatchLink { */ batchDebounce?: boolean; - /** - * The maximum number of operations to include in one fetch. - * - * Defaults to 0 (infinite operations within the interval). - */ + /** {@inheritDoc @apollo/client/link/batch!BatchLink.DocumentationTypes.Options#batchMax:member {"defaultValue": 0}} */ batchMax?: number; /** @@ -39,7 +46,7 @@ export declare namespace BatchLink { batchHandler?: BatchLink.BatchHandler; /** - * creates the key for a batch + * Creates the key for a batch */ batchKey?: (operation: ApolloLink.Operation) => string; } From 8247139bad6a34cbad510e63d631cae141489215 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:15:03 -0600 Subject: [PATCH 13/53] Update batch http link docs --- .../api/link/apollo-link-batch-http.mdx | 272 ++---------------- 1 file changed, 18 insertions(+), 254 deletions(-) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index 0f8b0f9e7df..4e05b6b010d 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -1,240 +1,12 @@ --- -title: Batch HTTP Link +title: BatchHttpLink description: Batch multiple operations into a single HTTP request --- -## Overview - -The `BatchHttpLink` is a terminating link that batches an array of individual GraphQL operations into a single HTTP request that's sent to a single GraphQL endpoint. - -```js -import { BatchHttpLink } from "@apollo/client/link/batch-http"; - -const link = new BatchHttpLink({ - uri: "http://localhost:4000/graphql", - batchMax: 5, // No more than 5 operations per batch - batchInterval: 20, // Wait no more than 20ms after first batched operation -}); -``` - -If you use `BatchHttpLink` instead of [`HttpLink`](./apollo-link-http) as your terminating link, Apollo Client automatically batches executed GraphQL operations and transmits them to your server according to the [batching options](#options) you provide. - -## Options - -The `BatchHttpLink` constructor accepts a configuration object that supports the following options: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -**Batching options** - -
- -###### `batchMax` - -`number` - - - -The maximum number of operations to include in a single batch. - -The default value is `10`. - -
- -###### `batchInterval` - -`number` - - - -The maximum number of milliseconds to wait before sending each batched request. If `batchMax` operations are batched before `batchInterval` is reached, the request is sent immediately. - -The default value is `10`. - -
- -###### `batchDebounce` - -`boolean` - - - -If `true`, the `batchInterval` timer is reset whenever an operation is added to the batch. In other words, the next batched request is not sent until either: - -- No operation is added for `batchInterval` milliseconds, or -- `batchMax` is reached. - -The default value is `false`. - -
- -###### `batchKey` - -`string` - - - -A function that accepts an operation and returns a string key, which uniquely names the batch the operation belongs to. - -[See the default function](https://github.com/apollographql/apollo-client/blob/main/src/link/batch-http/batchHttpLink.ts#L192-L206) - -
- -**HTTP options** - -
- -###### `uri` - -`String` or `Function` - - - -The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an `Operation` object and returns the string URL to use for that operation. - -The default value is `/graphql`. - -
- -###### `includeExtensions` - -`Boolean` - - - -If true, includes the `extensions` field in operations sent to your GraphQL endpoint. - -The default value is `false`. - -
- -###### `fetch` - -`Function` - - - -A function to use instead of calling the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) directly when sending HTTP requests to your GraphQL endpoint. The function must conform to the signature of `fetch`. - -By default, the Fetch API is used unless it isn't available in your runtime environment. - -See [Customizing `fetch`](./apollo-link-http/#customizing-fetch). - -
- -###### `headers` - -`Object` - - - -An object representing headers to include in every HTTP request, such as `{Authentication: 'Bearer abc123'}`. - -
- -###### `preserveHeaderCase` - -`Boolean` - - - -If set to true, header names won't be automatically normalized to lowercase. This allows for non-http-spec-compliant servers that might expect capitalized header names. - -The default value is `false`. - -
- -###### `credentials` - -`String` - - - -The credentials policy to use for each `fetch` call. Can be `omit`, `include`, or `same-origin`. - -
- -###### `fetchOptions` - -`Object` - - - -An object containing options to use for each call to `fetch`. If a particular option is not included in this object, the default value of that option is used. - -Note that if you set `fetchOptions.method` to `GET`, `BatchHttpLink` follows [standard GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). - -[See available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) - -
+ ## Context @@ -250,28 +22,20 @@ The batch HTTP link currently uses the context in two different ways, per batch For each query, the `http` field is used to modify each individual query in the batch, such as persisted queries (see below). -### Persisted queries - -The batch HTTP link supports an advanced GraphQL feature called persisted queries. This allows you to not send the stringified query over the wire, but instead send some kind of identifier for the query. To support this you need to attach the id somewhere in the extensions field, and pass the following options to the context: - -```js -operation.setContext({ - http: { - includeExtensions: true, - includeQuery: false, - }, -}); -``` - -From the context `http` object: +## Custom fetching -- `includeExtensions`: Send the extensions object for this request. -- `includeQuery`: Don't send the `query` field for this request. +See [Customizing `fetch`](apollo-link-http/#customizing-fetch). -See the [http option fields](https://www.apollographql.com/docs/react/api/link/apollo-link-http/#http-option-fields) for more information. +## Types -One way to use persisted queries is with [apollo-link-persisted-queries](https://www.apollographql.com/docs/react/api/link/persisted-queries) and [Apollo Server](/apollo-server/performance/apq/). + -## Custom fetching - -See [Customizing `fetch`](apollo-link-http/#customizing-fetch). + From a81fcd90a56159e6207fc4987872c6171975e1be Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:17:04 -0600 Subject: [PATCH 14/53] Add constrcturo signature --- docs/source/api/link/apollo-link-batch-http.mdx | 10 ++++++++++ docs/source/api/link/apollo-link-http.mdx | 2 ++ 2 files changed, 12 insertions(+) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index 4e05b6b010d..d9246da526f 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -8,6 +8,16 @@ description: Batch multiple operations into a single HTTP request customOrder={["summary", "example", "remarks"]} /> +## Constructor signature + +{/* TODO: Remove the custom signature once documentation supports rendering constructor functions */} + +```ts +constructor( + options: BatchHttpLink.Options & ClientAwarenessLink.Options = {} +): BatchHttpLink +``` + ## Context The batch HTTP link currently uses the context in two different ways, per batch and per query. The context fields below are used per batch and taken from the first operation in the batch. diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 5326eb65a43..7c679d87586 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -8,6 +8,8 @@ description: Get GraphQL results over a network using HTTP fetch. customOrder={["summary", "remarks", "example"]} /> +## Constructor signature + {/* TODO: Remove the custom signature once documentation supports rendering constructor functions */} ```ts From 28f164338ecc4dcd3425a04a93207a9cf2fa11ae Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:18:31 -0600 Subject: [PATCH 15/53] Nest configuring client awareness --- docs/source/api/link/apollo-link-client-awareness.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index 17426dc8381..ea41bed7679 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -8,7 +8,11 @@ description: API reference customOrder={["summary", "remarks", "example"]} /> -## Configuring with Apollo Client +## Configuring client awareness + +Client awareness can be configured in various ways throughout the client. + +### Configuring with Apollo Client You can configure client awareness when initializing your Apollo Client instance using the `clientAwareness` and `enhancedClientAwareness` options. Options configured with the `ClientAwarenessLink` constructor, `HttpLink` constructor, or [request context](./introduction#managing-context) take precedence. @@ -26,7 +30,7 @@ new ApolloClient({ }); ``` -## Configuring with `HttpLink` +### Configuring with `HttpLink` You can configure client awareness when initializing an `HttpLink` using the `clientAwareness` and `enhancedClientAwareness` options. These options take precedence over options provided to the `ApolloClient` constructor but can be overridden by [request context](./introduction#managing-context). @@ -55,7 +59,7 @@ If you are using `BaseHttpLink` and want client awareness functionality, you wil -## Configuring with request context +### Configuring with request context You can configure client awareness using request context. Provide the `clientAwareness` and `enhancedClientAwareness` fields in `context`. These values take precedence over all other configurations. From 497fbbf1ac8eb2b48802a40664d67d5da8633d23 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:35:46 -0600 Subject: [PATCH 16/53] Update error link api doc --- docs/source/api/link/apollo-link-error.mdx | 51 ++++++----------- src/link/error/index.ts | 66 +++++++++++++++++++++- 2 files changed, 80 insertions(+), 37 deletions(-) diff --git a/docs/source/api/link/apollo-link-error.mdx b/docs/source/api/link/apollo-link-error.mdx index adc0655a97f..5f2eaa347e3 100644 --- a/docs/source/api/link/apollo-link-error.mdx +++ b/docs/source/api/link/apollo-link-error.mdx @@ -3,46 +3,29 @@ title: Error Link description: Handle and inspect errors in your GraphQL network stack. --- -> We recommend reading [Apollo Link overview](./introduction/) before learning about individual links. + -Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](../../data/error-handling/) occurs. You create an instance of `ErrorLink` with a function that's executed if an operation returns one or more errors: +## Constructor signature -```js -import { ErrorLink } from "@apollo/client/link/error"; -import { - CombinedGraphQLErrors, - CombinedProtocolErrors, -} from "@apollo/client/errors"; +{/* TODO: Remove the custom signature once documentation supports rendering constructor functions */} -// Log any GraphQL errors, protocol errors, or network error that occurred -const errorLink = new ErrorLink(({ error, operation }) => { - if (CombinedGraphQLErrors.is(error)) { - error.errors.forEach(({ message, locations, path }) => - console.log( - `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}` - ) - ); - } else if (CombinedProtocolErrors.is(error)) { - error.errors.forEach(({ message, extensions }) => - console.log( - `[Protocol error]: Message: ${message}, Extensions: ${JSON.stringify( - extensions - )}` - ) - ); - } else { - console.error(`[Network error]: ${error}`); - } -}); +```ts +constructor( + errorHandler: ErrorLink.ErrorHandler +): ErrorLink ``` -This function is called after the GraphQL operation completes and execution is moving back _up_ your [link chain](./introduction/#handling-a-response). The function should not return a value unless you want to [retry the operation](../../data/error-handling#retrying-operations). - -For more information on the types of errors that might be encountered, see the guide on [error handling](../../data/error-handling). - -## Options +## Types -The function you provide to the `ErrorLink` constructor receives an object with the following fields: + | void; + } + + /** {@inheritDoc @apollo/client/link/error!ErrorLink.ErrorLinkDocumentationTypes.ErrorHandler:function(1)} */ export interface ErrorHandler { (options: ErrorHandlerOptions): Observable | void; } + /** + * The object provided to the `ErrorHandler` callback function. + */ export interface ErrorHandlerOptions { /** * The error that occurred during the operation execution. This can be a @@ -54,6 +70,50 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { return new ErrorLink(errorHandler); } +/** + * Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](../../data/error-handling/) + * occurs. You create an instance of `ErrorLink` with a function that's executed + * if an operation returns one or more errors: + * + * @remarks + * + * This link is used after the GraphQL operation completes and execution is + * moving back _up_ your [link chain](./introduction/#handling-a-response). The function should + * not return a value unless you want to [retry the operation](https://apollographql.com/docs/react/data/error-handling#retrying-operations). + * + * For more information on the types of errors that might be encountered, see the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). + * + * @example + * + * ```ts + * import { ErrorLink } from "@apollo/client/link/error"; + * import { + * CombinedGraphQLErrors, + * CombinedProtocolErrors, + * } from "@apollo/client/errors"; + * + * // Log any GraphQL errors, protocol errors, or network error that occurred + * const errorLink = new ErrorLink(({ error, operation }) => { + * if (CombinedGraphQLErrors.is(error)) { + * error.errors.forEach(({ message, locations, path }) => + * console.log( + * `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}` + * ) + * ); + * } else if (CombinedProtocolErrors.is(error)) { + * error.errors.forEach(({ message, extensions }) => + * console.log( + * `[Protocol error]: Message: ${message}, Extensions: ${JSON.stringify( + * extensions + * )}` + * ) + * ); + * } else { + * console.error(`[Network error]: ${error}`); + * } + * }); + * ``` + */ export class ErrorLink extends ApolloLink { constructor(errorHandler: ErrorLink.ErrorHandler) { super((operation, forward) => { From 6e108565d961a779c1ddd2b85e5c860cd2b7e2d8 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:36:00 -0600 Subject: [PATCH 17/53] Update title --- docs/source/api/link/apollo-link-error.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-error.mdx b/docs/source/api/link/apollo-link-error.mdx index 5f2eaa347e3..52593848bac 100644 --- a/docs/source/api/link/apollo-link-error.mdx +++ b/docs/source/api/link/apollo-link-error.mdx @@ -1,5 +1,5 @@ --- -title: Error Link +title: ErrorLink description: Handle and inspect errors in your GraphQL network stack. --- From b62778a3790cfa67bb71f8caa7bd846e3c8966c2 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:39:46 -0600 Subject: [PATCH 18/53] Add import for ClientAwarenessLink --- src/link/client-awareness/ClientAwarenessLink.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/link/client-awareness/ClientAwarenessLink.ts b/src/link/client-awareness/ClientAwarenessLink.ts index 498b258fbc1..46bff239e25 100644 --- a/src/link/client-awareness/ClientAwarenessLink.ts +++ b/src/link/client-awareness/ClientAwarenessLink.ts @@ -80,6 +80,8 @@ export declare namespace ClientAwarenessLink { * @example * * ```ts + * import { ClientAwarenessLink } from "@apollo/client/link/client-awareness"; + * * const link = new ClientAwarenessLink({ * clientAwareness: { * name: "My Client", From 1f639c4bff06cecf3e1b768482ef9f2371fab2e8 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:48:06 -0600 Subject: [PATCH 19/53] Add doc block for GraphQLWsLink --- .../api/link/apollo-link-subscriptions.mdx | 26 +++++++++---------- src/link/subscriptions/index.ts | 23 ++++++++++++++++ 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index 61121023d1c..d3379d7c716 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -1,11 +1,9 @@ --- -title: Subscriptions Link +title: GraphQLWsLink description: Execute subscriptions (or other operations) over WebSocket with the graphql-ws library --- -> We recommend reading [Apollo Link overview](./introduction/) before learning about individual links. - -The `GraphQLWsLink` is a [terminating link](./introduction/#the-terminating-link) that's used most commonly with GraphQL [subscriptions](../../data/subscriptions/) (which usually communicate over WebSocket), although you can send queries and mutations over WebSocket as well. + `GraphQLWsLink` requires the [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) library. Install it in your project like so: @@ -13,19 +11,19 @@ The `GraphQLWsLink` is a [terminating link](./introduction/#the-terminating-link npm install graphql-ws ``` -> **Note**: This link works with the newer `graphql-ws` library. If your server uses the older `subscriptions-transport-ws`, you should use the [`WebSocketLink` link from `@apollo/client/link/ws`](./apollo-link-ws) instead. + + +## Constructor signature -## Constructor +{/* TODO: Remove the custom signature once documentation supports rendering constructor functions */} ```js -import { GraphQLWsLink } from "@apollo/client/link/subscriptions"; -import { createClient } from "graphql-ws"; - -const link = new GraphQLWsLink( - createClient({ - url: "ws://localhost:3000/subscriptions", - }) -); +constructor( + client: Client +): GraphQLWsLink ``` ### Options diff --git a/src/link/subscriptions/index.ts b/src/link/subscriptions/index.ts index 95a0403f485..ded5ff93a9f 100644 --- a/src/link/subscriptions/index.ts +++ b/src/link/subscriptions/index.ts @@ -47,6 +47,29 @@ function isLikeErrorEvent(err: unknown): err is Event { return isNonNullObject(err) && err.target?.readyState === WebSocket.CLOSED; } +/** + * The `GraphQLWsLink` is a terminating link sends GraphQL operations over a + * WebSocket connection using the [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) library. It's used most + * commonly with GraphQL [subscriptions](https://apollographql.com/docs/react/data/subscriptions/), + * + * > [!NOTE] + * > This link works with the newer `graphql-ws` library. If your server uses + * > the older `subscriptions-transport-ws` library, you should use the + * > [`WebSocketLink`](https://apollographql.com/docs/react/api/link/apollo-link-ws) link from `@apollo/client/link/ws` instead. + * + * @example + * + * ```ts + * import { GraphQLWsLink } from "@apollo/client/link/subscriptions"; + * import { createClient } from "graphql-ws"; + * + * const link = new GraphQLWsLink( + * createClient({ + * url: "ws://localhost:3000/subscriptions", + * }) + * ); + * ``` + */ export class GraphQLWsLink extends ApolloLink { constructor(public readonly client: Client) { super(); From 90bd074ba8262371a5efd7af38a1a26c71f803f5 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:52:07 -0600 Subject: [PATCH 20/53] Tweak copy --- docs/source/api/link/apollo-link-client-awareness.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index ea41bed7679..45d52afaa01 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -10,7 +10,7 @@ description: API reference ## Configuring client awareness -Client awareness can be configured in various ways throughout the client. +Client awareness can be configured in various ways in Apollo Client. ### Configuring with Apollo Client From 8107854d52d8ac829da4897f040ac244649684c5 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Thu, 31 Jul 2025 17:52:16 -0600 Subject: [PATCH 21/53] Update api report --- .../api-report-link_batch-http.api.md | 21 +++++++++++++++++-- .api-reports/api-report-link_batch.api.md | 7 +++++++ .../api-report-link_client-awareness.api.md | 6 +++--- .api-reports/api-report-link_error.api.md | 7 +++++-- .api-reports/api-report-link_http.api.md | 8 +++---- .../api-report-link_subscriptions.api.md | 2 +- .api-reports/api-report.api.md | 16 +++++++------- 7 files changed, 46 insertions(+), 21 deletions(-) diff --git a/.api-reports/api-report-link_batch-http.api.md b/.api-reports/api-report-link_batch-http.api.md index e6311f4d5f9..18ccc6997c1 100644 --- a/.api-reports/api-report-link_batch-http.api.md +++ b/.api-reports/api-report-link_batch-http.api.md @@ -19,9 +19,26 @@ export class BaseBatchHttpLink extends ApolloLink { // @public (undocumented) export namespace BatchHttpLink { + export interface ContextOptions extends HttpLink.ContextOptions { + } // (undocumented) - export type ContextOptions = HttpLink.ContextOptions; - // (undocumented) + export namespace DocumentationTypes { + export interface Options { + batchDebounce?: boolean; + batchInterval?: number; + batchKey?: (operation: ApolloLink.Operation) => string; + batchMax?: number; + credentials?: string; + fetch?: typeof fetch; + fetchOptions?: any; + headers?: Record; + includeExtensions?: boolean; + includeUnusedVariables?: boolean; + preserveHeaderCase?: boolean; + print?: HttpLink.Printer; + uri?: string | HttpLink.UriFunction; + } + } export type Options = Pick & Omit; } diff --git a/.api-reports/api-report-link_batch.api.md b/.api-reports/api-report-link_batch.api.md index d7ba2b71bd2..def11c2ccf9 100644 --- a/.api-reports/api-report-link_batch.api.md +++ b/.api-reports/api-report-link_batch.api.md @@ -12,6 +12,13 @@ export namespace BatchLink { // (undocumented) export type BatchHandler = (operations: ApolloLink.Operation[], forward: ApolloLink.ForwardFunction[]) => Observable; // (undocumented) + export namespace DocumentationTypes { + // (undocumented) + export interface Options { + batchMax?: number; + } + } + // (undocumented) export interface Options { batchDebounce?: boolean; batchHandler?: BatchLink.BatchHandler; diff --git a/.api-reports/api-report-link_client-awareness.api.md b/.api-reports/api-report-link_client-awareness.api.md index e54102f6e5a..2d88f8eb6dd 100644 --- a/.api-reports/api-report-link_client-awareness.api.md +++ b/.api-reports/api-report-link_client-awareness.api.md @@ -20,12 +20,12 @@ export namespace ClientAwarenessLink { } // (undocumented) export interface Options { - clientAwareness?: ClientAwarenessOptions; - enhancedClientAwareness?: EnhancedClientAwarenessOptions; + clientAwareness?: ClientAwarenessLink.ClientAwarenessOptions; + enhancedClientAwareness?: ClientAwarenessLink.EnhancedClientAwarenessOptions; } } -// @public (undocumented) +// @public export class ClientAwarenessLink extends ApolloLink { constructor(constructorOptions?: ClientAwarenessLink.Options); } diff --git a/.api-reports/api-report-link_error.api.md b/.api-reports/api-report-link_error.api.md index 39f5baa2e14..2e9db05e90b 100644 --- a/.api-reports/api-report-link_error.api.md +++ b/.api-reports/api-report-link_error.api.md @@ -14,16 +14,19 @@ export namespace ErrorLink { // (undocumented) (options: ErrorHandlerOptions): Observable | void; } - // (undocumented) export interface ErrorHandlerOptions { error: ErrorLike; forward: ApolloLink.ForwardFunction; operation: ApolloLink.Operation; result?: ApolloLink.Result; } + // (undocumented) + export namespace ErrorLinkDocumentationTypes { + export function ErrorHandler(options: ErrorHandlerOptions): Observable | void; + } } -// @public (undocumented) +// @public export class ErrorLink extends ApolloLink { constructor(errorHandler: ErrorLink.ErrorHandler); } diff --git a/.api-reports/api-report-link_http.api.md b/.api-reports/api-report-link_http.api.md index eb9c5cd446d..3adfbfcbe63 100644 --- a/.api-reports/api-report-link_http.api.md +++ b/.api-reports/api-report-link_http.api.md @@ -74,7 +74,7 @@ export namespace HttpLink { fetchOptions?: RequestInit; headers?: Record; http?: HttpLink.HttpOptions; - uri?: string | UriFunction; + uri?: string | HttpLink.UriFunction; } export interface HttpOptions { accept?: string[]; @@ -90,8 +90,8 @@ export namespace HttpLink { includeExtensions?: boolean; includeUnusedVariables?: boolean; preserveHeaderCase?: boolean; - print?: Printer; - uri?: string | UriFunction; + print?: HttpLink.Printer; + uri?: string | HttpLink.UriFunction; useGETForQueries?: boolean; } // (undocumented) @@ -100,7 +100,7 @@ export namespace HttpLink { export type UriFunction = (operation: ApolloLink.Operation) => string; } -// @public (undocumented) +// @public export class HttpLink extends ApolloLink { constructor(options?: HttpLink.Options & ClientAwarenessLink.Options); } diff --git a/.api-reports/api-report-link_subscriptions.api.md b/.api-reports/api-report-link_subscriptions.api.md index 71b66e06114..cf2076f956e 100644 --- a/.api-reports/api-report-link_subscriptions.api.md +++ b/.api-reports/api-report-link_subscriptions.api.md @@ -8,7 +8,7 @@ import { ApolloLink } from '@apollo/client/link'; import type { Client } from 'graphql-ws'; import { Observable } from 'rxjs'; -// @public (undocumented) +// @public export class GraphQLWsLink extends ApolloLink { constructor(client: Client); // (undocumented) diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md index bd5b69aef54..750022ca2a8 100644 --- a/.api-reports/api-report.api.md +++ b/.api-reports/api-report.api.md @@ -667,14 +667,12 @@ namespace ClientAwarenessLink { } // (undocumented) interface Options { - // Warning: (ae-forgotten-export) The symbol "ClientAwarenessLink" needs to be exported by the entry point index.d.ts - clientAwareness?: ClientAwarenessOptions; - // Warning: (ae-forgotten-export) The symbol "ClientAwarenessLink" needs to be exported by the entry point index.d.ts - enhancedClientAwareness?: EnhancedClientAwarenessOptions; + clientAwareness?: ClientAwarenessLink.ClientAwarenessOptions; + enhancedClientAwareness?: ClientAwarenessLink.EnhancedClientAwarenessOptions; } } -// @public (undocumented) +// @public class ClientAwarenessLink extends ApolloLink { constructor(constructorOptions?: ClientAwarenessLink.Options); } @@ -1354,7 +1352,7 @@ export namespace HttpLink { fetchOptions?: RequestInit; headers?: Record; http?: HttpLink.HttpOptions; - uri?: string | UriFunction; + uri?: string | HttpLink.UriFunction; } export interface HttpOptions { accept?: string[]; @@ -1370,8 +1368,8 @@ export namespace HttpLink { includeExtensions?: boolean; includeUnusedVariables?: boolean; preserveHeaderCase?: boolean; - print?: Printer; - uri?: string | UriFunction; + print?: HttpLink.Printer; + uri?: string | HttpLink.UriFunction; useGETForQueries?: boolean; } // Warning: (ae-forgotten-export) The symbol "print_2" needs to be exported by the entry point index.d.ts @@ -1382,7 +1380,7 @@ export namespace HttpLink { export type UriFunction = (operation: ApolloLink.Operation) => string; } -// @public (undocumented) +// @public export class HttpLink extends ApolloLink { constructor(options?: HttpLink.Options & ClientAwarenessLink.Options); } From b2e925ee6d25e7f24ce8cb2604120b95de2a6781 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 16:08:20 +0200 Subject: [PATCH 22/53] reorder `ApolloLink` static properties * from/split are used most of the time * execute/empty less * concat is deprecated --- docs/source/api/link/apollo-link.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/api/link/apollo-link.mdx b/docs/source/api/link/apollo-link.mdx index b70e450a2fe..753e3f79195 100644 --- a/docs/source/api/link/apollo-link.mdx +++ b/docs/source/api/link/apollo-link.mdx @@ -13,16 +13,16 @@ description: API reference ## Static methods @@ -34,16 +34,16 @@ description: API reference /> From 4ee31a5baafef3fb8bc5c9721c495f1beb5f200e Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 16:40:30 +0200 Subject: [PATCH 23/53] restructure shared options between `HttpLink`, `BatchLink` and `BatchHttpLink` --- .../api/link/apollo-link-batch-http.mdx | 3 +- src/link/batch-http/batchHttpLink.ts | 59 +---- src/link/batch/batchLink.ts | 47 ++-- src/link/http/HttpLink.ts | 231 +++++++++--------- 4 files changed, 152 insertions(+), 188 deletions(-) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index d9246da526f..67658429157 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -39,9 +39,10 @@ See [Customizing `fetch`](apollo-link-http/#customizing-fetch). ## Types string; - - /** {@inheritDoc @apollo/client/link/batch!BatchLink.DocumentationTypes.Options#batchMax:member {"defaultValue": 10}} */ - batchMax?: number; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#uri:member} */ - uri?: string | HttpLink.UriFunction; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeExtensions:member} */ - includeExtensions?: boolean; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetch:member} */ - fetch?: typeof fetch; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#headers:member} */ - headers?: Record; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ - preserveHeaderCase?: boolean; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ - credentials?: string; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetchOptions:member} */ - fetchOptions?: any; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeUnusedVariables:member} */ - includeUnusedVariables?: boolean; - - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#print:member} */ - print?: HttpLink.Printer; - } + /** + * Options provided to the `BatchHttpLink` constructor. + */ + export interface Options + extends BatchLink.Shared.Options, + HttpLink.Shared.Options { + /** {@inheritDoc @apollo/client/link/batch!BatchLink.Shared.Options#batchMax:member {"defaultValue": 10}} */ + batchMax?: number; } - /** {@inheritDoc @apollo/client/link/batch-http!BatchHttpLink.DocumentationTypes.Options:interface} */ - export type Options = Pick< - BatchLink.Options, - "batchMax" | "batchDebounce" | "batchInterval" | "batchKey" - > & - Omit; - /** * Options passed to `BatchHttpLink` through [request context](https://apollographql.com/docs/react/api/link/introduction#managing-context). Previous * non-terminating links in the link chain also can set these values to diff --git a/src/link/batch/batchLink.ts b/src/link/batch/batchLink.ts index 9ffdbf3795d..a9d7d2d4634 100644 --- a/src/link/batch/batchLink.ts +++ b/src/link/batch/batchLink.ts @@ -6,14 +6,34 @@ import { ApolloLink } from "@apollo/client/link"; import { OperationBatcher } from "./batching.js"; export declare namespace BatchLink { - export namespace DocumentationTypes { + export namespace Shared { + /** These options are shared between `BatchLink` and `BatchHttpLink` */ interface Options { + /** + * The interval at which to batch, in milliseconds. + * + * @defaultValue 10 + */ + batchInterval?: number; + + /** + * "batchInterval" is a throttling behavior by default, if you instead wish + * to debounce outbound requests, set "batchDebounce" to true. More useful + * for mutations than queries. + */ + batchDebounce?: boolean; + /** * The maximum number of operations to include in a single batch. * * @defaultValue {{defaultValue}} */ batchMax?: number; + + /** + * Creates the key for a batch + */ + batchKey?: (operation: ApolloLink.Operation) => string; } } @@ -22,33 +42,14 @@ export declare namespace BatchLink { forward: ApolloLink.ForwardFunction[] ) => Observable; - export interface Options { - /** - * The interval at which to batch, in milliseconds. - * - * @defaultValue 10 - */ - batchInterval?: number; - - /** - * "batchInterval" is a throttling behavior by default, if you instead wish - * to debounce outbound requests, set "batchDebounce" to true. More useful - * for mutations than queries. - */ - batchDebounce?: boolean; - - /** {@inheritDoc @apollo/client/link/batch!BatchLink.DocumentationTypes.Options#batchMax:member {"defaultValue": 0}} */ - batchMax?: number; - + export interface Options extends Shared.Options { /** * The handler that should execute a batch of operations. */ batchHandler?: BatchLink.BatchHandler; - /** - * Creates the key for a batch - */ - batchKey?: (operation: ApolloLink.Operation) => string; + /** {@inheritDoc @apollo/client/link/batch!BatchLink.Shared.Options#batchMax:member {"defaultValue": 0}} */ + batchMax?: number; } } diff --git a/src/link/http/HttpLink.ts b/src/link/http/HttpLink.ts index 774a2e4b570..2ac3504751f 100644 --- a/src/link/http/HttpLink.ts +++ b/src/link/http/HttpLink.ts @@ -17,16 +17,16 @@ export declare namespace HttpLink { * > If a value is provided to both, the value in `context` takes precedence. */ interface ContextOptions { - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#uri:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#uri:member} */ uri?: string | HttpLink.UriFunction; - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#headers:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#headers:member} */ headers?: Record; - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#credentials:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#credentials:member} */ credentials?: RequestCredentials; - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#fetchOptions:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#fetchOptions:member} */ fetchOptions?: RequestInit; /** @@ -41,7 +41,7 @@ export declare namespace HttpLink { * context. */ export interface HttpOptions { - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#includeExtensions:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#includeExtensions:member} */ includeExtensions?: boolean; /** @@ -52,7 +52,7 @@ export declare namespace HttpLink { */ includeQuery?: boolean; - /** {@inheritDoc @apollo/client/link/http!HttpLink.Options#preserveHeaderCase:member} */ + /** {@inheritDoc @apollo/client/link/http!HttpLink.Shared.Options#preserveHeaderCase:member} */ preserveHeaderCase?: boolean; /** @@ -68,6 +68,117 @@ export declare namespace HttpLink { accept?: string[]; } + export namespace Shared { + /** These options are shared between `HttpLink` and `BatchHttpLink` */ + export interface Options { + /** + * The URL of the GraphQL endpoint to send requests to. Can also be a + * function that accepts an `ApolloLink.Operation` object and returns the + * string URL to use for that operation. + * + * @defaultValue "/graphql" + */ + uri?: string | HttpLink.UriFunction; + + /** + * If `true`, includes the `extensions` field in operations sent to your + * GraphQL endpoint. + * + * @defaultValue true + */ + includeExtensions?: boolean; + + /** + * A function to use instead of calling the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) directly + * when sending HTTP requests to your GraphQL endpoint. The function must + * conform to the signature of `fetch`. + * + * By default, the Fetch API is used unless it isn't available in your + * runtime environment. + * + * See [Customizing `fetch`](https://apollographql.com/docs/react/api/link/introduction#customizing-fetch). + */ + fetch?: typeof fetch; + + /** + * An object representing headers to include in every HTTP request. + * + * @example + * + * ```json + * { + * "Authorization": "Bearer 1234" + * } + * ``` + */ + headers?: Record; + + /** + * If `true`, header names won't be automatically normalized to lowercase. + * This allows for non-http-spec-compliant servers that might expect + * capitalized header names. + * + * @defaultValue false + */ + preserveHeaderCase?: boolean; + + /** + * The credentials policy to use for each `fetch` call. + */ + credentials?: RequestCredentials; + + /** + * Any overrides of the fetch options argument to pass to the fetch call. + * + * An object containing options to use for each call to `fetch`. If a + * particular option is not included in this object, the default value of + * that option is used. + * + * > [!NOTE] + * > If you set `fetchOptions.method` to `GET`, `HttpLink` follows [standard + * > GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). + * + * See [available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) + */ + fetchOptions?: RequestInit; + + /** + * If `true`, unused variables from the operation will not be stripped from + * the request and will instead be sent to the GraphQL endpoint. + * + * @remarks + * Unused variables are likely to trigger server-side validation errors, + * per https://spec.graphql.org/draft/#sec-All-Variables-Used. + * `includeUnusedVariables` can be useful if your server deviates + * from the GraphQL specification by not strictly enforcing that rule. + * + * @defaultValue false + */ + includeUnusedVariables?: boolean; + /** + * A function to use when transforming a GraphQL document into a string. It + * accepts an `ASTNode` (typically a `DocumentNode`) and the original `print` + * function as arguments, and is expected to return a string. This option + * enables you to, for example, use `stripIgnoredCharacters` to remove + * whitespace from queries. + * + * By default the [GraphQL `print` function](https://graphql.org/graphql-js/language/#print) is used. + * + * @example + * + * ```ts + * import { stripIgnoredCharacters } from "graphql"; + * + * const httpLink = new HttpLink({ + * uri: "/graphql", + * print: (ast, originalPrint) => stripIgnoredCharacters(originalPrint(ast)), + * }); + * ``` + */ + print?: HttpLink.Printer; + } + } + /** * Options provided to the `HttpLink` constructor. * @@ -77,78 +188,7 @@ export declare namespace HttpLink { * > these options as default values that are used when the request context * > does not override the value. */ - export interface Options { - /** - * The URL of the GraphQL endpoint to send requests to. Can also be a - * function that accepts an `ApolloLink.Operation` object and returns the - * string URL to use for that operation. - * - * @defaultValue "/graphql" - */ - uri?: string | HttpLink.UriFunction; - - /** - * If `true`, includes the `extensions` field in operations sent to your - * GraphQL endpoint. - * - * @defaultValue true - */ - includeExtensions?: boolean; - - /** - * A function to use instead of calling the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) directly - * when sending HTTP requests to your GraphQL endpoint. The function must - * conform to the signature of `fetch`. - * - * By default, the Fetch API is used unless it isn't available in your - * runtime environment. - * - * See [Customizing `fetch`](https://apollographql.com/docs/react/api/link/introduction#customizing-fetch). - */ - fetch?: typeof fetch; - - /** - * An object representing headers to include in every HTTP request. - * - * @example - * - * ```json - * { - * "Authorization": "Bearer 1234" - * } - * ``` - */ - headers?: Record; - - /** - * If `true`, header names won't be automatically normalized to lowercase. - * This allows for non-http-spec-compliant servers that might expect - * capitalized header names. - * - * @defaultValue false - */ - preserveHeaderCase?: boolean; - - /** - * The credentials policy to use for each `fetch` call. - */ - credentials?: RequestCredentials; - - /** - * Any overrides of the fetch options argument to pass to the fetch call. - * - * An object containing options to use for each call to `fetch`. If a - * particular option is not included in this object, the default value of - * that option is used. - * - * > [!NOTE] - * > If you set `fetchOptions.method` to `GET`, `HttpLink` follows [standard - * > GraphQL HTTP GET encoding](http://graphql.org/learn/serving-over-http/#get-request). - * - * See [available options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) - */ - fetchOptions?: RequestInit; - + interface Options extends Shared.Options { /** * If `true`, the link uses an HTTP `GET` request when sending query * operations to your GraphQL endpoint. Mutation operations continue to use @@ -158,41 +198,6 @@ export declare namespace HttpLink { * @defaultValue false */ useGETForQueries?: boolean; - - /** - * If `true`, unused variables from the operation will not be stripped from - * the request and will instead be sent to the GraphQL endpoint. - * - * @remarks - * Unused variables are likely to trigger server-side validation errors, - * per https://spec.graphql.org/draft/#sec-All-Variables-Used. - * `includeUnusedVariables` can be useful if your server deviates - * from the GraphQL specification by not strictly enforcing that rule. - * - * @defaultValue false - */ - includeUnusedVariables?: boolean; - /** - * A function to use when transforming a GraphQL document into a string. It - * accepts an `ASTNode` (typically a `DocumentNode`) and the original `print` - * function as arguments, and is expected to return a string. This option - * enables you to, for example, use `stripIgnoredCharacters` to remove - * whitespace from queries. - * - * By default the [GraphQL `print` function](https://graphql.org/graphql-js/language/#print) is used. - * - * @example - * - * ```ts - * import { stripIgnoredCharacters } from "graphql"; - * - * const httpLink = new HttpLink({ - * uri: "/graphql", - * print: (ast, originalPrint) => stripIgnoredCharacters(originalPrint(ast)), - * }); - * ``` - */ - print?: HttpLink.Printer; } interface Body { From 63047d6e184af9f013c87b99c52e545a15070e49 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 16:44:43 +0200 Subject: [PATCH 24/53] update type of `HttpLink.Options.fetchOptions` to `RequestInit` --- .changeset/plenty-flies-relate.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/plenty-flies-relate.md diff --git a/.changeset/plenty-flies-relate.md b/.changeset/plenty-flies-relate.md new file mode 100644 index 00000000000..6dc22b133e1 --- /dev/null +++ b/.changeset/plenty-flies-relate.md @@ -0,0 +1,5 @@ +--- +"@apollo/client": patch +--- + +update type of `HttpLink.Options.fetchOptions` to `RequestInit` From 2e72e4c2983fb372b2bac1c974535c1acbf9b704 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 16:48:13 +0200 Subject: [PATCH 25/53] fix typo --- src/link/client-awareness/ClientAwarenessLink.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/client-awareness/ClientAwarenessLink.ts b/src/link/client-awareness/ClientAwarenessLink.ts index 46bff239e25..e5239cc7874 100644 --- a/src/link/client-awareness/ClientAwarenessLink.ts +++ b/src/link/client-awareness/ClientAwarenessLink.ts @@ -67,7 +67,7 @@ export declare namespace ClientAwarenessLink { * @remarks * * Client awareness adds identifying information about the client to HTTP - * requests for use with metrics reporting tools, such as the [Apollo GraphOS](https://apollographql.com/docs/graphos/platform). + * requests for use with metrics reporting tools, such as [Apollo GraphOS](https://apollographql.com/docs/graphos/platform). * It is included in the functionality of [`HttpLink`](https://apollographql.com/docs/react/api/link/apollo-link-http) by default. * * Client awareness distinguishes between user-provided client awareness From f8124b3b9fa35a13841aff65de383288fec59447 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 16:53:07 +0200 Subject: [PATCH 26/53] type fixes --- config/helpers.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/config/helpers.ts b/config/helpers.ts index e8e3003cac0..12fef37120a 100644 --- a/config/helpers.ts +++ b/config/helpers.ts @@ -248,6 +248,7 @@ export function patchApiExtractorInternals() { for (const excerpt of item.excerptTokens) { const stringified = excerpt.canonicalReference?.toString(); if (stringified?.startsWith("@apollo/client!entrypoint_")) { + // @ts-ignore excerpt["_canonicalReference"] = DeclarationReference.parse( stringified.replace( /(@apollo\/client!entrypoint_[^.]+)[.:]/, From abc0d3a3f7bb827935878054901e54c013223ec6 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Fri, 1 Aug 2025 18:11:12 +0200 Subject: [PATCH 27/53] fix typo --- src/link/error/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index ffc175c60df..8dbebabd922 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -12,7 +12,7 @@ import { ApolloLink } from "@apollo/client/link"; export declare namespace ErrorLink { // Using a different namespace name to avoid clash with - // `ApolloLink.DocumentaitonTypes` + // `ApolloLink.DocumentationTypes` export namespace ErrorLinkDocumentationTypes { /** * Callback that is called by `ErrorLink` when an error occurs from a From 83ac42b24f8f5efab0e415a6a4a0cf55eead2c80 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 09:40:06 -0600 Subject: [PATCH 28/53] Remove handling errors section --- docs/source/api/link/apollo-link-http.mdx | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 7c679d87586..05962bed834 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -18,22 +18,6 @@ constructor( ): HttpLink ``` -## Handling errors - -`HttpLink` distinguishes between client errors, server errors, and GraphQL errors. You can add the [`ErrorLink`](./apollo-link-error) to your link chain to handle these errors via a [callback](./apollo-link-error#options). - -The following types of errors can occur: - -| Error | Description | Callback | Error Type | -| -------------- | ---------------------------------------------------------------------------------------------------------------------- | :------: | ---------------------------------------------------------- | -| Client Parse | The request body is not serializable, for example due to a circular reference. | `error` | `ClientParseError` | -| Server Parse | The server's response cannot be parsed ([response.json()](https://developer.mozilla.org/en-US/docs/Web/API/Body/json)) | `error` | [`ServerParseError`](../errors/ServerParseError) | -| Server Network | The server responded with a non-2xx HTTP code. | `error` | [`ServerError`](../errors/ServerError) | -| Server Data | The server's response didn't contain `data` or `errors`. | `error` | [`ServerError`](../errors/ServerError) | -| GraphQL Error | Resolving the GraphQL operation resulted in at least one error, which is present in the `errors` field. | `next` | [`CombinedGraphQLErrors`](../errors/CombinedGraphQLErrors) | - -See the documentation on [Identifying error types](../../data/error-handling#identifying-error-types) to learn how to distinguish between the different error types. - ## Operation results After your GraphQL endpoint (successfully) responds with the result of the sent operation, `HttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. From cd4467abd2095dfce3628c85a2805a34f42b68f7 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 09:52:18 -0600 Subject: [PATCH 29/53] Update subscription links in sidebar --- docs/source/_sidebar.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index 18cbd6b8341..aeb41dd8df0 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -195,7 +195,7 @@ items: href: ./api/link/apollo-link-client-awareness - label: ErrorLink href: ./api/link/apollo-link-error - - label: GraphQLWsLink (newer protocol) + - label: GraphQLWsLink href: ./api/link/apollo-link-subscriptions - label: HttpLink href: ./api/link/apollo-link-http @@ -211,7 +211,7 @@ items: href: ./api/link/apollo-link-schema - label: SetContextLink href: ./api/link/apollo-link-context - - label: WebSocketLink (older protocol) + - label: WebSocketLink (deprecated) href: ./api/link/apollo-link-ws - label: Community links href: ./api/link/community-links From 62cc51846b70a0f46865d86dd3b937e4430aad86 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 09:52:32 -0600 Subject: [PATCH 30/53] Remove rest link from documentation --- docs/source/_sidebar.yaml | 2 - docs/source/api/link/apollo-link-rest.mdx | 708 ---------------------- 2 files changed, 710 deletions(-) delete mode 100644 docs/source/api/link/apollo-link-rest.mdx diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index aeb41dd8df0..2957511b0f5 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -203,8 +203,6 @@ items: href: ./api/link/persisted-queries - label: RemoveTypenameFromVariablesLink href: ./api/link/apollo-link-remove-typename - - label: RestLink - href: ./api/link/apollo-link-rest - label: RetryLink href: ./api/link/apollo-link-retry - label: SchemaLink diff --git a/docs/source/api/link/apollo-link-rest.mdx b/docs/source/api/link/apollo-link-rest.mdx deleted file mode 100644 index 8f5c317dddb..00000000000 --- a/docs/source/api/link/apollo-link-rest.mdx +++ /dev/null @@ -1,708 +0,0 @@ ---- -title: REST Link -description: Call REST APIs inside your GraphQL queries. ---- - -## Overview - -> The [Apollo Link Rest](https://github.com/apollographql/apollo-link-rest) library is maintained by Apollo community members and not an Apollo GraphQL maintained library. - -Calling REST APIs from a GraphQL client opens the benefits of GraphQL for more people, whether: - -- You are in a front-end developer team that wants to try GraphQL without asking for the backend team to implement a GraphQL server. -- You have no access to change the backend because it's an existing set of APIs, potentially managed by a 3rd party. -- You have an existing codebase, but you're looking to evaluate whether GraphQL can work for your needs. -- You have a large codebase, and the GraphQL migration is happening on the backend, but you want to use GraphQL _now_ without waiting! - -With `apollo-link-rest`, you can call your endpoints inside your GraphQL queries and have all your data managed by Apollo Client. `apollo-link-rest` is suitable for just dipping your toes in the water, or doing a full-steam ahead integration, and then later on migrating to a backend-driven GraphQL experience. - -> For more advanced or complex back-ends, you may want to consider using [`@apollo/server`](/apollo-server/). - -## Quick start - -To get started, first install Apollo Client and any `peerDependencies` we need: - -```bash -npm install --save @apollo/client apollo-link-rest graphql qs -``` - -After this, you're ready to setup the Apollo Client instance: - -```js -import { ApolloClient, InMemoryCache } from "@apollo/client"; -import { RestLink } from "apollo-link-rest"; - -// Set `RestLink` with your endpoint -const restLink = new RestLink({ uri: "https://swapi.dev/api/" }); - -// Setup your client -const client = new ApolloClient({ - cache: new InMemoryCache(), - link: restLink, -}); -``` - -Now it's time to write our first query: - -```js -import { gql } from "@apollo/client"; - -const query = gql` - query Luke { - person @rest(type: "Person", path: "people/1/") { - name - } - } -`; -``` - -You can then fetch your data using Apollo Client: - -```js -// Invoke the query and log the person's name -client.query({ query }).then((response) => { - console.log(response.data.person.name); -}); -``` - -## Options - -The `RestLink` constructor accepts an options object that can be used to customize the behavior of the link. Supported options are outlined below: - -| Option | Type | Description | -| ------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `uri` | `string` | The URI key is a string endpoint/domain for your requests to hit (_optional_ when `endpoints` provides a default) | -| `endpoints: /map-of-endpoints/` | `any` | _optional_ A map of endpoints. If you use this, you need to provide `endpoint` to the `@rest(...)` directives. | -| `customFetch?` | `any` | _optional_ A custom `fetch` to handle `REST` calls | -| `headers?` | `Headers` | _optional_ An object representing values to be sent as headers with all requests. [Documented here](https://developer.mozilla.org/en-US/docs/Web/API/Request/headers) | -| `credentials?` | `string` | _optional_ A string representing the credentials policy the fetch call should operate with. [Document here](https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials) | -| `fieldNameNormalizer?: /function/` | `any` | _optional_ A function that takes the response field name and converts it into a GraphQL compliant name. This is useful if your `REST` API returns fields that aren't representable as GraphQL, or if you want to convert between `snake_case` field names in JSON to `camelCase` keyed fields. | -| `fieldNameDenormalizer?: /function/` | `any` | _optional_ A function that takes a GraphQL-compliant field name and converts it back into an endpoint-specific name. | -| `typePatcher: /map-of-functions/` | `any` | _optional_ A structure to allow you to specify the `__typename` when you have nested objects in your REST response. | -| `defaultSerializer /function/` | `any` | _optional_ A function that will be used by the `RestLink` as the default serializer when no `bodySerializer` is defined for a `@rest` call. The function will also be passed the current `Header` set, which can be updated before the request is sent to `fetch`. Default method uses `JSON.stringify` and sets the `Content-Type` to `application/json`. | -| `bodySerializers: /map-of-functions/` | `any` | _optional_ Structure to allow the definition of alternative serializers, which can then be specified by their key. | -| `responseTransformer?: /function/` | `any` | _optional_ Apollo expects a record response to return a root object, and a collection of records response to return an array of objects. Use this function to structure the response into the format Apollo expects if your response data is structured differently. | - -### Multiple endpoints - -If you want to be able to use multiple endpoints, you can create your link like: - -```js -const link = new RestLink({ - endpoints: { v1: "api.com/v1", v2: "api.com/v2" }, -}); -``` - -You then need to specify the endpoint you want to use, in the rest directive: - -```js -const postTitleQuery1 = gql` - query PostTitle { - post @rest(type: "Post", path: "/post", endpoint: "v1") { - id - title - } - } -`; -const postTitleQuery2 = gql` - query PostTitle { - post @rest(type: "[Tag]", path: "/tags", endpoint: "v2") { - id - tags - } - } -`; -``` - -If you have a default endpoint, you can create your link like: - -```js -const link = new RestLink({ - endpoints: { github: "github.com" }, - uri: "api.com", -}); -``` - -If you don't specify an endpoint in your query, the default endpoint (the one you specify in the `uri` option) will be used. - -### Typename patching - -When sending a query like: - -```graphql -query MyQuery { - planets @rest(type: "PlanetPayload", path: "planets/") { - count - next - results { - name - } - } -} -``` - -the outer response object (`data.planets`) gets its `__typename: "PlanetPayload"` from the [`@rest(...)` directive's `type` parameter](#rest-directive). You, however, need to have a way to set the typename of `PlanetPayload.results`. - -One way you can do this is by providing a `typePatcher`: - -```typescript -const restLink = new RestLink({ - uri: "/api", - typePatcher: { - PlanetPayload: ( - data: any, - outerType: string, - patchDeeper: RestLink.FunctionalTypePatcher - ): any => { - if (data.results != null) { - data.results = data.results.map((planet) => ({ - __typename: "Planet", - ...planet, - })); - } - return data; - }, - // ... other nested type patchers - }, -}); -``` - -If you have a very lightweight REST integration, you can use the `@type(name: ...)` directive. - -```graphql -query MyQuery { - planets @rest(type: "PlanetPayload", path: "planets/") { - count - next - results @type(name: "Planet") { - name - } - } -} -``` - -This is appropriate if you have a small list of nested objects. The cost of this strategy is that every query that deals with these objects needs to also include `@type(name: ...)`, which means this approach can be quite verbose and error prone. - -You can also use both of these approaches in tandem: - -```graphql -query MyQuery { - planets @rest(type: "PlanetPayload", path: "planets/") { - count - next - results @type(name: "Results") { - name - } - typePatchedResults { - name - } - } -} -``` - -```typescript -const restLink = new RestLink({ - uri: '/api', - typePatcher: { - PlanetPayload: ( - data: any, - outerType: string, - patchDeeper: RestLink.FunctionalTypePatcher, - ): any => { - if (data.typePatchedResults != null) { - data.typePatchedResults = - data.typePatchedResults.map(planet => { __typename: "Planet", ...planet }); - } - return data; - }, - // ... other nested type patchers - }, -}) -``` - -#### Warning - -It's important to note that at the moment the `typePatcher` is not able to act on nested objects within annotated `@type` objects. For instance, `failingResults` will not be patched if you define it on the `typePatcher`: - -```graphql -query MyQuery { - planets @rest(type: "PlanetPayload", path: "planets/") { - count - next - results @type(name: "Planet") { - name - failingResults { - name - } - } - typePatchedResults { - name - } - } -} -``` - -To make this work you should try to pick one strategy, and stick with it -- either all `typePatcher` or all `@type` directives. - -### Response transforming - -By default, Apollo expects an object at the root for record requests, and an array of objects at the root for collection requests. For example, if fetching a user by ID (`/users/1`), the following response is expected. - -```json -{ - "id": 1, - "name": "Apollo" -} -``` - -And when fetching for a list of users (`/users`), the following response is expected. - -```json -[ - { - "id": 1, - "name": "Apollo" - }, - { - "id": 2, - "name": "Starman" - } -] -``` - -If the structure of your API responses differs than what Apollo expects, you can define a `responseTransformer` in the client. This function receives the response object as the 1st argument, and the current `typeName` as the 2nd argument. It should return a `Promise` as it will be responsible for reading the response stream by calling one of `json()`, `text()` etc. - -For example, if the record is not at the root level: - -```json -{ - "meta": {}, - "data": [ - { - "id": 1, - "name": "Apollo" - }, - { - "id": 2, - "name": "Starman" - } - ] -} -``` - -The following transformer could be used to support it: - -```js -const link = new RestLink({ - uri: "/api", - responseTransformer: async (response) => - response.json().then(({ data }) => data), -}); -``` - -Plaintext, XML, or otherwise-encoded responses can be handled by manually parsing and converting them to JSON (using the previously described format that Apollo expects): - -```js -const link = new RestLink({ - uri: "/xmlApi", - responseTransformer: async (response) => - response.text().then((text) => parseXmlResponseToJson(text)), -}); -``` - -### Custom endpoint responses - -The client level `responseTransformer` applies for all responses, across all URIs and endpoints. If you need a custom `responseTransformer` per endpoint, you can define an object of options for that specific endpoint. - -```js -const link = new RestLink({ - endpoints: { - v1: { - uri: "/v1", - responseTransformer: async (response) => response.data, - }, - v2: { - uri: "/v2", - responseTransformer: async (response, typeName) => response[typeName], - }, - }, -}); -``` - -> When using the object form, the `uri` field is required. - -### Custom Fetch - -By default, Apollo uses the browsers `fetch` method to handle `REST` requests to your domain/endpoint. The `customFetch` option allows you to specify _your own_ request handler by defining a function that returns a `Promise` with a fetch-response-like object: - -```js -const link = new RestLink({ - endpoints: "/api", - customFetch: (uri, options) => - new Promise((resolve, reject) => { - // Your own (asynchronous) request handler - resolve(responseObject); - }), -}); -``` - -To resolve your GraphQL queries quickly, Apollo will issue requests to relevant endpoints as soon as possible. This is generally ok, but can lead to large numbers of `REST` requests to be fired at once; especially for deeply nested queries [(see `@export` directive)](#export-directive). - -> Some endpoints (like public APIs) might enforce _rate limits_, leading to failed responses and unresolved queries in such cases. - -By example, `customFetch` is a good place to manage your apps fetch operations. The following implementation makes sure to only issue 2 requests at a time (concurrency) while waiting at least 500ms until the next batch of requests is fired. - -```js -import pThrottle from "p-throttle"; - -const link = new RestLink({ - endpoints: "/api", - customFetch: pThrottle( - (uri, config) => { - return fetch(uri, config); - }, - 2, // Max. concurrent Requests - 500 // Min. delay between calls - ), -}); -``` - -> Since Apollo issues `Promise` based requests, we can resolve them as we see fit. This example uses [`pThrottle`](https://github.com/sindresorhus/p-throttle); part of the popular [promise-fun](https://github.com/sindresorhus/promise-fun) collection. - -### Complete options - -Here is one way you might customize `RestLink`: - -```js -import fetch from 'cross-fetch'; -import * as camelCase from 'camelcase'; -import * as snake_case from 'snake-case'; - -const link = new RestLink({ - endpoints: { github: 'github.com' }, - uri: 'api.com', - customFetch: fetch, - headers: { - "Content-Type": "application/json" - }, - credentials: "same-origin", - fieldNameNormalizer: (key: string) => camelCase(key), - fieldNameDenormalizer: (key: string) => snake_case(key), - typePatcher: { - Post: ()=> { - bodySnippet... - } - }, - defaultSerializer: (data: any, headers: Headers) => { - const formData = new FormData(); - for (let key in data) { - formData.append(key, data[key]); - } - headers.set("Content-Type", "x-www-form-encoded") - return {data: formData, headers}; - } -}); -``` - -## Link Context - -`RestLink` has an [interface `LinkChainContext`](https://github.com/apollographql/apollo-link-rest/blob/1824da47d5db77a2259f770d9c9dd60054c4bb1c/src/restLink.ts#L557-L570) which it uses as the structure of things that it will look for in the `context`, as it decides how to fulfill a specific `RestLink` request. (Please see the [`@apollo/client/link/context`](./apollo-link-context) page for a discussion of why you might want this). - -| Option | Type | Description | -| --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `credentials?` | `RequestCredentials` | Overrides the `RestLink`-level setting for `credentials`. [Values documented here](https://developer.mozilla.org/en-US/docs/Web/API/Request/headers) | -| `headers?` | `Headers` | Additional headers provided in this `context-link` [Values documented here](https://developer.mozilla.org/en-US/docs/Web/API/Request/headers) | -| `headersToOverride?` | `string[]` | If you provide this array, we will merge the headers you provide in this link, by replacing any matching headers that exist in the root `RestLink` configuration. Alternatively you can use `headersMergePolicy` for more fine-grained customization of the merging behavior. | -| `headersMergePolicy?` | `RestLink.HeadersMergePolicy` | This is a function that decide how the headers returned in this `contextLink` are merged with headers defined at the `RestLink`-level. If you don't provide this, the headers will be simply appended. To use this option, you can provide your own function that decides how to process the headers. [Code references](https://github.com/apollographql/apollo-link-rest/blob/8e57cabb5344209d9cfa391c1614fe8880efa5d9/src/restLink.ts#L462-L510) | -| `restResponses?` | `Response[]` | This will be populated after the operation has completed with the [Responses](https://developer.mozilla.org/en-US/docs/Web/API/Response) of every REST url fetched during the operation. This can be useful if you need to access the response headers to grab an authorization token for example. | - -### Example - -`RestLink` uses the `headers` field on the [`@apollo/client/link/context`](./apollo-link-context) so you can compose other links that provide additional & dynamic headers to a given query. - -Here is one way to add request `headers` to the context and retrieve the response headers of the operation: - -```js -const authRestLink = new ApolloLink((operation, forward) => { - operation.setContext(({ headers }) => { - const token = localStorage.getItem("token"); - return { - headers: { - ...headers, - Accept: "application/json", - Authorization: token, - }, - }; - }); - return forward(operation).map((result) => { - const { restResponses } = operation.getContext(); - const authTokenResponse = restResponses.find((res) => - res.headers.has("Authorization") - ); - // You might also filter on res.url to find the response of a specific API call - if (authTokenResponse) { - localStorage.setItem( - "token", - authTokenResponse.headers.get("Authorization") - ); - } - return result; - }); -}); - -const restLink = new RestLink({ uri: "uri" }); - -const client = new ApolloClient({ - cache: new InMemoryCache(), - link: ApolloLink.from([authRestLink, restLink]), -}); -``` - -## Link order - -If you are using multiple link types, `restLink` should go before `httpLink`, as `httpLink` will swallow any calls that should be routed through `apollo-link-rest`. - -For example: - -```js -const httpLink = createHttpLink({ uri: "server.com/graphql" }); -const restLink = new RestLink({ uri: "api.server.com" }); - -const client = new ApolloClient({ - cache: new InMemoryCache(), - link: ApolloLink.from([authLink, restLink, errorLink, retryLink, httpLink]), - // Note: httpLink is terminating so must be last, while retry & error wrap - // the links to their right. State & context links should happen before (to - // the left of) restLink. -}); -``` - -_Note: you should also consider this if you're using [`@apollo/client/link/context`](./apollo-link-context) to set `Headers`, you need that link to be before `restLink` as well._ - -## @rest directive - -This is where you setup the endpoint you want to fetch. The rest directive can be used at any depth in a query. - -### Arguments - -An `@rest(…)` directive takes two required and several optional arguments: - -| Option | Type | Description | -| --------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `type` | `string` | The GraphQL type this will return | -| `path` | `string` | uri-path to the REST API. This could be a path or a full url. If a path, the endpoint given on link creation or from the context is concatenated with it to produce a full `URI`. See also: `pathBuilder` | -| `method?` | `GET` `PUT` `POST` `DELETE` | The HTTP method to send the request via (i.e GET, PUT, POST) | -| `endpoint?` | `string` | Key to use when looking up the endpoint in the (optional) `endpoints` table if provided to RestLink at creation time. | -| `pathBuilder?: /function/` | `string` | If provided, this function gets to control what path is produced for this request. | -| `bodyKey?: "input"` | `string` | This is the name of the `variable` to use when looking to build a REST request-body for a `PUT` or `POST` request. It defaults to `input` if not supplied. | -| `bodyBuilder?: /function/` | `string` | If provided, this is the name a `function` that you provided to `variables`, that is called when a request-body needs to be built. This lets you combine arguments or encode the body in some format other than JSON. | -| `bodySerializer?: /string \| function/` | `string` | String key to look up a function in `bodySerializers` or a custom serialization function for the body/headers of this request before it is passed to the fetch call. Defaults to `JSON.stringify` and setting `Content-Type: application-json`. | - -### Variables - -You can use query `variables` inside nested queries, or in the the path argument of your directive: - -```graphql -query PostTitle { - post(id: "1") @rest(type: "Post", path: "/post/{args.id}") { - id - title - } -} -``` - -> **Warning**: Variables in the main path will not automatically have `encodeURIComponent` called on them. - -Additionally, you can also control the query-string: - -```graphql -query PostTitle { - postSearch(query: "some key words", page_size: 5) - @rest(type: "Post", path: "/search?{args}&{context.language}") { - id - title - } -} -``` - -Things to note: - -1. This will be converted into `/search?query=some%20key%20words&page_size=5&lang=en` -2. The `context.language / lang=en` is extracting an object from the Apollo Context, that was added via an `@apollo/client/link/context` Link. -3. The query string arguments are assembled by npm:qs and have `encodeURIComponent` called on them. - -The available variable sources are: - -| Option | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `args` | These are the things passed directly to this field parameters. In the above example `postSearch` had `query` and `page_size` in args. | -| `exportVariables` | These are the things in the parent context that were tagged as `@export(as: ...)` | -| `context` | These are the apollo-context, so you can have globals set up via `@apollo/client/link/context` | -| `@rest` | These include any other parameters you pass to the `@rest()` directive. This is probably more useful when working with `pathBuilder`, documented below. | - -#### `pathBuilder` - -If the variable-replacement options described above aren't enough, you can provide a `pathBuilder` to your query. This will be called to dynamically construct the path. This is considered an advanced feature, and is documented in the source -- it also should be considered syntactically unstable, and we're looking for feedback! - -#### `bodyKey` / `bodyBuilder` - -When making a `POST` or `PUT` HTTP request, you often need to provide a request body. By [convention](https://graphql.org/graphql-js/mutations-and-input-types/), GraphQL recommends you name your input-types as `input`, so by default that's where we'll look to find a JSON object for your body. - -##### `bodyKey` - -If you need/want to name it something different, you can pass `bodyKey`, and we'll look at that variable instead. - -In this example the publish API accepts a body in the variable `body` instead of input: - -```graphql -mutation PublishPost($someApiWithACustomBodyKey: PublishablePostInput!) { - publishedPost: publish(input: "Foo", body: $someApiWithACustomBodyKey) - @rest( - type: "Post" - path: "/posts/{args.input}/new" - method: "POST" - bodyKey: "body" - ) { - id - title - } -} -``` - -[Unit Test](https://github.com/apollographql/apollo-link-rest/blob/c9d81ae308e5f61b5ae992061de7abc6cb2f78e0/src/__tests__/restLink.ts#L1803-L1846) - -##### `bodyBuilder` - -If you need to structure your data differently, or you need to custom encode your body (say as form-encoded), you can provide `bodyBuilder` instead: - -```graphql -mutation EncryptedPost($input: PublishablePostInput!, $encryptor: any) { - publishedPost: publish(input: $input) - @rest( - type: "Post" - path: "/posts/new" - method: "POST" - bodyBuilder: $encryptor - ) { - id - title - } -} -``` - -[Unit Test](https://github.com/apollographql/apollo-link-rest/blob/c9d81ae308e5f61b5ae992061de7abc6cb2f78e0/src/__tests__/restLink.ts#L1847-L1904) - -##### `bodySerializer` - -If you need to serialize your data differently (say as form-encoded), you can provide a `bodySerializer` instead of relying on the default JSON serialization. -`bodySerializer` can be either a function of the form `(data: any, headers: Headers) => {body: any, header: Headers}` or a string key. When using the string key -`RestLink` will instead use the corresponding serializer from the `bodySerializers` object, that can optionally be passed in during initialization. - -```graphql -mutation EncryptedForm($input: PublishablePostInput!, $formSerializer: any) { - publishedPost: publish(input: $input) - @rest( - type: "Post" - path: "/posts/new" - method: "POST" - bodySerializer: $formSerializer - ) { - id - title - } - - publishRSS(input: $input) - @rest(type: "Post", path: "/feed", method: "POST", bodySerializer: "xml") -} -``` - -Where `formSerializer` could be defined as - -```typescript -const formSerializer = (data: any, headers: Headers) => { - const formData = new FormData(); - for (let key in data) { - if (data.hasOwnProperty(key)) { - formData.append(key, data[key]); - } - } - - headers.set("Content-Type", "application/x-www-form-urlencoded"); - - return { body: formData, headers }; -}; -``` - -And `"xml"` would have been defined on the `RestLink` directly - -```typescript -const restLink = new RestLink({ - ...otherOptions, - bodySerializers: { - xml: xmlSerializer, - }, -}); -``` - -## @export directive - -The export directive re-exposes a field for use in a later (nested) query. These are the same semantics that will be supported on the server, but when used in a `RestLink` you can use the exported variables for further calls (i.e. waterfall requests from nested fields). - -_Note: If you're constantly using @export you may prefer to take a look at [`@apollo/server`](/apollo-server/)._ - -### Arguments - -- `as: string`: name to create this as a variable to be used down the selection set - -### Example - -An example use-case would be getting a list of users, and hitting a different endpoint to fetch more data using the exported field in the REST query args. - -```graphql -const QUERY = gql` - query RestData($email: String!) { - users @rest(path: '/users/email?{args.email}', method: 'GET', type: 'User') { - id @export(as: "id") - firstName - lastName - friends @rest(path: '/friends/{exportVariables.id}', type: '[User]') { - firstName - lastName - } - } - } -`; -``` - -## Mutations - -You can write also mutations with the apollo-link-rest, for example: - -```graphql -mutation DeletePost($id: ID!) { - deletePostResponse(id: $id) - @rest(type: "Post", path: "/posts/{args.id}", method: "DELETE") { - NoResponse - } -} -``` - -## Troubleshooting - -Here are a few common `apollo-link-rest` problems and solutions. - -- `Missing field __typename in ...` -- If you see this, it's possible you haven't provided `type:` to the [`@rest(...)`](#rest-directive)-directive. Alternately you need to set up a [`typePatcher`](#typename-patching). -- `Headers is undefined` -- If you see something like this, you're running in a browser or other Javascript environment that does not yet support the full specification for the `Headers` API. - -## Example apps - -To get you started, here are some example apps: - -- [Simple](https://github.com/apollographql/apollo-link-rest/tree/master/examples/simple): - A very simple app with a single query that reflects the setup section. -- [Advanced](https://github.com/apollographql/apollo-link-rest/tree/master/examples/advanced): - A more complex app that demonstrates how to use an export directive. - -## Contributing - -Please join us on github [apollographql/apollo-link-rest](https://github.com/apollographql/apollo-link-rest/) and in the [Apollo GraphQL community forums](https://community.apollographql.com). From 22c5735afb8e512fc424fdd84c3dea0294411889 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 09:52:40 -0600 Subject: [PATCH 31/53] Simplify customizing fetch section --- docs/source/api/link/apollo-link-http.mdx | 35 +---------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 05962bed834..65b182e1268 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -24,40 +24,7 @@ After your GraphQL endpoint (successfully) responds with the result of the sent ## Customizing `fetch` -You can provide a custom [`fetch` option](#options-fetch) to the `HttpLink` constructor to enable many custom networking needs. For example, you can modify the request based on calculated headers or calculate the endpoint URI based on the operation's details. - -If you're targeting an environment that doesn't provide the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) (such as older browsers or the server) you can provide a different implementation of `fetch`. We recommend [`unfetch`](https://github.com/developit/unfetch) for older browsers and [`node-fetch`](https://github.com/bitinn/node-fetch) for running in Node. - -### Custom auth - -This example adds a custom `Authorization` header to every request before calling `fetch`: - -```js -const customFetch = (uri, options) => { - const { header } = Hawk.client.header( - "http://example.com:8000/resource/1?b=1&a=2", - "POST", - { credentials: credentials, ext: "some-app-data" } - ); - options.headers.Authorization = header; - return fetch(uri, options); -}; - -const link = new HttpLink({ fetch: customFetch }); -``` - -### Dynamic URI - -This example customizes the endpoint URL's query parameters before calling `fetch`: - -```js -const customFetch = (uri, options) => { - const { operationName } = JSON.parse(options.body); - return fetch(`${uri}/graph/graphql?opname=${operationName}`, options); -}; - -const link = new HttpLink({ fetch: customFetch }); -``` +You can provide a custom [`fetch` option](#options-fetch) to the `HttpLink` constructor if you need fine-grained customization to the underlying `fetch` call. The function should behave identically to the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch). ## Types From b849b8e5ab7c001fa755bfa90040ad47d1f99e61 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:12:26 -0600 Subject: [PATCH 32/53] Tweak description for client awareness link Co-authored-by: Lenz Weber-Tronic --- docs/source/api/link/apollo-link-client-awareness.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index 45d52afaa01..d89f7bf7178 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -61,7 +61,13 @@ If you are using `BaseHttpLink` and want client awareness functionality, you wil ### Configuring with request context -You can configure client awareness using request context. Provide the `clientAwareness` and `enhancedClientAwareness` fields in `context`. These values take precedence over all other configurations. +You can configure client awareness using request context. Provide the `clientAwareness` field in `context`. These values take precedence over all other configurations. + + + +The `enhancedClientAwareness` field is not supported in request context. This feature should either be fully opted in or out of. + + ```ts const client = new ApolloClient(/* ... */); From adb56bbee3bd603bb9b8418db48fd68e9b30c122 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:02:29 -0600 Subject: [PATCH 33/53] Add constructor signature to apollo link --- docs/source/api/link/apollo-link.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/api/link/apollo-link.mdx b/docs/source/api/link/apollo-link.mdx index 753e3f79195..42534fac00b 100644 --- a/docs/source/api/link/apollo-link.mdx +++ b/docs/source/api/link/apollo-link.mdx @@ -10,6 +10,14 @@ description: API reference customOrder={["summary", "remarks", "example"]} /> +## Constructor signature + +```ts +constructor( + request?: ApolloLink.RequestHandler +): ApolloLink +``` + ## Static methods Date: Mon, 4 Aug 2025 11:07:26 -0600 Subject: [PATCH 34/53] Remove response from context in batch http link --- docs/source/api/link/apollo-link-batch-http.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index 67658429157..e69b0ed7381 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -28,7 +28,6 @@ The batch HTTP link currently uses the context in two different ways, per batch | `credentials` | A string representing the credentials policy you want for the fetch call | | `uri` | A string of the endpoint you want to fetch from | | `fetchOptions` | Any overrides of the fetch options argument to pass to the fetch call | -| `response` | This is the raw response from the fetch request after it is made | For each query, the `http` field is used to modify each individual query in the batch, such as persisted queries (see below). From 10aa590c472e46d2e302ac60824e5f686651a606 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:08:34 -0600 Subject: [PATCH 35/53] Add section on operation results --- docs/source/api/link/apollo-link-batch-http.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index e69b0ed7381..9a46aea46e6 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -31,6 +31,10 @@ The batch HTTP link currently uses the context in two different ways, per batch For each query, the `http` field is used to modify each individual query in the batch, such as persisted queries (see below). +## Operation results + +After your GraphQL endpoint (successfully) responds with the result of the sent operation, `BatchHttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. + ## Custom fetching See [Customizing `fetch`](apollo-link-http/#customizing-fetch). From 5c1331c949aebd6653f18db36c8dc4c423da82ac Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:14:59 -0600 Subject: [PATCH 36/53] Remove enhancedClientAwareness from request context --- docs/source/api/link/apollo-link-client-awareness.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index d89f7bf7178..541dc545c41 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -79,9 +79,6 @@ function MyComponent() { name: "My Client", version: "my_client_version", }, - enhancedClientAwareness: { - transport: "extensions", - }, }, }); From e35cbcb65fdb9f30db0f22e9ad273b200abaea37 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:17:07 -0600 Subject: [PATCH 37/53] Fix link --- src/link/error/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 8dbebabd922..56d60410842 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -71,14 +71,14 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { } /** - * Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](../../data/error-handling/) + * Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](https://apollographql.com/docs/react/data/error-handling) * occurs. You create an instance of `ErrorLink` with a function that's executed * if an operation returns one or more errors: * * @remarks * * This link is used after the GraphQL operation completes and execution is - * moving back _up_ your [link chain](./introduction/#handling-a-response). The function should + * moving back _up_ your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The function should * not return a value unless you want to [retry the operation](https://apollographql.com/docs/react/data/error-handling#retrying-operations). * * For more information on the types of errors that might be encountered, see the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). From 9faf57a7de52ef47992864df28fa5c55e7568555 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:17:48 -0600 Subject: [PATCH 38/53] Use period --- src/link/error/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 56d60410842..e175ce1f199 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -73,7 +73,7 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { /** * Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](https://apollographql.com/docs/react/data/error-handling) * occurs. You create an instance of `ErrorLink` with a function that's executed - * if an operation returns one or more errors: + * if an operation returns one or more errors. * * @remarks * From 603e9b4438faffec19bfabc9e353cfc8580871c3 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:18:25 -0600 Subject: [PATCH 39/53] Remove italics --- src/link/error/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index e175ce1f199..7c12d3224c4 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -78,7 +78,7 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { * @remarks * * This link is used after the GraphQL operation completes and execution is - * moving back _up_ your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The function should + * moving back up your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The function should * not return a value unless you want to [retry the operation](https://apollographql.com/docs/react/data/error-handling#retrying-operations). * * For more information on the types of errors that might be encountered, see the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). From d844e1c4ce5bb462c891c7dc4661b810de41890e Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:20:34 -0600 Subject: [PATCH 40/53] Remove additional sentence --- src/link/error/index.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 7c12d3224c4..39cc597d079 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -72,8 +72,7 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { /** * Use the `ErrorLink` to perform custom logic when a [GraphQL or network error](https://apollographql.com/docs/react/data/error-handling) - * occurs. You create an instance of `ErrorLink` with a function that's executed - * if an operation returns one or more errors. + * occurs. * * @remarks * From ee56a82bdf5244f0526e64019db7d640169ab668 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:21:49 -0600 Subject: [PATCH 41/53] Add qualifier --- src/link/error/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 39cc597d079..3c28495f5b8 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -77,7 +77,7 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { * @remarks * * This link is used after the GraphQL operation completes and execution is - * moving back up your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The function should + * moving back up your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The `errorHandler` function should * not return a value unless you want to [retry the operation](https://apollographql.com/docs/react/data/error-handling#retrying-operations). * * For more information on the types of errors that might be encountered, see the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). From ad78ad052568db4b99204a9e74308f43730c775e Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:21:55 -0600 Subject: [PATCH 42/53] Formatting --- src/link/error/index.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 3c28495f5b8..18335a4f48d 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -80,7 +80,8 @@ export function onError(errorHandler: ErrorLink.ErrorHandler) { * moving back up your [link chain](https://apollographql.com/docs/react/introduction#handling-a-response). The `errorHandler` function should * not return a value unless you want to [retry the operation](https://apollographql.com/docs/react/data/error-handling#retrying-operations). * - * For more information on the types of errors that might be encountered, see the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). + * For more information on the types of errors that might be encountered, see + * the guide on [error handling](https://apollographql.com/docs/react/data/error-handling). * * @example * From 9358ac9f857f965698e53b69744d0dd8ad41ba43 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:24:47 -0600 Subject: [PATCH 43/53] Add more detail --- docs/source/api/link/apollo-link-subscriptions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index d3379d7c716..e37a252f6ab 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -34,4 +34,4 @@ The `createClient` function can take many options, described in the [`graphql-ws ## Usage -See [Subscriptions](../../data/subscriptions/). +See [Subscriptions](../../data/subscriptions/) for more information on using subscription operations in Apollo Client. From 9adaf03ab5a4cc9746d158f208d831d79ee0e65b Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:28:22 -0600 Subject: [PATCH 44/53] Tweak note --- src/link/subscriptions/index.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/link/subscriptions/index.ts b/src/link/subscriptions/index.ts index ded5ff93a9f..7f6295117fe 100644 --- a/src/link/subscriptions/index.ts +++ b/src/link/subscriptions/index.ts @@ -53,9 +53,9 @@ function isLikeErrorEvent(err: unknown): err is Event { * commonly with GraphQL [subscriptions](https://apollographql.com/docs/react/data/subscriptions/), * * > [!NOTE] - * > This link works with the newer `graphql-ws` library. If your server uses - * > the older `subscriptions-transport-ws` library, you should use the - * > [`WebSocketLink`](https://apollographql.com/docs/react/api/link/apollo-link-ws) link from `@apollo/client/link/ws` instead. + * > This link works with the `graphql-ws` library. If your server uses + * > the deprecated `subscriptions-transport-ws` library, use the deprecated + * > [`WebSocketLink`](https://apollographql.com/docs/react/api/link/apollo-link-ws) link instead. * * @example * From 27ddb990c759cb08d440468d7fad1b23ea1bab14 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:28:31 -0600 Subject: [PATCH 45/53] Change options in ws link --- docs/source/api/link/apollo-link-subscriptions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index e37a252f6ab..67ab3d1aa7e 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -30,7 +30,7 @@ constructor( The `GraphQLWsLink` constructor takes a single argument, which is a `Client` returned from the `graphql-ws` `createClient` function. -The `createClient` function can take many options, described in the [`graphql-ws` docs for `ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interfaces/ClientOptions). The one required option is `url`, which is the URL (typically starting with `ws://` or `wss://`, which are the equivalents of `http://` and `https://` respectively) to your WebSocket server. (Note that this differs from the [older link's URL option](./apollo-link-ws), which is named `uri` instead of `url`.) +The `createClient` function can take many options, described in the [`graphql-ws` docs for `ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interfaces/ClientOptions). The `url` option is required, which is the URL to your WebSocket server (typically starting with `ws://` or `wss://`, which are the equivalents of `http://` and `https://` respectively.) ## Usage From 2db5b3c998b49d11f348147cf4a2d0765daa7b01 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 11:48:45 -0600 Subject: [PATCH 46/53] Update options section --- docs/source/api/link/apollo-link-subscriptions.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index 67ab3d1aa7e..e61b1af14b6 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -28,9 +28,15 @@ constructor( ### Options -The `GraphQLWsLink` constructor takes a single argument, which is a `Client` returned from the `graphql-ws` `createClient` function. +The `GraphQLWsLink` constructor takes a single argument, which is a `Client` returned from the `graphql-ws` [`createClient`](https://the-guild.dev/graphql/ws/docs/client/functions/createClient) function. The `createClient` function requires the `url` option, which is the URL to your WebSocket server (typically starting with `ws://` or `wss://`, which are the equivalents of `http://` and `https://` respectively.) -The `createClient` function can take many options, described in the [`graphql-ws` docs for `ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interfaces/ClientOptions). The `url` option is required, which is the URL to your WebSocket server (typically starting with `ws://` or `wss://`, which are the equivalents of `http://` and `https://` respectively.) +See the [`ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interfaces/ClientOptions) documentation for more details on the supported options provided to the `createClient` function. + +#### Retrying failed connections + +See the [`graphql-ws` recipes](https://the-guild.dev/graphql/ws/recipes) for strategies on retrying failed connections from the client. We recommend this approach as it provides more detailed information on the reason the connection failed. + +You can also handle retries in the link chain in a more generic manner using the [`RetryLink`](./apollo-link-retry) to resend the operation to the terminating link. ## Usage From 7ead34e1aeb3c23012d5453e54605e7e91e48acb Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 13:32:12 -0600 Subject: [PATCH 47/53] Fix backtick --- src/link/error/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/error/index.ts b/src/link/error/index.ts index 18335a4f48d..624984611f5 100644 --- a/src/link/error/index.ts +++ b/src/link/error/index.ts @@ -18,7 +18,7 @@ export declare namespace ErrorLink { * Callback that is called by `ErrorLink` when an error occurs from a * downstream link in link chain. * - * @param options - The options object provided by ErrorLink` to the error + * @param options - The options object provided by `ErrorLink` to the error * handler when an error occurs. */ export function ErrorHandler( From fd751c381807df21d1706027357d69be432c75f2 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 13:32:29 -0600 Subject: [PATCH 48/53] Chores --- .../api-report-link_batch-http.api.md | 20 ++------------- .api-reports/api-report-link_batch.api.md | 19 +++++++------- .api-reports/api-report-link_http.api.md | 25 +++++++++++-------- .api-reports/api-report.api.md | 25 +++++++++++-------- 4 files changed, 41 insertions(+), 48 deletions(-) diff --git a/.api-reports/api-report-link_batch-http.api.md b/.api-reports/api-report-link_batch-http.api.md index 18ccc6997c1..e0a3636f9e4 100644 --- a/.api-reports/api-report-link_batch-http.api.md +++ b/.api-reports/api-report-link_batch-http.api.md @@ -21,25 +21,9 @@ export class BaseBatchHttpLink extends ApolloLink { export namespace BatchHttpLink { export interface ContextOptions extends HttpLink.ContextOptions { } - // (undocumented) - export namespace DocumentationTypes { - export interface Options { - batchDebounce?: boolean; - batchInterval?: number; - batchKey?: (operation: ApolloLink.Operation) => string; - batchMax?: number; - credentials?: string; - fetch?: typeof fetch; - fetchOptions?: any; - headers?: Record; - includeExtensions?: boolean; - includeUnusedVariables?: boolean; - preserveHeaderCase?: boolean; - print?: HttpLink.Printer; - uri?: string | HttpLink.UriFunction; - } + export interface Options extends BatchLink.Shared.Options, HttpLink.Shared.Options { + batchMax?: number; } - export type Options = Pick & Omit; } // @public diff --git a/.api-reports/api-report-link_batch.api.md b/.api-reports/api-report-link_batch.api.md index def11c2ccf9..d6a791ed860 100644 --- a/.api-reports/api-report-link_batch.api.md +++ b/.api-reports/api-report-link_batch.api.md @@ -12,20 +12,19 @@ export namespace BatchLink { // (undocumented) export type BatchHandler = (operations: ApolloLink.Operation[], forward: ApolloLink.ForwardFunction[]) => Observable; // (undocumented) - export namespace DocumentationTypes { - // (undocumented) + export interface Options extends Shared.Options { + batchHandler?: BatchLink.BatchHandler; + batchMax?: number; + } + // (undocumented) + export namespace Shared { export interface Options { + batchDebounce?: boolean; + batchInterval?: number; + batchKey?: (operation: ApolloLink.Operation) => string; batchMax?: number; } } - // (undocumented) - export interface Options { - batchDebounce?: boolean; - batchHandler?: BatchLink.BatchHandler; - batchInterval?: number; - batchKey?: (operation: ApolloLink.Operation) => string; - batchMax?: number; - } } // @public (undocumented) diff --git a/.api-reports/api-report-link_http.api.md b/.api-reports/api-report-link_http.api.md index 3adfbfcbe63..92f4ea2d5ae 100644 --- a/.api-reports/api-report-link_http.api.md +++ b/.api-reports/api-report-link_http.api.md @@ -82,21 +82,26 @@ export namespace HttpLink { includeQuery?: boolean; preserveHeaderCase?: boolean; } - export interface Options { - credentials?: RequestCredentials; - fetch?: typeof fetch; - fetchOptions?: RequestInit; - headers?: Record; - includeExtensions?: boolean; - includeUnusedVariables?: boolean; - preserveHeaderCase?: boolean; - print?: HttpLink.Printer; - uri?: string | HttpLink.UriFunction; + export interface Options extends Shared.Options { useGETForQueries?: boolean; } // (undocumented) export type Printer = (node: ASTNode, originalPrint: typeof print_2) => string; // (undocumented) + export namespace Shared { + export interface Options { + credentials?: RequestCredentials; + fetch?: typeof fetch; + fetchOptions?: RequestInit; + headers?: Record; + includeExtensions?: boolean; + includeUnusedVariables?: boolean; + preserveHeaderCase?: boolean; + print?: HttpLink.Printer; + uri?: string | HttpLink.UriFunction; + } + } + // (undocumented) export type UriFunction = (operation: ApolloLink.Operation) => string; } diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md index 750022ca2a8..35a378f35c3 100644 --- a/.api-reports/api-report.api.md +++ b/.api-reports/api-report.api.md @@ -1360,16 +1360,7 @@ export namespace HttpLink { includeQuery?: boolean; preserveHeaderCase?: boolean; } - export interface Options { - credentials?: RequestCredentials; - fetch?: typeof fetch; - fetchOptions?: RequestInit; - headers?: Record; - includeExtensions?: boolean; - includeUnusedVariables?: boolean; - preserveHeaderCase?: boolean; - print?: HttpLink.Printer; - uri?: string | HttpLink.UriFunction; + export interface Options extends Shared.Options { useGETForQueries?: boolean; } // Warning: (ae-forgotten-export) The symbol "print_2" needs to be exported by the entry point index.d.ts @@ -1377,6 +1368,20 @@ export namespace HttpLink { // (undocumented) export type Printer = (node: ASTNode, originalPrint: typeof print_2) => string; // (undocumented) + export namespace Shared { + export interface Options { + credentials?: RequestCredentials; + fetch?: typeof fetch; + fetchOptions?: RequestInit; + headers?: Record; + includeExtensions?: boolean; + includeUnusedVariables?: boolean; + preserveHeaderCase?: boolean; + print?: HttpLink.Printer; + uri?: string | HttpLink.UriFunction; + } + } + // (undocumented) export type UriFunction = (operation: ApolloLink.Operation) => string; } From 483aec5478b705f7a60aed91579454ffe291ffc7 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 13:37:43 -0600 Subject: [PATCH 49/53] Fix typo --- docs/source/api/link/apollo-link-client-awareness.mdx | 4 ++-- docs/source/api/link/apollo-link-error.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index 541dc545c41..da8cb3143ae 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -97,11 +97,11 @@ function MyComponent() { diff --git a/docs/source/api/link/apollo-link-error.mdx b/docs/source/api/link/apollo-link-error.mdx index 52593848bac..7007937c854 100644 --- a/docs/source/api/link/apollo-link-error.mdx +++ b/docs/source/api/link/apollo-link-error.mdx @@ -24,7 +24,7 @@ constructor( canonicalReference="@apollo/client/link/error!ErrorLink.ErrorLinkDocumentationTypes.ErrorHandler:function(1)" headingLevel={3} result={false} - displayName="ApolloLink.ErrorHandler" + displayName="ErrorLink.ErrorHandler" /> Date: Mon, 4 Aug 2025 13:40:33 -0600 Subject: [PATCH 50/53] AI suggestions --- docs/source/api/link/apollo-link-batch-http.mdx | 2 +- docs/source/api/link/apollo-link-client-awareness.mdx | 6 +++--- docs/source/api/link/apollo-link-http.mdx | 4 ++-- docs/source/api/link/apollo-link-subscriptions.mdx | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/api/link/apollo-link-batch-http.mdx b/docs/source/api/link/apollo-link-batch-http.mdx index 9a46aea46e6..ae702d6a96d 100644 --- a/docs/source/api/link/apollo-link-batch-http.mdx +++ b/docs/source/api/link/apollo-link-batch-http.mdx @@ -33,7 +33,7 @@ For each query, the `http` field is used to modify each individual query in the ## Operation results -After your GraphQL endpoint (successfully) responds with the result of the sent operation, `BatchHttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. +After your GraphQL endpoint successfully responds with the result of an operation, `BatchHttpLink` sets the `Response` object as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response. ## Custom fetching diff --git a/docs/source/api/link/apollo-link-client-awareness.mdx b/docs/source/api/link/apollo-link-client-awareness.mdx index da8cb3143ae..102354d09ff 100644 --- a/docs/source/api/link/apollo-link-client-awareness.mdx +++ b/docs/source/api/link/apollo-link-client-awareness.mdx @@ -55,17 +55,17 @@ const client = new ApolloClient({ -If you are using `BaseHttpLink` and want client awareness functionality, you will need to add `ClientAwarenessLink` to your link chain manually. `HttpLink` includes `ClientAwarenessLink` by default. +If you use `BaseHttpLink`, add `ClientAwarenessLink` to your link chain manually to enable client awareness. `HttpLink` includes `ClientAwarenessLink` by default. ### Configuring with request context -You can configure client awareness using request context. Provide the `clientAwareness` field in `context`. These values take precedence over all other configurations. +Configure client awareness on a per-request basis by providing the `clientAwareness` field in the request's `context`. These values take precedence over all other configurations. -The `enhancedClientAwareness` field is not supported in request context. This feature should either be fully opted in or out of. +The `enhancedClientAwareness` field is not supported in request context. Configure this feature at the client or link level instead. diff --git a/docs/source/api/link/apollo-link-http.mdx b/docs/source/api/link/apollo-link-http.mdx index 65b182e1268..4b82b662c11 100644 --- a/docs/source/api/link/apollo-link-http.mdx +++ b/docs/source/api/link/apollo-link-http.mdx @@ -20,11 +20,11 @@ constructor( ## Operation results -After your GraphQL endpoint (successfully) responds with the result of the sent operation, `HttpLink` sets it as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response before it's returned. +After your GraphQL endpoint successfully responds with the result of an operation, `HttpLink` sets the `Response` object as the `response` field of the operation `context`. This enables each previous link in your link chain to interact with the response. ## Customizing `fetch` -You can provide a custom [`fetch` option](#options-fetch) to the `HttpLink` constructor if you need fine-grained customization to the underlying `fetch` call. The function should behave identically to the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch). +Provide a custom [`fetch` option](#options-fetch) to the `HttpLink` constructor if you need fine-grained control over the underlying `fetch` call. The function should behave identically to the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch). ## Types diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index e61b1af14b6..16c85244d82 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -28,15 +28,15 @@ constructor( ### Options -The `GraphQLWsLink` constructor takes a single argument, which is a `Client` returned from the `graphql-ws` [`createClient`](https://the-guild.dev/graphql/ws/docs/client/functions/createClient) function. The `createClient` function requires the `url` option, which is the URL to your WebSocket server (typically starting with `ws://` or `wss://`, which are the equivalents of `http://` and `https://` respectively.) +The `GraphQLWsLink` constructor takes a single argument: a `Client` instance from the `graphql-ws` library. To create this instance, call the library's [`createClient`](https://the-guild.dev/graphql/ws/docs/client/functions/createClient) function. This function requires a `url` option, which is the URL to your WebSocket server. WebSocket URLs typically start with `ws://` or `wss://`. See the [`ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interfaces/ClientOptions) documentation for more details on the supported options provided to the `createClient` function. #### Retrying failed connections -See the [`graphql-ws` recipes](https://the-guild.dev/graphql/ws/recipes) for strategies on retrying failed connections from the client. We recommend this approach as it provides more detailed information on the reason the connection failed. +See the [`graphql-ws` recipes](https://the-guild.dev/graphql/ws/recipes) for strategies on retrying failed connections from the client. We recommend this approach because it provides more detailed information on why the connection failed. -You can also handle retries in the link chain in a more generic manner using the [`RetryLink`](./apollo-link-retry) to resend the operation to the terminating link. +Alternatively, you can handle retries more generically within the link chain by using [`RetryLink`](./apollo-link-retry). This link resends the operation to the terminating link upon failure. ## Usage From 56d8bf370cd0c6042bd2b34f85266a887ac421c0 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 13:55:48 -0600 Subject: [PATCH 51/53] Allow for variable replacement on escaped curlys --- config/inlineInheritDoc.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/inlineInheritDoc.ts b/config/inlineInheritDoc.ts index 91350b4faf4..42d96c880f6 100644 --- a/config/inlineInheritDoc.ts +++ b/config/inlineInheritDoc.ts @@ -37,7 +37,7 @@ import { } from "@microsoft/api-extractor"; import { ApiDocumentedItem, ApiModel } from "@microsoft/api-extractor-model"; import type { DocComment, DocExcerpt, DocNode } from "@microsoft/tsdoc"; -import { TextRange } from "@microsoft/tsdoc"; +import type { TextRange } from "@microsoft/tsdoc"; import { DeclarationReference } from "@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js"; import { visit } from "recast"; @@ -77,7 +77,7 @@ function getCommentFor( const unusedVariables = new Set(Object.keys(variables || {})); let string = renderDocComment(apiItem.tsdocComment); - string = string.replaceAll(/\{\{(\w+)\}\}/g, (_, variable) => { + string = string.replaceAll(/\\?\{\\?\{(\w+)\\?\}\\?\}/g, (_, variable) => { unusedVariables.delete(variable); const value = variables?.[variable]; if (value === undefined) { From cd70f2c13daf96c831816f0e5167edaf76da585e Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Mon, 4 Aug 2025 13:55:57 -0600 Subject: [PATCH 52/53] Escape curlys --- src/link/batch/batchLink.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/link/batch/batchLink.ts b/src/link/batch/batchLink.ts index a9d7d2d4634..56a5f7046fa 100644 --- a/src/link/batch/batchLink.ts +++ b/src/link/batch/batchLink.ts @@ -26,7 +26,7 @@ export declare namespace BatchLink { /** * The maximum number of operations to include in a single batch. * - * @defaultValue {{defaultValue}} + * @defaultValue \{\{defaultValue\}\} */ batchMax?: number; From 6e272c1acb129d6a09af32c822323c0d369c2f7e Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Tue, 5 Aug 2025 08:49:39 -0600 Subject: [PATCH 53/53] Tweak sentence --- docs/source/api/link/apollo-link-subscriptions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/api/link/apollo-link-subscriptions.mdx b/docs/source/api/link/apollo-link-subscriptions.mdx index 16c85244d82..2f740ea870d 100644 --- a/docs/source/api/link/apollo-link-subscriptions.mdx +++ b/docs/source/api/link/apollo-link-subscriptions.mdx @@ -34,7 +34,7 @@ See the [`ClientOptions`](https://the-guild.dev/graphql/ws/docs/client/interface #### Retrying failed connections -See the [`graphql-ws` recipes](https://the-guild.dev/graphql/ws/recipes) for strategies on retrying failed connections from the client. We recommend this approach because it provides more detailed information on why the connection failed. +See the [`graphql-ws` recipes](https://the-guild.dev/graphql/ws/recipes) for strategies on retrying failed connections from the client. We generally recommend this approach over retrying failed connections from the link chain or your components because it provides more detailed information on why the connection failed. Alternatively, you can handle retries more generically within the link chain by using [`RetryLink`](./apollo-link-retry). This link resends the operation to the terminating link upon failure.