Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
docs(graphcache): Add API entry note
+78
-12
+1
docs/api/graphcache.md
+1
docs/api/graphcache.md
···
27
27
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28
28
| `keys` | A mapping of key generator functions for types that are used to override the default key generation that _Graphcache_ uses to normalize data for given types. |
29
29
| `resolvers` | A nested mapping of resolvers, which are used to override the record or entity that _Graphcache_ resolves for a given field for a type. |
30
+
| `directives` | A mapping of directives, which are functions accepting directive arguments and returning a resolver, which can be referenced by `@localDirective` or `@_localDirective` in queries. |
30
31
| `updates` | A nested mapping of updater functions for mutation and subscription fields, which may be used to add side-effects that update other parts of the cache when the given subscription or mutation field is written to the cache. |
31
32
| `optimistic` | A mapping of mutation fields to resolvers that may be used to provide _Graphcache_ with an optimistic result for a given mutation field that should be applied to the cached data temporarily. |
32
33
| `schema` | A serialized GraphQL schema that is used by _Graphcache_ to resolve partial data, interfaces, and enums. The schema also used to provide helpful warnings for [schema awareness](../graphcache/schema-awareness.md). |
+77
-12
docs/graphcache/local-directives.md
+77
-12
docs/graphcache/local-directives.md
···
5
5
6
6
# Local Directives
7
7
8
-
Graphcache supports adding directives to GraphQL Documents, when we prefix a
9
-
directive with an underscore (`_`) it will be stripped from the document and stored
10
-
on the `_directives` property on the AST-node.
8
+
Previously, we've learned about local resolvers [on the "Normalized Caching"
9
+
page](./normalized-caching.md#manually-resolving-entities) and [the "Local Resolvers" page](./local-resolvers.md).
10
+
11
+
Resolvers allow us to change the data that Graphcache resolvers for a given field on a given type.
12
+
This, in turn, allows us to change which links and data are returned in a query’s result, which
13
+
otherwise may not be cached or be returned in a different shape.
14
+
15
+
Resolvers are useful to globally change how a field behaves, for instance, to tell Graphcache that
16
+
a `Query.item(id: $id)` field returns an item of type `Item` with the `id` field, or to transform
17
+
a value before it’s used in the UI.
18
+
19
+
However, resolvers are limited to changing the behaviour globally, not to change a field’s behaviour
20
+
per query. This is why **local directives** exist.
11
21
12
-
> Ensure you prefix directives with `_` if you only want to alter local behavior.
22
+
## Adding client-only directives
13
23
14
-
By default graphcache will add two directives `@_optional` and `@_required` which
15
-
allow you to mark fields as being optional or mandatory.
24
+
Any directive in our GraphQL documents that’s prefixed with an underscore character (`_`) will be
25
+
filtered by `@urql/core`. This means that our GraphQL API never sees it and it becomes
26
+
a “client-only directive”.
16
27
17
-
If you want to add directives yourself you can do so by performing
28
+
No matter whether we prefix a directive or not however, we can define local resolvers for directives
29
+
in Graphcache’s configuration and make conditional local resolvers.
18
30
19
31
```js
20
32
cacheExchange({
21
33
directives: {
22
-
// If you now add `@_pagination` to your document we will execute this
23
-
pagination: directiveArguments => () => {
24
-
/* Resolver */
34
+
pagination(directiveArgs) {
35
+
// This resolver is called for @_pagination directives
36
+
return (parent, args, cache, info) => {
37
+
return null;
38
+
};
25
39
},
26
40
},
27
41
});
28
42
```
29
43
30
-
The function signature of a directive is a function which receives the arguments the directive is called with in the document.
31
-
That function should returns a [Resolver](./local-directives.md).
44
+
Once we define a directive on the `directives` configuration object, we can reference it in our
45
+
GraphQL queries.
46
+
47
+
As per the above example, if we now reference `@_pagination` in a query, the resolver that’s
48
+
returned in the configuration will be applied to the field, just like a local resolver.
49
+
50
+
We can also reference the directive using `@pagination`, however, this will mean that it’s
51
+
also sent to the API, so this usually isn’t what we want.
52
+
53
+
## Client-controlled Nullability
54
+
55
+
Graphcache comes with two directives built-in by default. The `optional` and `required` directives.
56
+
These directives can be used as an alternative to [the Schema Awareness
57
+
feature’s](./schema-awareness.md) ability to generate partial results.
58
+
59
+
If we were to write a query that contains `@_optional` on a field, then the field is always allowed to be
60
+
nullable. In case it’s not cached, Graphcache will be able to replace it with a `null`
61
+
value.
62
+
63
+
Similarly, if we annotate a field with `@_required`, the value is not optional and, even if the
64
+
cache knows the value is set to `null`, it will become required and Graphcache will either cascade
65
+
to the next higher parent field annotated with `@_optional`, or will mark a query as a cache-miss.
66
+
67
+
## Pagination
68
+
69
+
Previously, in [the “Local Resolvers” page’s Pagination section](./local-resolvers.md#pagination) we
70
+
defined a local resolver to add infinite pagination to a given type’s field.
71
+
72
+
If we add the `simplePagination` or `relayPagination` helpers as directives instead, we can still
73
+
use our schema’s pagination field as normal, and instead, only use infinite pagination as required.
74
+
75
+
```js
76
+
import { simplePagination } from '@urql/exchange-graphcache/extras';
77
+
import { relayPagination } from '@urql/exchange-graphcache/extras';
78
+
79
+
cacheExchange({
80
+
directives: {
81
+
simplePagination,
82
+
relayPagination,
83
+
},
84
+
});
85
+
```
86
+
87
+
Defining directives for our resolver factory functions means that we can now use them selectively.
88
+
89
+
```graphql
90
+
{
91
+
todos(first: 10) @_relayPagination(mergeMode: "outwards") {
92
+
id
93
+
text
94
+
}
95
+
}
96
+
```
32
97
33
98
### Reading on
34
99