@spec child_spec(term()) :: Supervisor.child_spec()

The default child specification that can be used to run the client under a supervisor.

@spec close(client()) :: :ok

Closes the connection to the websocket.

@spec connected?(client()) :: boolean()

Indicates whether the client is connected to the Websocket.

@spec open(client()) :: :ok | {:error, Exception.t()}

Opens the connection to the websocket.

@spec open!(client()) :: :ok | no_return()

Opens the connection to the websocket. Raises on error.

@spec open_with(client(), any()) :: :ok | {:error, Exception.t()}

Opens the connection to the websocket using a custom payload.

@spec open_with!(client(), any()) :: :ok | no_return()

Opens the connection to the websocket using a custom payload. Raises on error.

@spec query(client(), query(), variables(), nil | timeout()) ::
  {:ok, any()} | {:error, Exception.t()}

Sends a GraphQL query or mutation to the websocket and returns the result.

Example

iex> GraphQLWSClient.query(
...>   client,
...>   "query GetPost($id: ID!) { post(id: $id) { body } }",
...>   %{"id" => 1337}
...> )
{:ok, %{"data" => %{"posts" => %{"body" => "Lorem Ipsum"}}}}copy

@spec query!(client(), query(), variables()) :: any() | no_return()

Sends a GraphQL query or mutation to the websocket and returns the result. Raises on error.

Example

iex> GraphQLWSClient.query!(
...>   client,
...>   "query GetPost($id: ID!) { post(id: $id) { body } }",
...>   %{"id" => 1337}
...> )
%{"data" => %{"posts" => %{"body" => "Lorem Ipsum"}}}copy

@spec start_link(
  GraphQLWSClient.Config.t()
  | Keyword.t()
  | map()
  | GenServer.options()
) ::
  GenServer.on_start()

Starts a GraphQL Websocket client.

Options

See GraphQLWSClient.Config.new/1 for a list of available options. Additionally, you may pass GenServer.options/0.

@spec start_link(
  GraphQLWSClient.Config.t() | Keyword.t() | map(),
  GenServer.options()
) ::
  GenServer.on_start()

Starts a GraphQL Websocket client using the given config and GenServer options.

Options

The first argument accept options as specified in GraphQLWSClient.Config.new/1. The second argument accepts GenServer.options/0.

@spec stream!(client(), query(), variables(), Keyword.t()) ::
  Enumerable.t() | no_return()

Sends a GraphQL subscription to the websocket and returns an event stream.

Options

• :buffer_size - Sets the buffer size. If the buffer is exceeded, the oldest events are discarded first. Although it is not recommended, you may also set the value to :infinity to set no limit. Defaults to 1000.

Example

iex> stream = GraphQLWSClient.stream!(
...>   client,
...>   """
...>     subscription CommentAdded($postId: ID!) {
...>       commentAdded(postId: $postId) { body }
...>     }
...>   """,
...>   %{"postId" => 1337}
...> )copy

Print events as they come in:

iex> stream
...> |> Stream.each(fn result -> IO.inspect(result) end)
...> |> Stream.run()copy

Wait for a fixed number of events to come in and then turn them into a list:

iex> stream |> Stream.take(3) |> Enum.to_list()copy

@spec subscribe(client(), query(), variables(), pid()) ::
  {:ok, subscription_id()} | {:error, Exception.t()}

Sends a GraphQL subscription to the websocket and registers a listener process to retrieve events.

Example

iex> GraphQLWSClient.subscribe(
...>   client,
...>   """
...>     subscription CommentAdded($postId: ID!) {
...>       commentAdded(postId: $postId) { body }
...>     }
...>   """,
...>   %{"postId" => 1337}
...> )
{:ok, "767f051c-63b7-4dd1-8d7a-af91f0ccaa71"}copy

@spec subscribe!(client(), query(), variables(), pid()) ::
  subscription_id() | no_return()

Sends a GraphQL subscription to the websocket and registers a listener process to retrieve events. Raises on error.

Example

iex> GraphQLWSClient.subscribe!(
...>   client,
...>   """
...>     subscription CommentAdded($postId: ID!) {
...>       commentAdded(postId: $postId) { body }
...>     }
...>   """,
...>   %{"postId" => 1337}
...> )
"3f59edba-27ae-4015-9740-cfb73c91c270"copy

@spec unsubscribe(client(), subscription_id()) :: :ok | {:error, Exception.t()}

Removes a subscription.

Example

iex> GraphQLWSClient.unsubscribe(client, "3f05c357-33a5-47ae-81d8-8da41b126126")
:okcopy

@spec unsubscribe!(client(), subscription_id()) :: :ok | no_return()

Removes a subscription. Raises on error.

Example

iex> GraphQLWSClient.unsubscribe!(client, "0c50dab3-1f3e-45e1-9537-bb7561a2bca3")
:okcopy