Designing a Functional GraphQL Library

DESIGNING A
FUNCTIONAL GRAPHQL LIBRARY
Functional Scala 2019

WHO AM I?
> Pierre Ricadat aka @ghostdogpr
>
!
exiled in
"
> Contributor to ZIO
> Creator of Caliban

GRAPHQL IN A NUTSHELL
> query language for APIs
> server exposes a typed schema
> client asks for what they want
> queries
> mutations
> subscriptions

WHY CREATE A GRAPHQL LIBRARY?
> Sangria is great but...
> lots of boilerplate
> Future-based
> schema and resolver tied together
> interesting approach by Morpheus (Haskell)
> it's fun!

GOALS
> minimal boilerplate
> purely functional
> strongly typed
> explicit errors
> ZIO
> schema / resolver separation

PLAN OF ACTION
query → parsing → validation → execution → result
↑
schema

QUERY PARSING
↑
schema

QUERY PARSING
GraphQL spec: https://graphql.github.io/graphql-spec/

QUERY PARSING
Fastparse: fast, easy to use, good documentation
def name[_: P]: P[String] = P(CharIn("_A-Za-z") ~~ CharIn("_0-9A-Za-z").repX).!
def fragmentName[_: P]: P[String] = P(name).filter(_ != "on")
def fragmentSpread[_: P]: P[FragmentSpread] =
P("..." ~ fragmentName ~ directives).map {
case (name, dirs) => FragmentSpread(name, dirs)
}

SCHEMA
↑
schema

SCHEMA
Idea from Morpheus:
derive GraphQL schema from basic types

SIMPLE API
type Queries {
pug: Pug!
}
case class Queries(pug: Pug)

OBJECTS
type Pug {
name: String!
nicknames: [String!]!
favoriteFood: String
}
case class Pug(
name: String,
nicknames: List[String],
favoriteFood: Option[String])

ENUMS
enum Color {
FAWN
BLACK
OTHER
}
sealed trait Color
case object FAWN extends Color
case object BLACK extends Color
case object OTHER extends Color

ARGUMENTS
type Queries {
pug(name: String!): Pug
}
case class PugName(name: String)
case class Queries(pug: PugName => Option[Pug])

EFFECTS
type Queries {
}
case class Queries(pug: PugName => Task[Pug])

RESOLVER
simple value
case class Queries(
pug: PugName => Task[Pug]
pugs: Task[List[Pug]]
)
val resolver = Queries(
args => PugService.findPug(args.name),
PugService.getAllPugs
)

SCHEMA
trait Schema[-R, T] {
// describe the type T
def toType(isInput: Boolean = false): __Type
// describe how to resolve a value of type T
def resolve(value: T): Step[R]
}

WHAT'S A STEP
> Pure Value (leaf)
> List
> Object
> Effect
> Stream

SCHEMA FOR STRING
implicit val stringSchema = new Schema[Any, String] {
def toType(isInput: Boolean = false): __Type =
__Type(__TypeKind.SCALAR, Some("String"))
def resolve(value: String): Step[R] =
PureStep(StringValue(value))
}

Schema for case classes and sealed traits?

MAGNOLIA
>
!
> ease of use
> compile time
> documentation, examples
>
"
> error messages (getting better!)

MAGNOLIA DERIVATION
def combine[T](
caseClass: CaseClass[Typeclass, T]): Typeclass[T]
def dispatch[T](
sealedTrait: SealedTrait[Typeclass, T]): Typeclass[T]

VALIDATION
↑
schema

EXECUTION
↑
schema

EXECUTION
1. Schema + Resolver => Execution Plan (tree of Steps)
2. Filter Plan to include only requested fields
3. Reduce Plan to pure values and effects
4. Run effects

N+1 PROBLEM
{
orders { # fetches orders (1 query)
id
customer { # fetches customer (n queries)
name
}
}
}

QUERY OPTIMIZATION
Naive ZIO[R, E, A] version
val getAllUserIds: ZIO[Any, Nothing, List[Int]] = ???
def getUserNameById(id: Int): ZIO[Any, Nothing, String] = ???
for {
userIds <- getAllUserIds
userNames <- ZIO.foreachPar(userIds)(getUserNameById)
} yield userNames

QUERY OPTIMIZATION
Meet ZQuery[R, E, A]
val getAllUserIds: ZQuery[Any, Nothing, List[Int]] = ???
def getUserNameById(id: Int): ZQuery[Any, Nothing, String] = ???
for {
userIds <- getAllUserIds
userNames <- ZQuery.foreachPar(userIds)(getUserNameById)
} yield userNames

ZQUERY BENEFITS
> parallelize queries
> cache identical queries (deduplication)
> batch queries if batching function provided

ZQUERY
> courtesy of @adamgfraser
> based on paper on Haxl
> "There is no Fork: An Abstraction for Efficient,
Concurrent, and Concise Data Access"
> will be extracted to its own library at some point

INTROSPECTION
Dogfooding
case class __Introspection(
__schema: __Schema,
__type: __TypeArgs => __Type)

USAGE
1. Define your queries / mutations / subscriptions
2. Provide a Schema for custom types
3. Provide a resolver
4. Profit

1. DEFINE YOUR QUERIES
case class Pug(name: String, nicknames: List[String], favoriteFood: Option[String])
case class PugName(name: NonEmptyString)
case class Queries(pugs: Task[List[Pug]], pug: PugName => Task[Pug])
type Pug {
name: String!
nicknames: [String!]!
favoriteFood: String
}
type Queries {
pugs: [Pug!]
}

2. PROVIDE A SCHEMA FOR CUSTOM TYPES
implicit val nesSchema: Schema[NonEmptyString] =
Schema.stringSchema.contramap(_.value)

3. PROVIDE A RESOLVER
def getPugs: Task[List[Pug]] = ???
def getPug(name: String): Task[Pug] = ???
val queries = Queries(
getPugs,
args => getPug(args.name))
val resolver = RootResolver(queries)

4. PROFIT
val interpreter = graphQL(resolver)
for {
result <- interpreter.execute(query)
_ <- zio.console.putStrLn(result.toString)
} yield ()

HTTP4S MODULE
val route: HttpRoutes[RIO[R, *]] =
Http4sAdapter.makeRestService(interpreter)
val wsRoute: HttpRoutes[RIO[R, *]] =
Http4sAdapter.makeWebSocketService(interpreter)

SCALAJS
Few and modern dependencies
ScalaJS support for free

CATS COMPATIBILITY
caliban-cats module
def executeAsync[F[_]: Async](...)(
implicit runtime: Runtime[Any]): F[GraphQLResponse[E]]
def makeRestServiceF[F[_]: Effect, Q, M, S, E](...)(
implicit runtime: Runtime[Any]): HttpRoutes[F]

PERFORMANCE
Caliban is fast
Check benchmarks module on github

FUTURE
> Query analysis
> Middleware (query-level, field-level)
> Code generation
> Other HTTP adapters (Akka HTTP) <- help needed
> Client support

WANNA KNOW MORE?
> Website: https://ghostdogpr.github.io/caliban/
> ZIO Discord: #caliban

Designing a Functional GraphQL Library

More Related Content

What's hot (20)

Similar to Designing a Functional GraphQL Library (20)

Recently uploaded (20)

Designing a Functional GraphQL Library