Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
https://github.com/reasonml-community/reason-apollo-hooks

Deprecated in favor of https://github.com/reasonml-community/graphql-ppx
https://github.com/reasonml-community/reason-apollo-hooks
apollo graphql reasonml
Last synced: about 2 months ago
JSON representation
Deprecated in favor of https://github.com/reasonml-community/graphql-ppx
Host: GitHub
URL: https://github.com/reasonml-community/reason-apollo-hooks
Owner: reasonml-community
License: mit
Archived: true
Created: 2019-04-23T17:16:19.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2020-11-19T12:35:42.000Z (over 3 years ago)
Last Synced: 2024-04-14T11:53:35.546Z (3 months ago)
Topics: apollo, graphql, reasonml
Language: Reason
Homepage: https://reasonml-community.github.io/reason-apollo-hooks/
Size: 1.32 MB
Stars: 139
Watchers: 11
Forks: 28
Open Issues: 24
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists

awesome-list - reason-apollo-hooks - community/graphql-ppx | reasonml-community | 140 | (Reason)
awesome-reasonml - reason-apollo-hooks - Ergonomic focused bindings for @apollo/react-hooks (Reason / Libraries and Bindings)
awesome-reasonml - reason-apollo-hooks - Ergonomic focused bindings for @apollo/react-hooks (Reason / Libraries and Bindings)
README

        # ⚠️ Prefer the new https://github.com/reasonml-community/reason-apollo-client instead

---

# reason-apollo-hooks

[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors-)

Reason bindings for the official [@apollo/react-hooks](https://www.npmjs.com/package/@apollo/react-hooks)

## Table of contents

- [reason-apollo-hooks](#reason-apollo-hooks)

  - [Table of contents](#table-of-contents)

  - [Installation :arrow_up:](#installation-arrowup)

  - [Setting up :arrow_up:](#setting-up-arrowup)

    - [Usage with reason-apollo :arrow_up:](#usage-with-reason-apollo-arrowup)

  - [Available hooks :arrow_up:](#available-hooks-arrowup)

    - [useQuery :arrow_up:](#usequery-arrowup)

    - [useMutation :arrow_up:](#usemutation-arrowup)

    - [useSubscription :arrow_up:](#usesubscription-arrowup)

  - [Cache :arrow_up:](#cache-arrowup)

  - [Fragment :arrow_up:](#fragment-arrowup)

  - [Getting it running](#getting-it-running)

  - [Contributors ✨](#contributors-%e2%9c%a8)

## Installation [:arrow_up:](#table-of-contents)

```

yarn add reason-apollo-hooks [email protected] @apollo/react-hooks

```

BuckleScript <= 5.0.0

```

yarn add [email protected] [email protected] @apollo/react-hooks

```

Follow the installation instructions of [graphql_ppx_re](https://github.com/baransu/graphql_ppx_re).

Then update your bsconfig.json

```diff

"bs-dependencies": [

  ...

+ "reason-apollo-hooks",

+ "reason-apollo"

]

```

## Setting up [:arrow_up:](#table-of-contents)

Add the provider in the top of the tree

```reason

/* Create an InMemoryCache */

let inMemoryCache = ApolloInMemoryCache.createInMemoryCache();

/* Create an HTTP Link */

let httpLink =

  ApolloLinks.createHttpLink(~uri="http://localhost:3010/graphql", ());

let client =

  ReasonApollo.createApolloClient(~link=httpLink, ~cache=inMemoryCache, ());

let app =

 

   ...

 

```

### Usage with reason-apollo [:arrow_up:](#table-of-contents)

To use with `reason-apollo`'s `ReasonApollo.Provider` already present in your project:

```reason

let client = ... // create Apollo client

ReactDOMRe.renderToElementWithId(

  

    

      

    

  ,

  "root",

);

```

## Available hooks [:arrow_up:](#table-of-contents)

### useQuery [:arrow_up:](#table-of-contents)

```reason

open ApolloHooks

module UserQuery = [%graphql {|

  query UserQuery {

    currentUser {

      name

    }

  }

|}];

[@react.component]

let make = () => {

  /* Both variant and records available */

  let (simple, _full) = useQuery(UserQuery.definition);

  


  {

    switch(simple) {

      | Loading => {React.string("Loading...")}

      | Data(data) =>

        {React.string(data##currentUser##name)}

      | NoData

      | Error(_) => {React.string("Get off my lawn!")}

    }

  }

  

}

```

Using the `full` record for more advanced cases

```reason

[@react.component]

let make = () => {

  /* Both variant and records available */

  let (_simple, full) = useQuery(UserQuery.definition);

  


  {

    switch(full) {

      | { loading: true }=> {React.string("Loading...")}

      | { data: Some(data) } =>

        {React.string(data##currentUser##name)}

      | any other possibilities =>

      | { error: Some(_) } => {React.string("Get off my lawn!")}

    }

  }

  

}

```

Using `fetchPolicy` to change interactions with the `apollo` cache, see [apollo docs](https://www.apollographql.com/docs/react/api/react-apollo/#optionsfetchpolicy).

```reason

let (_simple, full) = useQuery(~fetchPolicy=NetworkOnly, UserQuery.definition);

```

Using `errorPolicy` to change how errors are handled, see [apollo docs](https://www.apollographql.com/docs/react/api/react-apollo/#optionserrorpolicy).

```reason

let (simple, _full) = useQuery(~errorPolicy=All, UserQuery.definition);

```

Using `skip` to skip query entirely, see [apollo docs](https://www.apollographql.com/docs/react/api/react-apollo/#configskip).

```reason

let (simple, _full) =

  useQuery(

    ~skip=

      switch (value) {

      | None => true

      | _ => false

      },

    UserQuery.definition,

  );

```

### useMutation [:arrow_up:](#table-of-contents)

```reason

module ScreamMutation = [%graphql {|

  mutation ScreamMutation($screamLevel: Int!) {

    scream(level: $screamLevel) {

      error

    }

  }

|}];

[@react.component]

let make = () => {

  /* Both variant and records available */

  let ( screamMutation, simple, _full ) =

    useMutation(~variables=ScreamMutation.makeVariables(~screamLevel=10, ()), ScreamMutation.definition);

  let scream = (_) => {

    screamMutation()

      |> Js.Promise.then_(((simple, _full)) => {

           // Trigger side effects by chaining the promise returned by screamMutation()

           switch (simple) {

             // You *must* set the error policy to be able to handle errors

             // in then_. See EditPersons.re for more

           | ApolloHooks.Mutation.Errors(_theErrors) => Js.log("OH NO!")

           | NoData => Js.log("NO DATA?")

           | Data(_theData) => Js.log("DATA!")

           };

           Js.Promise.resolve();

         })

      |> ignore

  }

  // Use simple (and/or full) for (most) UI feedback

  


    {switch (simple) {

     | NotCalled

     | Data(_) => React.null

     | Loading =>  "Screaming!"->React.string 

     | NoData

     | Error(_) =>  "Something went wrong!"->React.string 

     }}

    

      {React.string("You kids get off my lawn!")}

    

  

}

```

If you don't know the value of the variables yet you can pass them in later

```reason

[@react.component]

let make = () => {

  /* Both variant and records available */

  let ( screamMutation, _simple, _full ) = useMutation(ScreamMutation.definition);

  let scream = (_) => {

    screamMutation(~variables=ScreamMutation.makeVariables(~screamLevel=10, ()), ())

      |> Js.Promise.then_(((simple, _full)) => {

           ...

         })

      |> ignore

  }

  


    

      {React.string("You kids get off my lawn!")}

    

  

}

```

### useSubscription [:arrow_up:](#table-of-contents)

In order to use subscriptions, you first need to set up your websocket link:

```diff

/* Create an InMemoryCache */

let inMemoryCache = ApolloInMemoryCache.createInMemoryCache();

/* Create an HTTP Link */

let httpLink =

  ApolloLinks.createHttpLink(~uri="http://localhost:3010/graphql", ());

+

+/* Create a WS Link */

+let webSocketLink =

+  ApolloLinks.webSocketLink({

+    uri: "wss://localhost:3010/graphql",

+    options: {

+      reconnect: true,

+      connectionParams: None,

+    },

+  });

+

+/* Using the ability to split links, you can send data to each link

+   depending on what kind of operation is being sent */

+let link =

+  ApolloLinks.split(

+    operation => {

+      let operationDefition =

+        ApolloUtilities.getMainDefinition(operation.query);

+      operationDefition.kind == "OperationDefinition"

+      && operationDefition.operation == "subscription";

+    },

+    webSocketLink,

+    httpLink,

+  );

let client =

-  ReasonApollo.createApolloClient(~link=httpLink, ~cache=inMemoryCache, ());

+  ReasonApollo.createApolloClient(~link, ~cache=inMemoryCache, ());

let app =

 

   ...

 

```

Then, you can implement `useSubscription` in a similar manner to `useQuery`

```reason

module UserAdded = [%graphql {|

  subscription userAdded {

    userAdded {

      id

      name

    }

  }

|}];

[@react.component]

let make = () => {

  let (userAddedSubscription, _full) = ApolloHooks.useSubscription(UserAdded.definition);

  switch (userAddedSubscription) {

    | Loading => 
 {ReasonReact.string("Loading")} 

    | Error(error) =>  {ReasonReact.string(error##message)} 

    | Data(_response) =>

      

      

      

    

  };

};

```

## Cache [:arrow_up:](#table-of-contents)

There are a couple of caveats with manual cache updates.

**TL;DR**

1. If you need to remove items from cached data, it is enough to just filter them out and save the result into cache as is.

2. If you need to add the result of a mutation to a list of items with the same shape, you simply concat it with the list and save into cache as it.

3. When you need to update a field, you have to resort to raw javascript to use spread operator on `Js.t` object in order to preserve `__typename` that `apollo` adds to all queries by default.

An example of cache update could look like this:

```reason

module PersonsQuery = [%graphql

{|

  query getAllPersons  {

    allPersons  {

      id

      age

      name

    }

  }

|}

];

module PersonsReadQuery = ApolloClient.ReadQuery(PersonsQuery);

module PersonsWriteQuery = ApolloClient.WriteQuery(PersonsQuery);

external cast: Js.Json.t => PersonsQuery.t = "%identity";

let updatePersons = (~client, ~name, ~age) => {

  let query = PersonsQuery.make();

  let readQueryOptions = ApolloHooks.Utils.toReadQueryOptions(query);

  // can throw exception of cache is empty

  switch (PersonsReadQuery.readQuery(client, readQueryOptions)) {

  | exception _ => ()

  | cachedResponse =>

    switch (cachedResponse |> Js.Nullable.toOption) {

    | None => ()

    | Some(cachedPersons) =>

      // readQuery will return unparsed data with __typename field, need to cast it since

      // it has type Json.t, but we know it will have the same type as PersonsReadQuery.t

      let persons = cast(cachedPersons);

      // to remove items, simply filter them out

      let updatedPersons = {

        "allPersons":

          Belt.Array.keep(persons##allPersons, person => person##age !== age),

      };

      // when updating items, __typename must be preserved, but since it is not a record,

      // can't use spread, so use JS to update items

      let updatedPersons = {

        "allPersons":

          Belt.Array.map(persons##allPersons, person =>

            person##name === name ? [%bs.raw {| {...person, age } |}] : person

          ),

      };

      PersonsWriteQuery.make(

        ~client,

        ~variables=query##variables,

        ~data=updatedPersons,

        (),

      );

    }

  };

};

```

`reason-apollo-hooks` parses response data from a query or mutation using parse function created by `graphql_ppx`. For example, when using `@bsRecord` directive, the response object will be parsed from a `Js.t` object to a reason record. In this case, the response data in reason code is not the same object that is stored in cache, since `react-apollo` saves data in cache before it is parsed and returned to the component. However, when updating cache, the data must be in the same format or apollo cache won't work correctly and throw errors.

If using directives like `@bsRecord`, `@bsDecoder` or `@bsVariant` in `graphql_ppx`, the data needs to be serialized back to JS object before it is written in cache. Since there is currently no way to serialize this data (see [this issue](https://github.com/mhallin/graphql_ppx/issues/71) in `graphql_ppx`), queries that will be updated in cache shouldn't use any of those directive, unless you will take care of the serialization yourself.

By default, apollo will add field `__typename` to the queries and will use it to normalize data and manipulate cache (see [normalization](https://www.apollographql.com/docs/react/advanced/caching/#normalization)). This field won't exist on parsed reason objects, since it is not included in the actual query you write, but is added by apollo before sending the query. Since `__typename` is crucial for the cache to work correctly, we need to read data from cache in its raw unparsed format, which is achieved with `readQuery` from `ApolloClient.ReadQuery` defined in `reason-apollo`.

## Fragment [:arrow_up:](#table-of-contents)

Using [fragments](https://www.apollographql.com/docs/react/data/fragments/).

Fragments can be defined and used like this:

```reason

// Fragments.re

module PersonFragment = [%graphql

  {|

  fragment person on Person {

      id

      name

      age

  }

|}

];

```

```reason

module PersonsQuery = [%graphql

{|

  query getAllPersons  {

    ...Fragments.PersonFragment.Person

  }

|}

];

```

See [examples/persons/src/fragments/LoadMoreFragments.re](examples/persons/src/fragments/LoadMoreFragments.re).

## Getting it running

```sh

yarn

yarn start

```

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    
_{Gabriel Rubens}
💻 📖 🤔

    
_{Ariel Schiavoni}
📖

    
_Matt
💻

    
_{Tomasz Cichocinski}
🐛 💻

    
_{Thibaut Mattio}
💻

    
_{Emilio Srougo}
🐛

    
_{Mike Anderson}
💻

  

  

    
_{Yuri Jean Fabris}
💻

    
_{Margarita Krutikova}
💻 👀 🤔

    
_{Kyrylo Yakymenko}
🐛 💻

    
_{Lukas Hambsch}
🐛

    
_{Jaap Frolich}
💻 👀 🤔

    
_{Rickard Laurin}
🐛

    
_{Medson Oliveira}
💻 👀 🤔

  

  

    
_soulplant
💻

    
_mbirkegaard
💻

    
_{Dragoș Străinu}
📖

    
_{Brad Dunn}
📖

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!