Update docs and changeset

.changeset/slimy-shrimps-run.md

@@ -2,4 +2,8 @@
 '@urql/exchange-graphcache': patch
 ---
 
-When comparing selection-sets during `optimistic` mutations we shouldn't look at field-aliases but instead leverage field-names. This also removes the warning for missing fields in optimistic return values
+Graphcache's `optimistic` option now accepts optimistic mutation resolvers that return fields by
+name rather than alias. Previously, depending on which mutation was run, the optimistic resolvers
+would read your optimistic data by field alias (i.e. "alias" for `alias: id` rather than "id").
+Instead, optimistic updates now correctly use field names and allow you to also pass resolvers as
+values on your optimistic config.

docs/api/graphcache.md

@@ -145,11 +145,11 @@ interface OptimisticMutationConfig {
 A `OptimisticMutationResolver` receives three arguments when it's called: `variables`, `cache`, and
 `info`.
 
-| Argument    | Type     | Description                                                                                                 |
-| ----------- | -------- | ----------------------------------------------------------------------------------------------------------- |
-| `variables` | `object` | The variables that the given mutation received.                                                             |
-| `cache`     | `Cache`  | The cache using which data can be read or written. [See `Cache`.](#cache)                                   |
-| `info`      | `Info`   | Additional metadata and information about the current operation and the current field. [See `Info`.](#info) |
+| Argument | Type     | Description                                                                                                 |
+| -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `args`   | `object` | The arguments that the given mutation field received.                                                       |
+| `cache`  | `Cache`  | The cache using which data can be read or written. [See `Cache`.](#cache)                                   |
+| `info`   | `Info`   | Additional metadata and information about the current operation and the current field. [See `Info`.](#info) |
 
 [Read more about how to set up `optimistic` on the "Custom Updates"
 page.](../graphcache/cache-updates.md)

docs/graphcache/cache-updates.md

@@ -475,11 +475,13 @@ that imitates the result that the API is assumed to send back:
 ```js
 const cache = cacheExchange({
   optimistic: {
-    favoriteTodo: (variables, cache, info) => ({
-      __typename: 'Todo',
-      id: variables.id,
-      favorite: true,
-    }),
+    favoriteTodo(args, cache, info) {
+      return {
+        __typename: 'Todo',
+        id: variables.id,
+        favorite: true,
+      };
+    },
   },
 });
 ```
@@ -495,6 +497,29 @@ doesn't contain then we'll see a warning, since this is a common mistake. To wor
 enough data we may use methods like `cache.readFragment` and `cache.resolve` to retrieve more data
 from our cache.
 
+If we'd like to make sure we don't compute more fields than we need, for instance because one
+mutation is run with several different selection sets, then we may pass nested optimistic resolver
+functions in our optimistic object, like so:
+
+```js
+const cache = cacheExchange({
+  optimistic: {
+    favoriteTodo(variables, cache, info) {
+      return {
+        __typename: 'Todo',
+        id: variables.id,
+        favorite(args, cache, info) {
+          return true;
+        },
+      },
+    },
+  },
+});
+```
+
+The function signature and arguments it receives is identical to the toplevel optimistic function
+you define.
+
 ### Variables for Optimistic Updates
 
 Sometimes it's not possible for us to retrieve all data that an optimistic update requires to create