You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Curious to know more about the internals of `reason-urql`? You've come to the right place!
4
+
5
+
## The `response` variant
6
+
7
+
`reason-urql` uses a special `variant` called `response` to make pattern matching on the results you get from your GraphQL API as easy as possible. In JS land, users have to do something like the following:
8
+
9
+
```js
10
+
// Inside a React component
11
+
const [result] =useQuery({ query, variables });
12
+
13
+
if (result.fetching) {
14
+
return<Loading />; // Some fetching UI.
15
+
} elseif (result.error) {
16
+
return<Error error={result.error} />; // Some error UI.
17
+
}
18
+
19
+
return<Data data={result.data} />; // Some data UI.
20
+
```
21
+
22
+
This is fine and works great for JS users, but we have pattern matching in Reason! Enter `reason-urql`'s `response` variant. `response` is a single variant with five constructors:
23
+
24
+
```reason
25
+
type response('response) {
26
+
| Fetching
27
+
| Data('response)
28
+
| PartialData('response, GraphQLError.t)
29
+
| Error(CombinedError.t)
30
+
| Empty;
31
+
}
32
+
```
33
+
34
+
This variant is always available on the record returned by `reason-urql`'s hooks. Let's go over what each constructor (or "tag") means and when you'd want to pattern match on each.
35
+
36
+
### The `Fetching` constructor
37
+
38
+
`Fetching` refers to when your query, mutation, or subscription is fetching data but has not yet received a response. For `useQuery` and `useMutation` this will turn `true` when the initial request has been fired off, and turn to `false` once data (or an error) has been received. Note that for `useSubscription`, `fetching` will always be `true` as long as the subcription is active. For this case, the `Data` constructor will take precedence even while `fetching` is still `true`.
39
+
40
+
### The `Data` constructor
41
+
42
+
`Data(d)` refers to when your query, mutation, or subscription has received data from your GraphQL API. It takes a single argument, `d`, that represents the actual data returned by your GraphQL API. You can then operate on `d` however you like to return UI.
43
+
44
+
### The `PartialData` constructor
45
+
46
+
`PartialData(d, e)` is quite similar to `Data` with one major difference – it represents the case where **both** data and errors were returned by your GraphQL API. This can happen if data resolves fine for parts of your query or mutation but fails to resolve for others. The type of `e` is our binding to `GraphQLError`, which gives you access to the message, source locations, and extensions of the error returned by your GraphQL server.
47
+
48
+
### The `Error` constructor
49
+
50
+
`Error(e)` refers to when your query, mutation, or subscription has encountered an error in the course of execution. It takes a single argument, `e`, that represents the [`CombinedError`](https://formidable.com/open-source/urql/docs/basics/errors/) returned by `urql`. `CombinedError` will return a record containing `message`, `networkError`, `graphQLErrors`, and `response`, allowing you to subsequently render different UI based on the _types_ of errors you encountered.
51
+
52
+
### The `Empty` constructor
53
+
54
+
The `Empty` constructor is reserved for the rare case where `reason-urql` has made a request to your GraphQL API but neither `data` nor `errors` were returned. In practice, this case is very rare. It may occur if your user goes offline unexpectedly or if your GraphQL API returns `undefined` in cases where no data matches a particular resolver. Think of it as your fallback case.
Copy file name to clipboardExpand all lines: docs/client-and-provider.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -115,7 +115,7 @@ Imperatively execute a GraphQL query operation.
115
115
|`pollInterval`|`int=?`| Optional. Instructs the client to reexecute the query every `pollInterval` milliseconds. |
116
116
|`meta`|`Types.operationDebugMeta=?`| Optional. Add metadata that is only available in development with devtools. |
117
117
118
-
`client.executeQuery` returns a [`wonka``source`](https://wonka.kitten.sh/api/sources) containing the results of executing the query. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `NotFound`, in addition to `data` and `error` fields for accessing the raw response values if desired.
118
+
`client.executeQuery` returns a [`wonka``source`](https://wonka.kitten.sh/api/sources) containing the results of executing the query. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `Empty`, in addition to `data` and `error` fields for accessing the raw response values if desired.
| Data(d) => /* Access data returned from executing the request. */
147
147
| Error(e) => /* Access any errors returned from executing the request. */
148
-
| NotFound => /* Fallback if neither Data nor Error return information. */
148
+
| Empty => /* Fallback if neither Data nor Error return information. */
149
149
}
150
150
});
151
151
```
@@ -164,7 +164,7 @@ The same as `Client.executeQuery`, but returns a `Js.Promise.t` rather than a `w
164
164
|`pollInterval`|`int=?`| Optional. Instructs the client to reexecute the query every `pollInterval` milliseconds. |
165
165
|`meta`|`Types.operationDebugMeta=?`| Optional. Add metadata that is only available in development with devtools. |
166
166
167
-
`Client.query` returns a `Js.Promise.t` containing the results of executing the query. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `NotFound`, in addition to `data` and `error` fields for accessing the raw response values if desired.
167
+
`Client.query` returns a `Js.Promise.t` containing the results of executing the query. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `Empty`, in addition to `data` and `error` fields for accessing the raw response values if desired.
| Data(d) => /* Access data returned from executing the request. */
196
196
| Error(e) => /* Access any errors returned from executing the request. */
197
-
| NotFound => /* Fallback if neither Data nor Error return information. */
197
+
| Empty => /* Fallback if neither Data nor Error return information. */
198
198
}
199
199
});
200
200
```
@@ -213,7 +213,7 @@ Execute a GraphQL mutation operation.
213
213
|`pollInterval`|`int=?`| Optional. Instructs the client to reexecute the mutation every `pollInterval` milliseconds. |
214
214
|`meta`|`Types.operationDebugMeta=?`| Optional. Add metadata that is only available in development with devtools. |
215
215
216
-
`Client.executeMutation` returns a [`wonka``source`](https://wonka.kitten.sh/api/sources) containing the results of executing the mutation. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `NotFound`, in addition to `data` and `error` fields for accessing the raw response values if desired.
216
+
`Client.executeMutation` returns a [`wonka``source`](https://wonka.kitten.sh/api/sources) containing the results of executing the mutation. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `Empty`, in addition to `data` and `error` fields for accessing the raw response values if desired.
| Data(d) => /* Access data returned from executing the request. */
245
245
| Error(e) => /* Access any errors returned from executing the request. */
246
-
| NotFound => /* Fallback if neither Data nor Error return information. */
246
+
| Empty => /* Fallback if neither Data nor Error return information. */
247
247
}
248
248
});
249
249
```
@@ -262,7 +262,7 @@ The same as `Client.executeMutation`, but returns a `Js.Promise.t` rather than a
262
262
|`pollInterval`|`int=?`| Optional. Instructs the client to reexecute the mutation every `pollInterval` milliseconds. |
263
263
|`meta`|`Types.operationDebugMeta=?`| Optional. Add metadata that is only available in development with devtools. |
264
264
265
-
`Client.mutation` returns a `Js.Promise.t` containing the results of executing the mutation. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `NotFound`, in addition to `data` and `error` fields for accessing the raw response values if desired.
265
+
`Client.mutation` returns a `Js.Promise.t` containing the results of executing the mutation. The result record has a variant type called `response` with constructors for `Data(d)`, `Error(e)`, and `Empty`, in addition to `data` and `error` fields for accessing the raw response values if desired.
0 commit comments