Skip to content

update link docs #12994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −47
Open

update link docs #12994

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 11 additions & 43 deletions docs/source/api/link/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,50 +91,25 @@

#### Additive composition

Additive composition composes a link chain by executing links in serial order. You use the [`from`](#from) and [`concat`](#concat) helpers to create a link chain using additive composition.
Additive composition composes a link chain by executing links in serial order. You use the [`ApolloLink.from`](#from) and [`ApolloLink.concat`](#concat) helpers to create a link chain using additive composition.

Check warning on line 94 in docs/source/api/link/introduction.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/api/link/introduction.mdx#L94 

Avoid using 'compose' unless referring to federated schema composition. Use 'build' as the verb for constructing a link chain.

```suggestion
Additive composition builds a link chain by executing links in serial order. You use the [`ApolloLink.from`](#from) and [`ApolloLink.concat`](#concat) helpers to create a link chain using additive composition.
```

##### `from`
##### `ApolloLink.from`

The most common way to compose multiple links together is to use the `from` helper. Pass an array of link objects to `from` to create a composed link that executes each link in serial order:
The most common way to compose multiple links together is to use the static `ApolloLink.from` helper. Pass an array of link objects to `ApolloLink.from` to create a composed link that executes each link in serial order:

Check warning on line 98 in docs/source/api/link/introduction.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/api/link/introduction.mdx#L98 

Avoid using 'compose' unless referring to federated schema composition. Use 'build' as the verb for constructing a link chain.

```suggestion
The most common way to build a link chain is to use the static `ApolloLink.from` helper. Pass an array of link objects to `ApolloLink.from` to create a link that executes each link in serial order:
```

```ts
import { from, HttpLink, ApolloLink } from "@apollo/client";
import { HttpLink, ApolloLink } from "@apollo/client";
import { RetryLink } from "@apollo/client/link/retry";
import MyAuthLink from "../auth";

const link = from([
new RetryLink(),
new MyAuthLink(),
new HttpLink({ uri: "http://localhost:4000/graphql" }),
]);

// this also works
const link = ApolloLink.from([
new RetryLink(),
new MyAuthLink(),
new HttpLink({ uri: "http://localhost:4000/graphql" }),
]);
```

##### `concat`

Combine two links together into a single composed link using the `concat` method.

```ts
import { concat, ApolloLink, HttpLink } from "@apollo/client";
import MyAuthLink from "../auth";

const link = concat(
new MyAuthLink(),
new HttpLink({ uri: "http://localhost:4000/graphql" })
);

// this also works
const link = ApolloLink.concat(
new MyAuthLink(),
new HttpLink({ uri: "http://localhost:4000/graphql" })
);
```
##### `ApolloLink.concat`

Each link object includes a `concat` instance method to combine two links into a single composed link. This is useful to combine multiple links together using a chain of function calls:

Expand All @@ -156,28 +131,21 @@

#### Directional composition

You might want your link chain's execution to branch, depending on the details of the operation being performed. You use the `split` function to create a link that conditionally routes to different sub-chains.
You might want your link chain's execution to branch, depending on the details of the operation being performed. You use the `ApolloLink.split` method to create a link that conditionally routes to different sub-chains.

Check notice on line 134 in docs/source/api/link/introduction.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/api/link/introduction.mdx#L134 

Use 'can' instead of 'might want' to describe a capability. This is more direct and authoritative.

```suggestion
You can branch your link chain's execution, depending on the details of the operation being performed. You use the `ApolloLink.split` method to create a link that conditionally routes to different sub-chains.
```

The `split` function takes three arguments:
The `ApolloLink.split` function takes three arguments:

| Name | Description |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `test` | A function that takes in the current `operation` and returns `true` or `false`. Returning `true` executes the `left` link. Returning `false` executes the `right` link. |
| `left` | The link passed as the second argument to `split`. This link executes when the `test` function returns `true`. |
| `right` | An optional link passed as the third argument to `split`. This link executes when the `test` function returns `false`. If this is not provided, the request handler's `forward` parameter is used. |

The following example uses `split` to create a link that routes to different `HttpLink` instances depending on the associated context's `version`:
The following example uses `ApolloLink.split` to create a link that routes to different `HttpLink` instances depending on the associated context's `version`:

```ts
import { ApolloLink, HttpLink, split } from "@apollo/client";

const link = split(
(operation) => operation.getContext().version === 1,
new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
);
import { ApolloLink, HttpLink } from "@apollo/client";

Check warning on line 147 in docs/source/api/link/introduction.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/api/link/introduction.mdx#L147 

Avoid repeating imports. Declare all necessary imports once at the beginning of the article or within the first relevant code example.

```suggestion
// This import is redundant and should be removed.
```

// this also works
const link = ApolloLink.split(
(operation) => operation.getContext().version === 1,
new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
Expand Down Expand Up @@ -214,12 +182,12 @@
In the following example, all subscription operations are sent to `GraphQLWsLink`, with all other operations sent to `HttpLink`:

```ts
import { split, HttpLink } from "@apollo/client";
import { ApolloLink, HttpLink } from "@apollo/client";

Check warning on line 185 in docs/source/api/link/introduction.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/api/link/introduction.mdx#L185 

Avoid repeating imports. Declare all necessary imports once at the beginning of the article or within the first relevant code example.

```suggestion
// This import is redundant and should be removed.
```
import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
import { OperationTypeNode } from "graphql";
import { createClient } from "graphql-ws";

const link = split(
const link = ApolloLink.split(
({ operationType }) => {
return operationType === OperationTypeNode.SUBSCRIPTION;
},
Expand Down
4 changes: 2 additions & 2 deletions docs/source/data/subscriptions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ The following example expands on the previous one by initializing both a `GraphQ

```ts title="index.ts"
import { OperationTypeNode } from "graphql";
import { split, HttpLink } from "@apollo/client";
import { ApolloLink, HttpLink } from "@apollo/client";
import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
import { createClient } from "graphql-ws";

Expand All @@ -188,7 +188,7 @@ const wsLink = new GraphQLWsLink(
// * A function that's called for each operation to execute
// * The Link to use for an operation if the function returns a "truthy" value
// * The Link to use for an operation if the function returns a "falsy" value
const splitLink = split(
const splitLink = ApolloLink.split(
({ operationType }) => {
return operationType === OperationTypeNode.SUBSCRIPTION;
},
Expand Down
4 changes: 2 additions & 2 deletions docs/source/networking/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
```js
import ApolloClient from "apollo-client";
import { HttpLink } from "apollo-link-http";
import { ApolloLink, concat } from "apollo-link";
import { ApolloLink } from "apollo-link";

Check failure on line 75 in docs/source/networking/authentication.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/networking/authentication.mdx#L75 

The 'apollo-link' package is deprecated. Use '@apollo/client' for all Apollo Client-related imports.

```suggestion
import { ApolloLink } from "@apollo/client";
```
import { InMemoryCache } from "apollo-cache-inmemory";
import { getMainDefinition } from "apollo-utilities";

Expand All @@ -89,7 +89,7 @@
return forward(operation);
});
export const apolloClient = new ApolloClient({
link: concat(authMiddleware, httpLink),
link: authMiddleware.concat(httpLink),
cache: new InMemoryCache(),
});
```
Expand Down