Skip to main content

gql

A functional server and client GraphQL implementation for Scala

Documentation

Powerful algebraic resolvers

"friends" -> resolve(_
  .evalMap(getFriends)
  .streamMap(is => peopleEvents(is.map(_.id)))
  .rethrow
  .arg(limitArg) andThen batchGetPeople
)

gql distills what it means to be a GraphQL resolver into a concise, well-behaved algebra that composes.

Declarative schema definition

tpe[IO, Person](
  "Person",
  "name" -> lift(_.name),
  "friends" -> eff(p => getFriends(p.id))
)

gql comes with syntax and a DSL for succinctly defining schemas.

Typed functional graphql

(
  arg[String]("firstName"),
  arg[String]("lastName")
).mapN(_ + " " + _)

gql adopts a simple and predictable approach to GraphQL. Every aspect has been crafted to minimize friction by employing the proper structures.

Query planning

slowFields ::: fastFields.contramap(...)

gql features a query planner heuristic that enables better-than-naive query performance and an expressive batching api that helps the user optimize their schema in a complely typed functional manner.

Signal based subscriptions

"data" -> resolve(_
  .streamMap(subscribeToIds)
  .andThen(batchGetData)
  .streamMap(subscribeToSubIds)
)

gql features an unusual subscription model that is instead based on signals. That is, streams or even resources of data can appear anywhere in the schema and gql will efficiently re-execute the query and handle resource leasing.

Easy to extend

gql.http4s.Http4sRoutes.ws(queryCompiler, _)

gql is designed to be easily extended with new features. Want to provide a custom query planner or calculate cost estimates yourself? No problem.

gql also comes with some pre-built extensions such as http4s integration, graphql-ws, tracing and global object identification.

Client-side dsl

fragment("PersonFragment", "Person") {
  (
    sel[String]("name"),
    sel[Option[Int]]("age")
  ).mapN(Person.apply)
}

gql also features a client which can either be declared via the dsl or code generated from a graphql query.

gql is modular and as such, client queries can be validated against the same implementation rules as a gql server.