Wesley

Wesley is a compiler for GraphQL schemas. It reads GraphQL SDL and lowers it to a deterministic intermediate representation, which it hashes and compares to report breaking changes. It lists a schema's root operations, which it reads from the SDL in a separate pass, and from the two together it emits Rust and TypeScript.

It is written in Rust and ships as a command-line tool, wesley, and as a set of library crates. Wesley is pre-1.0: the CLI, the library APIs, and the emitted code may change between releases.

Install

cargo install wesley-cli

To install a pre-release, name its exact version:

cargo install wesley-cli --version 0.3.0-alpha.3

From a checkout of this repository:

cargo install --locked --path crates/wesley-cli

A first look

Save this as shop.graphql:

type Product {
  id: ID!
  name: String!
  priceCents: Int!
  tags: [String!]!
}

type Query {
  product(id: ID!): Product
  products: [Product!]!
}

Hash it. The hash is computed from the lowered schema, not from the file's bytes, so whitespace and comments do not change it. The order of types and fields does:

wesley schema hash --schema shop.graphql

c876e111112a5efc81126f5f7ac1ace60b033c111a42f2b5bb9b997a4c789ebc

Emit Rust:

wesley emit rust --schema shop.graphql --out shop.rs

// @generated by Wesley. Do not edit.

#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct Product {
    pub id: String,
    pub name: String,
    #[serde(rename = "priceCents")]
    pub price_cents: i32,
    pub tags: Vec<String>,
}

Getting started continues from here: operations, TypeScript, and catching a breaking change in CI.

Documentation

• Getting started: a walkthrough from an empty directory.
• CLI reference: the help the CLI prints for every command group. A test holds each help page to describing every option its usage lines offer.
• Architecture: the crates, what each one owns, and how a schema moves through them.
• CI: what runs on a pull request and how to run it locally.
• Rust standard and testing standard: binding for every change.
• Releasing: how a version is tagged and published.
• Contributing and changelog.

Using Wesley as a library

The compiler kernel is wesley-core. It is synchronous, and with default features off it pulls in no async runtime:

wesley-core = { version = "=0.3.0-alpha.3", default-features = false }

let ir = wesley_core::lower_schema_sdl(sdl)?;
let hash = wesley_core::compute_registry_hash(&ir)?;

The crate READMEs describe each library: wesley-core, wesley-emit-rust, wesley-emit-typescript, wesley-emit-codec, and wesley-cli.

License

Apache-2.0. See LICENSE and NOTICE.