documentation updates for LocalState

Author: phryneas

.claude/documentation.md

@@ -26,8 +26,22 @@ Spelling and grammar should follow American English conventions.
 Content should be framed towards the reader in an active voice (e.g. "You can use the `useQuery` hook to fetch data" instead of "The `useQuery` hook can be used to fetch data"). Passive voice can be used to describe the behavior of the library (e.g. "The `useQuery` hook returns an object containing the query result") as a result of userland code usage.
 The use of "we" should be avoided, unless it is used to refer to the Apollo Client team as a whole (e.g. "We recommend using fragment colocation and data masking.").
 
-### Change documentation
-If documentation is updated, it should always describe the new status quo and not contain statements like "previously" or "previous behavior".
+### Change documentation - CRITICAL RULE
+**NEVER reference changes, previous versions, or historical behavior in documentation.** Documentation must ONLY describe the current state of the library.
+
+FORBIDDEN phrases and patterns:
+- "previously" or "previous behavior"
+- "has been restructured" or "has been changed"
+- "now takes" or "now provides"
+- "in earlier versions"
+- "used to be" or "was changed"
+- Any reference to what something was like before
+
+CORRECT approach:
+- Describe how things work today
+- State what the current behavior is
+- Explain the current API without comparing to past versions
+
 If new features are added to the documentation, they can include a `<MinVersion version="3.10.0">` tag wrapping the headline of the new feature, to indicate that this feature is only available in Apollo Client 3.10.0 and later.
 For features that are introduced in a major version, the `<MinVersion>` tag should not be used, as for each major version, a separate copy of the documentation is maintained.
 Currently, this documentation copy is the copy for Apollo Client with the major version 4, so all references to previous versions can be removed.
@@ -40,3 +54,11 @@ Never use phrases like "since version 4.0, this or that change applied". Only do
 
 ### Updating DocBlocks
 If outdated or incorrect documentation is found in `docs/public/client.api.json`, find the closest parent `fileUrlPath` in the JSON structure and update the original DocBlock in that file. Then run `npm run docmodel` to regenerate the JSON file and read the `docs/public/client.api.json` again.
+
+### DocBlock Guidelines
+- Use `@template` to document TypeScript generics, not `@param`
+- Example: `@template TData - The type of data returned by the query`
+- Use `@param` only for actual function parameters
+- Use `@returns` to document return values
+- Use `@defaultValue` to document default values for properties in interfaces describing options
+- Use `@example` for code examples

docs/source/local-state/local-resolvers.mdx

@@ -87,10 +87,20 @@ fieldName: (obj, args, context, info) => result;
 
 1. `obj`: The object containing the result returned from the resolver on the parent field or the `ROOT_QUERY` object in the case of a top-level query or mutation.
 2. `args`: An object containing all of the arguments passed into the field. For example, if you called a mutation with `updateNetworkStatus(isConnected: true)`, the `args` object would be `{ isConnected: true }`.
-3. `context`: An object of contextual information shared between your React components and your Apollo Client network stack. In addition to any custom context properties that may be present, local resolvers always receive the following:
-    - `context.client`: The Apollo Client instance.
-    - `context.cache`: The Apollo Cache instance, which can be used to manipulate the cache with `context.cache.readQuery`, `.writeQuery`, `.readFragment`, `.writeFragment`, `.modify`, and `.evict`. You can learn more about these methods in [Managing the cache](#managing-the-cache).
-    - `context.getCacheKey`: Get a key from the cache using a `__typename` and `id`.
+3. `context`: The context argument provides additional information without the possibility of name clashes. It takes the following shape:
+    ```ts
+    {
+      // The request context. By default this is of type `DefaultContext`,
+      // but can be changed if a `context` function is provided to LocalState
+      requestContext: TContextValue,
+      // The client instance making the request
+      client: ApolloClient,
+      // Whether the resolver is run as a result of gathering exported variables
+      // or resolving the value as part of the result
+      phase: "exports" | "resolve"
+    }
+    ```
+    To access the cache, use `context.client.cache`.
 4. `info`: Information about the execution state of the query. You will probably never have to use this one.
 
 Let's take a look at an example of a resolver where we toggle a todo's completed status:
@@ -103,9 +113,9 @@ const client = new ApolloClient({
   localState: new LocalState({
     resolvers: {
       Mutation: {
-        toggleTodo: (_root, variables, { cache }) => {
-          cache.modify({
-            id: cache.identify({
+        toggleTodo: (_root, variables, { client }) => {
+          client.cache.modify({
+            id: client.cache.identify({
               __typename: 'TodoItem',
               id: variables.id,
             }),
@@ -121,10 +131,62 @@ const client = new ApolloClient({
 });
 ```
 
-In previous versions of Apollo Client, toggling the `completed` status of the `TodoItem` required reading a fragment from the cache, modifying the result by negating the `completed` boolean, and then writing the fragment back into the cache. Apollo Client 3.0 introduced the `cache.modify` method as an easier and faster way to update specific fields within a given entity object. To determine the ID of the entity, we pass the `__typename` and primary key fields of the object to `cache.identify` method.
+To determine the ID of the entity, we pass the `__typename` and primary key fields of the object to `cache.identify` method. The `cache.modify` is used to update specific fields within a given entity object.
 
 Once we toggle the `completed` field, since we don't plan on using the mutation's return result in our UI, we return `null` since all GraphQL types are nullable by default.
 
+### Type safety with LocalState
+
+The `LocalState` class accepts a `Resolvers` generic that provides autocompletion and type checking against your resolver types to ensure your resolvers are type-safe:
+
+```ts
+import { LocalState } from "@apollo/client/local-state";
+import { Resolvers } from "./path/to/local-resolvers-types.ts";
+
+// LocalState accepts a `Resolvers` generic.
+const localState = new LocalState<Resolvers>({
+  resolvers: {
+    // Your resolvers will be type-checked against the Resolvers type
+  }
+});
+```
+
+You may also pass a `ContextValue` generic used to ensure the `context` function returns the correct type. This type is inferred from your resolvers if not provided:
+
+```ts
+new LocalState<Resolvers, ContextValue>({
+  // The return value of this function will be type-checked
+  context: (options) => ({
+    // ...
+  }),
+  resolvers: {
+    // ...
+  }
+});
+```
+
+### Error handling
+
+Throwing errors in a resolver will set the field value as `null` and add an error to the response's `errors` array. This follows GraphQL's standard error handling behavior:
+
+```ts
+const localState = new LocalState({
+  resolvers: {
+    Query: {
+      riskyField: () => {
+        throw new Error("Something went wrong!");
+        // This will result in: { data: { riskyField: null }, errors: [...] }
+      }
+    }
+  }
+});
+```
+
+### Data handling
+
+- **Remote result dealiasing**: Remote results are dealiased before they are passed as the parent object to a resolver so that you can access fields by their field name.
+- **Null data handling**: If the server returns `data: null` or does not provide a result, your local resolvers will not be called.
+
 Let's learn how to trigger our `toggleTodo` mutation from our component:
 
 ```jsx
@@ -289,8 +351,8 @@ const GET_LAUNCH_DETAILS = gql`
 
 This query includes a mixture of both remote and local fields. `isInCart` is the only field marked with an `@client` directive, so it's the field we'll focus on. When Apollo Client executes this query and tries to find a result for the `isInCart` field, it runs through the following steps:
 
-1. Has a resolver function been set (either through the `ApolloClient` constructor `resolvers` parameter or Apollo Client's `setResolvers` / `addResolvers` methods) that is associated with the field name `isInCart`? If yes, run and return the result from the resolver function.
-2. If a matching resolver function can't be found, check the Apollo Client cache to see if a `isInCart` value can be found directly. If so, return that value.
+1. Has a resolver function been set for the field name `isInCart`? If yes, run and return the result from the resolver function.
+2. If a matching resolver function can't be found, check the Apollo Client cache to see if a `isInCart` value can be found directly or read with a `read` field `TypePolicy`. If so, return that value.
 
 Let's look at both of these steps more closely.
 
@@ -350,22 +412,22 @@ const GET_LAUNCH_DETAILS = gql`
 // ... run the query using client.query, a <Query /> component, etc.
 ```
 
-Here when the `GET_LAUNCH_DETAILS` query is executed, Apollo Client looks for a local resolver associated with the `isInCart` field. Since we've defined a local resolver for the `isInCart` field in the `ApolloClient` constructor, it finds a resolver it can use. This resolver function is run, then the result is calculated and merged in with the rest of the query result (if a local resolver can't be found, Apollo Client will check the cache for a matching field - see [Local data query flow](#local-data-query-flow) for more details).
+Here when the `GET_LAUNCH_DETAILS` query is executed, Apollo Client looks for a local resolver associated with the `isInCart` field. Since we've defined a local resolver for the `isInCart` field in the `LocalState` instance, it finds a resolver it can use. This resolver function is run, then the result is calculated and merged in with the rest of the query result (if a local resolver can't be found, Apollo Client will check the cache for a matching field - see [Local data query flow](#local-data-query-flow) for more details).
 
-Setting resolvers through `ApolloClient`'s constructor `resolvers` parameter, or through its `setResolvers` / `addResolvers` methods, adds resolvers to Apollo Client's internal resolver map (refer to the [Local resolvers](#local-resolvers) section for more details concerning the resolver map). In the above example we added a  `isInCart` resolver, for the `Launch` GraphQL object type, to the resolver map. Let's look at the `isInCart` resolver function more closely:
+Setting resolvers through the `LocalState`'s `resolvers` option or through its `addResolvers` method adds resolvers to the internal resolver map (refer to the [Local resolvers](#local-resolvers) section for more details concerning the resolver map). In the above example we added a  `isInCart` resolver, for the `Launch` GraphQL object type, to the resolver map. Let's look at the `isInCart` resolver function more closely:
 
 ```js
   resolvers: {
     Launch: {
-      isInCart: (launch, _args, { cache }) => {
-        const { cartItems } = cache.readQuery({ query: GET_CART_ITEMS });
+      isInCart: (launch, _args, { client }) => {
+        const { cartItems } = client.cache.readQuery({ query: GET_CART_ITEMS });
         return cartItems.includes(launch.id);
       },
     },
   },
 ```
 
-`launch` holds the data returned from the server for the rest of the query, which means in this case we can use `launch` to get the current launch `id`. We aren't using any arguments in this resolver, so we can skip the second resolver parameter. From the `context` however (the third parameter), we're using the `cache` reference, to work directly with the cache ourselves. So in this resolver, we're making a call directly to the cache to get all cart items, checking to see if any of those loaded cart items matches the parent  `launch.id`, and returning `true` / `false` accordingly. The returned boolean is then incorporated back into the result of running the original query.
+`launch` holds the data returned from the server for the rest of the query, which means in this case we can use `launch` to get the current launch `id`. We aren't using any arguments in this resolver, so we can skip the second resolver parameter. From the `context` however (the third parameter), we're using the `client` reference to access the cache. So in this resolver, we're making a call directly to the cache to get all cart items, checking to see if any of those loaded cart items matches the parent  `launch.id`, and returning `true` / `false` accordingly. The returned boolean is then incorporated back into the result of running the original query.
 
 Just like resolvers on the server, local resolvers are extremely flexible. They can be used to perform any kind of local computation you want, before returning a result for the specified field. You can manually query (or write to) the cache in different ways, call other helper utilities or libraries to prep/validate/clean data, track statistics, call into other data stores to prep a result, etc.
 
@@ -954,7 +1016,7 @@ In order to toggle our todo, we need the todo and its status from the cache, whi
 
 ### Code splitting
 
-Depending on the complexity and size of your local resolvers, you might not always want to define them up front, when you create your initial `ApolloClient` instance. If you have local resolvers that are only needed in a specific part of your application, you can leverage Apollo Client's [`addResolvers` and `setResolvers`](#methods) functions to adjust your resolver map at any point. This can be really useful when leveraging techniques like route based code-splitting, using something like [`react-loadable`](https://github.com/jamiebuilds/react-loadable).
+Depending on the complexity and size of your local resolvers, you might not always want to define them up front, when you create your initial `ApolloClient` instance. If you have local resolvers that are only needed in a specific part of your application, you can dynamically call `client.localState.addResolvers` to dynamically add new resolvers. This can be really useful when leveraging techniques like route based code-splitting.
 
 Let's say we're building a messaging app and have a `/stats` route that is used to return the total number of messages stored locally. If we use `react-loadable` to load our `Stats` component like:
 
@@ -969,12 +1031,12 @@ export const Stats = Loadable({
 });
 ```
 
-and wait until our `Stats` component is called to define our local resolvers (using `addResolvers`):
+and wait until our `Stats` component is called to define our local resolvers:
 
 ```js
 import React from "react";
 import { gql } from "@apollo/client";
-import { ApolloConsumer, useApolloClient, useQuery } from "@apollo/client/react";
+import { useApolloClient, useQuery } from "@apollo/client/react";
 
 const GET_MESSAGE_COUNT = gql`
   query GetMessageCount {
@@ -986,7 +1048,7 @@ const GET_MESSAGE_COUNT = gql`
 
 const resolvers = {
   Query: {
-    messageCount: (_, args, { cache }) => {
+    messageCount: (_, args, { client }) => {
       // ... calculate and return the number of messages in
       // the cache ...
       return {
@@ -999,7 +1061,7 @@ const resolvers = {
 
 export function MessageCount() {
   const client = useApolloClient();
-  client.addResolvers(resolvers);
+  client.localState.addResolvers(resolvers);
 
   const { loading, data: { messageCount } } = useQuery(GET_MESSAGE_COUNT);
 
@@ -1040,15 +1102,19 @@ const client = new ApolloClient({
 
 <FunctionDetails canonicalReference="@apollo/client!LocalState#addResolvers:member(1)" headingLevel={5}  parameters={false} />
 
-**Typescript interfaces/types:**
+#### Typescript interfaces/types:
 
 ```ts
 interface Resolvers {
   [key: string]: {
     [field: string]: (
       rootValue?: any,
       args?: any,
-      context?: any,
+      context?: {
+        requestContext: any;
+        client: ApolloClient;
+        phase: "exports" | "resolve";
+      },
       info?: any,
     ) => any;
   };

docs/source/local-state/managing-state-with-field-policies.mdx

@@ -19,6 +19,28 @@ The values for these fields are calculated locally using any logic you want, suc
 
 As shown, a query can include both local-only fields _and_ fields that are fetched from your GraphQL server.
 
+<Note>
+
+**Important**: Using `@client` fields requires configuring local state in your Apollo Client instance. If you use `@client` fields without configuring local state, you'll get an error like:
+
+```
+Query 'ProductDetails' contains '@client' fields but local state has not been configured.
+```
+
+To enable `@client` fields, you must provide a `LocalState` instance to your Apollo Client:
+
+```ts
+import { ApolloClient, InMemoryCache } from '@apollo/client';
+import { LocalState } from '@apollo/client/local-state';
+
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  localState: new LocalState(),
+});
+```
+
+</Note>
+
 ## Defining
 
 Let's say we're building an e-commerce application. Most of a product's details are stored on our back-end server, but we want to define a `Product.isInCart` boolean field that's local to the client. First, we create a **field policy** for `isInCart`.