From one type to a served endpoint.
Eleven steps, in the order a program grows: the types, what resolves their
fields, the roots, an input object and the errors a resolver can raise, subscriptions,
federation, the schema as text, then the endpoint that serves all of it. The code comes from
src/examples/guide and the output is what that program prints.
00Add it
One line, and the same code runs on wasm, wasm-gc,
js and native.
moon add moonbitstack/moongql
The four packages beside this guide build one server each — the same types, the same
answers, four ways of writing them. src/examples/guide/check runs every document
below against all four and stops if they disagree, so what you see here is the output of the
way you picked.
01One type, four ways
A schema is types with fields. Write them as #gql annotations on the structs you
already have, as calls on the schema, as types with an impl saying how they cross
the wire, or as SDL text with a resolver registered per field. The switch at the top of the
page picks which way every block here is written; all four build the same schema and answer the
same documents.
annotations
// A struct's fields become the type's fields. `key=` makes it a federated
// entity; `description=` is what introspection reports.
#gql.type(description="Someone who writes books")
pub struct Author {
id : String
name : String
}
#gql.type(key="id")
pub struct Book {
id : String
title : String
author_id : String
}
The generator reads the annotations and writes the calls the other two ways write by hand.
functions
let author = schema.object("Author", description="Someone who writes books")
author.field("id", NonNull(Scalar("String")))
author.field("name", NonNull(Scalar("String")))
let book = schema.object("Book")
book.field("id", NonNull(Scalar("String")))
book.field("title", NonNull(Scalar("String")))
// The author id is data on the type, and what `Author.books` is resolved from.
book.field("authorId", NonNull(Scalar("String")))
Each call names a type and gives it a field; a field's type says how its value is read.
classes
// A struct holds the type's data; the two impls say how it crosses the wire,
// under the names the schema uses.
pub(all) struct Author {
id : String
name : String
}
pub impl @moongql.ToGql for Author with fn to_gql(self) {
{ "id": self.id, "name": self.name }
}
pub impl @moongql.FromGql for Author with fn from_gql(v) {
{ id: @moongql.read(v, "id"), name: @moongql.read(v, "name"), }
}
pub extend Author with @moongql.ToGql::{to_gql}
pub extend Author with @moongql.FromGql::{from_gql}
pub(all) struct Book {
id : String
title : String
author_id : String
}
pub impl @moongql.ToGql for Book with fn to_gql(self) {
{ "id": self.id, "title": self.title, "authorId": self.author_id }
}
pub impl @moongql.FromGql for Book with fn from_gql(v) {
{
id: @moongql.read(v, "id"),
title: @moongql.read(v, "title"),
author_id: @moongql.read(v, "authorId"),
}
}
pub extend Book with @moongql.ToGql::{to_gql}
pub extend Book with @moongql.FromGql::{from_gql}
The two impls are exactly what the generator writes for an annotated struct; writing them yourself is how a type joins the executor.
sdl
let schema = @moongql.Schema::of_sdl(
(
#|"Someone who writes books."
#|type Author {
#| id: ID!
#| name: String!
#| "Their books, in the order they were added"
#| books: [Book!]!
#|}
#|
#|type Book {
#| id: ID!
#| title: String!
#| authorId: String!
#|}
),
) catch {
e => abort(e.to_string())
}
The type system is the source: `Schema::of_sdl` reads it, and the fields it declares are the fields the executor resolves.
02A field that resolves
A field whose value is not already on the parent is resolved by a function: a method on the
type, or a closure registered under "Type.field". The field's declared type tells
the executor whether what comes back is a leaf, a list or an object.
annotations
// A method is a field of its type, asked on the value it belongs to.
#gql.field(description="Their books, in the order they were added")
fn Author::books(self : Author) -> Array[Book] {
shelf.filter(b => b.author_id == self.id)
}
functions
author.field("books", NonNull(ListOf(NonNull(Named("Book")))))
resolvers.field("Author", "books", info => {
let id = key_of(info.parent, "id")
Json(shelf.filter(b => key_of(b, "authorId") == id))
})
classes
// A method is a field: it is asked on the value it belongs to, and whatever it
// returns is turned back into JSON.
fn Author::books(self : Author) -> Array[Book] {
shelf.filter(b => b.author_id == self.id)
}
resolvers.field("Author", "books", info => {
@moongql.ToGql::to_gql(
Author::books(@moongql.FromGql::from_gql(info.parent)),
)
})
sdl
resolvers.field("Author", "books", info => {
let id = key_of(info.parent, "id")
Json(shelf.filter(b => key_of(b, "authorId") == id))
})
`books` is already a field of `Author` in the SDL; all that is left is the function registered under its name.
Only the fields the document selects are resolved, and a resolver's value is read under the
names the schema uses — which is why author_id is written out as
authorId once, in the conversion.
03Root fields and arguments
Query is a type like any other, and its fields are the entry points. An argument
is declared with its type, and a resolver reads it by name.
annotations
// A free function is a root field; its parameters are the field's arguments.
#gql.query
fn author(id : String) -> Author? {
writers.iter().find_first(a => a.id == id)
}
#gql.query
fn books() -> Array[Book] {
shelf.copy()
}
functions
let query = schema.object("Query")
query.field_args(
"author",
[("id", NonNull(Scalar("String")))],
Named("Author"),
)
query.field("books", NonNull(ListOf(NonNull(Named("Book")))))
resolvers.field("Query", "author", info => {
let id = info.arg("id")
match writers.iter().find_first(a => key_of(a, "id") == id) {
Some(a) => a
None => Json::null()
}
})
resolvers.field("Query", "books", _info => Json(shelf.copy()))
classes
// The roots are types too — the operations hang off them.
pub(all) struct Query {}
fn Query::author(id : String) -> Author? {
writers.iter().find_first(a => a.id == id)
}
fn Query::books() -> Array[Book] {
shelf.copy()
}
resolvers.field("Query", "author", info => {
@moongql.ToGql::to_gql(Query::author(info.read("id")))
})
resolvers.field("Query", "books", _info => {
@moongql.ToGql::to_gql(Query::books())
})
sdl
schema.add_sdl(
(
#|type Query {
#| author(id: ID!): Author
#| books: [Book!]!
#|}
),
) catch {
e => abort(e.to_string())
}
resolvers.field("Query", "author", info => {
let id = info.arg("id")
match writers.iter().find_first(a => key_of(a, "id") == id) {
Some(a) => a
None => Json::null()
}
})
resolvers.field("Query", "books", _info => Json(shelf.copy()))
recorded · the same answer from all four
{"data":{"author":{"name":"Ursula","books":[{"title":"The Dispossessed"},{"title":"Lathe"}]}}}
{"data":{"books":[{"title":"The Dispossessed"},{"title":"Lathe"},{"title":"Exhalation"}]}}
A nullable argument may be left out, and a nullable field may answer null; a
non-null field that answers null is a field error, and it takes the nearest
nullable parent with it.
04An input object, a mutation, an error
A mutation takes its payload as an input object: a type whose fields are the caller's to
send. A resolver that declares raise may fail, and its error becomes a field error
carrying the path and the place in the document.
annotations
// What a mutation takes: an input object is a struct too, and every field of it
// is data the caller sends.
#gql.input
pub struct NewBook {
title : String
author_id : String
}
`#gql.input` and `#gql.mutation`; the input struct's reading side is generated with it.
functions
let new_book = schema.input("NewBook")
new_book.field("title", NonNull(Scalar("String")))
new_book.field("authorId", NonNull(Scalar("String")))
let mutation = schema.object("Mutation")
mutation.field_args(
"addBook",
[("input", NonNull(Named("NewBook")))],
NonNull(Named("Book")),
)
schema.set_mutation("Mutation")
The input is a type with fields, and the payload is one argument declared with it.
classes
// What a mutation takes: a struct whose fields are the caller's to send.
pub(all) struct NewBook {
title : String
author_id : String
}
pub impl @moongql.FromGql for NewBook with fn from_gql(v) {
{ title: @moongql.read(v, "title"), author_id: @moongql.read(v, "authorId"), }
}
pub extend NewBook with @moongql.FromGql::{from_gql}
The input is a struct with the reading half only — nothing sends one back out.
sdl
schema.add_sdl(
(
#|input NewBook {
#| title: String!
#| authorId: String!
#|}
#|
#|type Mutation {
#| addBook(input: NewBook!): Book!
#|}
),
) catch {
e => abort(e.to_string())
}
The input and the mutation are SDL; the resolver that fills the mutation in is the MoonBit part.
annotations
// A resolver that declares `raise` may fail; the error becomes a field error in
// the response, with the path and the place in the document.
#gql.mutation
fn add_book(input : NewBook) -> Book raise {
if input.title == "" {
raise @exec.FieldError("a book needs a title")
}
let book : Book = {
id: "b\{(shelf.length() + 1)}",
title: input.title,
author_id: input.author_id,
}
shelf.push(book)
book
}
functions
resolvers.field("Mutation", "addBook", info => {
let input = info.arg("input")
let title = match key_of(input, "title") {
String(t) => t
_ => ""
}
if title == "" {
raise @exec.FieldError("a book needs a title")
}
let book : Json = {
"id": Json("b\{shelf.length() + 1}"),
"title": Json(title),
"authorId": key_of(input, "authorId"),
}
shelf.push(book)
book
})
classes
pub(all) struct Mutation {}
fn Mutation::add_book(input : NewBook) -> Book raise {
if input.title == "" {
raise @exec.FieldError("a book needs a title")
}
let book : Book = {
id: "b\{(shelf.length() + 1)}",
title: input.title,
author_id: input.author_id,
}
shelf.push(book)
book
}
resolvers.field("Mutation", "addBook", info => {
let result = Mutation::add_book(info.read("input")) catch {
e => raise @moongql.field_error(e)
}
@moongql.ToGql::to_gql(result)
})
sdl
resolvers.field("Mutation", "addBook", info => {
let input = info.arg("input")
let title = match key_of(input, "title") {
String(t) => t
_ => ""
}
if title == "" {
raise @exec.FieldError("a book needs a title")
}
let book : Json = {
"id": Json("b\{shelf.length() + 1}"),
"title": Json(title),
"authorId": key_of(input, "authorId"),
}
shelf.push(book)
book
})
recorded · one book added, one refused
{"data":{"addBook":{"id":"b4","title":"Dune"}}}
{"data":null,"errors":[{"message":"a book needs a title","locations":[{"line":1,"column":12}],"path":["addBook"]}]}
05Subscriptions
A subscription field answers with the stream of its events; the executor resolves the
selection set against each one. Over the wire the same thing is carried by
graphql-transport-ws: connection_init, subscribe, then
next for each payload and complete at the end.
annotations
// A subscription returns the events it produces, one array; every event becomes
// one response payload.
#gql.subscription
fn book_added() -> Array[Book] {
shelf.copy()
}
functions
subscription.field("bookAdded", NonNull(Named("Book")))
classes
pub(all) struct Subscription {}
fn Subscription::book_added() -> Array[Book] {
shelf.copy()
}
let subscribers = @moongql.Subscribers::new()
subscribers.field("Subscription", "bookAdded", _info => {
Subscription::book_added().map(b => @moongql.ToGql::to_gql(b))
})
sdl
schema.add_sdl(
(
#|type Subscription {
#| bookAdded: Book!
#|}
),
) catch {
e => abort(e.to_string())
}
subscribers.field("Subscription", "bookAdded", _info => shelf.copy())
recorded · one payload per event
{"data":{"bookAdded":{"title":"The Dispossessed"}}} {"data":{"bookAdded":{"title":"Lathe"}}} {"data":{"bookAdded":{"title":"Exhalation"}}} {"data":{"bookAdded":{"title":"Dune"}}}
Four events, because the mutation above added a fourth book before this ran. A real source would be an event bus; the shape a subgraph fills in is the same.
06Subgraphs that compose
An entity is a type with a @key and a way to turn a representation — a
{__typename, key} pair — back into the object. The subgraph then answers
_service { sdl } and _entities(representations:), and a gateway can
join it to its siblings.
annotations
// With `key=` on the type, a reference function is all a subgraph needs to turn
// a representation back into the object.
#gql.reference
fn book_by_id(id : String) -> Book? raise {
shelf.iter().find_first(b => b.id == id)
}
functions
let fed = @moongql.Federation::new(v2=true)
fed.entity(name="Book", key="id", resolve=(rep, _ctx) => {
let id = key_of(rep, "id")
match shelf.iter().find_first(b => key_of(b, "id") == id) {
Some(b) => b
None => Json::null()
}
})
classes
let fed = @moongql.Federation::new(v2=true)
fed.entity(name="Book", key="id", resolve=(rep, _ctx) => {
let id : String = @moongql.read(rep, "id")
match shelf.iter().find_first(b => b.id == id) {
Some(b) => @moongql.ToGql::to_gql(b)
None => Json::null()
}
})
sdl
let fed = @moongql.Federation::new(v2=true)
fed.entity(name="Book", key="id", resolve=(rep, _ctx) => {
let id = key_of(rep, "id")
match shelf.iter().find_first(b => key_of(b, "id") == id) {
Some(b) => b
None => Json::null()
}
})
recorded · a representation resolved
{"data":{"_entities":[{"id":"b2","title":"Lathe"}]}}
What comes back is the object, and the fields named by @requires that the
gateway sent along stay on it for this subgraph's resolvers to read.
07The same schema, as text
to_sdl writes the type system out — descriptions, argument defaults,
@deprecated(reason:), directives and the schema block. Reading it
back with Schema::of_sdl gives the same schema, so the next print is identical.
let s = Schema::of_sdl( #|type Query { #| "Whoever is asking." #| me: User #|} #|type User { #| id: ID! #| legacyName: String! @deprecated(reason: "use name") #|} ) s.to_sdl()
prints the description and the deprecation back, unchanged
type Query {
"Whoever is asking."
me: User
}
type User {
id: ID!
legacyName: String! @deprecated(reason: "use name")
}
08The schema first
Write the SDL and mark it #gql.sdl, or point #gql.sdl(file="schema.graphql")
at a file from a declare fn. The generator writes the structs and enums, and a
declare fn for every root field, every field with arguments and every field of an
object type. The compiler names the ones you have not written.
#gql.sdl let shop : String = #|type Book { id: ID! title: String! author: Author! } #|type Author { id: ID! name: String! } #|type Query { book(id: ID!): Book } fn Query::book(id : String) -> Book? raise { ... } fn Book::author(self : Book) -> Author raise { ... }
Declare your own struct Book to keep what the schema does not show, such as the
id behind Book::author: the generator binds to it instead of writing one.
09Variables, fragments, directives
A document can take its values from outside. Variables are declared in the operation and
passed as a map; fragments and @skip / @include work as the
specification describes.
let vars : Map[String, Json] = { "uid": "1" } execute(schema, resolvers, "query ($uid: ID!) { hero: user(id: $uid) { ...who } } fragment who on User { id name }", variables=vars)
prints
{"data":{"hero":{"id":"1","name":"Alice"}}}
A document that carries the type system instead — an SDL definition where an operation belongs — is not executable, and validation says so by name rather than letting the executor walk past it.
10Batch the N+1 away
A DataLoader queues the keys a resolution pass asks for, dedupes them, and runs
one batch over the distinct set — so a list of twenty authors costs one query, not twenty.
let loader = DataLoader::new(fn(keys) { fetch_authors(keys) }) let a = loader.load("1") let b = loader.load("2") loader.dispatch() // one call for both keys
11Serve it
graphql_handler turns the schema into a handler on the ASGI seam: a
POST reads { query, variables } and answers
{ data, errors }; a GET without ?query= serves the IDE —
the library's own page, with nothing fetched from a CDN. The endpoint defaults to
/graphql and the port to 12000.
let app = graphql_app(schema, resolvers) // the MoonQL page let app = graphql_app(schema, resolvers, ide=@moongql.graphiql) let app = graphql_app(schema, resolvers, ide=@moongql.off) // no IDE: 405
a POST, and what comes back
content-type: application/json
{"query":"{ user(id: \"1\") { id name } }"}
200 application/json
{"data":{"user":{"id":"1","name":"lfanke"}}}
Run moon run src/examples/22-http-server for the whole transport, or open the
showcase to query a schema in the browser.