README.md

GraphQL Websocket Client

An extensible client for connecting with GraphQL over Websockets following the graphql-ws conventions.

Installation

The package can be installed by adding graphql_ws_client to your list of dependencies in mix.exs.

def deps do
  [
    {:graphql_ws_client, "~> 2.0"},
  ]
end

If you are using the default configuration, GraphQLWSClient.Drivers.Gun is used as driver and you will need the gun and jason packages as well.

def deps do
  [
    # ...
    {:gun, "~> 2.1"},
    {:jason, "~> 1.4"},
  ]
end

Take a look in the driver documentation to find out how to customize driver options.

Alternatively, you can write your own driver based on the GraphQLWSClient.Driver behaviour.

Usage

Connect to a socket:

{:ok, socket} = GraphQLWSClient.start_link(url: "ws://localhost:4000/socket")

Send a query or mutation and return the result immediately:

{:ok, result} = GraphQLWSClient.query(socket, "query GetPost { ... }")

Register a subscription to listen for events:

{:ok, subscription_id} = GraphQLWSClient.subscribe(
  socket,
  "subscription PostCreated { ... }"
)

GraphQLWSClient.query!(socket, "mutation CreatePost { ... }")

receive do
  %GraphQLWSClient.Event{type: :error, id: ^subscription_id, payload: error} ->
    IO.inspect(error, label: "error")
  %GraphQLWSClient.Event{type: :next, id: ^subscription_id, payload: result} ->
    IO.inspect(result)
  %GraphQLWSClient.Event{type: :complete, id: ^subscription_id} ->
    IO.puts("Stream closed")
end

GraphQLClient.close(socket)

You would usually put this inside of a custom GenServer and handle the events in handle_info/3.

Alternatively, you can create a stream of results:

socket
|> GraphQLWSClient.stream!("subscription PostCreated { ... }")
|> Stream.each(fn result ->
  IO.inspect(result)
end)
|> Stream.run()

Custom Client

If you want to run the client as part of a supervision tree in your application, you can also use GraphQLWSClient to create your own client.

defmodule MyClient do
  use GraphQLWSClient, otp_app: :my_app
end

Then, you can configure your client using a config file:

import Config

config :my_app, MyClient,
  url: "ws://localhost:4000/socket"

Docs

Documentation can be found at https://hexdocs.pm/graphql_ws_client or generated locally using mix docs.