docs: add final documentation updates for v3.

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0-rc.0] - 2020-11-12
+
+This release is the first release candidate for v3.0.0, which will use `@reasonml-community/graphql-ppx` as our PPX preprocessor for GraphQL operations. Breaking changes will be listed in the release notes for the first stable release of v3.0.0.
+
+### Diff
+
+https://github.com/FormidableLabs/reason-urql/compare/v2.1.0...v3.0.0-rc.0
+
 ## [2.1.0] - 2020-09-17
 
 This release brings our `urql` dependency up to v1.10.0, at parity with the current state of `urql` 🙌. There are no code changes involved from the previous RC release.

README.md

@@ -28,23 +28,37 @@ Reason bindings for Formidable's Universal React Query Library, [`urql`](https:/
 
 ## 💾 Installation
 
-#### 1. Install `reason-urql` and its `peerDependencies`.
+### 1. Install `reason-urql` and its `peerDependencies`.
 
 ```sh
 yarn add reason-urql urql graphql
 ```
 
 We try to keep our bindings as close to latest `urql` as possible. However, `urql` tends to make releases a bit ahead of `reason-urql`. To get a compatible version, we recommend always staying strictly within this project's `peerDependency` range for `urql`.
 
-#### 2. Add `@reasonml-community/graphql-ppx`.
+#### 1a. **Important note for users of `bs-platform>=8.0.0`**.
+
+If using `bs-platform>=8.0.0` you'll need to use [`yarn resolutions`](https://classic.yarnpkg.com/en/docs/selective-version-resolutions/) to specify a specific version of `wonka` to resolve. `urql` has an explicit dependency on latest `wonka` `v4`, which is incompatible with `bs-platform>=8.0.0`. See [this issue](https://github.com/kitten/wonka/issues/85) for more details.
+
+In your `package.json`, add the following:
+
+```json
+"resolutions": {
+  "wonka": "5.0.0-rc.1"
+}
+```
+
+If you're using `npm`, you may need to stay on `[email protected]` until `urql` takes a dependency on `wonka>=5.0.0`.
+
+### 2. Add `@reasonml-community/graphql-ppx`.
 
 To get the most out of compile time type checks for your GraphQL queries, mutations, and subscriptions, we use [`@reasonml-community/graphql-ppx`](https://github.com/reasonml-community/graphql-ppx). Add this to your project's `devDependencies`.
 
 ```sh
 yarn add @reasonml-community/graphql-ppx --dev
 ```
 
-#### 3. Update `bsconfig.json`.
+### 3. Update `bsconfig.json`.
 
 Add `reason-urql`, `wonka`, and `@reasonml-community/graphql-ppx` to your `bs-dependencies` and `@reasonml-community/graphql-ppx/ppx` to your `ppx_flags` in `bsconfig.json`.
 
@@ -59,7 +73,7 @@ Add `reason-urql`, `wonka`, and `@reasonml-community/graphql-ppx` to your `bs-de
 }
 ```
 
-#### 4. Send an introspection query to your API.
+### 4. Send an introspection query to your API.
 
 Finally, you'll need to send an introspection query to your GraphQl API, using a tool like [`graphql-cli`](https://github.com/Urigo/graphql-cli/). You should generate a file called `graphql_schema.json` at the root of your project that `graphql-ppx` can use to type check your queries. **You should check this file into version control** and keep it updated as your API changes.
 

docs/client-and-provider.md

@@ -151,7 +151,7 @@ module GetAllDogs = [%graphql
 
 Client.executeQuery(~client, ~query=(module GetAllDogs), ())
   |> Wonka.subscribe((. data) => {
-    switch(Client.(data.response)) {
+    switch(Types.(data.response)) {
       | Data(d) => /* Access data returned from executing the request. */
       | Error(e) => /* Access any errors returned from executing the request. */
       | Empty => /* Fallback if neither Data nor Error return information. */
@@ -188,7 +188,7 @@ module GetAllDogs = [%graphql
 
 Client.query(~client, ~query=(module GetAllDogs), ())
   |> Js.Promise.then_(data => {
-    switch(Client.(data.response)) {
+    switch(Types.(data.response)) {
       | Data(d) => /* Access data returned from executing the request. */
       | Error(e) => /* Access any errors returned from executing the request. */
       | Empty => /* Fallback if neither Data nor Error return information. */
@@ -241,7 +241,7 @@ module LikeDog = [%graphql
 
 Client.executeMutation(~client, ~mutation=(module LikeDog), LikeDog.{ key: "VmeRTX7j-" })
   |> Wonka.subscribe((. data) => {
-    switch(Client.(data.response)) {
+    switch(Types.(data.response)) {
       | Data(d) => /* Access data returned from executing the request. */
       | Error(e) => /* Access any errors returned from executing the request. */
       | Empty => /* Fallback if neither Data nor Error return information. */
@@ -278,7 +278,7 @@ module LikeDog = [%graphql
 
 Client.mutation(~client, ~mutation=(module LikeDog), LikeDog.{ key: "VmeRTX7j-" })
   |> Js.Promise.then_(data => {
-    switch (Client.(data.response)) {
+    switch (Types.(data.response)) {
       | Data(d) => /* Access data returned from executing the request. */
       | Error(e) => /* Access any errors returned from executing the request. */
       | Empty => /* Fallback if neither Data nor Error return information. */
@@ -326,7 +326,7 @@ module SubscribeMessages = [%graphql
 
 Client.executeSubscription(~client, ~subscription=(module SubscribeMessages), ())
   |> Wonka.subscribe((. data) => {
-    switch(Client.(data.response)) {
+    switch(Types.(data.response)) {
       | Data(d) => /* Access data returned from executing the request. */
       | Error(e) => /* Access any errors returned from executing the request. */
       | Empty => /* Fallback if neither Data nor Error return information. */

docs/error.md

@@ -27,7 +27,7 @@ switch (response) {
 Depending on the types of errors you get from your GraphQL API, you may want to do different things. Here's an example showing how to handle `networkError`s and `graphQLErrors` indepedently.
 
 ```reason
-let ({ response }, _) = useQuery(~request, ());
+let ({ response }, _) = useQuery(~query=(module MyQuery), ());
 
 switch (response) {
   | Error(e) =>

docs/getting-started.md

@@ -4,19 +4,19 @@ This document well help you get started with `reason-urql`. It picks up right wh
 
 ## Setting Up the Client
 
-To get started with `reason-urql`, the first thing you'll want to do is create your client. Your client is the core orchestrator of communication with your GraphQL API, handling all outgoing requests and incoming responses. To create a client, simply call the `make` function from the `Client` module.
+To get started with `reason-urql`, the first thing you'll want to do is create your client. Your client is the core orchestrator of communication with your GraphQL API, handling all outgoing requests and incoming responses. To create a client, call the `make` function from the `Client` module.
 
 ```reason
 open ReasonUrql;
 
 let client = Client.make(~url="https://mygraphqlapi.com/graphql", ());
 ```
 
-The `client` accepts a few other configuration options, including `fetchOptions` and `exchanges`, but only `url` is required. By default, `reason-urql` will apply `urql`'s `defaultExchanges` if no exchanges are provided; this will include the `fetchExchange` for executing requests, the `cacheExchange` for caching responses from your API, and the `dedupExchange` for deduplicating in-flight requests. It will also apply standard fetch options if no `fetchOptions` argument is provided, using `POST` as the request method and `application/json` as the `Content-Type` header. We'll see later how to work with these options.
+The `client` accepts a few other configuration options, including `fetchOptions` and `exchanges`, but only `url` is required. By default, `reason-urql` will apply `urql`'s `defaultExchanges` if no exchanges are provided; this will include the `fetchExchange` for executing requests, the `cacheExchange` for caching responses from your API, and the `dedupExchange` for deduplicating in-flight requests. It will also apply standard fetch options if no `fetchOptions` argument is provided, using `POST` as the HTTP method and `application/json` as the `Content-Type` header. We'll see later how to work with these options.
 
 ## Linking Client with Provider
 
-Once you have your `Client` setup, you'll need to pass it to your `Provider`, which should wrap the root level of your application. This allows `reason-urql`'s hooks to access the `Client` to execute operations lower down in your React tree.
+Once you have your `Client` setup, you'll need to pass it to your `Provider`, which should wrap the root level of your application. This allows `reason-urql`'s hooks to access the `Client` in order to execute operations lower down in your React tree.
 
 ```reason
 open ReasonUrql;
@@ -52,11 +52,9 @@ module DogsQuery = [%graphql
 
 [@react.component]
 let make = () => {
-  /* Build your request by calling .make on your query. */
-  let request = DogsQuery.make();
-
-  /* Pass the request to useQuery. */
-  let (Hooks.{ response }, executeQuery) = Hooks.useQuery(~request, ());
+  /* Pass the graphql-ppx module as a first-class module to useQuery. */
+  let (Hooks.{response}, executeQuery)
+    = Hooks.useQuery(~query=(module DogsQuery), ());
 
   /* Pattern match on the response variant.
   This variant has constructors for Fetching, Data(d), PartialData(d, e) Error(e), and Empty. */
@@ -65,11 +63,11 @@ let make = () => {
     | Data(d)
     | PartialData(d, _) => {
       Array.map(dog =>
-        <div key=dog##key>
-          <span> {j|$dog##name $dog##likes|j}->React.string </span>
-          <span> dog##breed->React.string <span>
+        <div key=dog.key>
+          <span> {j|$dog.name $dog.likes|j}->React.string </span>
+          <span> dog.breed->React.string <span>
         </div>,
-        d##dogs
+        d.dogs
       )
     }
     | Error(e) =>
@@ -82,11 +80,11 @@ let make = () => {
 }
 ```
 
-Sweet 😎! We've executed a query with our `useQuery` hook. Notice that we didn't have to write _any_ types to get 💯% type inference and type safety on the response. We use type information included in the query module you pass to `useQuery` to ensure that you're using the data returned by your query in a fully safe way.
+Sweet 😎! We've executed a query with our `useQuery` hook. Notice that we didn't have to write _any_ types to get 💯% type inference and type safety on the response. We use type information included in the query module you pass to `useQuery` to ensure that you're using the data returned by your query in a fully type-safe way.
 
 ## Can I See an Example?
 
-Check out the example in `examples/2-query` to see a more involved example of using `useQuery`, in addition to `reason-urql`'s `Query` component.
+Check out the example in `examples/2-query` to see a more involved example of using `useQuery`.
 
 ## Writing Your First Mutation
 
@@ -112,13 +110,11 @@ module LikeDogMutation = [%graphql
 
 [@react.component]
 let make = (~key: string) => {
-  /* Build your request by calling .make on your mutation, passing variables as labeled arguments. */
-  let request = LikeDogMutation.make(~key, ());
-
   /* Pass the request to useMutation. */
-  let (_, executeMutation) = Hooks.useMutation(~request);
+  let (_, executeMutation) =
+    Hooks.useMutation(~mutation=(module LikeDogMutation));
 
-  <button onClick={_e => executeMutation() |> ignore}>
+  <button onClick={_e => executeMutation({key}) |> ignore}>
       "Execute the Mutation (and Reward a Good Dog)"->React.string
   </button>
 }
@@ -133,14 +129,12 @@ open ReasonUrql;
 
 [@react.component]
 let make = (~key: string) => {
-  /* Build your request by calling .make on your mutation, passing variables as labeled arguments. */
-  let request = LikeDogMutation.make(~key, ());
-
   /* Pass the request to useMutation. */
-  let (Hooks.{ response }, executeMutation) = Hooks.useMutation(~request);
+  let (Hooks.{response}, executeMutation)
+    = Hooks.useMutation(~mutation=(module LikeDogMutation));
 
   let button = React.useMemo1(() =>
-    <button onClick={_e => executeMutation() |> ignore}>
+    <button onClick={_e => executeMutation({key}) |> ignore}>
         "Execute the Mutation (and Reward a Good Dog)"->React.string
     </button>,
     [|executeMutation|]
@@ -165,4 +159,4 @@ let make = (~key: string) => {
 
 ## Can I See an Example?
 
-Check out the example in `examples/3-mutation` to see a more involved example of using `useMutation`, in addition to `reason-urql`'s `Mutation` component.
+Check out the example in `examples/3-mutation` to see a more involved example of using `useMutation`.