Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
Update readmes with links to new docs (#597)
* convert links
* update main readme
* clean up readme, refer to docs
* mention svelte as well
* adjust graphcache readme
* Add detailed TOC to README
* Fix link in populate readme
* Fix link in Graphcache readme
Co-authored-by: Phil Plückthun <phil@kitten.sh>
authored by
Jovi De Croock
Phil Plückthun
and committed by
GitHub
1ae7988f
72483b32
+22
-422
+14
-326
README.md
+14
-326
README.md
···
25
25
26
26
## ✨ Features
27
27
28
-
- 📦 **One package** to get a working GraphQL client in React or Preact
29
-
- ⚙️ Fully **customisable** behaviour [via "exchanges"](#-add-on-exchanges)
28
+
- 📦 **One package** to get a working GraphQL client in React, Preact, and Svelte
29
+
- ⚙️ Fully **customisable** behaviour [via "exchanges"](https://formidable.com/open-source/urql/docs/concepts/exchanges)
30
30
- 🗂 Logical but simple default behaviour and document caching
31
-
- ⚛️ Minimal React components and hooks
32
-
- 🌱 Normalized caching via [`@urql/exchange-graphcache`](https://github.com/FormidableLabs/urql/tree/master/exchanges/graphcache)
31
+
- 🌱 Normalized caching via [`@urql/exchange-graphcache`](https://formidable.com/open-source/urql/docs/graphcache)
33
32
34
-
`urql` is a GraphQL client that exposes a set of React components and hooks. It's built to be highly customisable and versatile so you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.
33
+
`urql` is a GraphQL client that exposes a set of helpers for several frameworks. It's built to be highly customisable and versatile so you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.
35
34
36
35
While GraphQL is an elegant protocol and schema language, client libraries today typically come with large API footprints. We aim to create something more lightweight instead.
37
36
38
-
Some of the available exchanges that extend `urql` are listed below in the ["Ecosystem" list](https://github.com/FormidableLabs/urql#-ecosystem) including a normalized cache and a Chrome devtools extension.
39
-
40
-
## 📃 [Documentation](https://formidable.com/open-source/urql/docs)
41
-
42
-
[The documentation contains everything you need to know about `urql`](https://formidable.com/open-source/urql/docs)
43
-
44
-
- [Getting Started guide](https://formidable.com/open-source/urql/docs/getting-started/)
45
-
- [Architecture](https://formidable.com/open-source/urql/docs/architecture/)
46
-
- [Basics](https://formidable.com/open-source/urql/docs/basics/)
47
-
- [Extending & Experimenting](https://formidable.com/open-source/urql/docs/extending-and-experimenting/)
48
-
- [API](https://formidable.com/open-source/urql/docs/api/)
49
-
- [Guides](./docs/guides.md)
50
-
51
-
_You can find the raw markdown files inside this repository's `docs` folder._
52
-
53
-
## 🏎️ Intro & Showcase
54
-
55
-
### Installation
37
+
## Installation
56
38
57
39
```sh
58
40
yarn add urql graphql
···
60
42
npm install --save urql graphql
61
43
```
62
44
63
-
### Queries
64
-
65
-
There are three hooks, one for each possible GraphQL operation.
66
-
67
-
The [`useQuery` hook](https://formidable.com/open-source/urql/docs/api/#usequery-hook) is
68
-
used to send GraphQL queries and will provide GraphQL results from your API.
69
-
70
-
When you're using `useQuery` it'll accept a configuration object that may contain keys for `query` and `variables`.
71
-
The `query` can either be your GraphQL query as a string or as a `DocumentNode`, which may be
72
-
parsed using [`graphql-tag`](https://github.com/apollographql/graphql-tag) for instance.
73
-
74
-
```js
75
-
import { useQuery } from 'urql';
76
-
77
-
const YourComponent = () => {
78
-
const [result] = useQuery({
79
-
query: `{ todos { id } }`,
80
-
});
81
-
82
-
if (result.error) return <Error message={result.error.message} />;
83
-
if (result.fetching) return <Loading />;
84
-
85
-
return <List data={result.data.todos} />;
86
-
};
87
-
```
88
-
89
-
Internally, `urql` will create a unique `key` for any operation it starts which is a hash of `query` and
90
-
`variables`. The internal "Exchange pipeline" is then responsible for fulfilling the operation.
91
-
92
-
<img width="606" src="docs/assets/urql-operation-keys.png" alt="Diagram: An Operation key is computed by hashing the combination of the stringified query and the stabily stringified variables. DocumentNodes may either be stringified fully or just by using their operation names. Properties of any variables object need to be stabily sorted." />
93
-
94
-
The result's error is a [`CombinedError`](https://formidable.com/open-source/urql/docs/api/#combinederror-class), which
95
-
normalises GraphQL errors and Network errors by combining them into one wrapping class.
96
-
97
-
<img width="693" src="docs/assets/urql-combined-error.png" alt="Diagram: A CombinedError has two states. It can either have a property 'networkError', or it can have multiple, rehydrated GraphQL errors on the 'graphQLErrors' property. The message of the CombinedError will always be a summary of the errors it contains." />
98
-
99
-
[Learn more about `useQuery` in the Getting Started guide](https://formidable.com/open-source/urql/docs/getting-started/#writing-queries)
100
-
101
-
### Mutations
102
-
103
-
The [`useMutation` hook](https://formidable.com/open-source/urql/docs/api/#usemutation-hook) is very similar to the `useQuery` hook,
104
-
but instead of sending queries it sends mutations whenever the `executeMutation` method is called with the variables for the mutation.
105
-
106
-
```js
107
-
import { useMutation } from 'urql';
108
-
109
-
const YourComponent = () => {
110
-
const [result, executeMutation] = useMutation(
111
-
`mutation AddTodo($text: String!) { addTodo(text: $text) { id } }`
112
-
);
113
-
114
-
const add = () =>
115
-
executeMutation({ text: 'New todo!' }).then(result => {
116
-
/* ... */
117
-
});
118
-
119
-
return <button onClick={add}>Go!</button>;
120
-
};
121
-
```
122
-
123
-
The `useMutation` hook provides a result, just like `useQuery` does, but it doesn't execute the mutation automatically.
124
-
Instead it starts once the `executeMutation` function is called with some variables. This also returns a promise that
125
-
resolves to the result as well.
126
-
127
-
[Learn more about `useMutation` in the Getting Started guide](https://formidable.com/open-source/urql/docs/getting-started/#writing-mutations)
128
-
129
-
### Pausing and Request Policies
130
-
131
-
The `useQuery` hook and `useMutation` hook differ by when their operations execute by default.
132
-
Mutations will only execute once the `executeMutation` method is called with some variables.
133
-
The `useQuery` hook can actually be used similarly. The hook also provides an `executeQuery`
134
-
function that can be called imperatively to change what query the hook is running.
135
-
136
-
Unlike the `useMutation` hook, the `useQuery`'s `executeQuery` function accepts an `OperationContext` as the argument, this allows you to for example override the `requestPolicy` or even the `fetchOptions`.
137
-
138
-
```js
139
-
const [result, executeQuery] = useQuery({
140
-
query: 'query ($sort: Sorting!) { todos(sort: $sort) { text } }',
141
-
variables: { sort: 'by-date' },
142
-
});
143
-
144
-
// executeQuery can trigger queries and override options
145
-
const update = () => executeQuery({ requestPolicy: 'network-only' });
146
-
```
147
-
148
-
Instead of running the `useQuery` operation eagerly you may also pass `pause: true`, which causes the
149
-
hook not to run your query automatically until `pause` becomes `false` or until `executeQuery` is called
150
-
manually.
151
-
152
-
```js
153
-
// This won't execute automatically...
154
-
const [result, executeQuery] = useQuery({
155
-
query: '{ todos { text } }',
156
-
pause: true,
157
-
});
158
-
159
-
// ...but it can still be triggered programmatically
160
-
const execute = () => executeQuery();
161
-
```
162
-
163
-
Apart from `pause` you may also pass a `requestPolicy` option that changes how the cache treats your data.
164
-
By default this option will be set to `"cache-first"` which will give you cached data when it's available,
165
-
but it can also be set to `"network-only"` which skips the cache entirely and refetches. Another option is
166
-
`"cache-and-network"` which may give you cached data but then refetches in the background.
167
-
168
-
```js
169
-
const [result, executeQuery] = useQuery({
170
-
query: '{ todos { text } }',
171
-
// Refetch up-to-date data in the background
172
-
requestPolicy: 'cache-and-network',
173
-
});
174
-
175
-
// this will tell you whether something is fetching in the background
176
-
result.stale; // true
177
-
```
178
-
179
-
Therefore to [refetch data for your `useQuery` hook](https://formidable.com/open-source/urql/docs/getting-started/#refetching-data),
180
-
you can call `executeQuery` with the `network-only` request policy.
181
-
182
-
```js
183
-
const [result, executeQuery] = useQuery({
184
-
query: '{ todos { text } }',
185
-
});
186
-
187
-
// We change the requestPolicy to bypass the cache just this once
188
-
const refetch = () => executeQuery({ requestPolicy: 'network-only' });
189
-
```
190
-
191
-
[Learn more about request policies in our Getting Started section!](https://formidable.com/open-source/urql/docs/getting-started/#refetching-data)
192
-
193
-
### Client and Exchanges
194
-
195
-
In `urql` all operations are controlled by a central [`Client`](https://formidable.com/open-source/urql/docs/api/#client-class).
196
-
This client is responsible for managing GraphQL operations and sending requests.
197
-
198
-
<img width="787" src="docs/assets/urql-client-architecture.png" alt="Diagram: The Client is an event hub on which operations may be dispatched by hooks. This creates an input stream (displayed as operations A, B, and C). Each Operation Result that then comes back from the client corresponds to one operation that has been sent to the client. This is the output stream of results (displayed as results A, B, and C)" />
199
-
200
-
Any hook in `urql` dispatches its operation on the client (A, B, C) which will be handled by the client on a
201
-
single stream of inputs. As responses come back from the cache or your GraphQL API one or more results are
202
-
dispatched on an output stream that correspond to the operations, which update the hooks.
203
-
204
-
205
-
Hence the client can be seen as an event hub. Operations are sent to the client, which executes them and
206
-
sends back a result. A special teardown-event is issued when a hook unmounts or updates to a different
207
-
operation.
208
-
209
-
<img width="700" src="docs/assets/urql-signals.png" alt="Diagram: Operations can be seen as signals. Operations with an 'operationName' of query, mutation, or subscription start a query of the given DocumentNode operation. The same operation with an 'operationName' of 'teardown' instructs the client to stop or cancel an ongoing operation of the same key. Operation Results carry the original operation on an 'operation' property, which means they can be identified by reading the key of this operation."/>
210
-
211
-
[Learn more about the shape of operations and results in our Architecture section!](https://formidable.com/open-source/urql/docs/architecture/)
212
-
213
-
_Exchanges_ are separate middleware-like extensions that determine how operations flow through the client
214
-
and how they're fulfilled. All functionality in `urql` can be customised by changing the client's exchanges
215
-
or by writing a custom one.
216
-
217
-
_Exchanges_ are named as such because middleware are often associated with a single stream of inputs,
218
-
like Express' per-request handlers and middleware, which imperatively send results, or Redux's middleware,
219
-
which only deal with actions.
220
-
221
-
Instead _Exchanges_ are nested and deal with two streams, the input stream of operations and the output stream of results,
222
-
where the stream of operations go through a pipeline like an intersection in an arbitrary order.
223
-
224
-
<img width="634" src="docs/assets/urql-exchanges.png" alt="Diagram: By default the client has three exchanges. Operations flow through a 'dedup', 'cache', and 'fetch' exchange in this exact order. Their results are flowing backwards through this same chain of exchanges. The 'dedupExchange' deduplicates ongoing operations by their key. The 'cacheExchange' caches results and retrieves them by the operations' keys. The 'fetchExchange' sends operations to a GraphQL API and supports cancellation." />
225
-
226
-
By default there are three exchanges. The `dedupExchange` deduplicates operations with the same key, the
227
-
cache exchange handles caching and has a "document" strategy by default, and the `fetchExchange` is typically
228
-
the last exchange and sends operations to a GraphQL API.
229
-
230
-
There are also other exchanges, both built into `urql` and as separate packages, that can be used to add
231
-
more functionality, like the `subscriptionExchange` for instance.
232
-
233
-
[Learn more about Exchanges and how to write them in our Guides section!](https://formidable.com/open-source/urql/docs/guides/)
234
-
235
-
### Document Caching
236
-
237
-
The default cache in `urql` works like a document or page cache, for example like a browser would cache pages.
238
-
With this default `cacheExchange` results are cached by the operation key that requested them. This means that
239
-
each unique operation can have exactly one cached result.
240
-
241
-
These results are aggressively invalidated. Whenever you send a mutation, each result that contains `__typename`s
242
-
that also occur in the mutation result is invalidated.
243
-
244
-
<img width="736" src="docs/assets/urql-document-caching.png" alt="Diagram: First, a query is made that gets a type, in this example a 'Book'. The result contains the '__typename' field that says 'Book'. This is stored in a mapping of all types to the operations that contained this type. Later a mutation may change some data and will have overlapping types, in this example a 'Book' is liked. The mutation also contains a 'Book' so it retrieves the original operation that was getting a 'Book' and reexecutes and invalidates it." />
245
-
246
-
### Normalized Caching
247
-
248
-
You can opt into having a fully normalized cache by using the [`@urql/exchange-graphcache`](https://github.com/FormidableLabs/urql-exchange-graphcache)
249
-
package. The normalized cache is a cache that stores every separate entity in a big graph. Therefore multiple separate queries, subscriptions, and mutations
250
-
can update each other, if they contain overlapping data with the same type and ID.
251
-
252
-
<img width="466" src="docs/assets/urql-normalized-cache.png" alt="Diagram: A normalized cache contains a graph of different nodes. Queries point to different nodes, which point to other nodes, and so on and so forth. Nodes may be reused and are called 'entities'. Each entity corresponds to an object that came back from the API." />
253
-
254
-
Getting started with Graphcache is easy and is as simple as installing it and adding it to your client.
255
-
Afterwards it comes with a lot of ways to configure it so that less requests need to be sent to your API.
256
-
For instance, you can set up mutations to update unrelated queries in your cache or have optimistic updates.
257
-
258
-
```js
259
-
import { createClient, dedupExchange, fetchExchange } from 'urql';
260
-
import { cacheExchange } from '@urql/exchange-graphcache';
261
-
262
-
const client = createClient({
263
-
url: 'http://localhost:1234/graphql',
264
-
exchanges: [
265
-
dedupExchange,
266
-
// Replace the default cacheExchange with the new one
267
-
cacheExchange({
268
-
/* config */
269
-
}),
270
-
fetchExchange,
271
-
],
272
-
});
273
-
```
274
-
275
-
`urql`'s normalized cache is a little different than ones that you may find in other GraphQL client libraries.
276
-
It focuses on doing the right thing and being intuitive whenever possible, hence it has a lot of warnings that
277
-
may be logged during development that tell you what may be going wrong at any given point in time.
278
-
279
-
It also supports "schema awareness". By adding introspected schema data it becomes able to deliver safe, partial
280
-
GraphQL results entirely from cache and to match fragments to interfaces deterministically.
281
-
282
-
[Read more about _Graphcache_ on its repository!](https://github.com/FormidableLabs/urql-exchange-graphcache)
283
-
284
-
### Server-side Rendering
285
-
286
-
`urql` supports server-side rendering via its **suspense mode** and its `ssrExchange`.
287
-
When setting up SSR you will need to set `suspense: true` on the `Client` for the server-side
288
-
and add an `ssrExchange`.
289
-
290
-
```js
291
-
import {
292
-
Client,
293
-
dedupExchange,
294
-
cacheExchange,
295
-
fetchExchange,
296
-
ssrExchange,
297
-
} from 'urql';
45
+
## 📃 [Documentation](https://formidable.com/open-source/urql/docs/)
298
46
299
-
// Depending on your build process you may want to use one of these checks:
300
-
const isServer = typeof window !== 'object' || process.browser;
47
+
The documentation contains everything you need to know about `urql`, and contains several sections in order of importance
48
+
when you first get started:
301
49
302
-
const ssrCache = ssrExchange({ isClient: !isServer });
50
+
- **[Basics](https://formidable.com/open-source/urql/docs/basics/)** — contains the ["Getting Started" guide](https://formidable.com/open-source/urql/docs/basics/getting-started/) and all you need to know when first using `urql`.
51
+
- **[Main Concepts](https://formidable.com/open-source/urql/docs/concepts/)** — explains how `urql` functions and is built and covers GraphQL clients in general, on the ["Philosophy" page](https://formidable.com/open-source/urql/docs/concepts/philosophy).
52
+
- **[Advanced](https://formidable.com/open-source/urql/docs/advanced/)** — covers more uncommon use-cases and things you don't immediately need when getting started.
53
+
- **[Graphcache](https://formidable.com/open-source/urql/docs/graphcache/)** — documents ["Normalized Caching" support](https://formidable.com/open-source/urql/docs/graphcache/normalized-caching/) which enables more complex apps and use-cases.
54
+
- **[API](https://formidable-com-urql-staging-595.surge.sh/docs/api/)** — the API documentation for each individual package.
303
55
304
-
const client = new Client({
305
-
suspense: isServer
306
-
exchanges: [
307
-
dedupExchange,
308
-
cacheExchange,
309
-
// Add this after the cacheExchange but before fetchExchange:
310
-
ssrCache,
311
-
fetchExchange
312
-
]
313
-
});
314
-
```
315
-
316
-
The `ssrExchange` is another small cache that stores full results temporarily.
317
-
On the server you may call `ssrCache.extractData()` to get the serialisable data
318
-
for the server's SSR data, while on the client you can call `ssrCache.restoreData(...)`
319
-
to restore the server's SSR data.
320
-
321
-
[Read more about SSR in our Basics' SSR section!](https://formidable.com/open-source/urql/docs/basics/#server-side-rendering)
322
-
323
-
### Client-side Suspense
324
-
325
-
You may also activate the Client's suspense mode on the client-side and use React Suspense for
326
-
data loading in your entire app! This requires you to use the [`@urql/exchange-suspense`](https://github.com/FormidableLabs/urql-exchange-suspense)
327
-
package.
328
-
329
-
```js
330
-
import { Client, dedupExchange, cacheExchange, fetchExchange } from 'urql';
331
-
332
-
import { suspenseExchange } from '@urql/exchange-suspense';
333
-
334
-
const client = new Client({
335
-
url: 'http://localhost:1234/graphql',
336
-
suspense: true, // Enable suspense mode
337
-
exchanges: [
338
-
dedupExchange,
339
-
suspenseExchange, // Add suspenseExchange to your urql exchanges
340
-
cacheExchange,
341
-
fetchExchange,
342
-
],
343
-
});
344
-
```
345
-
346
-
## 📦 Ecosystem
347
-
348
-
`urql` has an extended ecosystem of additional packages that either are ["Exchanges" which extend
349
-
`urql`'s core functionality](https://formidable.com/open-source/urql/docs/architecture/#exchanges)
350
-
or are built to make certain tasks easier.
351
-
352
-
- [`@urql/devtools`](https://github.com/FormidableLabs/urql-devtools): A Chrome extension for monitoring and debugging
353
-
- [`@urql/exchange-graphcache`](https://github.com/FormidableLabs/urql/tree/master/exchanges/graphcache): A full normalized cache implementation
354
-
- [`@urql/exchange-suspense`](https://github.com/FormidableLabs/urql-exchange-suspense): An experimental exchange for using `<React.Suspense>`
355
-
- [`next-urql`](https://github.com/FormidableLabs/next-urql): Helpers for adding `urql` to [Next.js](https://github.com/zeit/next.js/) with SSR support
356
-
- [`reason-urql`](https://github.com/FormidableLabs/reason-urql): Reason bindings for `urql`
357
-
- [`urql-persisted-queries`](https://github.com/Daniel15/urql-persisted-queries): An exchange for adding persisted query support
358
-
- [`@urql/preact`](https://github.com/FormidableLabs/urql/tree/master/packages/preact-urql): Preact implementation of urql hooks and components
359
-
360
-
[You can find the full list of exchanges in the docs.](./docs/exchanges.md)
361
-
362
-
## 💡 Examples
363
-
364
-
There are currently three examples included in this repository:
365
-
366
-
- [Getting Started: A basic app with queries and mutations](examples/1-getting-started/)
367
-
- [Using Subscriptions: An app that demos subscriptions](examples/2-using-subscriptions/)
368
-
- [SSR with Next: A Next.js app showing server-side-rendering support](examples/3-ssr-with-nextjs/)
56
+
_You can find the raw markdown files inside this repository's `docs` folder._
369
57
370
58
## Maintenance Status
371
59
+3
-87
exchanges/graphcache/README.md
+3
-87
exchanges/graphcache/README.md
···
25
25
26
26
`urql` is already quite a comprehensive GraphQL client. However in several cases it may be
27
27
desirable to have data update across the entirety of an app when a response updates some
28
-
known pieces of data. This cache also provides configurable APIs to:
29
-
30
-
- resolve Query data from the offline cache
31
-
- update Query data after mutations/subscriptions responses
32
-
- provide optimistic Mutation responses
28
+
known pieces of data.
33
29
34
-
> ⚠️ Note: Documentation for some parts of `@urql/exchange-graphcache` are still being worked on!
35
-
> For help or features requests, please join our [Spectrum](https://spectrum.chat/urql).
30
+
[Learn more about Graphcache and normalized caching on our docs!](https://formidable.com/open-source/urql/docs/graphcache/)
36
31
37
32
## Quick Start Guide
38
33
···
49
44
50
45
```js
51
46
import { createClient, dedupExchange, fetchExchange } from 'urql';
52
-
53
47
import { cacheExchange } from '@urql/exchange-graphcache';
54
48
55
49
const client = createClient({
···
58
52
dedupExchange,
59
53
// Replace the default cacheExchange with the new one
60
54
cacheExchange({
61
-
/* config */
55
+
/* optional config */
62
56
}),
63
57
fetchExchange,
64
58
],
···
74
68
- [x] Optimistic updates
75
69
- [ ] Basic offline and persistence support
76
70
- [ ] Advanced fragment and entity invalidation
77
-
78
-
This cache defaults to **delivering safe results** by marking results as incomplete
79
-
when any field is missing, triggering a `network-only` operation (a request), when
80
-
it encounters uncached fields.
81
-
82
-
Furthermore there's one case in caching where only having the `__typename` field
83
-
leads to potentially unsafe behaviour: **interfaces**. When the cache encounters a
84
-
fragment that tries to get data for an interface, it can't tell whether the
85
-
cached type matches the interface. In this case we resort to a heuristic
86
-
by default. When all fields of the fragment are on the target type, then the
87
-
fragment matches successfully and we log a warning.
88
-
89
-
Schema awareness has been introduced to the cache to improve this behaviour.
90
-
When you pass your API's GraphQL schema to the cache, it becomes able to
91
-
deliver **partial results**. When the cache has enough information so that
92
-
only **optional fields** in a given query are missing, then it delivers
93
-
a partial result from the cached data. Subsequently it still issues a network
94
-
request (like with `cache-and-network`) to ensure that all information will
95
-
still be delivered eventually.
96
-
97
-
With a schema the cache can also match fragments that refer to interfaces
98
-
**deterministically**, since it can look at the schema to match fragments
99
-
against types.
100
-
101
-
Schema awareness is also an important stepping stone for offline support.
102
-
Without partial results it becomes difficult to deliver an offline UI
103
-
safely, when just some bits of information are missing.
104
-
105
-
Read more about the [architecture](../../docs/graphcache/architecture.md)
106
-
107
-
## Usage
108
-
109
-
You can currently configure:
110
-
111
-
- `resolvers`: A nested `['__typename'][fieldName]` map to resolve results from cache
112
-
- `updates`: A Mutation/Subscription field map to apply side-effect updates to the cache
113
-
- `optimistic`: A mutation field map to supply optimistic mutation responses
114
-
- `keys`: A `__typename` map of functions to generate keys with
115
-
- `schema`: An introspected GraphQL schema in JSON format. When it's passed the cache will
116
-
deliver partial results and enable deterministic fragment matching.
117
-
118
-
> Note that you don't need any of these options to get started
119
-
120
-
### Keys
121
-
122
-
Keys are used when you need a slight alteration to the value of your identifier or
123
-
when the identifier is a non-traditional property.
124
-
125
-
[Read more](../../docs/graphcache/keys.md)
126
-
127
-
### Resolvers
128
-
129
-
Resolvers are needed when you want to do additional resolving, for example do some
130
-
custom date formatting.
131
-
132
-
[Read more](../../docs/graphcache/resolvers.md)
133
-
134
-
### Updates
135
-
136
-
The graph cache will automatically handle updates but some things are quite hard to
137
-
incorporate. Let's say you delete/add an item, it's hard for us to know you wanted to
138
-
delete or where to add an item in a list.
139
-
140
-
[Read more](../../docs/graphcache/updates.md)
141
-
142
-
### Optimistic
143
-
144
-
Here you can configure optimistic responses, this means that we don't wait for the server
145
-
to respond but offer the user to instantly replace the data with the variables from the
146
-
mutation.
147
-
148
-
[Read more](../../docs/graphcache/optimistic.md)
149
-
150
-
### Schema
151
-
152
-
Our way to see what your backend schema looks like, this offers additional functionality.
153
-
154
-
[Read more](../../docs/graphcache/schema.md)
155
71
156
72
## Maintenance Status
157
73
+1
-1
exchanges/graphcache/package.json
+1
-1
exchanges/graphcache/package.json
···
3
3
"version": "2.2.2",
4
4
"description": "A normalized and configurable cache exchange for urql",
5
5
"sideEffects": false,
6
-
"homepage": "https://formidable.com/open-source/urql/docs/",
6
+
"homepage": "https://formidable.com/open-source/urql/docs/graphcache",
7
7
"bugs": "https://github.com/FormidableLabs/urql/issues",
8
8
"license": "MIT",
9
9
"repository": {
+3
-7
exchanges/populate/README.md
+3
-7
exchanges/populate/README.md
···
2
2
3
3
`populate` is an exchange for auto-populating fields in your mutations.
4
4
5
+
[Read more about the `populateExchange` on our docs!](https://formidable.com/open-source/urql/docs/advanced/auto-populate-mutations)
6
+
5
7
## Quick Start Guide
6
8
7
9
First install `@urql/exchange-populate` alongside `urql`:
···
20
22
21
23
const client = createClient({
22
24
url: 'http://localhost:1234/graphql',
23
-
exchanges: [
24
-
dedupExchange,
25
-
populateExchange,
26
-
cacheExchange,
27
-
fetchExchange,
28
-
],
25
+
exchanges: [dedupExchange, populateExchange, cacheExchange, fetchExchange],
29
26
});
30
27
```
31
28
32
29
## Example usage
33
30
34
31
Consider the following queries which have been requested in other parts of your application:
35
-
36
32
37
33
```graphql
38
34
# Query 1
+1
-1
exchanges/populate/package.json
+1
-1
exchanges/populate/package.json
···
3
3
"version": "0.1.1",
4
4
"description": "An exchange that automaticcally populates the mutation selection body",
5
5
"sideEffects": false,
6
-
"homepage": "https://formidable.com/open-source/urql/docs/",
6
+
"homepage": "https://formidable.com/open-source/urql/docs/advanced/auto-populate-mutations",
7
7
"bugs": "https://github.com/FormidableLabs/urql/issues",
8
8
"license": "MIT",
9
9
"repository": {