gleamql - v0.5.0

gleamql

Query a GraphQL server with gleamql.

This library provides a type-safe way to build GraphQL queries and mutations while ensuring the query structure and response decoder stay synchronized.

Example

import gleamql
import gleamql/field
import gleamql/operation
import gleam/json
import gleam/hackney

pub type Country {
  Country(name: String)
}

pub fn main() {
  let country_op = 
    operation.query("CountryQuery")
    |> operation.variable("code", "ID!")
    |> operation.field(
      field.object("country", fn() {
        use name <- field.field(field.string("name"))
        field.build(Country(name:))
      })
      |> field.arg("code", "code")
    )

  let assert Ok(Some(Country(name: "United Kingdom"))) =
    gleamql.new(country_op)
    |> gleamql.host("countries.trevorblades.com")
    |> gleamql.path("/graphql")
    |> gleamql.json_content_type()
    |> gleamql.send(hackney.send, [
      #("code", json.string("GB"))
    ])
}

Types

Error

</>

Errors that can occur when sending a GraphQL request.

The error type is generic over the HTTP client error type, preserving all error information from the underlying HTTP client.

pub type Error(http_error) {
  NetworkError(http_error)
  HttpError(status: Int, body: String)
  GraphQLErrors(List(GraphQLError))
  InvalidJson(json.DecodeError, body: String)
  DecodeError(List(decode.DecodeError), body: String)
}

Constructors 

  • NetworkError(http_error)

    Network-level failure (timeout, connection refused, DNS issues, etc.). Preserves the original HTTP client error for full context.

  • HttpError(status: Int, body: String)

    Server returned a non-2xx HTTP status code. Includes the status code and response body for debugging.

  • GraphQLErrors(List(GraphQLError))

    GraphQL server returned one or more errors in the response. Even with errors, GraphQL typically returns 200 OK with error objects. This variant contains ALL errors returned by the server.

  • InvalidJson(json.DecodeError, body: String)

    Response body wasn’t valid JSON. Includes the JSON decode error and response body for debugging.

  • DecodeError(List(decode.DecodeError), body: String)

    JSON was valid but didn’t match the expected GraphQL response structure. Includes the decode errors and response body for debugging.

GraphQLError

</>

A GraphQL error as defined in the GraphQL specification (Section 7.1.2).

GraphQL servers may return multiple errors in a single response. Each error includes a message and optionally includes path and extensions fields.

pub type GraphQLError {
  GraphQLError(
    message: String,
    path: option.Option(List(dynamic.Dynamic)),
    extensions: option.Option(dynamic.Dynamic),
  )
}

Constructors 

  • GraphQLError(
  message: String,
  path: option.Option(List(dynamic.Dynamic)),
  extensions: option.Option(dynamic.Dynamic),
)

    Arguments

    message

    Human-readable error message

    path

    Path to the field that caused the error (can contain strings or integers). Use gleam/dynamic to decode the path segments as needed.

    extensions

    Additional error information (server-specific). Use gleam/dynamic to decode the extensions as needed.

Request

</>

GleamQL Request

pub type Request(t) {
  Request(
    http_request: request.Request(String),
    operation: operation.Operation(t),
  )
}

Constructors

Values

</> 
pub fn header(
  req: Request(t),
  key: String,
  value: String,
) -> Request(t)

Set a header on the request.

If already present, it is replaced.

Example

gleamql.header(req, "Authorization", "Bearer token123")

host

</> 
pub fn host(req: Request(t), host: String) -> Request(t)

Set the host of the request.

Example

gleamql.host(req, "api.example.com")

json_content_type

</> 
pub fn json_content_type(req: Request(t)) -> Request(t)

Set the Content-Type header to application/json.

This is required by most GraphQL servers.

Example

gleamql.json_content_type(req)

new

</> 
pub fn new(op: operation.Operation(t)) -> Request(t)

Construct a GleamQL Request with an operation.

Example

gleamql.new(country_operation)
|> gleamql.host("api.example.com")
|> gleamql.path("/graphql")
|> gleamql.json_content_type()
|> gleamql.send(hackney.send, [#("code", json.string("GB"))])

path

</> 
pub fn path(req: Request(t), path: String) -> Request(t)

Set the path of the request.

Example

gleamql.path(req, "/graphql")

scheme

</> 
pub fn scheme(req: Request(t), scheme: http.Scheme) -> Request(t)

Set the schema of the request (http or https).

Example

import gleam/http
gleamql.scheme(req, http.Https)

send

</> 
pub fn send(
  req: Request(t),
  http_send: fn(request.Request(String)) -> Result(
    response.Response(String),
    e,
  ),
  variables: List(#(String, json.Json)),
) -> Result(option.Option(t), Error(e))

Send the built request to a GraphQL server with variable values.

A HTTP client is needed to send the request, see https://github.com/gleam-lang/http#client-adapters.

Example

import gleam/hackney
import gleam/json

gleamql.send(request, hackney.send, [
  #("code", json.string("GB")),
  #("lang", json.string("en")),
])

Variable values must be provided as a list of name/JSON pairs. The names should match the variables defined in the operation.

Returns Ok(Some(data)) if the query succeeded and returned data, Ok(None) if the query succeeded but returned null, or an Error if the request failed at any level (network, HTTP, GraphQL, or decoding).

✨ Search Document