Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add bindings for useClient hook. #159

Merged
merged 3 commits into from
Apr 12, 2020
Merged

Add bindings for useClient hook. #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a445b55
Add bindings for useClient hook.
Apr 11, 2020
e845066
Remove bs-fetch peerDep from installation steps.
Apr 11, 2020
c6cb1e6
Add useClient to docs.
Apr 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,10 @@ Reason bindings for Formidable's Universal React Query Library, [`urql`](https:/

## 💾 Installation

#### 1. Install `reason-urql` & `bs-fetch` peer dependency.
#### 1. Install `reason-urql`.

```sh
yarn add reason-urql bs-fetch
yarn add reason-urql
```

#### 2. Add `graphql_ppx_re` or `graphql_ppx`.
Expand Down Expand Up @@ -159,6 +159,7 @@ This project follows the [all contributors spec](https://github.com/kentcdodds/a

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

## Maintenance Status
Expand Down
134 changes: 132 additions & 2 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,30 @@ let make = () => {

Check out `examples/5-subscription` to see an example of using the `useSubscription` hook.

### `useClient`

`useClient` allows you to access your `urql` client instance anywhere within your React component tree.

#### Return Type

| Return Value | Type | Description |
| ------------ | ---------- | ------------------------------------------------ |
| `client` | `Client.t` | The `urql` client instance for your application. |

#### Example

```reason
open ReasonUrql;
open Hooks;

[@react.component]
let make = () => {
let client = useClient();

<div> "You can now use your client!"->React.string </div>
}
```

## Components

### `Query`
Expand Down Expand Up @@ -647,6 +671,14 @@ Imperatively execute a GraphQL query operation.
| `request` | `UrqlTypes.request` | The `graphql_ppx` request representing your query. Generated by calling `.make()` on the `graphql_ppx` module. If you're not using `graphql_ppx`, pass a `Js.t` of the following shape: `{. "query": string, "variables": Js.Json.t, "parse": Js.Json.t => 'response }` |
| `opts` | `option(Client.ClientTypes.partialOperationContext)=?` | Optional. Additional options to pass to the client to alter the execution parameters of the query. |

#### Return Type

Returns a `wonka` `source` 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.

| Return | Description |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Wonka.Types.sourceT(ClientTypes.clientResponse('response))` | A `wonka` `source` containing a record of the results of query execution. Use the `response` field on this record for pattern matching. |

#### Example

```reason
Expand Down Expand Up @@ -676,7 +708,52 @@ Client.executeQuery(~client, ~request=GetAllDogs.make(), ())
});
```

#### `Client.executeMutation`
### `Client.query`

The same as `Client.executeQuery`, but returns a `Promise` rather than a `wonka` `source`.

| Argument | Type | Description |
| --------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `Client.t` | The `urql` client instance. |
| `request` | `UrqlTypes.request` | The `graphql_ppx` request representing your query. Generated by calling `.make()` on the `graphql_ppx` module. If you're not using `graphql_ppx`, pass a `Js.t` of the following shape: `{. "query": string, "variables": Js.Json.t, "parse": Js.Json.t => 'response }` |
| `opts` | `option(Client.ClientTypes.partialOperationContext)=?` | Optional. Additional options to pass to the client to alter the execution parameters of the query. |

#### Return Type

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.

| Return | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `Js.Promise.t(ClientTypes.clientResponse('response))` | A `Promise` containing a record of the results of query execution. Use the `response` field on this record for pattern matching. |

```reason
open ReasonUrql;

let client = Client.make(~url="https://localhost:3000/graphql", ());

module GetAllDogs = [%graphql
{|
query dogs {
dogs {
name
breed
likes
}
}
|}
];

Client.query(~client, ~request=GetAllDogs.make(), ())
|> Js.Promise.then_((. result) => {
switch(result.response) {
| Data(d) => /* Access data returned from executing the request. */
| Error(e) => /* Access any errors returned from executing the request. */
| NotFound => /* Fallback if neither Data nor Error return information. */
}
});
```

### `Client.executeMutation`

Execute a GraphQL mutation operation.

Expand All @@ -686,6 +763,14 @@ Execute a GraphQL mutation operation.
| `request` | `UrqlTypes.request` | The `graphql_ppx` request representing your mutation. Generated by calling `.make()` on the `graphql_ppx` module. If you're not using `graphql_ppx`, pass a `Js.t` of the following shape: `{. "query": string, "variables": Js.Json.t, "parse": Js.Json.t => 'response }` |
| `opts` | `option(Client.ClientTypes.partialOperationContext)=?` | Optional. Additional options to pass to the client to alter the execution parameters of the mutation. |

#### Return Type

Returns a `wonka` `source` 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.

| Return | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Wonka.Types.sourceT(ClientTypes.clientResponse('response))` | A `wonka` `source` containing a record of the results of mutation execution. Use the `response` field on this record for pattern matching. |

#### Example

```reason
Expand Down Expand Up @@ -715,7 +800,52 @@ Client.executeMutation(~client, ~request=LikeDog.make(~key="VmeRTX7j-", ()), ())
});
```

#### `Client.executeSubscription`
### `Client.mutation`

The same as `Client.executeMutation`, but returns a `Promise` rather than a `wonka` `source`.

| Argument | Type | Description |
| --------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `Client.t` | The `urql` client instance. |
| `request` | `UrqlTypes.request` | The `graphql_ppx` request representing your query. Generated by calling `.make()` on the `graphql_ppx` module. If you're not using `graphql_ppx`, pass a `Js.t` of the following shape: `{. "query": string, "variables": Js.Json.t, "parse": Js.Json.t => 'response }` |
| `opts` | `option(Client.ClientTypes.partialOperationContext)=?` | Optional. Additional options to pass to the client to alter the execution parameters of the mutation. |

#### Return Type

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.

| Return | Description |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Js.Promise.t(ClientTypes.clientResponse('response))` | A `Promise` containing a record of the results of mutation execution. Use the `response` field on this record for pattern matching. |

```reason
open ReasonUrql;

let client = Client.make(~url="https://localhost:3000/graphql", ());

module LikeDog = [%graphql
{|
mutation likeDog($key: ID!) {
likeDog(key: $key) {
name
breed
likes
}
}
|}
];

Client.mutation(~client, ~request=LikeDog.make(~key="VmeRTX7j-", ()), ())
|> Js.Promise.then_((. result) => {
switch(result.response) {
| Data(d) => /* Access data returned from executing the request. */
| Error(e) => /* Access any errors returned from executing the request. */
| NotFound => /* Fallback if neither Data nor Error return information. */
}
});
```

### `Client.executeSubscription`

Execute a GraphQL subscription operation. If using the `executeSubscription` method, be sure your client is configured with the `subscriptionExchange`.

Expand Down
2 changes: 2 additions & 0 deletions src/ReasonUrql.re
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,9 @@ module Hooks = {
response: UrqlTypes.response('ret),
extensions: option('extensions),
};

include UrqlUseMutation;
include UrqlUseQuery;
include UrqlUseSubscription;
include UrqlUseClient;
};
1 change: 1 addition & 0 deletions src/hooks/UrqlUseClient.re
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[@bs.module "urql"] external useClient: unit => UrqlClient.t = "useClient";
1 change: 1 addition & 0 deletions src/hooks/UrqlUseClient.rei
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
[@bs.module "urql"] external useClient: unit => UrqlClient.t = "useClient";