Merge branch 'release-4.0' into pr/codemod-legacyEntryPoints

Author: phryneas

.api-reports/api-report-masking.api.md

@@ -62,8 +62,8 @@ type ExtractByMatchingTypeNames<Union extends {
 
 // Warning: (ae-forgotten-export) The symbol "PreserveTypes" needs to be exported by the entry point index.d.ts
 //
-// @public (undocumented)
-export type FragmentType<TData> = ApplyHKTImplementationWithDefault<TypeOverrides, "FragmentType", PreserveTypes.TypeOverrides, TData>;
+// @public
+export type FragmentType<TFragmentData> = ApplyHKTImplementationWithDefault<TypeOverrides, "FragmentType", PreserveTypes.TypeOverrides, TFragmentData>;
 
 // @public (undocumented)
 export namespace GraphQLCodegenDataMasking {

.api-reports/api-report.api.md

@@ -1146,8 +1146,8 @@ interface FragmentRegistryAPI {
 
 // Warning: (ae-forgotten-export) The symbol "PreserveTypes" needs to be exported by the entry point index.d.ts
 //
-// @public (undocumented)
-export type FragmentType<TData> = ApplyHKTImplementationWithDefault<TypeOverrides, "FragmentType", PreserveTypes.TypeOverrides, TData>;
+// @public
+export type FragmentType<TFragmentData> = ApplyHKTImplementationWithDefault<TypeOverrides, "FragmentType", PreserveTypes.TypeOverrides, TFragmentData>;
 
 // @public @deprecated (undocumented)
 export const from: typeof ApolloLink.from;

docs/source/api/link/introduction.mdx

@@ -517,6 +517,12 @@ const link = new OperationCountLink();
 
 As an operation moves along the link chain, it maintains a `context` that each link can read and modify. This enables both links and request-based APIs (such as [`useQuery`](../react/useQuery)) to pass metadata along the chain that other links use in their execution logic. Context is not included in the terminating link's request to the GraphQL server or other destination.
 
+<Note>
+
+If your application is built using TypeScript, we recommend reading the [Defining context types](../../development-testing/static-typing#defining-context-types) guide to learn how to provide types for the context object.
+
+</Note>
+
 ### Reading context
 
 You get the current context object by calling `operation.getContext()` in a [request handler](#the-request-handler).

docs/source/data/fragments.mdx

@@ -1286,6 +1286,31 @@ To migrate from CodeGen's fragment masking feature to Apollo Client's data maski
 
 3. [Enable data masking](#enabling-data-masking) in Apollo Client.
 
+#### Setting data masking types
+
+By default, Apollo Client makes no modification to the operation types provided to its APIs, regardless of whether the type definitions are masked or unmasked. This provides a simpler upgrade path when you're ready to [incrementally adopt](#incremental-adoption-in-an-existing-application) data masking.
+
+To use GraphQL Codegen's masking format with your operation types, you need to tell Apollo Client to use the associated GraphQL Codegen masking types. You do this by defining a [type override](../development-testing/static-typing#overriding-type-implementations-of-built-in-types) that uses the GraphQL Codegen masking format.
+
+Create a TypeScript file that will be used to modify the `TypeOverrides` interface. Extend `TypeOverrides` with the `GraphQLCodegenDataMasking.TypeOverrides` interface.
+
+```ts title="apollo-client.d.ts"
+// This import is necessary to ensure all Apollo Client imports
+// are still available to the rest of the application.
+import "@apollo/client";
+import type { GraphQLCodegenDataMasking } from "@apollo/client/masking";
+
+declare module "@apollo/client" {
+  interface TypeOverrides extends GraphQLCodegenDataMasking.TypeOverrides {}
+}
+```
+
+<Note>
+
+This example uses `apollo-client.d.ts` as the file name to make it easily identifiable. You can give this file any name.
+
+</Note>
+
 #### Using with fragments
 
 When using [colocated fragments](#colocating-fragments) with your components, it's best to ensure the object passed to your component is done in a type-safe way. This means:
@@ -1519,3 +1544,137 @@ query GetPosts {
 Repeat this process until all `@unmask` directives have been removed from your codebase.
 
 Congratulations 🎉! Your application is now using data masking everywhere 😎.
+
+### Defining your own masking types using higher-kinded types
+
+<Note>
+
+If you are using the [data masking types generated from GraphQL Codegen](#setting-data-masking-types), you can safely skip this section.
+
+</Note>
+
+Apollo Client provides an [integration](#setting-data-masking-types) with GraphQL Codegen's [fragment masking](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#fragment-masking) output and orients its masking utility types around this format. If you aren't using GraphQL Codegen to generate your types, or your types are generated in a different format, the type implementations built into Apollo Client might be incompatible which results in inaccurate types.
+
+You can use a technique called _higher-kinded types_ (HKT) to provide your own type implementations for Apollo Client's masking types. You can think of higher-kinded types as a way to define types and interfaces with generics that can be filled in by Apollo Client internals at a later time. Passing around un-evaluated types is otherwise not possible in TypeScript.
+
+#### Example
+
+Let's add our own type overrides for the `MaybeMasked` and `Unmasked` utility types.
+
+The `MaybeMasked` type is used throughout Apollo Client to return the masked or unmasked type definition for a given type, assuming they have data masking types enabled and are maskable. Otherwise, it returns the unmasked type that is passed in.
+
+The `Unmasked` type unwraps a masked type to its full result type and is used throughout Apollo Client where the full data type is needed for a given API (e.g. `client.writeQuery`).
+
+For this example, we'll assume the data masking types are enabled and the operation types are generated using two variations:
+
+1. Data masked types are generated with a `__masked` virtual property. Its value is the operation type with any masked fields removed from the type.
+
+   ```ts
+   type MaskedQuery = {
+     // The masked variant of the operation type is provided under the
+     // `__masked` virtual property
+     __masked?: { user: { __typename: "User"; id: number } };
+
+     // The full result type includes all other fields in the type
+     user: { __typename: "User"; id: number; name: string };
+   };
+   ```
+
+2. Unmasked types are generated as their full result type with no `__masked` virtual property applied to them.
+
+   ```ts
+   type UnmaskedQuery = {
+     user: { __typename: "User"; id: number; name: string };
+   };
+   ```
+
+<Note>
+
+This is a hypothetical format that doesn't exist in Apollo Client or any known code generation tool. This format is used specifically for this example to illustrate how to provide type overrides to Apollo Client.
+
+</Note>
+
+First, let's define our custom implementation of the `MaybeMasked` type. The implementation works by checking if the `__masking` virtual property exists on the type. If so, it returns the value on the `__masked` property as the type, otherwise it returns the input type unmodified.
+
+```ts title="masked-types.ts"
+type MaybeMasked<TData> =
+  TData extends { __masked?: infer TMaskedData } ? TMaskedData : TData;
+```
+
+Now let's provide an implementation for the `Unmasked` type that works in contrast to `MaybeMasked` by returning the unwrapped full result type. The implementation works by removing the `__masked` virtual property on the input type. This can be accomplished using the built-in [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) type.
+
+```ts {4} title="masked-types.ts"
+type MaybeMasked<TData> =
+  TData extends { __masked?: infer TMaskedData } ? TMaskedData : TData;
+
+type Unmasked<TData> = Omit<TData, "__masked">;
+```
+
+Now that our custom type implementations are in place, we need to define higher-kinded types for each of these custom types. This provides the bridge needed by Apollo Client to use our custom type implementations. This is done by extending the `HKT` interface exported by `@apollo/client/utilities`.
+
+Let's provide HKTs for our `MaybeMasked` and `Unmasked` types. We'll put these in the same file as our type implementations.
+
+```ts {1,8-11,13-16} title="masked-types.ts"
+import { HKT } from "@apollo/client/utilities";
+
+type MaybeMasked<TData> =
+  TData extends { __masked?: infer TMaskedData } ? TMaskedData : TData;
+
+type Unmasked<TData> = Omit<TData, "__masked">;
+
+export interface MaybeMaskedHKT extends HKT {
+  arg1: unknown; // TData
+  return: MaybeMasked<this["arg1"]>;
+}
+
+export interface UnmaskedHKT extends HKT {
+  arg1: unknown; // TData
+  return: Unmasked<this["arg1"]>;
+}
+```
+
+With our HKT types in place, we now need to tell Apollo Client about them.
+
+Apollo Client uses [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to provide a hook point for overridable types. The `TypeOverrides` interface exported by the `@apollo/client` package is used for this purpose. Each property in the `TypeOverrides` interface corresponds to an overridable type in Apollo Client.
+
+Let's add type overrides for our custom type implementations. Create a TypeScript file and define a `TypeOverrides` interface for the `@apollo/client` module.
+
+```ts title=apollo-client.d.ts
+// This import is necessary to ensure all Apollo Client imports
+// are still available to the rest of the application.
+import "@apollo/client";
+
+declare module "@apollo/client" {
+  export interface TypeOverrides {
+    // Type overrides will go here
+  }
+}
+```
+
+Now we'll import our HKT types and add them as keys in the `TypeOverrides` interface.
+
+```ts {4,8-9} title=apollo-client.d.ts
+// This import is necessary to ensure all Apollo Client imports
+// are still available to the rest of the application.
+import "@apollo/client";
+import { MaybeMaskedHKT, UnmaskedHKT } from "./masked-types.ts";
+
+declare module "@apollo/client" {
+  export interface TypeOverrides {
+    MaybeMasked: MaybeMaskedHKT;
+    Unmasked: UnmaskedHKT;
+  }
+}
+```
+
+And that's it! Now when Apollo Client uses the `MaybeMasked` or `Unmasked` types in its APIs, our custom implementation will be used instead 🎉.
+
+#### Available type overrides
+
+The following masking utility types are available to override:
+
+- `FragmentType<TFragmentData>` - Type used with [fragments](#using-with-fragments) to ensure parent objects contain the fragment spread from the type.
+- `MaybeMasked<TData>` - Conditionally returns `TData` as either its masked type or unmasked type
+- `Unmasked<TData>` - Unwraps `TData` into the full result type
+
+For more information about other overridable types in Apollo Client, see the [TypeScript guide](../development-testing/static-typing).

docs/source/data/mutations.mdx

@@ -13,6 +13,12 @@ This article demonstrates how to send updates to your GraphQL server with the `u
 
 ## Prerequisites
 
+<Note>
+
+If your application is built using TypeScript, we recommend reading the [TypeScript guide](../development-testing/static-typing) to learn how to use TypeScript with Apollo Client.
+
+</Note>
+
 This article assumes you're familiar with building basic GraphQL mutations. If you need a refresher, we recommend that you
 [read this guide](http://graphql.org/learn/queries/#mutations).
 

docs/source/data/queries.mdx

@@ -16,6 +16,12 @@ This article shows how to fetch GraphQL data in React with the `useQuery` hook a
 
 ## Prerequisites
 
+<Note>
+
+If your application is built using TypeScript, we recommend reading the [TypeScript guide](../development-testing/static-typing) to learn how to use TypeScript with Apollo Client.
+
+</Note>
+
 This article assumes you're familiar with building basic GraphQL queries. If you need a refresher, we recommend [this guide](http://graphql.org/learn/queries/). You can also build example queries against Apollo's [full-stack tutorial server](https://apollo-fullstack-tutorial.herokuapp.com/graphql).
 
 This article also assumes that you've already set up Apollo Client and have wrapped your React app in an `ApolloProvider` component. For more information, see the [getting started guide](../get-started/).
@@ -70,6 +76,12 @@ As our query executes and the values of `loading`, `error`, and `data` change, t
 
 When the user selects a dog breed from the populated dropdown, the selection is sent to the parent component via the provided `onDogSelected` function.
 
+<Note>
+
+If you are using TypeScript, `data` is typed as `unknown` when the query type is unknown. Accessing fields on `data` results in a TypeScript error. See the [TypeScript with Apollo Client](../development-testing/static-typing) guide to learn how to add types for your queries.
+
+</Note>
+
 In the next step, we'll associate the dropdown with a more sophisticated query that uses GraphQL variables.
 
 ## Caching query results