commit 699089ddc74ba5149f2b5d6cc0f747dc379f99b7 · kitten.sh/urql

+2 -3

docs/advanced/authentication.md

···

       51
       51
        
       in front of all `fetchExchange`s but after all other synchronous exchanges, like the `cacheExchange`.

     

       52
       52
        
       

     

       53
       53
        
       ```js

     

       54
       54
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       54
       54
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       55
       55
        
       import { authExchange } from '@urql/exchange-auth';

     

       56
       56
        
       

     

       57
       57
       -
       const client = createClient({

     

       57
       57
       +
       const client = new Client({

     

       58
       58
        
         url: 'http://localhost:3000/graphql',

     

       59
       59
        
         exchanges: [

     

       60
       60
       -
           dedupExchange,

     

       61
       60
        
           cacheExchange,

     

       62
       61
        
           authExchange(async utils => {

     

       63
       62
        
             return {

+29 -29

docs/advanced/authoring-exchanges.md

···

       41
       41
        
       

     

       42
       42
        
       ## Using Exchanges

     

       43
       43
        
       

     

       44
       44
       -
       The `Client` accepts an `exchanges` option that defaults to the three default exchanges mentioned above. When we pass a custom list of exchanges the `Client` uses the `composeExchanges`

     

       45
       45
       -
       utility, which starts chaining these exchanges.

     

       44
       44
       +
       The `Client` accepts an `exchanges` option that. Initially, we may choose to just

     

       45
       45
       +
       set this to two very standard exchanges — `cacheExchange` and `fetchExchange`.

     

       46
       46
        
       

     

       47
       47
        
       In essence these exchanges build a pipeline that runs in the order they're passed; _Operations_ flow

     

       48
       48
        
       in from the start to the end, and _Results_ are returned through the chain in reverse.

     

       49
       49
        
       

     

       50
       50
       -
       If we look at our list of default exchanges — `dedupExchange`, `cacheExchange`, and then

     

       51
       51
       -
       `fetchExchange` — an incoming operation is treated as follows:

     

       50
       50
       +
       Suppose we pass the `cacheExchange` and then the `fetchExchange` to the `exchanges`.

     

       52
       51
        
       

     

       53
       53
       -
       **First,** ongoing operations are deduplicated. It wouldn't make sense to send the

     

       54
       54
       -
       same operation / request twice in parallel.

     

       55
       55
       -
       

     

       56
       56
       -
       **Second,** operations are checked against the cache. Depending on the `requestPolicy`,

     

       52
       52
       +
       **First,** operations are checked against the cache. Depending on the `requestPolicy`,

     

       57
       53
        
       cached results can be resolved from here instead, which would mean that the cache sends back the

     

       58
       54
        
       result, and the operation doesn't travel any further in the chain.

     

       59
       55
        
       

     

       60
       60
       -
       **Third,** operations are sent to the API, and the result is turned into an `OperationResult`.

     

       56
       56
       +
       **Second,** operations are sent to the API, and the result is turned into an `OperationResult`.

     

       61
       57
        
       

     

       62
       58
        
       **Lastly,** operation results then travel through the exchanges in _reverse order_, which is because

     

       63
       59
        
       exchanges are a pipeline where all operations travel forward deeper into the exchange chain, and

     
···

       65
       61
        
       result.

     

       66
       62
        
       

     

       67
       63
        
       ```js

     

       68
       68
       -
       import { createClient, dedupExchange, fetchExchange, cacheExchange } from 'urql';

     

       64
       64
       +
       import { Client, fetchExchange, cacheExchange } from 'urql';

     

       69
       65
        
       

     

       70
       70
       -
       const client = createClient({

     

       66
       66
       +
       const client = new Client({

     

       71
       67
        
         url: 'http://localhost:3000/graphql',

     

       72
       72
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       68
       68
       +
         exchanges: [cacheExchange, fetchExchange],

     

       73
       69
        
       });

     

       74
       70
        
       ```

     

       75
       71
        
       

     

       76
       76
       -
       We can add more exchanges to this chain, for instance, we can add the `errorExchange`, which calls a

     

       77
       77
       -
       global callback whenever it sees [a `CombinedError`](../basics/errors.md) on an `OperationResult`.

     

       72
       72
       +
       We can add more exchanges to this chain, for instance, we can add the `mapExchange`, which can call a

     

       73
       73
       +
       callback whenever it sees [a `CombinedError`](../basics/errors.md) occur on a result.

     

       78
       74
        
       

     

       79
       75
        
       ```js

     

       80
       80
       -
       import { createClient, dedupExchange, fetchExchange, cacheExchange, errorExchange } from 'urql';

     

       76
       76
       +
       import { Client, fetchExchange, cacheExchange, mapExchange } from 'urql';

     

       81
       77
        
       

     

       82
       82
       -
       const client = createClient({

     

       78
       78
       +
       const client = new Client({

     

       83
       79
        
         url: 'http://localhost:3000/graphql',

     

       84
       80
        
         exchanges: [

     

       85
       85
       -
           dedupExchange,

     

       86
       81
        
           cacheExchange,

     

       87
       87
       -
           errorExchange({

     

       82
       82
       +
           mapExchange({

     

       88
       83
        
             onError(error) {

     

       89
       84
        
               console.error(error);

     

       90
       85
        
             },

     
···

       123
       118
        
       ### Forward and Return Composition

     

       124
       119
        
       

     

       125
       120
        
       When you create a `Client` and pass it an array of exchanges, `urql` composes them left-to-right.

     

       126
       126
       -
       If we look at our previous `noopExchange` example in context, we can track what it does if it is located between the `dedupExchange` and the `fetchExchange`.

     

       121
       121
       +
       If we look at our previous `noopExchange` example in context, we can track what it does if it is located between the `cacheExchange` and the `fetchExchange`.

     

       127
       122
        
       

     

       128
       123
        
       ```js

     

       129
       129
       -
       import { Client, dedupExchange, fetchExchange } from 'urql';

     

       124
       124
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       130
       125
        
       

     

       131
       126
        
       const noopExchange = ({ client, forward }) => {

     

       132
       127
        
         return operations$ => {

     

       133
       128
        
           // <-- The ExchangeIO function

     

       134
       134
       -
           // We receive a stream of Operations from `dedupExchange` which

     

       129
       129
       +
           // We receive a stream of Operations from `cacheExchange` which

     

       135
       130
        
           // we can modify before...

     

       136
       131
        
           const forwardOperations$ = operations$;

     

       137
       132
        
       

     
···

       141
       136
        
           const operationResult$ = forward(operations$);

     

       142
       137
        
       

     

       143
       138
        
           // We get back `fetchExchange`'s stream of results, which we can

     

       144
       144
       -
           // also change before returning, which is what `dedupExchange`

     

       139
       139
       +
           // also change before returning, which is what `cacheExchange`

     

       145
       140
        
           // will receive when calling `forward`.

     

       146
       141
        
           return operationResult$;

     

       147
       142
        
         };

     

       148
       143
        
       };

     

       149
       144
        
       

     

       150
       145
        
       const client = new Client({

     

       151
       151
       -
         exchanges: [dedupExchange, noopExchange, fetchExchange],

     

       146
       146
       +
         exchanges: [cacheExchange, noopExchange, fetchExchange],

     

       152
       147
        
       });

     

       153
       148
        
       ```

     

       154
       149
        
       

     
···

       215
       210
        
       This why **all exchanges should be ordered synchronous first and

     

       216
       211
        
       asynchronous last**.

     

       217
       212
        
       

     

       218
       218
       -
       The default order of exchanges is:

     

       213
       213
       +
       What we for instance repeat as the default setup in our docs is this:

     

       219
       214
        
       

     

       220
       215
        
       ```js

     

       221
       221
       -
       import { dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       216
       216
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       222
       217
        
       

     

       223
       223
       -
       [dedupExchange, cacheExchange, fetchExchange];

     

       218
       218
       +
       new Client({

     

       219
       219
       +
         // ...

     

       220
       220
       +
         exchanges: [cacheExchange, fetchExchange];

     

       221
       221
       +
       });

     

       224
       222
        
       ```

     

       225
       223
        
       

     

       226
       226
       -
       Both the `dedupExchange` and `cacheExchange` are completely

     

       227
       227
       -
       synchronous. The `fetchExchange` is asynchronous since

     

       228
       228
       -
       it makes a `fetch` request and waits for a server response.

     

       224
       224
       +
       The `cacheExchange` is completely synchronous.

     

       225
       225
       +
       The `fetchExchange` is asynchronous since it makes a `fetch` request and waits for a server response.

     

       226
       226
       +
       If we put an asynchronous exchange in front of the `cacheExchange`, that would be unexpected, and

     

       227
       227
       +
       since all results would then be delayed, nothing would ever be "cached" and instead always take some

     

       228
       228
       +
       amount of time to be returned.

     

       229
       229
        
       

     

       230
       230
        
       When you're adding more exchanges, it's often crucial

     

       231
       231
        
       to put them in a specific order. For instance, an authentication exchange

+4 -4

docs/advanced/auto-populate-mutations.md

···

       28
       28
        
       client options.

     

       29
       29
        
       

     

       30
       30
        
       ```ts

     

       31
       31
       -
       import { createClient, dedupExchange, fetchExchange } from '@urql/core';

     

       31
       31
       +
       import { Client, fetchExchange } from '@urql/core';

     

       32
       32
        
       import { populateExchange } from '@urql/exchange-populate';

     

       33
       33
        
       

     

       34
       34
       -
       const client = createClient({

     

       34
       34
       +
       const client = new Client({

     

       35
       35
        
         // ...

     

       36
       36
       -
         exchanges: [dedupExchange, populateExchange({ schema }), cacheExchange, fetchExchange],

     

       36
       36
       +
         exchanges: [populateExchange({ schema }), cacheExchange, fetchExchange],

     

       37
       37
        
       });

     

       38
       38
        
       ```

     

       39
       39
        
       

     

       40
       40
        
       The `populateExchange` should be placed in front of the `cacheExchange`, especially if you're using

     

       41
       41
        
       [Graphcache](../graphcache/README.md), since it won't understand the `@populate` directive on its

     

       42
       42
       -
       own. It should also be placed after the `dedupExchange` to avoid unnecessary work.

     

       42
       42
       +
       own. It should also be placed in front the `cacheExchange` to avoid unnecessary work.

     

       43
       43
        
       

     

       44
       44
        
       Adding the `populateExchange` now enables us to use the `@populate` directive in our mutations.

     

       45
       45

+1 -1

docs/advanced/debugging.md

···

       46
       46
        
       

     

       47
       47
        
       ```

     

       48
       48
        
       const { unsubscribe } = client.subscribeToDebugTarget(event => {

     

       49
       49
       -
         if (event.source === 'dedupExchange')

     

       49
       49
       +
         if (event.source === 'cacheExchange')

     

       50
       50
        
           return;

     

       51
       51
        
         console.log(event); // { type, message, operation, data, source, timestamp }

     

       52
       52
        
       });

+34 -34

docs/advanced/persistence-and-uploads.md

···

       5
       5
        
       

     

       6
       6
        
       # Persisted Queries and Uploads

     

       7
       7
        
       

     

       8
       8
       -
       `urql` supports both [Automatic Persisted

     

       9
       9
       -
       Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/), Persisted Queries, and

     

       10
       10
       -
       [File Uploads](https://www.apollographql.com/docs/apollo-server/data/file-uploads/).

     

       11
       11
       -
       

     

       12
       12
       -
       While File Uploads should work without any modifications, an additional exchange must be installed

     

       13
       13
       -
       and added for Persisted Queries to work.

     

       8
       8
       +
       `urql` supports (Automatic) Persisted Queries, and File Uploads via GraphQL

     

       9
       9
       +
       Multipart requests. For persisted queries to work, some setup work is needed,

     

       10
       10
       +
       while File Upload support is built into `@urql/core@4`.

     

       14
       11
        
       

     

       15
       12
        
       ## Automatic Persisted Queries

     

       16
       13
        
       

     
···

       31
       28
        
       easier for a CDN to cache, as by default most caches would not cache POST requests automatically.

     

       32
       29
        
       

     

       33
       30
        
       In `urql`, we may use the `@urql/exchange-persisted` package's `persistedExchange` to

     

       34
       34
       -
       implement Automatic Persisted Queries. This exchange works alongside the default `fetchExchange`

     

       35
       35
       -
       and other exchanges by adding the `extensions.persistedQuery` parameters to a GraphQL request.

     

       31
       31
       +
       enable support for Automatic Persisted Queries. This exchange works alongside other fetch or

     

       32
       32
       +
       subscription exchanges by adding metadata for persisted queries to each GraphQL

     

       33
       33
       +
       request by modifying the `extensions` object of operations.

     

       36
       34
        
       

     

       37
       35
        
       ### Installation & Setup

     

       38
       36
        
       

     
···

       45
       43
        
       ```

     

       46
       44
        
       

     

       47
       45
        
       You'll then need to add the `persistedExchange` function, that this package exposes,

     

       48
       48
       -
       to your `exchanges`.

     

       46
       46
       +
       to your `exchanges`, in front of exchanges that communicate with the API:

     

       49
       47
        
       

     

       50
       48
        
       ```js

     

       51
       51
       -
       import { createClient, dedupExchange, fetchExchange, cacheExchange } from 'urql';

     

       52
       52
       -
       import { persistedExchange } from '@urql/exchange-persisted-fetch';

     

       49
       49
       +
       import { Client, fetchExchange, cacheExchange } from 'urql';

     

       50
       50
       +
       import { persistedExchange } from '@urql/exchange-persisted';

     

       53
       51
        
       

     

       54
       54
       -
       const client = createClient({

     

       52
       52
       +
       const client = new Client({

     

       55
       53
        
         url: 'http://localhost:1234/graphql',

     

       56
       54
        
         exchanges: [

     

       57
       57
       -
           dedupExchange,

     

       58
       55
        
           cacheExchange,

     

       59
       56
        
           persistedExchange({

     

       60
       57
        
             preferGetForPersistedQueries: true,

     
···

       66
       63
        
       

     

       67
       64
        
       As we can see, typically it's recommended to set `preferGetForPersistedQueries` to `true` to force

     

       68
       65
        
       all persisted queries to use GET requests instead of POST so that CDNs can do their job.

     

       69
       69
       -
       We also added the `persistedExchange` in front of the usual `fetchExchange`, since it has to

     

       70
       70
       -
       update operations before they reach an exchange that talks to an API.

     

       66
       66
       +
       It does so by setting the `preferGetMethod` option to `'force'` when it's

     

       67
       67
       +
       updating operations.

     

       71
       68
        
       

     

       72
       72
       -
       The `preferGetForPersistedQueries` is similar to the [`Client`'s

     

       73
       73
       -
       `preferGetMethod`](../api/core.md#client) but only switches persisted queries to use GET requests

     

       74
       74
       -
       instead. This is preferable since sometimes the GraphQL query can grow too large for a simple GET

     

       75
       75
       -
       query to handle, while the `persistedExchange`'s SHA256 hashes will remain predictably small.

     

       69
       69
       +
       The `fetchExchange` can see the modifications that the `persistedExchange` is

     

       70
       70
       +
       making to operations, and understands to leave out the `query` from any request

     

       71
       71
       +
       as needed. The same should be happening to the `subscriptionExchange`, if you're

     

       72
       72
       +
       using it for queries.

     

       76
       73
        
       

     

       77
       74
        
       ### Customizing Hashing

     

       78
       75
        
       

     
···

       89
       86
        
       second argument, a GraphQL `DocumentNode` object.

     

       90
       87
        
       

     

       91
       88
        
       ```js

     

       92
       92
       -
       persistedFetchExchange({

     

       89
       89
       +
       persistedExchange({

     

       93
       90
        
         generateHash: (_, document) => document.documentId,

     

       94
       91
        
       });

     

       95
       92
        
       ```

     
···

       101
       98
        
       ```js

     

       102
       99
        
       import sha256 from 'hash.js/lib/hash/sha/256';

     

       103
       100
        
       

     

       104
       104
       -
       persistedFetchExchange({

     

       105
       105
       -
         generateHash: async query => {

     

       101
       101
       +
       persistedExchange({

     

       102
       102
       +
         async generateHash(query) {

     

       106
       103
        
           return sha256().update(query).digest('hex');

     

       107
       104
        
         },

     

       108
       105
        
       });

     
···

       115
       112
        
       

     

       116
       113
        
       ## File Uploads

     

       117
       114
        
       

     

       118
       118
       -
       Many GraphQL server frameworks and APIs support the ["GraphQL Multipart Request

     

       119
       119
       -
       Spec](https://github.com/jaydenseric/graphql-multipart-request-spec) to allow files to be uploaded.

     

       120
       120
       -
       Often, this is defined in schemas using a `File` or `Upload` input.

     

       121
       121
       -
       This allows us to pass a `File` or `Blob` directly to our GraphQL requests as variables, and the

     

       122
       122
       -
       spec requires us to perform this request as a multipart upload.

     

       115
       115
       +
       GraphQL server APIs commonly support the [GraphQL Multipart Request

     

       116
       116
       +
       spec](https://github.com/jaydenseric/graphql-multipart-request-spec) to allow for File Uploads

     

       117
       117
       +
       directly with a GraphQL API.

     

       123
       118
        
       

     

       124
       124
       -
       Files are often handled in the browser via the [File API](https://developer.mozilla.org/en-US/docs/Web/API/File),

     

       125
       125
       -
       which we may typically get to via a [file input](https://developer.mozilla.org/en-US/docs/Web/API/File/Using_files_from_web_applications)

     

       119
       119
       +
       If a GraphQL API supports this, we can pass a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File)

     

       120
       120
       +
       or a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) directly into our variables and

     

       121
       121
       +
       define the corresponding scalar for our variable, which is often called `File` or `Upload`.

     

       122
       122
       +
       

     

       123
       123
       +
       In a browser, the `File` object may often be retrieved via a

     

       124
       124
       +
       [file input](https://developer.mozilla.org/en-US/docs/Web/API/File/Using_files_from_web_applications),

     

       126
       125
        
       for example.

     

       127
       126
        
       

     

       128
       128
       -
       In `urql`, these are supported natively, so as long as your JS environment supports either `File` or

     

       129
       129
       -
       `Blob`s, you can pass these directly to any `urql` API via your `variables`, and the default

     

       130
       130
       -
       `fetchExchange` will swich to using a multipart request instead.

     

       127
       127
       +
       The `@urql/core@4` package supports File Uploads natively, so we won't have to do any installation

     

       128
       128
       +
       or setup work. When `urql` sees a `File` or a `Blob` anywhere in your `variables`, it switches to

     

       129
       129
       +
       a `multipart/form-data` request, converts the request to a `FormData` object, according to the

     

       130
       130
       +
       GraphQL Multipart Request specification, and sends it off to the API.

     

       131
       131
        
       

     

       132
       132
       -
       Previously, this worked by installing the [`@urql/multipart-fetch-exchange` package](../api/multipart-fetch-exchange.md),

     

       133
       133
       -
       however, this package has been deprecated and file uploads are now built into `@urql/core`.

     

       132
       132
       +
       > **Note:** Previously, this worked by installing the `@urql/multipart-fetch-exchange` package.

     

       133
       133
       +
       > however, this package has been deprecated and file uploads are now built into `@urql/core@4`.

+5 -7

docs/advanced/retry-operations.md

···

       22
       22
        
       You'll then need to add the `retryExchange`, exposed by this package, to your `urql` Client:

     

       23
       23
        
       

     

       24
       24
        
       ```js

     

       25
       25
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       25
       25
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       26
       26
        
       import { retryExchange } from '@urql/exchange-retry';

     

       27
       27
        
       

     

       28
       28
        
       // None of these options have to be added, these are the default values.

     
···

       36
       36
        
       

     

       37
       37
        
       // Note the position of the retryExchange - it should be placed prior to the

     

       38
       38
        
       // fetchExchange and after the cacheExchange for it to function correctly

     

       39
       39
       -
       const client = createClient({

     

       39
       39
       +
       const client = new Client({

     

       40
       40
        
         url: 'http://localhost:1234/graphql',

     

       41
       41
        
         exchanges: [

     

       42
       42
       -
           dedupExchange,

     

       43
       42
        
           cacheExchange,

     

       44
       43
        
           retryExchange(options), // Use the retryExchange factory to add a new exchange

     

       45
       44
        
           fetchExchange,

     
···

       69
       68
        
       let's look at an example:

     

       70
       69
        
       

     

       71
       70
        
       ```js

     

       72
       72
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       71
       71
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       73
       72
        
       import { retryExchange } from '@urql/exchange-retry';

     

       74
       73
        
       

     

       75
       75
       -
       const client = createClient({

     

       74
       74
       +
       const client = new Client({

     

       76
       75
        
         url: 'http://localhost:1234/graphql',

     

       77
       76
        
         exchanges: [

     

       78
       78
       -
           dedupExchange,

     

       79
       77
        
           cacheExchange,

     

       80
       78
        
           retryExchange({

     

       81
       79
        
             retryIf: error => {

     

       82
       82
       -
               return !!(error.graphQLErrors.length > 0 || error.networkError);

     

       80
       80
       +
               return !!(error.graphQLErrors.length > 0 || error.networkError);

     

       83
       81
        
             },

     

       84
       82
        
           }),

     

       85
       83
        
           fetchExchange,

+6 -7

docs/advanced/server-side-rendering.md

···

       18
       18
        
       To start out with the `ssrExchange` we have to add the exchange to our `Client`:

     

       19
       19
        
       

     

       20
       20
        
       ```js

     

       21
       21
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange, ssrExchange } from '@urql/core';

     

       21
       21
       +
       import { Client, cacheExchange, fetchExchange, ssrExchange } from '@urql/core';

     

       22
       22
        
       

     

       23
       23
        
       const isServerSide = typeof window === 'undefined';

     

       24
       24
        
       

     
···

       28
       28
        
         initialState: !isServerSide ? window.__URQL_DATA__ : undefined,

     

       29
       29
        
       });

     

       30
       30
        
       

     

       31
       31
       -
       const client = createClient({

     

       31
       31
       +
       const client = new Client({

     

       32
       32
        
         exchanges: [

     

       33
       33
       -
           dedupExchange,

     

       34
       33
        
           cacheExchange,

     

       35
       34
        
           ssr, // Add `ssr` in front of the `fetchExchange`

     

       36
       35
        
           fetchExchange,

     
···

       113
       112
        
       import prepass from 'react-ssr-prepass';

     

       114
       113
        
       

     

       115
       114
        
       import {

     

       116
       116
       -
         createClient,

     

       117
       117
       -
         dedupExchange,

     

       115
       115
       +
         Client,

     

       118
       116
        
         cacheExchange,

     

       119
       117
        
         fetchExchange,

     

       120
       118
        
         ssrExchange,

     
···

       125
       123
        
         // ...

     

       126
       124
        
         const ssr = ssrExchange({ isClient: false });

     

       127
       125
        
       

     

       128
       128
       -
         const client createClient({

     

       126
       126
       +
         const client new Client({

     

       127
       127
       +
           url: 'https://??',

     

       129
       128
        
           suspense: true, // This activates urql's Suspense mode on the server-side

     

       130
       130
       -
           exchanges: [dedupExchange, cacheExchange, ssr, fetchExchange]

     

       129
       129
       +
           exchanges: [cacheExchange, ssr, fetchExchange]

     

       131
       130
        
         });

     

       132
       131
        
       

     

       133
       132
        
         const element = (

+13 -18

docs/advanced/subscriptions.md

···

       13
       13
        
       To add support for subscriptions we need to add the `subscriptionExchange` to our `Client`.

     

       14
       14
        
       

     

       15
       15
        
       ```js

     

       16
       16
       -
       import { Client, dedupExchange, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       16
       16
       +
       import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       17
       17
        
       

     

       18
       18
        
       const client = new Client({

     

       19
       19
        
         url: 'http://localhost:3000/graphql',

     

       20
       20
        
         exchanges: [

     

       21
       21
       -
           dedupExchange,

     

       22
       21
        
           cacheExchange,

     

       23
       22
        
           fetchExchange,

     

       24
       23
        
           subscriptionExchange({

     
···

       47
       46
        
       For backends supporting `graphql-ws`, we recommend using the [graphql-ws](https://github.com/enisdenjo/graphql-ws) client.

     

       48
       47
        
       

     

       49
       48
        
       ```js

     

       50
       50
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       49
       49
       +
       import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       51
       50
        
       import { createClient as createWSClient } from 'graphql-ws';

     

       52
       51
        
       

     

       53
       52
        
       const wsClient = createWSClient({

     

       54
       53
        
         url: 'ws://localhost/graphql',

     

       55
       54
        
       });

     

       56
       55
        
       

     

       57
       57
       -
       const client = createClient({

     

       56
       56
       +
       const client = new Client({

     

       58
       57
        
         url: '/graphql',

     

       59
       58
        
         exchanges: [

     

       60
       60
       -
           dedupExchange,

     

       61
       59
        
           cacheExchange,

     

       62
       60
        
           fetchExchange,

     

       63
       61
        
           subscriptionExchange({

     
···

       85
       83
        
       > The `subscriptions-transport-ws` package isn't actively maintained. If your API supports the new protocol or you can swap the package out, consider using [`graphql-ws`](#setting-up-graphql-ws) instead.

     

       86
       84
        
       

     

       87
       85
        
       ```js

     

       88
       88
       -
       import { Client, dedupExchange, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       86
       86
       +
       import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';

     

       89
       87
        
       import { SubscriptionClient } from 'subscriptions-transport-ws';

     

       90
       88
        
       

     

       91
       89
        
       const subscriptionClient = new SubscriptionClient('ws://localhost/graphql', { reconnect: true });

     
···

       93
       91
        
       const client = new Client({

     

       94
       92
        
         url: '/graphql',

     

       95
       93
        
         exchanges: [

     

       96
       96
       -
           dedupExchange,

     

       97
       94
        
           cacheExchange,

     

       98
       95
        
           fetchExchange,

     

       99
       96
        
           subscriptionExchange({

     
···

       195
       192
        
                 from

     

       196
       193
        
                 text

     

       197
       194
        
               }

     

       198
       198
       -
             }`

     

       199
       199
       -
           });

     

       195
       195
       +
             }

     

       196
       196
       +
           `,

     

       197
       197
       +
         });

     

       200
       198
        
       </script>

     

       201
       199
        
       

     

       202
       200
        
       {#if !$messages.data}

     
···

       267
       265
        
                   text

     

       268
       266
        
                 }

     

       269
       267
        
               }

     

       270
       270
       -
             `

     

       268
       268
       +
             `,

     

       271
       269
        
           }, handleSubscription)

     

       272
       270
        
       

     

       273
       271
        
           return {

     
···

       298
       296
        
       use subscriptions in a Node.js environment.

     

       299
       297
        
       

     

       300
       298
        
       ```js

     

       301
       301
       -
       import { pipe, subscribe } from 'wonka';

     

       299
       299
       +
       import { gql } from '@urql/core';

     

       302
       300
        
       

     

       303
       303
       -
       const MessageSub = `

     

       301
       301
       +
       const MessageSub = gql`

     

       304
       302
        
         subscription MessageSub {

     

       305
       303
        
           newMessages {

     

       306
       304
        
             id

     
···

       310
       308
        
         }

     

       311
       309
        
       `;

     

       312
       310
        
       

     

       313
       313
       -
       const { unsubscribe } = pipe(

     

       314
       314
       -
         client.subscription(MessageSub),

     

       315
       315
       -
         subscribe(result => {

     

       316
       316
       -
           console.log(result); // { data: ... }

     

       317
       317
       -
         })

     

       318
       318
       -
       );

     

       311
       311
       +
       const { unsubscribe } = client.subscription(MessageSub).subscribe(result => {

     

       312
       312
       +
         console.log(result); // { data: ... }

     

       313
       313
       +
       });

     

       319
       314
        
       ```

+5 -1

docs/api/README.md

···

       11
       11
        
       Most of these packages will refer to or use utilities and types from the `@urql/core` package. [Read

     

       12
       12
        
       more about the core package on the "Core" page.](../basics/core.md)

     

       13
       13
        
       

     

       14
       14
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       15
       15
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       16
       16
       +
       > TypeScript Language Server.

     

       17
       17
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       18
       18
       +
       

     

       14
       19
        
       - [`@urql/core` API docs](./core.md)

     

       15
       20
        
       - [`urql` React API docs](./urql.md)

     

       16
       21
        
       - [`@urql/preact` Preact API docs](./preact.md)

     
···

       18
       23
        
       - [`@urql/exchange-graphcache` API docs](./graphcache.md)

     

       19
       24
        
       - [`@urql/exchange-retry` API docs](./retry-exchange.md)

     

       20
       25
        
       - [`@urql/exchange-execute` API docs](./execute-exchange.md)

     

       21
       21
       -
       - [`@urql/exchange-multipart-fetch` API docs](./multipart-fetch-exchange.md)

     

       22
       26
        
       - [`@urql/exchange-request-policy` API docs](./request-policy-exchange.md)

     

       23
       27
        
       - [`@urql/exchange-auth` API docs](./auth-exchange.md)

     

       24
       28
        
       - [`@urql/exchange-refocus` API docs](./refocus-exchange.md)

docs/api/auth-exchange.md

···

       5
       5
        
       

     

       6
       6
        
       # Authentication Exchange

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/exchange-auth` package contains an addon `authExchange` for `urql` that aims to make it

     

       9
       14
        
       easy to implement complex authentication and reauthentication flows as are typically found with JWT

     

       10
       15
        
       token based API authentication.

+6 -1

docs/api/core.md

···

       5
       5
        
       

     

       6
       6
        
       # @urql/core

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/core` package is the basis of all framework bindings. Each bindings-package,

     

       9
       14
        
       like [`urql` for React](./urql.md) or [`@urql/preact`](./preact.md), will reuse the core logic and

     

       10
       15
        
       reexport all exports from `@urql/core`.

     
···

       22
       27
        
       

     

       23
       28
        
       | Input             | Type                                        | Description                                                                                                                                                                                                                                                                                                    |

     

       24
       29
        
       | ----------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

     

       25
       25
       -
       | `exchanges`       | `Exchange[]`                                | An array of `Exchange`s that the client should use                                                                                                                                                                                                                   |

     

       30
       30
       +
       | `exchanges`       | `Exchange[]`                                | An array of `Exchange`s that the client should use                                                                                                                                                                                                                                                             |

     

       26
       31
        
       | `url`             | `string`                                    | The GraphQL API URL as used by `fetchExchange`                                                                                                                                                                                                                                                                 |

     

       27
       32
        
       | `fetchOptions`    | `RequestInit \| () => RequestInit`          | Additional `fetchOptions` that `fetch` in `fetchExchange` should use to make a request                                                                                                                                                                                                                         |

     

       28
       33
        
       | `fetch`           | `typeof fetch`                              | An alternative implementation of `fetch` that will be used by the `fetchExchange` instead of `window.fetch`                                                                                                                                                                                                    |

docs/api/execute-exchange.md

···

       5
       5
        
       

     

       6
       6
        
       # Execute Exchange

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/exchange-execute` package contains an addon `executeExchange` for `urql` that may be used to

     

       9
       14
        
       execute queries against a local schema. It is therefore a drop-in replacement for the default

     

       10
       15
        
       _fetchExchange_ and useful for the server-side, debugging, or testing.

docs/api/graphcache.md

···

       5
       5
        
       

     

       6
       6
        
       # @urql/exchange-graphcache

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/exchange-graphcache` package contains an addon `cacheExchange` for `urql` that may be

     

       9
       14
        
       used to replace the default [`cacheExchange`](./core.md#cacheexchange), which switches `urql` from

     

       10
       15
        
       using ["Document Caching"](../basics/document-caching.md) to ["Normalized

-46

docs/api/multipart-fetch-exchange.md

···

       1
       1
       -
       ---

     

       2
       2
       -
       title: '@urql/exchange-multipart-fetch'

     

       3
       3
       -
       order: 7

     

       4
       4
       -
       ---

     

       5
       5
       -
       

     

       6
       6
       -
       # Multipart Fetch Exchange

     

       7
       7
       -
       

     

       8
       8
       -
       > **Deprecation**: The `multipartFetchExchange` has been deprecated, and

     

       9
       9
       -
       > `@urql/core` now supports GraphQL Multipart Requests natively. This won't

     

       10
       10
       -
       > break the behaviour of your existing apps, however, it's recommended to remove

     

       11
       11
       -
       > the `multipartFetchExchange` from your apps.

     

       12
       12
       -
       

     

       13
       13
       -
       The `@urql/exchange-multipart-fetch` package contains an addon `multipartFetchExchange` for `urql`

     

       14
       14
       -
       that enables file uploads via `multipart/form-data` POST requests.

     

       15
       15
       -
       

     

       16
       16
       -
       It follows the unofficial [GraphQL Multipart Request

     

       17
       17
       -
       Spec](https://github.com/jaydenseric/graphql-multipart-request-spec) which is supported by the

     

       18
       18
       -
       [Apollo Sever package](https://www.apollographql.com/docs/apollo-server/data/file-uploads/).

     

       19
       19
       -
       

     

       20
       20
       -
       This exchange uses the same fetch logic as the [`fetchExchange`](./core.md#fetchexchange) and by reusing logic from `@urql/core/internal`.

     

       21
       21
       -
       The `multipartFetchExchange` is a drop-in replacement for the default

     

       22
       22
       -
       [`fetchExchange`](./core.md#fetchexchange) and will act exactly like the `fetchExchange` unless the

     

       23
       23
       -
       `variables` that it receives for mutations contain any `File`s as detected by the `extract-files` package.

     

       24
       24
       -
       

     

       25
       25
       -
       ## Installation and Setup

     

       26
       26
       -
       

     

       27
       27
       -
       First install `@urql/exchange-multipart-fetch` alongside `urql`:

     

       28
       28
       -
       

     

       29
       29
       -
       ```sh

     

       30
       30
       -
       yarn add @urql/exchange-multipart-fetch

     

       31
       31
       -
       # or

     

       32
       32
       -
       npm install --save @urql/exchange-multipart-fetch

     

       33
       33
       -
       ```

     

       34
       34
       -
       

     

       35
       35
       -
       The `multipartFetchExchange` is a drop-in replacement for the `fetchExchange`, which should be

     

       36
       36
       -
       replaced in the list of `exchanges`:

     

       37
       37
       -
       

     

       38
       38
       -
       ```js

     

       39
       39
       -
       import { createClient, dedupExchange, cacheExchange } from 'urql';

     

       40
       40
       -
       import { multipartFetchExchange } from '@urql/exchange-multipart-fetch';

     

       41
       41
       -
       

     

       42
       42
       -
       const client = createClient({

     

       43
       43
       -
         url: 'http://localhost:3000/graphql',

     

       44
       44
       -
         exchanges: [dedupExchange, cacheExchange, multipartFetchExchange],

     

       45
       45
       -
       });

     

       46
       46
       -
       ```

docs/api/preact.md

···

       5
       5
        
       

     

       6
       6
        
       # @urql/preact

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/preact` API is the same as the React `urql` API.

     

       9
       14
        
       Please refer to [the "urql" API docs](./urql.md) for details on the Preact API.

docs/api/refocus-exchange.md

···

       5
       5
        
       

     

       6
       6
        
       # Refocus Exchange

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       `@urql/exchange-refocus` is an exchange for the `urql` that tracks currently active operations and redispatches them when the

     

       9
       14
        
       window regains focus

     

       10
       15

docs/api/request-policy-exchange.md

···

       5
       5
        
       

     

       6
       6
        
       # Request Policy Exchange

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/exchange-request-policy` package contains an addon `requestPolicyExchange` for `urql`

     

       9
       14
        
       that may be used to upgrade [Operations' Request Policies](./core.md#requestpolicy) on a

     

       10
       15
        
       time-to-live basis.

docs/api/retry-exchange.md

···

       5
       5
        
       

     

       6
       6
        
       # Retry Exchange

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       The `@urql/exchange-retry` package contains an addon `retryExchange` for `urql` that may be used to

     

       9
       14
        
       let failed operations be retried, typically when a previous operation has failed with a network

     

       10
       15
        
       error.

docs/api/svelte.md

···

       5
       5
        
       

     

       6
       6
        
       # Svelte API

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       ## queryStore

     

       9
       14
        
       

     

       10
       15
        
       The `queryStore` factory accepts properties as inputs and returns a Svelte pausable, readable store

+12 -7

docs/api/urql.md

···

       5
       5
        
       

     

       6
       6
        
       # React API

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       ## useQuery

     

       9
       14
        
       

     

       10
       15
        
       Accepts a single required options object as an input with the following properties:

     
···

       14
       19
        
       | `query`         | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode.                       |

     

       15
       20
        
       | `variables`     | `?object`                | The variables to be used with the GraphQL request.                                                       |

     

       16
       21
        
       | `requestPolicy` | `?RequestPolicy`         | An optional [request policy](./core.md#requestpolicy) that should be used specifying the cache strategy. |

     

       17
       17
       -
       | `pause`         | `?boolean`               | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery).              |

     

       22
       22
       +
       | `pause`         | `?boolean`               | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery).         |

     

       18
       23
        
       | `context`       | `?object`                | Holds the contextual information for the query.                                                          |

     

       19
       24
        
       

     

       20
       25
        
       This hook returns a tuple of the shape `[result, executeQuery]`.

     
···

       46
       51
        
       

     

       47
       52
        
       Accepts a single required options object as an input with the following properties:

     

       48
       53
        
       

     

       49
       49
       -
       | Prop                                                 | Type                     | Description                                                                        |

     

       50
       50
       -
       | ---------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |

     

       51
       51
       -
       | `query`                                              | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode. |

     

       52
       52
       -
       | `variables`                                          | `?object`                | The variables to be used with the GraphQL request.                                 |

     

       53
       53
       -
       | `pause`                                              | `?boolean`               | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery). |

     

       54
       54
       -
       | `context`                                            | `?object`                | Holds the contextual information for the query.                                    |

     

       54
       54
       +
       | Prop        | Type                     | Description                                                                                      |

     

       55
       55
       +
       | ----------- | ------------------------ | ------------------------------------------------------------------------------------------------ |

     

       56
       56
       +
       | `query`     | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode.               |

     

       57
       57
       +
       | `variables` | `?object`                | The variables to be used with the GraphQL request.                                               |

     

       58
       58
       +
       | `pause`     | `?boolean`               | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery). |

     

       59
       59
       +
       | `context`   | `?object`                | Holds the contextual information for the query.                                                  |

     

       55
       60
        
       

     

       56
       61
        
       The hook optionally accepts a second argument, which may be a handler function with a type signature

     

       57
       62
        
       of:

docs/api/vue.md

···

       5
       5
        
       

     

       6
       6
        
       # Vue API

     

       7
       7
        
       

     

       8
       8
       +
       > **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.

     

       9
       9
       +
       > You can view TSDocs while using these packages in your editor, as long as it supports the

     

       10
       10
       +
       > TypeScript Language Server.

     

       11
       11
       +
       > We're planning to replace these API docs with a separate web app soon.

     

       12
       12
       +
       

     

       8
       13
        
       ## useQuery

     

       9
       14
        
       

     

       10
       15
        
       Accepts a single required options object as an input with the following properties:

+110 -91

docs/architecture.md

···

       5
       5
        
       

     

       6
       6
        
       # Architecture

     

       7
       7
        
       

     

       8
       8
       -
       `urql` is a highly customizable and flexible GraphQL client, that happens to come with some default

     

       9
       9
       -
       [core behavior in the core package](./basics/core.md).

     

       8
       8
       +
       `urql` is a highly customizable and flexible GraphQL client.

     

       9
       9
       +
       As you use it in your app, it's split into three parts:

     

       10
       10
       +
       

     

       11
       11
       +
       - Bindings — such as for React, Preact, Vue, or Svelte — which interact with `@urql/core`'s

     

       12
       12
       +
         `Client`.

     

       13
       13
       +
       - The Client — as created [with the core `@urql/core` package](./basics/code.md), which interacts with "exchanges" to execute GraphQL

     

       14
       14
       +
         operations, and which you can also use directly.

     

       15
       15
       +
       - Exchanges, which provide functionality like fetching or caching to the `Client`.

     

       10
       16
        
       

     

       11
       17
        
       By default, `urql` aims to provide the minimal amount of features that allow us to build an app

     

       12
       18
        
       quickly. However, `urql` has also been designed to be a GraphQL Client

     
···

       34
       40
        
       ## Requests and Operations on the Client

     

       35
       41
        
       

     

       36
       42
        
       If `urql` was a train it would take several stops to arrive at its terminus, our API. It starts with us

     

       37
       37
       -
       defining queries or mutations. Any GraphQL request can be abstracted into their query documents and

     

       38
       38
       -
       their variables. In `urql`, these GraphQL requests are treated as unique objects, which are uniquely

     

       39
       39
       -
       identified by the query document and variables (which is why a `key` is generated from the two). This

     

       40
       40
       -
       `key` is a hash number of the query document and variables and uniquely identifies our

     

       41
       41
       -
       [`GraphQLRequest`](./api/core.md#graphqlrequest).

     

       43
       43
       +
       defining queries or mutations by writing in GraphQL's query language.

     

       44
       44
       +
       

     

       45
       45
       +
       Any GraphQL request can be abstracted into its query documents and its variables.

     

       46
       46
       +
       

     

       47
       47
       +
       ```js

     

       48
       48
       +
       import { gql } from '@urql/core';

     

       49
       49
       +
       

     

       50
       50
       +
       const query = gql`

     

       51
       51
       +
         query($name: String!) {

     

       52
       52
       +
           helloWorld(name: $name)

     

       53
       53
       +
         }

     

       54
       54
       +
       `;

     

       55
       55
       +
       

     

       56
       56
       +
       const request = createRequest(query, {

     

       57
       57
       +
         name: 'Urkel',

     

       58
       58
       +
       });

     

       59
       59
       +
       ```

     

       60
       60
       +
       

     

       61
       61
       +
       In `urql`, these GraphQL requests are treated as unique objects and each GraphQL request will have

     

       62
       62
       +
       a `key` generated for them. This `key` is a hash of the query document and the variables you provide

     

       63
       63
       +
       and are set on the `key` property of a [`GraphQLRequest`](./api/core.md#graphqlrequest).

     

       42
       64
        
       

     

       43
       43
       -
       Whenever we decide to send a request to our API we start by using `urql`'s

     

       44
       44
       -
       [`Client`](./api/core.md#client). It accepts several options like `url` or `requestPolicy` which are

     

       45
       45
       -
       extra information on how the GraphQL requests are executed.

     

       65
       65
       +
       Whenever we decide to send our GraphQL requests to a GraphQL API we start by using `urql`'s

     

       66
       66
       +
       [`Client`](./api/core.md#client).

     

       67
       67
       +
       The `Client` accepts several options to configure its behaviour and the behaviour of exchanges,

     

       68
       68
       +
       like the `fetchExchange`. For instance, we can pass it a `url` which the `fetchExchange` will

     

       69
       69
       +
       use to make a `fetch` call to our GraphQL API.

     

       46
       70
        
       

     

       47
       71
        
       ```js

     

       48
       48
       -
       import { Client, dedupExchange, cacheExchange, fetchExchange } from '@urql/core';

     

       72
       72
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       49
       73
        
       

     

       50
       50
       -
       new Client({

     

       74
       74
       +
       const client = new Client({

     

       51
       75
        
         url: 'http://localhost:3000/graphql',

     

       52
       52
       -
         requestPolicy: 'cache-first',

     

       53
       53
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange]

     

       76
       76
       +
         exchanges: [cacheExchange, fetchExchange],

     

       54
       77
        
       });

     

       55
       78
        
       ```

     

       56
       79
        
       

     

       57
       57
       -
       The bindings that we've seen in [the "Basics" section](./basics/README.md) interact with [the

     

       58
       58
       -
       `Client`](./api/core.md#client) directly and are a thin abstraction on top of it. Though some methods can be called on it directly, as seen [on the "Core Usage"

     

       80
       80
       +
       Above, we're defining a `Client` that is ready to accept our requests. It will apply basic

     

       81
       81
       +
       document caching and will send uncached requests to the `url` we pass it.

     

       82
       82
       +
       The bindings that we've seen in [the "Basics" section](./basics/README.md), like `useQuery` for

     

       83
       83
       +
       React for example, interact with [the `Client`](./api/core.md#client) directly and are a thin

     

       84
       84
       +
       abstraction.

     

       85
       85
       +
       

     

       86
       86
       +
       Some methods can be called on it directly however, as seen [on the "Core Usage"

     

       59
       87
        
       page](./basics/core.md#one-off-queries-and-mutations).

     

       60
       88
        
       

     

       61
       61
       -
       When we send our queries or mutations to the `Client`, internally they will be managed as

     

       62
       62
       -
       [`Operation`](./api/core.md#operation)s. An "Operation" is an extension of `GraphQLRequest`s. Not

     

       63
       63
       -
       only do they carry the `query`, `variables`, and a `key` property, they will also identify the

     

       64
       64
       -
       `kind` of operation that is executed, like `"query"` or `"mutation"`. We can also find the

     

       65
       65
       -
       `Client`'s options on `operation.context` which carries an operation's metadata.

     

       89
       89
       +
       ```js

     

       90
       90
       +
       // Given our request and client defined above, we can call

     

       91
       91
       +
       const subscription = client.executeQuery(request).subscribe(result => {

     

       92
       92
       +
         console.log(result.data);

     

       93
       93
       +
       });

     

       94
       94
       +
       ```

     

       95
       95
       +
       

     

       96
       96
       +
       As we've seen, `urql` defines our query documents and variables as

     

       97
       97
       +
       [`GraphQLRequest`s](./api/core.md#graphqlrequest). However, since we have more metadata that is

     

       98
       98
       +
       needed, like our `url` option on the `Client`, `urql` internally creates [`Operation`s](./api/core.md#operation)

     

       99
       99
       +
       each time a request is executed. The operations are then forwarded to the exchanges, like the

     

       100
       100
       +
       `cacheExchange` and `fetchExchange`.

     

       101
       101
       +
       

     

       102
       102
       +
       An "Operation" is an extension of `GraphQLRequest`s. Not only do they carry the `query`, `variables`,

     

       103
       103
       +
       and a `key` property, they will also identify the `kind` of operation that is executed, like

     

       104
       104
       +
       `"query"` or `"mutation"`, and they contain the `Client`'s options on `operation.context`.

     

       66
       105
        
       

     

       67
       106
        
       ![Operations and Results](./assets/urql-event-hub.png)

     

       68
       107
        
       

     

       69
       69
       -
       It's the `Client`s responsibility to accept an `Operation` and execute it. The bindings internally

     

       70
       70
       -
       call the `client.executeQuery`, `client.executeMutation`, or `client.executeSubscription` methods,

     

       71
       71
       -
       and we'll get a "stream" of results. This "stream" allows us to register a callback with it to

     

       72
       72
       -
       receive results.

     

       108
       108
       +
       This means, once we hand over a GraphQL request to the `Client`, it will create an `Operation`,

     

       109
       109
       +
       and then hand it over to the exchanges until a result comes back.

     

       73
       110
        
       

     

       74
       74
       -
       In the diagram we can see that each operation is a signal for our request to start at which point

     

       75
       75
       -
       we can expect to receive our results eventually on a callback. Once we're not interested in results

     

       76
       76
       -
       anymore a special "teardown" signal is issued on the `Client`. While we don't see operations outside

     

       77
       77
       -
       the `Client`, they're what travel through the "Exchanges" on the `Client`.

     

       111
       111
       +
       As shown in the diagram, each operation is like an event or signal for a GraphQL request to start,

     

       112
       112
       +
       and the exchanges will eventually send back a corresponding result.

     

       113
       113
       +
       However, because the cache can send updates to us whenever it detects a change, or you could cancel

     

       114
       114
       +
       a GraphQL request before it finishes, a special "teardown" `Operation` also exists, which cancels

     

       115
       115
       +
       ongoing requests.

     

       78
       116
        
       

     

       79
       117
        
       ## The Client and Exchanges

     

       80
       118
        
       

     

       81
       119
        
       To reiterate, when we use `urql`'s bindings for our framework of choice, methods are called on the

     

       82
       120
        
       `Client`, but we never see the operations that are created in the background from our bindings. We

     

       83
       121
        
       call a method like `client.executeQuery` (or it's called for us in the bindings), an operation is

     

       84
       84
       -
       issued internally when we subscribe with a callback, and later our callback is called with results.

     

       122
       122
       +
       issued internally when we subscribe with a callback, and later, we're given results.

     

       85
       123
        
       

     

       86
       124
        
       ![Operations stream and results stream](./assets/urql-client-architecture.png)

     

       87
       125
        
       

     
···

       126
       164
        
       

     

       127
       165
        
       ### The Exchanges

     

       128
       166
        
       

     

       129
       129
       -
       The default set of exchanges that `@urql/core` contains and applies to a `Client` are:

     

       167
       167
       +
       By default, the `Client` doesn't do anything with GraphQL requests. It contains only the logic to

     

       168
       168
       +
       manage and differentiate between active and inactive requests and converts them to operations.

     

       169
       169
       +
       To actually do something with our GraphQL requests, it needs _exchanges_, which are like plugins

     

       170
       170
       +
       that you can pass to create a pipeline of how GraphQL operations are executed.

     

       171
       171
       +
       

     

       172
       172
       +
       By default, you may want to add the `cacheExchange` and the `fetchExchange` from `@urql/core`:

     

       130
       173
        
       

     

       131
       131
       -
       - `dedupExchange`: Deduplicates pending operations (pending = waiting for a result)

     

       132
       132
       -
       - `cacheExchange`: The default caching logic with ["Document Caching"](./basics/document-caching.md)

     

       133
       133
       -
       - `fetchExchange`: Sends an operation to the API using `fetch` and adds results to the output stream

     

       174
       174
       +
       - `cacheExchange`: Caches GraphQL results with ["Document Caching"](./basics/document-caching.md)

     

       175
       175
       +
       - `fetchExchange`: Executes GraphQL requests with a `fetch` HTTP call

     

       134
       176
        
       

     

       135
       135
       -
       When we don't pass the `exchanges` option manually to our `Client` then these are the ones that will

     

       136
       136
       -
       be applied. As we can see, an exchange exerts a lot of power over our operations and results. They

     

       137
       137
       -
       determine a lot of the logic of the `Client`, taking care of things like deduplication, caching, and

     

       138
       138
       -
       sending requests to our API.

     

       177
       177
       +
       ```js

     

       178
       178
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       139
       179
        
       

     

       140
       140
       -
       Some of the exchanges that are available to us are:

     

       180
       180
       +
       const client = new Client({

     

       181
       181
       +
         url: 'http://localhost:3000/graphql',

     

       182
       182
       +
         exchanges: [cacheExchange, fetchExchange],

     

       183
       183
       +
       });

     

       184
       184
       +
       ```

     

       141
       185
        
       

     

       142
       142
       -
       - [`mapExchange`](./api/core.md#mapexchange): Allows reacting to operations, results, and errors

     

       186
       186
       +
       As we can tell, exchanges define not only how GraphQL requests are executed and handled, but also

     

       187
       187
       +
       get control over caching. Exchanges can be used to change almost any behaviour in the `Client`,

     

       188
       188
       +
       although internally they only handle incoming & outgoing requests and incoming & outgoing results.

     

       189
       189
       +
       

     

       190
       190
       +
       Some more exchanges that we can use with our `Client` are:

     

       191
       191
       +
       

     

       192
       192
       +
       - [`mapExchange`](./api/core.md#mapexchange): Allows changing and reacting to operations, results, and errors

     

       143
       193
        
       - [`ssrExchange`](./advanced/server-side-rendering.md): Allows for a server-side renderer to

     

       144
       194
        
         collect results for client-side rehydration.

     

       145
       145
       -
       - [`retryExchange`](./advanced/retry-operations.md): Allows operations to be retried

     

       146
       146
       -
       - [`multipartFetchExchange`](./advanced/persistence-and-uploads.md#file-uploads): Provides multipart file upload capability

     

       195
       195
       +
       - [`retryExchange`](./advanced/retry-operations.md): Allows operations to be retried on errors

     

       147
       196
        
       - [`persistedFetchExchange`](./advanced/persistence-and-uploads.md#automatic-persisted-queries): Provides support for Automatic

     

       148
       197
        
         Persisted Queries

     

       149
       149
       -
       - [`authExchange`](./advanced/authentication.md): Allows complex authentication flows to be implemented

     

       150
       150
       -
         easily.

     

       151
       151
       -
       - [`requestPolicyExchange`](./api/request-policy-exchange.md): Automatically upgrades `cache-only` and `cache-first` operations to `cache-and-network` after a given amount of time.

     

       152
       152
       -
       - [`refocusExchange`](./api/refocus-exchange.md): Tracks open queries and refetches them

     

       153
       153
       -
         when the window regains focus.

     

       198
       198
       +
       - [`authExchange`](./advanced/authentication.md): Allows refresh authentication to be implemented easily.

     

       199
       199
       +
       - [`requestPolicyExchange`](./api/request-policy-exchange.md): Automatically refreshes results given a TTL.

     

       154
       200
        
       - `devtoolsExchange`: Provides the ability to use the [urql-devtools](https://github.com/urql-graphql/urql-devtools)

     

       155
       201
        
       

     

       156
       202
        
       We can even swap out our [document cache](./basics/document-caching.md), which is implemented by

     
···

       182
       228
        
       directly](./basics/core.md#one-off-queries-and-mutations) or write exchanges then we'll see streams

     

       183
       229
        
       and will have to deal with their API.

     

       184
       230
        
       

     

       185
       185
       -
       ### The Wonka library

     

       186
       186
       -
       

     

       187
       187
       -
       `urql` utilises the [Wonka](https://github.com/kitten/wonka) library for its streams. It has a

     

       188
       188
       -
       few advantages that are specifically tailored for the `urql` library and ecosystem:

     

       189
       189
       -
       

     

       190
       190
       -
       - It is extremely lightweight and treeshakeable, with a size of around 3.7kB minzipped.

     

       191
       191
       -
       - It's cross-platform and cross-language compatible, having been written in

     

       192
       192
       -
         [Reason](https://reasonml.github.io/) and provides support for [Flow](https://flow.org/)

     

       193
       193
       -
         and [TypeScript](https://www.typescriptlang.org/v2/).

     

       194
       194
       -
       - It's a predictable and iterable toolchain, emitting synchronous events whenever possible.

     

       195
       195
       -
       

     

       196
       196
       -
       Typical usage of Wonka will involve creating a _source_ of some values and a _sink_.

     

       197
       197
       -
       

     

       198
       198
       -
       ```js

     

       199
       199
       -
       import { fromArray, map, subscribe, pipe } from 'wonka';

     

       200
       200
       -
       

     

       201
       201
       -
       const { unsubscribe } = pipe(

     

       202
       202
       -
         fromArray([1, 2, 3]),

     

       203
       203
       -
         map(x => x * 2),

     

       204
       204
       -
         subscribe(x => {

     

       205
       205
       -
           console.log(x); // 2, 4, 6

     

       206
       206
       -
         })

     

       207
       207
       -
       );

     

       208
       208
       -
       ```

     

       209
       209
       -
       

     

       210
       210
       -
       In Wonka, like with Observables, streams are cancellable by calling the `unsubscribe` method that a

     

       211
       211
       -
       subscription returns.

     

       212
       212
       -
       

     

       213
       213
       -
       [Read more about Wonka in its documentation](https://wonka.kitten.sh/basics/background).

     

       214
       214
       -
       

     

       215
       231
        
       ### Stream patterns with the client

     

       216
       232
        
       

     

       217
       233
        
       When we call methods on the `Client` like [`client.executeQuery`](./api/core.md#clientexecutequery)

     

       218
       218
       -
       or [`client.query`](./api/core.md#clientquery) then these will return a Wonka stream. Those are

     

       219
       219
       -
       essentially just a bunch of callbacks.

     

       234
       234
       +
       or [`client.query`](./api/core.md#clientquery) then these will return a "stream" of results.

     

       220
       235
        
       

     

       221
       221
       -
       We can use [`wonka`'s `subscribe`](https://wonka.kitten.sh/api/sinks#subscribe) function to start

     

       222
       222
       -
       this stream. We pass this function a callback and will receive results back from the `Client`, as it

     

       223
       223
       -
       starts our operation. When we unsubscribe then the `Client` will stop this operation by sending a

     

       224
       224
       -
       special "teardown" operation to our exchanges.

     

       236
       236
       +
       It's normal for GraphQL subscriptions to deliver multiple results, however, even GraphQL queries can

     

       237
       237
       +
       give you multiple results in `urql`. This is because operations influence one another. When a cache

     

       238
       238
       +
       invalidates a query, this query may refetch, and a new result is delivered to your application.

     

       239
       239
       +
       

     

       240
       240
       +
       Multiple results mean that once you subscribe to a GraphQL query via the `Client`, you may receive

     

       241
       241
       +
       new results in the future.

     

       225
       242
        
       

     

       226
       243
        
       ```js

     

       227
       227
       -
       import { pipe, subscribe } from 'wonka';

     

       244
       244
       +
       import { gql } from '@urql/core';

     

       228
       245
        
       

     

       229
       229
       -
       const QUERY = `

     

       246
       246
       +
       const QUERY = gql`

     

       230
       247
        
         query Test($id: ID!) {

     

       231
       248
        
           getUser(id: $id) {

     

       232
       249
        
             id

     
···

       235
       252
        
         }

     

       236
       253
        
       `;

     

       237
       254
        
       

     

       238
       238
       -
       const { unsubscribe } = pipe(

     

       239
       239
       -
         client.query(QUERY, { id: 'test' }),

     

       240
       240
       -
         subscribe(result => {

     

       241
       241
       -
           console.log(result); // { data: ... }

     

       242
       242
       -
         })

     

       243
       243
       -
       );

     

       255
       255
       +
       client.query(QUERY, { id: 'test' }).subscribe(result => {

     

       256
       256
       +
         console.log(result); // { data: ... }

     

       257
       257
       +
       });

     

       244
       258
        
       ```

     

       245
       259
        
       

     

       246
       260
        
       Read more about the available APIs on the `Client` in the [Core API docs](./api/core.md).

     

       261
       261
       +
       

     

       262
       262
       +
       Internally, these streams and all exchanges are written using a library called

     

       263
       263
       +
       [`wonka`](https://wonka.kitten.sh/basics/background), which is a tiny Observable-like

     

       264
       264
       +
       library. It is used to write exchanges and when we interact with the `Client` it is used internally

     

       265
       265
       +
       as well.

+56 -32

docs/basics/core.md

···

       27
       27
        
       `@urql/core` or use it standalone, e.g. in a Node.js environment.

     

       28
       28
        
       

     

       29
       29
        
       ```sh

     

       30
       30
       -
       yarn add @urql/core graphql

     

       30
       30
       +
       yarn add @urql/core

     

       31
       31
        
       # or

     

       32
       32
       -
       npm install --save @urql/core graphql

     

       32
       32
       +
       npm install --save @urql/core

     

       33
       33
        
       ```

     

       34
       34
        
       

     

       35
       35
        
       Since all bindings and all exchanges depend on `@urql/core`, we may sometimes run into problems

     
···

       39
       39
        
       deduplicating our dependencies.

     

       40
       40
        
       

     

       41
       41
        
       ```sh

     

       42
       42
       +
       # npm

     

       43
       43
       +
       npm dedupe

     

       44
       44
       +
       # pnpm

     

       45
       45
       +
       pnpm dedupe

     

       46
       46
       +
       # yarn

     

       42
       47
        
       npx yarn-deduplicate && yarn

     

       43
       43
       -
       # or

     

       44
       44
       -
       npm dedupe

     

       45
       48
        
       ```

     

       46
       49
        
       

     

       47
       50
        
       ## GraphQL Tags

     
···

       130
       133
        
       

     

       131
       134
        
       ### Setting up the `Client`

     

       132
       135
        
       

     

       133
       133
       -
       The `@urql/core` package exports a function called `createClient` which we can use to

     

       136
       136
       +
       The `@urql/core` package exports a `Client` class, which we can use to

     

       134
       137
        
       create the GraphQL client. This central `Client` manages all of our GraphQL requests and results.

     

       135
       138
        
       

     

       136
       139
        
       ```js

     

       137
       137
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/core';

     

       140
       140
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       138
       141
        
       

     

       139
       139
       -
       const client = createClient({

     

       142
       142
       +
       const client = new Client({

     

       140
       143
        
         url: 'http://localhost:3000/graphql',

     

       141
       141
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       144
       144
       +
         exchanges: [cacheExchange, fetchExchange],

     

       142
       145
        
       });

     

       143
       146
        
       ```

     

       144
       147
        
       

     

       145
       145
       -
       At the bare minimum we'll need to pass an API's `url` when we create a `Client` to get started.

     

       148
       148
       +
       At the bare minimum we'll need to pass an API's `url`, and the `fetchExchange`,

     

       149
       149
       +
       when we create a `Client` to get started.

     

       146
       150
        
       

     

       147
       151
        
       Another common option is `fetchOptions`. This option allows us to customize the options that will be

     

       148
       152
        
       passed to `fetch` when a request is sent to the given API `url`. We may pass in an options object, or

     
···

       152
       156
        
       GraphQL API.

     

       153
       157
        
       

     

       154
       158
        
       ```js

     

       155
       155
       -
       const client = createClient({

     

       159
       159
       +
       const client = new Client({

     

       156
       160
        
         url: 'http://localhost:3000/graphql',

     

       157
       157
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       161
       161
       +
         exchanges: [cacheExchange, fetchExchange],

     

       158
       162
        
         fetchOptions: () => {

     

       159
       163
        
           const token = getToken();

     

       160
       164
        
           return {

     
···

       166
       170
        
       

     

       167
       171
        
       ### The `Client`s options

     

       168
       172
        
       

     

       169
       169
       -
       As we've seen above, the most important option for the `Client` is `url`, since it won't work

     

       170
       170
       -
       without it. However, another important option on the `Client` is the `exchanges` option.

     

       173
       173
       +
       As we've seen above, the most important options for the `Client` are `url` and `exchanges`.

     

       174
       174
       +
       The `url` option is used by the `fetchExchange` to send GraphQL requests to an API.

     

       171
       175
        
       

     

       172
       172
       -
       This option passes a list of exchanges to the `Client`, which tell it how to execute our requests

     

       173
       173
       -
       and how to cache data in a certain order.

     

       176
       176
       +
       The `exchanges` option is of particular importance however because it tells the `Client` what to do

     

       177
       177
       +
       with our GraphQL requests:

     

       174
       178
        
       

     

       175
       179
        
       ```js

     

       176
       176
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/core';

     

       180
       180
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       177
       181
        
       

     

       178
       178
       -
       const client = createClient({

     

       182
       182
       +
       const client = new Client({

     

       179
       183
        
         url: 'http://localhost:3000/graphql',

     

       180
       180
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       184
       184
       +
         exchanges: [cacheExchange, fetchExchange],

     

       181
       185
        
       });

     

       182
       186
        
       ```

     

       183
       187
        
       

     

       188
       188
       +
       For instance, here, the `Client`'s caching and fetching features are only available because we're

     

       189
       189
       +
       passing it exchanges. In the above example, the `Client` will try to first read a GraphQL request

     

       190
       190
       +
       from a local cache, and if this request isn't cached it'll make an HTTP request.

     

       191
       191
       +
       The caching in `urql` is also implemented as an exchange, so for instance, the behavior described

     

       192
       192
       +
       on the ["Document Caching" page](./document-caching.md) is all contained within the `cacheExchange`

     

       193
       193
       +
       above.

     

       194
       194
       +
       

     

       184
       195
        
       Later, [in the "Advanced" section](../advanced/README.md) we'll see many more features that `urql`

     

       185
       196
        
       supports by adding new exchanges to this list. On [the "Architecture" page](../architecture.md)

     

       186
       197
        
       we'll also learn more about what exchanges are and why they exist.

     

       187
       187
       -
       

     

       188
       188
       -
       For now, it's enough for us to know that our requests are executed using the logic in the

     

       189
       189
       -
       exchanges in order. First, the `dedupExchange` deduplicates requests if we send the same queries

     

       190
       190
       -
       twice, the `cacheExchange` implements the default "document caching" behaviour (as we'll learn about

     

       191
       191
       -
       on the ["Document Caching"](./document-caching.md) page), and lastly the `fetchExchange` is

     

       192
       192
       -
       responsible for sending our requests to our GraphQL API.

     

       193
       198
        
       

     

       194
       199
        
       ### One-off Queries and Mutations

     

       195
       200
        
       

     
···

       220
       225
        
       result as a promise. This may be useful when we don't plan on cancelling queries, or we don't

     

       221
       226
        
       care about future updates to this data and are just looking to query a result once.

     

       222
       227
        
       

     

       228
       228
       +
       This can also be written using async/await by simply awaiting the return value of `client.query`:

     

       229
       229
       +
       

     

       230
       230
       +
       ```js

     

       231
       231
       +
       const QUERY = `

     

       232
       232
       +
         query Test($id: ID!) {

     

       233
       233
       +
           getUser(id: $id) {

     

       234
       234
       +
             id

     

       235
       235
       +
             name

     

       236
       236
       +
           }

     

       237
       237
       +
         }

     

       238
       238
       +
       `;

     

       239
       239
       +
       

     

       240
       240
       +
       async function query() {

     

       241
       241
       +
         const result = await client.query(QUERY, { id: 'test' });

     

       242
       242
       +
         console.log(result); // { data: ... }

     

       243
       243
       +
       }

     

       244
       244
       +
       ```

     

       245
       245
       +
       

     

       223
       246
        
       The same can be done for mutations by calling the `client.mutation` method instead of the

     

       224
       247
        
       `client.query` method.

     

       248
       248
       +
       

     

       249
       249
       +
       It's worth noting that promisifying a query result will always only give us _one_ result, because

     

       250
       250
       +
       we're not calling `subscribe`. This means that we'll never see cache updates when we're asking for

     

       251
       251
       +
       a single result like we do above.

     

       252
       252
       +
       

     

       253
       253
       +
       #### Reading only cache data

     

       225
       254
        
       

     

       226
       255
        
       Similarly there's a way to read data from the cache synchronously, provided that the cache has

     

       227
       256
        
       received a result for a given query before. The `Client` has a `readQuery` method, which is a

     
···

       258
       287
        
       somewhere else then we'll get notified of the new API result as well, as long as we're subscribed.

     

       259
       288
        
       

     

       260
       289
        
       ```js

     

       261
       261
       -
       import { pipe, subscribe } from 'wonka';

     

       262
       262
       -
       

     

       263
       290
        
       const QUERY = `

     

       264
       291
        
         query Test($id: ID!) {

     

       265
       292
        
           getUser(id: $id) {

     
···

       269
       296
        
         }

     

       270
       297
        
       `;

     

       271
       298
        
       

     

       272
       272
       -
       const { unsubscribe } = pipe(

     

       273
       273
       -
         client.query(QUERY, { id: 'test' }),

     

       274
       274
       -
         subscribe(result => {

     

       275
       275
       -
           console.log(result); // { data: ... }

     

       276
       276
       -
         })

     

       277
       277
       -
       );

     

       299
       299
       +
       const { unsubscribe } = client.query(QUERY, { id: 'test' }).subscribe(result => {

     

       300
       300
       +
         console.log(result); // { data: ... }

     

       301
       301
       +
       });

     

       278
       302
        
       ```

     

       279
       303
        
       

     

       280
       304
        
       This code example is similar to the one before. However, instead of sending a one-off query, we're

+21 -21

docs/basics/react-preact.md

···

       18
       18
        
       with at first. We'll install the package with our package manager of choice.

     

       19
       19
        
       

     

       20
       20
        
       ```sh

     

       21
       21
       -
       yarn add urql graphql

     

       21
       21
       +
       yarn add urql

     

       22
       22
        
       # or

     

       23
       23
       -
       npm install --save urql graphql

     

       23
       23
       +
       npm install --save urql

     

       24
       24
        
       ```

     

       25
       25
        
       

     

       26
       26
        
       To use `urql` with Preact, we have to install `@urql/preact` instead of `urql` and import from

     
···

       37
       37
        
       

     

       38
       38
        
       ### Setting up the `Client`

     

       39
       39
        
       

     

       40
       40
       -
       The `urql` and `@urql/preact` packages export a method called `createClient` which we can use to

     

       40
       40
       +
       The `urql` and `@urql/preact` packages export a `Client` class, which we can use to

     

       41
       41
        
       create the GraphQL client. This central `Client` manages all of our GraphQL requests and results.

     

       42
       42
        
       

     

       43
       43
        
       ```js

     

       44
       44
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       44
       44
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       45
       45
        
       

     

       46
       46
       -
       const client = createClient({

     

       46
       46
       +
       const client = new Client({

     

       47
       47
        
         url: 'http://localhost:3000/graphql',

     

       48
       48
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       48
       48
       +
         exchanges: [cacheExchange, fetchExchange],

     

       49
       49
        
       });

     

       50
       50
        
       ```

     

       51
       51
        
       

     

       52
       52
       -
       At the bare minimum we'll need to pass an API's `url` when we create a `Client` to get started.

     

       52
       52
       +
       At the bare minimum we'll need to pass an API's `url` and `exchanges` when we create a `Client`

     

       53
       53
       +
       to get started.

     

       53
       54
        
       

     

       54
       55
        
       Another common option is `fetchOptions`. This option allows us to customize the options that will be

     

       55
       56
        
       passed to `fetch` when a request is sent to the given API `url`. We may pass in an options object, or

     
···

       59
       60
        
       GraphQL API.

     

       60
       61
        
       

     

       61
       62
        
       ```js

     

       62
       62
       -
       const client = createClient({

     

       63
       63
       +
       const client = new Client({

     

       63
       64
        
         url: 'http://localhost:3000/graphql',

     

       64
       64
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       65
       65
       +
         exchanges: [cacheExchange, fetchExchange],

     

       65
       66
        
         fetchOptions: () => {

     

       66
       67
        
           const token = getToken();

     

       67
       68
        
           return {

     
···

       78
       79
        
       the `Provider` export.

     

       79
       80
        
       

     

       80
       81
        
       ```jsx

     

       81
       81
       -
       import { createClient, Provider, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       82
       82
       +
       import { Client, Provider, cacheExchange, fetchExchange } from 'urql';

     

       82
       83
        
       

     

       83
       83
       -
       const client = createClient({

     

       84
       84
       +
       const client = new Client({

     

       84
       85
        
         url: 'http://localhost:3000/graphql',

     

       85
       85
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       86
       86
       +
         exchanges: [cacheExchange, fetchExchange],

     

       86
       87
        
       });

     

       87
       88
        
       

     

       88
       89
        
       const App = () => (

     
···

       107
       108
        
       todo items. Let's dive right into it!

     

       108
       109
        
       

     

       109
       110
        
       ```jsx

     

       110
       110
       -
       import { useQuery } from 'urql';

     

       111
       111
       +
       import { gql, useQuery } from 'urql';

     

       111
       112
        
       

     

       112
       112
       -
       const TodosQuery = `

     

       113
       113
       +
       const TodosQuery = gql`

     

       113
       114
        
         query {

     

       114
       115
        
           todos {

     

       115
       116
        
             id

     
···

       154
       155
        
       to supply variables to our query.

     

       155
       156
        
       

     

       156
       157
        
       ```jsx

     

       157
       157
       -
       const TodosListQuery = `

     

       158
       158
       +
       const TodosListQuery = gql`

     

       158
       159
        
         query ($from: Int!, $limit: Int!) {

     

       159
       159
       -
           todos (from: $from, limit: $limit) {

     

       160
       160
       +
           todos(from: $from, limit: $limit) {

     

       160
       161
        
             id

     

       161
       162
        
             title

     

       162
       163
        
           }

     
···

       198
       199
        
       

     

       199
       200
        
       ```jsx

     

       200
       201
        
       const Todos = ({ from, limit }) => {

     

       201
       201
       -
         const shouldPause = from === undefined || from === null ||

     

       202
       202
       -
                             limit === undefined || limit === null;

     

       202
       202
       +
         const shouldPause = from === undefined || from === null || limit === undefined || limit === null;

     

       203
       203
        
         const [result, reexecuteQuery] = useQuery({

     

       204
       204
        
           query: TodosListQuery,

     

       205
       205
        
           variables: { from, limit },

     
···

       244
       244
        
       we may also change the `Client`'s default `requestPolicy` by passing it there.

     

       245
       245
        
       

     

       246
       246
        
       ```js

     

       247
       247
       -
       import { createClient } from 'urql';

     

       247
       247
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       248
       248
        
       

     

       249
       249
       -
       const client = createClient({

     

       249
       249
       +
       const client = new Client({

     

       250
       250
        
         url: 'http://localhost:3000/graphql',

     

       251
       251
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       251
       251
       +
         exchanges: [cacheExchange, fetchExchange],

     

       252
       252
        
         // every operation will by default use cache-and-network rather

     

       253
       253
        
         // than cache-first now:

     

       254
       254
        
         requestPolicy: 'cache-and-network',

+17 -16

docs/basics/svelte.md

···

       17
       17
        
       Installing `@urql/svelte` is quick and no other packages are immediately necessary.

     

       18
       18
        
       

     

       19
       19
        
       ```sh

     

       20
       20
       -
       yarn add @urql/svelte graphql

     

       20
       20
       +
       yarn add @urql/svelte

     

       21
       21
        
       # or

     

       22
       22
       -
       npm install --save @urql/svelte graphql

     

       22
       22
       +
       npm install --save @urql/svelte

     

       23
       23
        
       ```

     

       24
       24
        
       

     

       25
       25
        
       Most libraries related to GraphQL also need the `graphql` package to be installed as a peer

     
···

       44
       44
        
       

     

       45
       45
        
       ### Setting up the `Client`

     

       46
       46
        
       

     

       47
       47
       -
       The `@urql/svelte` package exports a method called `createClient` which we can use to create

     

       47
       47
       +
       The `@urql/svelte` package exports a `Client` class, which we can use to create

     

       48
       48
        
       the GraphQL client. This central `Client` manages all of our GraphQL requests and results.

     

       49
       49
        
       

     

       50
       50
        
       ```js

     

       51
       51
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/svelte';

     

       51
       51
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/svelte';

     

       52
       52
        
       

     

       53
       53
       -
       const client = createClient({

     

       53
       53
       +
       const client = new Client({

     

       54
       54
        
         url: 'http://localhost:3000/graphql',

     

       55
       55
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       55
       55
       +
         exchanges: [cacheExchange, fetchExchange],

     

       56
       56
        
       });

     

       57
       57
        
       ```

     

       58
       58
        
       

     

       59
       59
       -
       At the bare minimum we'll need to pass an API's `url` when we create a `Client` to get started.

     

       59
       59
       +
       At the bare minimum we'll need to pass an API's `url` and `exchanges`

     

       60
       60
       +
       when we create a `Client` to get started.

     

       60
       61
        
       

     

       61
       62
        
       Another common option is `fetchOptions`. This option allows us to customize the options that will be

     

       62
       63
        
       passed to `fetch` when a request is sent to the given API `url`. We may pass in an options object or

     
···

       66
       67
        
       GraphQL API.

     

       67
       68
        
       

     

       68
       69
        
       ```js

     

       69
       69
       -
       const client = createClient({

     

       70
       70
       +
       const client = new Client({

     

       70
       71
        
         url: 'http://localhost:3000/graphql',

     

       71
       71
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       72
       72
       +
         exchanges: [cacheExchange, fetchExchange],

     

       72
       73
        
         fetchOptions: () => {

     

       73
       74
        
           const token = getToken();

     

       74
       75
        
           return {

     
···

       87
       88
        
       

     

       88
       89
        
       ```html

     

       89
       90
        
       <script>

     

       90
       90
       -
         import { createClient, setContextClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/svelte';

     

       91
       91
       +
         import { Client, setContextClient, cacheExchange, fetchExchange } from '@urql/svelte';

     

       91
       92
        
       

     

       92
       92
       -
         const client = createClient({

     

       93
       93
       +
         const client = new Client({

     

       93
       94
        
           url: 'http://localhost:3000/graphql',

     

       94
       94
       -
           exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       95
       95
       +
           exchanges: [cacheExchange, fetchExchange],

     

       95
       96
        
         });

     

       96
       97
        
       

     

       97
       98
        
         setContextClient(client);

     
···

       291
       292
        
       we may also change the `Client`'s default `requestPolicy` by passing it there.

     

       292
       293
        
       

     

       293
       294
        
       ```js

     

       294
       294
       -
       import { createClient } from '@urql/svelte';

     

       295
       295
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/svelte';

     

       295
       296
        
       

     

       296
       296
       -
       const client = createClient({

     

       297
       297
       +
       const client = new Client({

     

       297
       298
        
         url: 'http://localhost:3000/graphql',

     

       298
       298
       -
           exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       299
       299
       +
         exchanges: [cacheExchange, fetchExchange],

     

       299
       300
        
         // every operation will by default use cache-and-network rather

     

       300
       301
        
         // than cache-first now:

     

       301
       302
        
         requestPolicy: 'cache-and-network',

     
···

       400
       401
        
           result = mutationStore({

     

       401
       402
        
             client,

     

       402
       403
        
             query: gql`

     

       403
       403
       -
               mutation($id: ID!, $title: String!) {

     

       404
       404
       +
               mutation ($id: ID!, $title: String!) {

     

       404
       405
        
                 updateTodo(id: $id, title: $title) {

     

       405
       406
        
                   id

     

       406
       407
        
                   title

+6 -5

docs/basics/typescript-integration.md

···

       14
       14
        
       To get and running, install the following packages:

     

       15
       15
        
       

     

       16
       16
        
       ```sh

     

       17
       17
       -
       yarn add graphql

     

       18
       18
       -
       yarn add -D typescript @graphql-codegen/cli @graphql-codegen/client-preset

     

       17
       17
       +
       yarn add -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset

     

       19
       18
        
       # or

     

       20
       20
       -
       npm install graphql

     

       21
       21
       -
       npm install -D typescript @graphql-codegen/cli @graphql-codegen/client-preset

     

       19
       19
       +
       npm install -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset

     

       22
       20
        
       ```

     

       23
       21
        
       

     

       24
       22
        
       Then, add the following script to your `package.json`:

     
···

       140
       138
        
       

     

       141
       139
        
       function App() {

     

       142
       140
        
         // `data` is typed!

     

       143
       143
       -
         const [{ data }] = useQuery({ query: allFilmsWithVariablesQueryDocument, variables: { first: 10 } });

     

       141
       141
       +
         const [{ data }] = useQuery({

     

       142
       142
       +
           query: allFilmsWithVariablesQueryDocument,

     

       143
       143
       +
           variables: { first: 10 },

     

       144
       144
       +
         });

     

       144
       145
        
         return (

     

       145
       146
        
           <div className="App">

     

       146
       147
        
             {data && (

+3 -3

docs/basics/ui-patterns.md

···

       169
       169
        
       else our requests will never get upgraded.

     

       170
       170
        
       

     

       171
       171
        
       ```js

     

       172
       172
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       172
       172
       +
       import { Client, cacheExchange, fetchExchange } from 'urql';

     

       173
       173
        
       import { refocusExchange } from '@urql/exchange-refocus';

     

       174
       174
        
       

     

       175
       175
       -
       const client = createClient({

     

       175
       175
       +
       const client = new Client({

     

       176
       176
        
         url: 'some-url',

     

       177
       177
       -
         exchanges: [dedupExchange, refocusExchange(), cacheExchange, fetchExchange],

     

       177
       177
       +
         exchanges: [refocusExchange(), cacheExchange, fetchExchange],

     

       178
       178
        
       });

     

       179
       179
        
       ```

     

       180
       180

+42 -41

docs/basics/vue.md

···

       33
       33
        
       

     

       34
       34
        
       ### Setting up the `Client`

     

       35
       35
        
       

     

       36
       36
       -
       The `@urql/vue` package exports a method called `createClient` which we can use to create

     

       36
       36
       +
       The `@urql/vue` package exports a `Client` class, which we can use to create

     

       37
       37
        
       the GraphQL client. This central `Client` manages all of our GraphQL requests and results.

     

       38
       38
        
       

     

       39
       39
        
       ```js

     

       40
       40
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/vue';

     

       40
       40
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/vue';

     

       41
       41
        
       

     

       42
       42
       -
       const client = createClient({

     

       42
       42
       +
       const client = new Client({

     

       43
       43
        
         url: 'http://localhost:3000/graphql',

     

       44
       44
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       44
       44
       +
         exchanges: [cacheExchange, fetchExchange],

     

       45
       45
        
       });

     

       46
       46
        
       ```

     

       47
       47
        
       

     

       48
       48
       -
       At the bare minimum we'll need to pass an API's `url` when we create a `Client` to get started.

     

       48
       48
       +
       At the bare minimum we'll need to pass an API's `url` and `exchanges` when we create a `Client`

     

       49
       49
       +
       to get started.

     

       49
       50
        
       

     

       50
       51
        
       Another common option is `fetchOptions`. This option allows us to customize the options that will be

     

       51
       52
        
       passed to `fetch` when a request is sent to the given API `url`. We may pass in an options object or

     
···

       55
       56
        
       GraphQL API.

     

       56
       57
        
       

     

       57
       58
        
       ```js

     

       58
       58
       -
       const client = createClient({

     

       59
       59
       +
       const client = new Client({

     

       59
       60
        
         url: 'http://localhost:3000/graphql',

     

       60
       60
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       61
       61
       +
         exchanges: [cacheExchange, fetchExchange],

     

       61
       62
        
         fetchOptions: () => {

     

       62
       63
        
           const token = getToken();

     

       63
       64
        
           return {

     
···

       75
       76
        
       

     

       76
       77
        
       The first method is to use `@urql/vue`'s `provideClient` function. This must be called in any of

     

       77
       78
        
       your parent components and accepts either a `Client` directly or just the options that you'd pass to

     

       78
       78
       -
       `createClient`.

     

       79
       79
       +
       `Client`.

     

       79
       80
        
       

     

       80
       81
        
       ```html

     

       81
       82
        
       <script>

     

       82
       82
       -
         import { createClient, provideClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/vue';

     

       83
       83
       +
         import { Client, provideClient, cacheExchange, fetchExchange } from '@urql/vue';

     

       83
       84
        
       

     

       84
       84
       -
         const client = createClient({

     

       85
       85
       +
         const client = new Client({

     

       85
       86
        
           url: 'http://localhost:3000/graphql',

     

       86
       86
       -
           exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       87
       87
       +
           exchanges: [cacheExchange, fetchExchange],

     

       87
       88
        
         });

     

       88
       89
        
       

     

       89
       90
        
         provideClient(client);

     
···

       107
       108
        
       app.mount('#app');

     

       108
       109
        
       ```

     

       109
       110
        
       

     

       110
       110
       -
       The plugin also accepts `createClient`'s options or a `Client` as its inputs.

     

       111
       111
       +
       The plugin also accepts `Client`'s options or a `Client` as its inputs.

     

       111
       112
        
       

     

       112
       113
        
       ## Queries

     

       113
       114
        
       

     
···

       134
       135
        
       </template>

     

       135
       136
        
       

     

       136
       137
        
       <script>

     

       137
       137
       -
       import { useQuery } from '@urql/vue';

     

       138
       138
       +
       import { gql, useQuery } from '@urql/vue';

     

       138
       139
        
       

     

       139
       140
        
       export default {

     

       140
       141
        
         setup() {

     

       141
       142
        
           const result = useQuery({

     

       142
       142
       -
             query: `

     

       143
       143
       +
             query: gql`

     

       143
       144
        
               {

     

       144
       145
        
                 todos {

     

       145
       146
        
                   id

     
···

       184
       185
        
       </template>

     

       185
       186
        
       

     

       186
       187
        
       <script>

     

       187
       187
       -
       import { useQuery } from '@urql/vue';

     

       188
       188
       +
       import { gql, useQuery } from '@urql/vue';

     

       188
       189
        
       

     

       189
       190
        
       export default {

     

       190
       191
        
         props: ['from', 'limit'],

     

       191
       192
        
         setup({ from, limit }) {

     

       192
       193
        
           return useQuery({

     

       193
       193
       -
             query: `

     

       194
       194
       +
             query: gql`

     

       194
       195
        
               query ($from: Int!, $limit: Int!) {

     

       195
       196
        
                 todos(from: $from, limit: $limit) {

     

       196
       197
        
                   id

     
···

       221
       222
        
       </template>

     

       222
       223
        
       

     

       223
       224
        
       <script>

     

       224
       224
       -
       import { useQuery } from '@urql/vue';

     

       225
       225
       +
       import { gql, useQuery } from '@urql/vue';

     

       225
       226
        
       

     

       226
       227
        
       export default {

     

       227
       228
        
         setup() {

     

       228
       229
        
           const from = ref(0);

     

       229
       230
        
       

     

       230
       231
        
           const result = useQuery({

     

       231
       231
       -
             query: `

     

       232
       232
       +
             query: gql`

     

       232
       233
        
               query ($from: Int!, $limit: Int!) {

     

       233
       234
        
                 todos(from: $from, limit: $limit) {

     

       234
       235
        
                   id

     
···

       266
       267
        
       

     

       267
       268
        
       ```js

     

       268
       269
        
       import { reactive } from 'vue'

     

       269
       269
       -
       import { useQuery } from '@urql/vue';

     

       270
       270
       +
       import { gql, useQuery } from '@urql/vue';

     

       270
       271
        
       

     

       271
       272
        
       export default {

     

       272
       273
        
         props: ['from', 'limit'],

     

       273
       274
        
         setup({ from, limit }) {

     

       274
       275
        
           const shouldPause = computed(() => from == null || limit == null);

     

       275
       276
        
           return useQuery({

     

       276
       276
       -
             query: `

     

       277
       277
       +
             query: gql`

     

       277
       278
        
               query ($from: Int!, $limit: Int!) {

     

       278
       279
        
                 todos(from: $from, limit: $limit) {

     

       279
       280
        
                   id

     
···

       307
       308
        
       </template>

     

       308
       309
        
       

     

       309
       310
        
       <script>

     

       310
       310
       -
       import { useQuery } from '@urql/vue';

     

       311
       311
       +
       import { gql, useQuery } from '@urql/vue';

     

       311
       312
        
       

     

       312
       313
        
       export default {

     

       313
       314
        
         setup() {

     

       314
       315
        
           return useQuery({

     

       315
       315
       -
             query: `

     

       316
       316
       +
             query: gql`

     

       316
       317
        
               {

     

       317
       318
        
                 todos {

     

       318
       319
        
                   id

     
···

       364
       365
        
       we may also change the `Client`'s default `requestPolicy` by passing it there.

     

       365
       366
        
       

     

       366
       367
        
       ```js

     

       367
       367
       -
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from '@urql/vue';

     

       368
       368
       +
       import { Client, cacheExchange, fetchExchange } from '@urql/vue';

     

       368
       369
        
       

     

       369
       369
       -
       const client = createClient({

     

       370
       370
       +
       const client = new Client({

     

       370
       371
        
         url: 'http://localhost:3000/graphql',

     

       371
       371
       -
         exchanges: [dedupExchange, cacheExchange, fetchExchange],

     

       372
       372
       +
         exchanges: [cacheExchange, fetchExchange],

     

       372
       373
        
         // every operation will by default use cache-and-network rather

     

       373
       374
        
         // than cache-first now:

     

       374
       375
        
         requestPolicy: 'cache-and-network',

     
···

       415
       416
        
       `requestPolicy` of our query just once and set it to `network-only` to skip the cache.

     

       416
       417
        
       

     

       417
       418
        
       ```js

     

       418
       418
       -
       import { useQuery } from '@urql/vue';

     

       419
       419
       +
       import { gql, useQuery } from '@urql/vue';

     

       419
       420
        
       

     

       420
       421
        
       export default {

     

       421
       422
        
         setup() {

     

       422
       423
        
           const result = useQuery({

     

       423
       423
       -
             query: `

     

       424
       424
       +
             query: gql`

     

       424
       425
        
               {

     

       425
       426
        
                 todos {

     

       426
       427
        
                   id

     
···

       473
       474
        
       </template>

     

       474
       475
        
       

     

       475
       476
        
       <script>

     

       476
       476
       -
       import { useQuery } from '@urql/vue';

     

       477
       477
       +
       import { gql, useQuery } from '@urql/vue';

     

       477
       478
        
       

     

       478
       479
        
       export default {

     

       479
       480
        
         async setup() {

     

       480
       481
        
           const { data, error } = await useQuery({

     

       481
       481
       -
             query: `

     

       482
       482
       +
             query: gql`

     

       482
       483
        
               {

     

       483
       484
        
                 todos {

     

       484
       485
        
                   id

     
···

       580
       581
        
       example! We'll set up a mutation that _updates_ a todo item's title.

     

       581
       582
        
       

     

       582
       583
        
       ```js

     

       583
       583
       -
       import { useMutation } from '@urql/vue';

     

       584
       584
       +
       import { gql, useMutation } from '@urql/vue';

     

       584
       585
        
       

     

       585
       586
        
       export default {

     

       586
       587
        
         setup() {

     

       587
       587
       -
           const { executeMutation: updateTodo } = useMutation(`

     

       588
       588
       -
             mutation ($id: ID!, $title: String!) {

     

       589
       589
       -
               updateTodo (id: $id, title: $title) {

     

       588
       588
       +
           const { executeMutation: updateTodo } = useMutation(gql`

     

       589
       589
       +
             mutation($id: ID!, $title: String!) {

     

       590
       590
       +
               updateTodo(id: $id, title: $title) {

     

       590
       591
        
                 id

     

       591
       592
        
                 title

     

       592
       593
        
               }

     
···

       616
       617
        
       `executeMutation` method returns when it's called:

     

       617
       618
        
       

     

       618
       619
        
       ```js

     

       619
       619
       -
       import { useMutation } from '@urql/vue';

     

       620
       620
       +
       import { gql, useMutation } from '@urql/vue';

     

       620
       621
        
       

     

       621
       622
        
       export default {

     

       622
       623
        
         setup() {

     

       623
       623
       -
           const updateTodoResult = useMutation(`

     

       624
       624
       -
             mutation ($id: ID!, $title: String!) {

     

       625
       625
       -
               updateTodo (id: $id, title: $title) {

     

       624
       624
       +
           const updateTodoResult = useMutation(gql`

     

       625
       625
       +
             mutation($id: ID!, $title: String!) {

     

       626
       626
       +
               updateTodo(id: $id, title: $title) {

     

       626
       627
        
                 id

     

       627
       628
        
                 title

     

       628
       629
        
               }

     
···

       657
       658
        
       [Read more about errors on our "Errors" page.](./errors.md)

     

       658
       659
        
       

     

       659
       660
        
       ```js

     

       660
       660
       -
       import { useMutation } from '@urql/vue';

     

       661
       661
       +
       import { gql, useMutation } from '@urql/vue';

     

       661
       662
        
       

     

       662
       663
        
       export default {

     

       663
       664
        
         setup() {

     

       664
       664
       -
           const updateTodoResult = useMutation(`

     

       665
       665
       -
             mutation ($id: ID!, $title: String!) {

     

       666
       666
       -
               updateTodo (id: $id, title: $title) {

     

       665
       665
       +
           const updateTodoResult = useMutation(gql`

     

       666
       666
       +
             mutation($id: ID!, $title: String!) {

     

       667
       667
       +
               updateTodo(id: $id, title: $title) {

     

       667
       668
        
                 id

     

       668
       669
        
                 title

     

       669
       670
        
               }

+46 -47

docs/comparison.md

···

       35
       35
        
       

     

       36
       36
        
       ### Core Features

     

       37
       37
        
       

     

       38
       38
       -
       |                                            | urql                               | Apollo                                                                     | Relay                          |

     

       39
       39
       -
       | ------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------ |

     

       40
       40
       -
       | Extensible on a network level              | ✅ Exchanges                       | ✅ Links                                                                   | ✅ Network Layers              |

     

       41
       41
       -
       | Extensible on a cache / control flow level | ✅ Exchanges                       | 🛑                                                                         | 🛑                             |

     

       42
       42
       -
       | Base Bundle Size                           | **5.9kB** (7.1kB with bindings)    | 32.9kB                                                                     | 27.7kB (34.1kB with bindings)  |

     

       43
       43
       -
       | Devtools                                   | ✅                                 | ✅                                                                         | ✅                             |

     

       44
       44
       -
       | Subscriptions                              | ✅                                 | ✅                                                                         | ✅                             |

     

       45
       45
       -
       | Client-side Rehydration                    | ✅                                 | ✅                                                                         | ✅                             |

     

       46
       46
       -
       | Polled Queries                             | 🔶                                 | ✅                                                                         | ✅                             |

     

       47
       47
       -
       | Lazy Queries                               | ✅                                 | ✅                                                                         | ✅                             |

     

       48
       48
       -
       | Stale while Revalidate / Cache and Network | ✅                                 | ✅                                                                         | ✅                             |

     

       49
       49
       -
       | Focus Refetching                           | ✅ `@urql/exchange-refocus`        | 🛑                                                                         | 🛑                             |

     

       50
       50
       -
       | Stale Time Configuration                   | ✅ `@urql/exchange-request-policy` | ✅                                                                         | 🛑                             |

     

       51
       51
       -
       | Persisted Queries                          | ✅ `@urql/exchange-persisted`      | ✅ `apollo-link-persisted-queries`                                         | ✅                             |

     

       52
       52
       -
       | Batched Queries                            | 🛑                                 | ✅ `apollo-link-batch-http`                                                | 🟡 `react-relay-network-layer` |

     

       53
       53
       -
       | Live Queries                               | 🛑                                 | 🛑                                                                         | ✅                             |

     

       54
       54
       -
       | Defer & Stream Directives                  | ✅                                 | ✅ / 🛑 (`@defer` is supported in >=3.7.0, `@stream` is not yet supported) | 🟡 (unreleased)                |

     

       55
       55
       -
       | Switching to `GET` method                  | ✅                                 | ✅                                                                         | 🟡 `react-relay-network-layer` |

     

       56
       56
       -
       | File Uploads                               | ✅                                 | 🟡 `apollo-upload-client`                                                  | 🛑                             |

     

       57
       57
       -
       | Retrying Failed Queries                    | ✅ `@urql/exchange-retry`          | ✅ `apollo-link-retry`                                                     | ✅ `DefaultNetworkLayer`       |

     

       58
       58
       -
       | Easy Authentication Flows                  | ✅ `@urql/exchange-auth`           | 🛑 (no docs for refresh-based authentication)                              | 🟡 `react-relay-network-layer` |

     

       59
       59
       -
       | Automatic Refetch after Mutation           | ✅ (with document cache)           | 🛑                                                                         | ✅                             |

     

       38
       38
       +
       |                                            | urql                                           | Apollo                                                                                           | Relay                                                                                                            |

     

       39
       39
       +
       | ------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |

     

       40
       40
       +
       | Extensible on a network level              | ✅ Exchanges                                   | ✅ Links                                                                                         | ✅ Network Layers                                                                                                |

     

       41
       41
       +
       | Extensible on a cache / control flow level | ✅ Exchanges                                   | 🛑                                                                                               | 🛑                                                                                                               |

     

       42
       42
       +
       | Base Bundle Size                           | **10kB** (11kB with bindings)                  | ~50kB (55kB with React hooks)                                                                    | 45kB (66kB with bindings)                                                                                        |

     

       43
       43
       +
       | Devtools                                   | ✅                                             | ✅                                                                                               | ✅                                                                                                               |

     

       44
       44
       +
       | Subscriptions                              | 🔶 [Docs](./advanced/subscriptions.md)         | 🔶 [Docs](https://www.apollographql.com/docs/react/data/subscriptions/#setting-up-the-transport) | 🔶 [Docs](https://relay.dev/docs/guided-tour/updating-data/graphql-subscriptions/#configuring-the-network-layer) |

     

       45
       45
       +
       | Client-side Rehydration                    | ✅ [Docs](./advanced/server-side-rendering.md) | ✅ [Docs](https://www.apollographql.com/docs/react/performance/server-side-rendering)            | 🛑                                                                                                               |

     

       46
       46
       +
       | Polled Queries                             | 🔶                                             | ✅                                                                                               | ✅                                                                                                               |

     

       47
       47
       +
       | Lazy Queries                               | ✅                                             | ✅                                                                                               | ✅                                                                                                               |

     

       48
       48
       +
       | Stale while Revalidate / Cache and Network | ✅                                             | ✅                                                                                               | ✅                                                                                                               |

     

       49
       49
       +
       | Focus Refetching                           | ✅ `@urql/exchange-refocus`                    | 🛑                                                                                               | 🛑                                                                                                               |

     

       50
       50
       +
       | Stale Time Configuration                   | ✅ `@urql/exchange-request-policy`             | ✅                                                                                               | 🛑                                                                                                               |

     

       51
       51
       +
       | Persisted Queries                          | ✅ `@urql/exchange-persisted`                  | ✅ `apollo-link-persisted-queries`                                                               | 🔶                                                                                                               |

     

       52
       52
       +
       | Batched Queries                            | 🛑                                             | ✅ `apollo-link-batch-http`                                                                      | 🟡 `react-relay-network-layer`                                                                                   |

     

       53
       53
       +
       | Live Queries                               | ✅ (via Incremental Delivery)                  | 🛑                                                                                               | ✅                                                                                                               |

     

       54
       54
       +
       | Defer & Stream Directives                  | ✅                                             | ✅ / 🛑 (`@defer` is supported in >=3.7.0, `@stream` is not yet supported)                       | 🟡 (unreleased)                                                                                                  |

     

       55
       55
       +
       | Switching to `GET` method                  | ✅                                             | ✅                                                                                               | 🟡 `react-relay-network-layer`                                                                                   |

     

       56
       56
       +
       | File Uploads                               | ✅                                             | 🟡 `apollo-upload-client`                                                                        | 🛑                                                                                                               |

     

       57
       57
       +
       | Retrying Failed Queries                    | ✅ `@urql/exchange-retry`                      | ✅ `apollo-link-retry`                                                                           | ✅ `DefaultNetworkLayer`                                                                                         |

     

       58
       58
       +
       | Easy Authentication Flows                  | ✅ `@urql/exchange-auth`                       | 🛑 (no docs for refresh-based authentication)                                                    | 🟡 `react-relay-network-layer`                                                                                   |

     

       59
       59
       +
       | Automatic Refetch after Mutation           | ✅ (with document cache)                       | 🛑                                                                                               | ✅                                                                                                               |

     

       60
       60
        
       

     

       61
       61
        
       Typically these are all additional addon features that you may expect from a GraphQL client, no

     

       62
       62
        
       matter which framework you use it with. It's worth mentioning that all three clients support some

     
···

       82
       82
        
       |                                | urql           | Apollo              | Relay              |

     

       83
       83
        
       | ------------------------------ | -------------- | ------------------- | ------------------ |

     

       84
       84
        
       | React Bindings                 | ✅             | ✅                  | ✅                 |

     

       85
       85
       -
       | React Concurrent Hooks Support | ✅             | 🛑                  | ✅ (experimental)  |

     

       86
       86
       -
       | React Legacy Hooks Support     | ✅             | ✅                  | 🟡 `relay-hooks`   |

     

       87
       87
       -
       | React Suspense (Experimental)  | ✅             | 🛑                  | ✅                 |

     

       85
       85
       +
       | React Concurrent Hooks Support | ✅             | ✅                  | ✅                 |

     

       86
       86
       +
       | React Suspense                 | ✅             | 🛑                  | ✅                 |

     

       88
       87
        
       | Next.js Integration            | ✅ `next-urql` | 🟡                  | 🔶                 |

     

       89
       88
        
       | Preact Support                 | ✅             | 🔶                  | 🔶                 |

     

       90
       89
        
       | Svelte Bindings                | ✅             | 🟡 `svelte-apollo`  | 🟡 `svelte-relay`  |

     
···

       94
       93
        
       

     

       95
       94
        
       ### Caching and State

     

       96
       95
        
       

     

       97
       97
       -
       |                                                         | urql                                                                  | Apollo                    | Relay                                          |

     

       98
       98
       -
       | ------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------- | ---------------------------------------------- |

     

       99
       99
       -
       | Caching Strategy                                        | Document Caching, Normalized Caching with `@urql/exchange-graphcache` | Normalized Caching        | Normalized Caching (schema restrictions apply) |

     

       100
       100
       -
       | Added Bundle Size                                       | +6.5kB (with Graphcache)                                              | +0 (default)              | +0 (default)                                   |

     

       101
       101
       -
       | Automatic Garbage Collection                            | ✅                                                                    | 🔶                        | ✅                                             |

     

       102
       102
       -
       | Local State Management                                  | 🛑                                                                    | ✅                        | ✅                                             |

     

       103
       103
       -
       | Pagination Support                                      | 🔶                                                                    | 🔶                        | ✅                                             |

     

       104
       104
       -
       | Optimistic Updates                                      | ✅                                                                    | ✅                        | ✅                                             |

     

       105
       105
       -
       | Local Updates                                           | ✅                                                                    | ✅                        | ✅                                             |

     

       106
       106
       -
       | Out-of-band Cache Updates                               | 🛑 (stays true to server data)                                        | ✅                        | ✅                                             |

     

       107
       107
       -
       | Local Resolvers and Redirects                           | ✅                                                                    | ✅                        | 🛑 (not needed)                                |

     

       108
       108
       -
       | Complex Resolvers (nested non-normalized return values) | ✅                                                                    | 🛑                        | 🛑 (not needed)                                |

     

       109
       109
       -
       | Commutativity Guarantees                                | ✅                                                                    | 🛑                        | ✅                                             |

     

       110
       110
       -
       | Partial Results                                         | ✅                                                                    | ✅                        | 🛑                                             |

     

       111
       111
       -
       | Safe Partial Results (schema-based)                     | ✅                                                                    | 🛑                        | 🛑                                             |

     

       112
       112
       -
       | Persistence Support                                     | ✅                                                                    | ✅ `apollo-cache-persist` | 🟡 `@wora/relay-store`                         |

     

       113
       113
       -
       | Offline Support                                         | ✅                                                                    | 🛑                        | 🟡 `@wora/relay-offline`                       |

     

       96
       96
       +
       |                                                         | urql                                                                  | Apollo                              | Relay                                          |

     

       97
       97
       +
       | ------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------- |

     

       98
       98
       +
       | Caching Strategy                                        | Document Caching, Normalized Caching with `@urql/exchange-graphcache` | Normalized Caching                  | Normalized Caching (schema restrictions apply) |

     

       99
       99
       +
       | Added Bundle Size                                       | +8kB (with Graphcache)                                                | +0 (default)                        | +0 (default)                                   |

     

       100
       100
       +
       | Automatic Garbage Collection                            | ✅                                                                    | 🔶                                  | ✅                                             |

     

       101
       101
       +
       | Local State Management                                  | 🛑                                                                    | ✅                                  | ✅                                             |

     

       102
       102
       +
       | Pagination Support                                      | 🔶                                                                    | 🔶                                  | ✅                                             |

     

       103
       103
       +
       | Optimistic Updates                                      | ✅                                                                    | ✅                                  | ✅                                             |

     

       104
       104
       +
       | Local Updates                                           | ✅                                                                    | ✅                                  | ✅                                             |

     

       105
       105
       +
       | Out-of-band Cache Updates                               | 🛑 (stays true to server data)                                        | ✅                                  | ✅                                             |

     

       106
       106
       +
       | Local Resolvers and Redirects                           | ✅                                                                    | ✅                                  | 🛑                                             |

     

       107
       107
       +
       | Complex Resolvers (nested non-normalized return values) | ✅                                                                    | 🛑                                  | 🛑                                             |

     

       108
       108
       +
       | Commutativity Guarantees                                | ✅                                                                    | 🛑                                  | ✅                                             |

     

       109
       109
       +
       | Partial Results                                         | ✅                                                                    | ✅                                  | 🛑                                             |

     

       110
       110
       +
       | Safe Partial Results (schema-based)                     | ✅                                                                    | 🔶 (experimental via `useFragment`) | 🛑                                             |

     

       111
       111
       +
       | Persistence Support                                     | ✅                                                                    | ✅ `apollo-cache-persist`           | 🟡 `@wora/relay-store`                         |

     

       112
       112
       +
       | Offline Support                                         | ✅                                                                    | 🛑                                  | 🟡 `@wora/relay-offline`                       |

     

       114
       113
        
       

     

       115
       114
        
       `urql` is the only of the three clients that doesn't pick [normalized

     

       116
       115
        
       caching](./graphcache/normalized-caching.md) as its default caching strategy. Typically this is seen

     
···

       145
       144
        
       but often this comparison is hard to make. When you start comparing bundle sizes of these three

     

       146
       145
        
       GraphQL clients you should keep in mind that:

     

       147
       146
        
       

     

       148
       148
       -
       - Parts of the `graphql` package tree-shake away and may also be replaced (e.g. `parse`)

     

       149
       149
       -
       - All packages in `urql` reuse parts of `@urql/core` and `wonka`, which means adding all their total

     

       147
       147
       +
       - Some dependencies may be external and the above sizes listed are total minified+gzipped sizes

     

       148
       148
       +
         - `@urql/core` imports from `wonka` for stream utilities and `@0no-co/graphql.web` for GraphQL query

     

       149
       149
       +
           language utilities

     

       150
       150
       +
         - Other GraphQL clients may import other exernal dependencies.

     

       151
       151
       +
       - All `urql` packages reuse parts of `@urql/core` and `wonka`, which means adding all their total

     

       150
       152
        
         sizes up doesn't give you a correct result of their total expected bundle size.

     

       151
       151
       -
       - These sizes may change drastically given the code you write and add yourself, but can be managed

     

       152
       152
       -
         via precompilation (e.g. with `babel-plugin-graphql-tag` or GraphQL Code Generator for Apollo and

     

       153
       153
       -
         `urql`)

+3 -3

docs/graphcache/README.md

···

       70
       70
        
       without passing any options.

     

       71
       71
        
       

     

       72
       72
        
       ```js

     

       73
       73
       -
       import { createClient, dedupExchange, fetchExchange } from 'urql';

     

       73
       73
       +
       import { Client, fetchExchange } from 'urql';

     

       74
       74
        
       import { cacheExchange } from '@urql/exchange-graphcache';

     

       75
       75
        
       

     

       76
       76
       -
       const client = createClient({

     

       76
       76
       +
       const client = new Client({

     

       77
       77
        
         url: 'http://localhost:3000/graphql',

     

       78
       78
       -
         exchanges: [dedupExchange, cacheExchange({}), fetchExchange],

     

       78
       78
       +
         exchanges: [cacheExchange({}), fetchExchange],

     

       79
       79
        
       });

     

       80
       80
        
       ```

     

       81
       81

+6 -6

docs/graphcache/offline.md

···

       32
       32
        
       `offlineExchange` that's also exported by `@urql/exchange-graphcache`.

     

       33
       33
        
       

     

       34
       34
        
       ```js

     

       35
       35
       -
       import { createClient, dedupExchange, fetchExchange } from 'urql';

     

       35
       35
       +
       import { Client, fetchExchange } from 'urql';

     

       36
       36
        
       import { offlineExchange } from '@urql/exchange-graphcache';

     

       37
       37
        
       

     

       38
       38
        
       const cache = offlineExchange({

     
···

       45
       45
        
         },

     

       46
       46
        
       });

     

       47
       47
        
       

     

       48
       48
       -
       const client = createClient({

     

       48
       48
       +
       const client = new Client({

     

       49
       49
        
         url: 'http://localhost:3000/graphql',

     

       50
       50
       -
         exchanges: [dedupExchange, cache, fetchExchange],

     

       50
       50
       +
         exchanges: [cache, fetchExchange],

     

       51
       51
        
       });

     

       52
       52
        
       ```

     

       53
       53
        
       

     
···

       61
       61
        
       function from `@urql/exchange-graphcache/default-storage`.

     

       62
       62
        
       

     

       63
       63
        
       ```js

     

       64
       64
       -
       import { createClient, dedupExchange, fetchExchange } from 'urql';

     

       64
       64
       +
       import { Client, fetchExchange } from 'urql';

     

       65
       65
        
       import { offlineExchange } from '@urql/exchange-graphcache';

     

       66
       66
        
       import { makeDefaultStorage } from '@urql/exchange-graphcache/default-storage';

     

       67
       67
        
       

     
···

       81
       81
        
         },

     

       82
       82
        
       });

     

       83
       83
        
       

     

       84
       84
       -
       const client = createClient({

     

       84
       84
       +
       const client = new Client({

     

       85
       85
        
         url: 'http://localhost:3000/graphql',

     

       86
       86
       -
         exchanges: [dedupExchange, cache, fetchExchange],

     

       86
       86
       +
         exchanges: [cache, fetchExchange],

     

       87
       87
        
       });

     

       88
       88
        
       ```

     

       89
       89