From one type to a served endpoint.

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.

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)),
  )
})

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())
})

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.

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.ResolverError("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.ResolverError("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.ResolverError("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)
})

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))
})

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()
  }
})