yume/juniper
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rework Book (#1230)

Browse source 
- rework and update existing chapters
- mention correct case transformation for GraphQL enums (#1029)
- document N+1 mitigation techniques and look-ahead features (#234, #444)
- mention all integration crates (#867)
- fix Book links (#679, #974, #1056)
- remove old version of Book (#1168)

Additionally:
- disable `bson`, `url`, `uuid` and `schema-language` Cargo features by default in `juniper` crate

Co-authored-by: Christian Legnitto <LegNeato@users.noreply.github.com>
This commit is contained in:
Kai Ren 2024-03-20 15:53:25 +01:00 committed by GitHub
parent 86b5319315
commit ec0d7d8097
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
79 changed files with 3947 additions and 3320 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/ci.yml vendored
View file

@ -404,7 +404,7 @@ jobs:
deploy-book:
name: deploy (Book)
if: ${{ github.ref == 'refs/heads/master'
|| startsWith(github.ref, 'refs/tags/juniper@') }}
|| startsWith(github.ref, 'refs/tags/juniper') }}
needs: ["codespell", "test", "test-book"]
runs-on: ubuntu-latest
steps:

6
README.md
View file

@ -108,10 +108,10 @@ Juniper has not reached 1.0 yet, thus some API instability should be expected.
[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
[hyper]: https://hyper.rs
[rocket]: https://rocket.rs
[book]: https://graphql-rust.github.io
[book]: https://graphql-rust.github.io/juniper
[book_master]: https://graphql-rust.github.io/juniper/master
[book_index]: https://graphql-rust.github.io
[book_quickstart]: https://graphql-rust.github.io/quickstart.html
[book_index]: https://graphql-rust.github.io/juniper
[book_quickstart]: https://graphql-rust.github.io/juniper/quickstart.html
[docsrs]: https://docs.rs/juniper
[warp]: https://github.com/seanmonstar/warp
[warp_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples

1
benches/Cargo.toml
View file

@ -6,6 +6,7 @@ authors = ["Christoph Herzog <chris@theduke.at>"]
publish = false
[dependencies]
dataloader = "0.17" # for Book only
futures = "0.3"
juniper = { path = "../juniper" }

7
book/book.toml
View file

@ -1,8 +1,11 @@
[book]
title = "Juniper Book (GraphQL server for Rust)"
title = "Juniper Book"
description = "User guide for Juniper (GraphQL server library for Rust)."
language = "en"
multilingual = false
authors = [
"Kai Ren (@tyranron)",
]
src = "src"
[build]
@ -10,7 +13,7 @@ build-dir = "_rendered"
create-missing = false
[output.html]
git_repository_url = "https://github.com/graphql-rs/juniper"
git_repository_url = "https://github.com/graphql-rust/juniper"
[rust]
edition = "2021"

73
book/src/README.md
View file

@ -1,73 +0,0 @@
# Juniper
Juniper is a [GraphQL] server library for Rust. Build type-safe and fast API
servers with minimal boilerplate and configuration.
[GraphQL][graphql] is a data query language developed by Facebook intended to
serve mobile and web application frontends.
_Juniper_ makes it possible to write GraphQL servers in Rust that are
type-safe and blazingly fast. We also try to make declaring and resolving
GraphQL schemas as convenient as possible as Rust will allow.
Juniper does not include a web server - instead it provides building blocks to
make integration with existing servers straightforward. It optionally provides a
pre-built integration for the [Hyper][hyper], [Rocket], and [Warp][warp] frameworks, including
embedded [Graphiql][graphiql] for easy debugging.
- [Cargo crate](https://crates.io/crates/juniper)
- [API Reference][docsrs]
## Features
Juniper supports the full GraphQL query language according to the
[specification (October 2021)][graphql_spec], including interfaces, unions, schema
introspection, and validations.
It does not, however, support the schema language.
As an exception to other GraphQL libraries for other languages, Juniper builds
non-null types by default. A field of type `Vec<Episode>` will be converted into
`[Episode!]!`. The corresponding Rust type for e.g. `[Episode]` would be
`Option<Vec<Option<Episode>>>`.
## Integrations
### Data types
Juniper has automatic integration with some very common Rust crates to make
building schemas a breeze. The types from these crates will be usable in
your Schemas automatically.
- [uuid][uuid]
- [url][url]
- [chrono][chrono]
- [bson][bson]
### Web Frameworks
- [hyper][hyper]
- [rocket][rocket]
- [warp][warp]
## API Stability
Juniper has not reached 1.0 yet, thus some API instability should be expected.
[graphql]: http://graphql.org
[graphiql]: https://github.com/graphql/graphiql
[graphql_spec]: https://spec.graphql.org/October2021
[test_schema_rs]: https://github.com/graphql-rust/juniper/blob/master/juniper/src/tests/schema.rs
[tokio]: https://github.com/tokio-rs/tokio
[hyper_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_hyper/examples
[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
[hyper]: https://hyper.rs
[rocket]: https://rocket.rs
[book]: https://graphql-rust.github.io
[book_quickstart]: https://graphql-rust.github.io/quickstart.html
[docsrs]: https://docs.rs/juniper
[warp]: https://github.com/seanmonstar/warp
[warp_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples
[uuid]: https://crates.io/crates/uuid
[url]: https://crates.io/crates/url
[chrono]: https://crates.io/crates/chrono
[bson]: https://crates.io/crates/bson

57
book/src/SUMMARY.md
View file

@ -1,39 +1,28 @@
- [Introduction](README.md)
# Summary
- [Introduction](introduction.md)
- [Quickstart](quickstart.md)
- [Type System](types/index.md)
- [Defining objects](types/objects/defining_objects.md)
- [Complex fields](types/objects/complex_fields.md)
- [Using contexts](types/objects/using_contexts.md)
- [Error handling](types/objects/error_handling.md)
- [Other types](types/other-index.md)
- [Enums](types/enums.md)
- [Type system](types/index.md)
- [Objects](types/objects/index.md)
- [Complex fields](types/objects/complex_fields.md)
- [Context](types/objects/context.md)
- [Error handling](types/objects/error/index.md)
- [Field errors](types/objects/error/field.md)
- [Schema errors](types/objects/error/schema.md)
- [Generics](types/objects/generics.md)
- [Interfaces](types/interfaces.md)
- [Unions](types/unions.md)
- [Enums](types/enums.md)
- [Input objects](types/input_objects.md)
- [Scalars](types/scalars.md)
- [Unions](types/unions.md)
- [Schemas and mutations](schema/schemas_and_mutations.md)
- [Adding A Server](servers/index.md)
- [Official Server Integrations](servers/official.md) - [Hyper](servers/hyper.md)
- [Warp](servers/warp.md)
- [Rocket](servers/rocket.md)
- [Hyper](servers/hyper.md)
- [Third Party Integrations](servers/third-party.md)
- [Schema](schema/index.md)
- [Subscriptions](schema/subscriptions.md)
- [Introspection](schema/introspection.md)
- [Serving](serve/index.md)
- [Batching](serve/batching.md)
- [Advanced Topics](advanced/index.md)
- [Introspection](advanced/introspection.md)
- [Non-struct objects](advanced/non_struct_objects.md)
- [Implicit and explicit null](advanced/implicit_and_explicit_null.md)
- [Objects and generics](advanced/objects_and_generics.md)
- [Multiple operations per request](advanced/multiple_ops_per_request.md)
- [Dataloaders](advanced/dataloaders.md)
- [Subscriptions](advanced/subscriptions.md)
# - [Context switching]
# - [Dynamic type system]
- [Implicit and explicit `null`](advanced/implicit_and_explicit_null.md)
- [N+1 problem](advanced/n_plus_1.md)
- [DataLoader](advanced/dataloader.md)
- [Look-ahead](advanced/lookahead.md)
- [Eager loading](advanced/eager_loading.md)

198
book/src/advanced/dataloader.md Normal file
View file

@ -0,0 +1,198 @@
DataLoader
==========
DataLoader pattern, named after the correspondent [`dataloader` NPM package][0], represents a mechanism of batching and caching data requests in a delayed manner for solving the [N+1 problem](n_plus_1.md).
> A port of the "Loader" API originally developed by [@schrockn] at Facebook in 2010 as a simplifying force to coalesce the sundry key-value store back-end APIs which existed at the time. At Facebook, "Loader" became one of the implementation details of the "Ent" framework, a privacy-aware data entity loading and caching layer within web server product code. This ultimately became the underpinning for Facebook's GraphQL server implementation and type definitions.
In [Rust] ecosystem, DataLoader pattern is introduced with the [`dataloader` crate][1], naturally usable with [Juniper].
Let's remake our [example of N+1 problem](n_plus_1.md), so it's solved by applying the DataLoader pattern:
```rust
# extern crate anyhow;
# extern crate dataloader;
# extern crate juniper;
# use std::{collections::HashMap, sync::Arc};
# use anyhow::anyhow;
# use dataloader::non_cached::Loader;
# use juniper::{graphql_object, GraphQLObject};
#
# type CultId = i32;
# type UserId = i32;
#
# struct Repository;
#
# impl Repository {
# async fn load_cults_by_ids(&self, cult_ids: &[CultId]) -> anyhow::Result<HashMap<CultId, Cult>> { unimplemented!() }
# async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
# }
#
struct Context {
repo: Repository,
cult_loader: CultLoader,
}
impl juniper::Context for Context {}
#[derive(Clone, GraphQLObject)]
struct Cult {
id: CultId,
name: String,
}
struct CultBatcher {
repo: Repository,
}
// Since `BatchFn` doesn't provide any notion of fallible loading, like
// `try_load()` returning `Result<HashMap<K, V>, E>`, we handle possible
// errors as loaded values and unpack them later in the resolver.
impl dataloader::BatchFn<CultId, Result<Cult, Arc<anyhow::Error>>> for CultBatcher {
async fn load(
&mut self,
cult_ids: &[CultId],
) -> HashMap<CultId, Result<Cult, Arc<anyhow::Error>>> {
// Effectively performs the following SQL query:
// SELECT id, name FROM cults WHERE id IN (${cult_id1}, ${cult_id2}, ...)
match self.repo.load_cults_by_ids(cult_ids).await {
Ok(found_cults) => {
found_cults.into_iter().map(|(id, cult)| (id, Ok(cult))).collect()
}
// One could choose a different strategy to deal with fallible loads,
// like consider values that failed to load as absent, or just panic.
// See cksac/dataloader-rs#35 for details:
// https://github.com/cksac/dataloader-rs/issues/35
Err(e) => {
// Since `anyhow::Error` doesn't implement `Clone`, we have to
// work around here.
let e = Arc::new(e);
cult_ids.iter().map(|k| (k.clone(), Err(e.clone()))).collect()
}
}
}
}
type CultLoader = Loader<CultId, Result<Cult, Arc<anyhow::Error>>, CultBatcher>;
fn new_cult_loader(repo: Repository) -> CultLoader {
CultLoader::new(CultBatcher { repo })
// Usually a `Loader` will coalesce all individual loads which occur
// within a single frame of execution before calling a `BatchFn::load()`
// with all the collected keys. However, sometimes this behavior is not
// desirable or optimal (perhaps, a request is expected to be spread out
// over a few subsequent ticks).
// A larger yield count will allow more keys to be appended to the batch,
// but will wait longer before the actual load. For more details see:
// https://github.com/cksac/dataloader-rs/issues/12
// https://github.com/graphql/dataloader#batch-scheduling
.with_yield_count(100)
}
struct Person {
id: UserId,
name: String,
cult_id: CultId,
}
#[graphql_object]
#[graphql(context = Context)]
impl Person {
fn id(&self) -> CultId {
self.id
}
fn name(&self) -> &str {
self.name.as_str()
}
async fn cult(&self, ctx: &Context) -> anyhow::Result<Cult> {
ctx.cult_loader
// Here, we don't run the `CultBatcher::load()` eagerly, but rather
// only register the `self.cult_id` value in the `cult_loader` and
// wait for other concurrent resolvers to do the same.
// The actual batch loading happens once all the resolvers register
// their IDs and there is nothing more to execute.
.try_load(self.cult_id)
.await
// The outer error is the `io::Error` returned by `try_load()` if
// no value is present in the `HashMap` for the specified
// `self.cult_id`, meaning that there is no `Cult` with such ID
// in the `Repository`.
.map_err(|_| anyhow!("No cult exists for ID `{}`", self.cult_id))?
// The inner error is the one returned by the `CultBatcher::load()`
// if the `Repository::load_cults_by_ids()` fails, meaning that
// running the SQL query failed.
.map_err(|arc_err| anyhow!("{arc_err}"))
}
}
struct Query;
#[graphql_object]
#[graphql(context = Context)]
impl Query {
async fn persons(ctx: &Context) -> anyhow::Result<Vec<Person>> {
// Effectively performs the following SQL query:
// SELECT id, name, cult_id FROM persons
ctx.repo.load_all_persons().await
}
}
fn main() {
}
```
And now, performing a [GraphQL query which lead to N+1 problem](n_plus_1.md)
```graphql
query {
persons {
id
name
cult {
id
name
}
}
}
```
will lead to efficient [SQL] queries, just as expected:
```sql
SELECT id, name, cult_id FROM persons;
SELECT id, name FROM cults WHERE id IN (1, 2, 3, 4);
```
## Caching
[`dataloader::cached`] provides a [memoization][2] cache: after `BatchFn::load()` is called once with given keys, the resulting values are cached to eliminate redundant loads.
DataLoader caching does not replace [Redis], [Memcached], or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data [in the context of a single request][3].
> **WARNING**: A DataLoader should be created per-request to avoid risk of bugs where one client is able to load cached/batched data from another client outside its authenticated scope. Creating a DataLoader within an individual resolver will prevent batching from occurring and will nullify any benefits of it.
## Full example
For a full example using DataLoaders in [Juniper] check out the [`jayy-lmao/rust-graphql-docker` repository][4].
[`dataloader::cached`]: https://docs.rs/dataloader/latest/dataloader/cached/index.html
[@schrockn]: https://github.com/schrockn
[Juniper]: https://docs.rs/juniper
[Memcached]: https://memcached.org
[Redis]: https://redis.io
[Rust]: https://www.rust-lang.org
[SQL]: https://en.wikipedia.org/wiki/SQL
[0]: https://github.com/graphql/dataloader
[1]: https://docs.rs/crate/dataloader
[2]: https://en.wikipedia.org/wiki/Memoization
[3]: https://github.com/graphql/dataloader#caching
[4]: https://github.com/jayy-lmao/rust-graphql-docker

194
book/src/advanced/dataloaders.md
View file

@ -1,194 +0,0 @@
# Avoiding the N+1 Problem With Dataloaders
A common issue with graphql servers is how the resolvers query their datasource.
This issue results in a large number of unnecessary database queries or http requests.
Say you were wanting to list a bunch of cults people were in
```graphql
query {
persons {
id
name
cult {
id
name
}
}
}
```
What would be executed by a SQL database would be:
```sql
SELECT id, name, cult_id FROM persons;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 2;
SELECT id, name FROM cults WHERE id = 2;
SELECT id, name FROM cults WHERE id = 2;
# ...
```
Once the list of users has been returned, a separate query is run to find the cult of each user.
You can see how this could quickly become a problem.
A common solution to this is to introduce a **dataloader**.
This can be done with Juniper using the crate [cksac/dataloader-rs](https://github.com/cksac/dataloader-rs), which has two types of dataloaders; cached and non-cached.
#### Cached Loader
DataLoader provides a memoization cache, after .load() is called once with a given key, the resulting value is cached to eliminate redundant loads.
DataLoader caching does not replace Redis, Memcache, or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data in the context of a single request to your Application. [(read more)](https://github.com/graphql/dataloader#caching)
### What does it look like?
!FILENAME Cargo.toml
```toml
[dependencies]
actix-identity = "0.4.0-beta.4"
actix-rt = "1.0"
actix-web = "2.0"
async-trait = "0.1.30"
dataloader = "0.12.0"
futures = "0.3"
juniper = "0.16.0"
postgres = "0.15.2"
```
```rust, ignore
// use dataloader::cached::Loader;
use dataloader::non_cached::Loader;
use dataloader::BatchFn;
use std::collections::HashMap;
use postgres::{Connection, TlsMode};
use std::env;
pub fn get_db_conn() -> Connection {
let pg_connection_string = env::var("DATABASE_URI").expect("need a db uri");
println!("Connecting to {pg_connection_string}");
let conn = Connection::connect(&pg_connection_string[..], TlsMode::None).unwrap();
println!("Connection is fine");
conn
}
#[derive(Debug, Clone)]
pub struct Cult {
pub id: i32,
pub name: String,
}
pub fn get_cult_by_ids(hashmap: &mut HashMap<i32, Cult>, ids: Vec<i32>) {
let conn = get_db_conn();
for row in &conn
.query("SELECT id, name FROM cults WHERE id = ANY($1)", &[&ids])
.unwrap()
{
let cult = Cult {
id: row.get(0),
name: row.get(1),
};
hashmap.insert(cult.id, cult);
}
}
pub struct CultBatcher;
#[async_trait]
impl BatchFn<i32, Cult> for CultBatcher {
// A hashmap is used, as we need to return an array which maps each original key to a Cult.
async fn load(&self, keys: &[i32]) -> HashMap<i32, Cult> {
println!("load cult batch {keys:?}");
let mut cult_hashmap = HashMap::new();
get_cult_by_ids(&mut cult_hashmap, keys.to_vec());
cult_hashmap
}
}
pub type CultLoader = Loader<i32, Cult, CultBatcher>;
// To create a new loader
pub fn get_loader() -> CultLoader {
Loader::new(CultBatcher)
// Usually a DataLoader will coalesce all individual loads which occur
// within a single frame of execution before calling your batch function with all requested keys.
// However sometimes this behavior is not desirable or optimal.
// Perhaps you expect requests to be spread out over a few subsequent ticks
// See: https://github.com/cksac/dataloader-rs/issues/12
// More info: https://github.com/graphql/dataloader#batch-scheduling
// A larger yield count will allow more requests to append to batch but will wait longer before actual load.
.with_yield_count(100)
}
#[juniper::graphql_object(Context = Context)]
impl Cult {
// your resolvers
// To call the dataloader
pub async fn cult_by_id(ctx: &Context, id: i32) -> Cult {
ctx.cult_loader.load(id).await
}
}
```
### How do I call them?
Once created, a dataloader has the async functions `.load()` and `.load_many()`.
In the above example `cult_loader.load(id: i32).await` returns `Cult`. If we had used `cult_loader.load_many(Vec<i32>).await` it would have returned `Vec<Cult>`.
### Where do I create my dataloaders?
**Dataloaders** should be created per-request to avoid risk of bugs where one user is able to load cached/batched data from another user/ outside of its authenticated scope.
Creating dataloaders within individual resolvers will prevent batching from occurring and will nullify the benefits of the dataloader.
For example:
_When you declare your context_
```rust, ignore
use juniper;
#[derive(Clone)]
pub struct Context {
pub cult_loader: CultLoader,
}
impl juniper::Context for Context {}
impl Context {
pub fn new(cult_loader: CultLoader) -> Self {
Self {
cult_loader
}
}
}
```
_Your handler for GraphQL (Note: instantiating context here keeps it per-request)_
```rust, ignore
pub async fn graphql(
st: web::Data<Arc<Schema>>,
data: web::Json<GraphQLRequest>,
) -> Result<HttpResponse, Error> {
// Context setup
let cult_loader = get_loader();
let ctx = Context::new(cult_loader);
// Execute
let res = data.execute(&st, &ctx).await;
let json = serde_json::to_string(&res).map_err(error::ErrorInternalServerError)?;
Ok(HttpResponse::Ok()
.content_type("application/json")
.body(json))
}
```
### Further Example:
For a full example using Dataloaders and Context check out [jayy-lmao/rust-graphql-docker](https://github.com/jayy-lmao/rust-graphql-docker).

280
book/src/advanced/eager_loading.md Normal file
View file

@ -0,0 +1,280 @@
Eager loading
=============
As a further evolution of the [dealing with the N+1 problem via look-ahead](lookahead.md#n1-problem), we may systematically remodel [Rust] types mapping to [GraphQL] ones in the way to encourage doing eager preloading of data for its [fields][0] and using the already preloaded data when resolving a particular [field][0].
At the moment, this approach is represented with the [`juniper-eager-loading`] crate for [Juniper].
> **NOTE**: Since this library requires [`juniper-from-schema`], it's best first to become familiar with it.
<!-- TODO: Provide example of solving the problem from "N+1 chapter" once `juniper-eager-loading` support the latest `juniper`. -->
From ["How this library works at a high level"][11] and ["A real example"][12] sections of [`juniper-eager-loading`] documentation:
> ### How this library works at a high level
>
> If you have a GraphQL type like this
>
> ```graphql
> type User {
> id: Int!
> country: Country!
> }
> ```
>
> You might create the corresponding Rust model type like this:
>
> ```rust
> struct User {
> id: i32,
> country_id: i32,
> }
> ```
>
> However this approach has one big issue. How are you going to resolve the field `User.country`
> without doing a database query? All the resolver has access to is a `User` with a `country_id`
> field. It can't get the country without loading it from the database...
>
> Fundamentally these kinds of model structs don't work for eager loading with GraphQL. So
> this library takes a different approach.
>
> What if we created separate structs for the database models and the GraphQL models? Something
> like this:
>
> ```rust
> # fn main() {}
> #
> mod models {
> pub struct User {
> id: i32,
> country_id: i32
> }
>
> pub struct Country {
> id: i32,
> }
> }
>
> struct User {
> user: models::User,
> country: HasOne<Country>,
> }
>
> struct Country {
> country: models::Country
> }
>
> enum HasOne<T> {
> Loaded(T),
> NotLoaded,
> }
> ```
>
> Now we're able to resolve the query with code like this:
>
> 1. Load all the users (first query).
> 2. Map the users to a list of country ids.
> 3. Load all the countries with those ids (second query).
> 4. Pair up the users with the country with the correct id, so change `User.country` from
> `HasOne::NotLoaded` to `HasOne::Loaded(matching_country)`.
> 5. When resolving the GraphQL field `User.country` simply return the loaded country.
>
> ### A real example
>
> ```rust,ignore
> use juniper::{Executor, FieldResult};
> use juniper_eager_loading::{prelude::*, EagerLoading, HasOne};
> use juniper_from_schema::graphql_schema;
> use std::error::Error;
>
> // Define our GraphQL schema.
> graphql_schema! {
> schema {
> query: Query
> }
>
> type Query {
> allUsers: [User!]! @juniper(ownership: "owned")
> }
>
> type User {
> id: Int!
> country: Country!
> }
>
> type Country {
> id: Int!
> }
> }
>
> // Our model types.
> mod models {
> use std::error::Error;
> use juniper_eager_loading::LoadFrom;
>
> #[derive(Clone)]
> pub struct User {
> pub id: i32,
> pub country_id: i32
> }
>
> #[derive(Clone)]
> pub struct Country {
> pub id: i32,
> }
>
> // This trait is required for eager loading countries.
> // It defines how to load a list of countries from a list of ids.
> // Notice that `Context` is generic and can be whatever you want.
> // It will normally be your Juniper context which would contain
> // a database connection.
> impl LoadFrom<i32> for Country {
> type Error = Box<dyn Error>;
> type Context = super::Context;
>
> fn load(
> employments: &[i32],
> field_args: &(),
> ctx: &Self::Context,
> ) -> Result<Vec<Self>, Self::Error> {
> // ...
> # unimplemented!()
> }
> }
> }
>
> // Our sample database connection type.
> pub struct DbConnection;
>
> impl DbConnection {
> // Function that will load all the users.
> fn load_all_users(&self) -> Vec<models::User> {
> // ...
> # unimplemented!()
> }
> }
>
> // Our Juniper context type which contains a database connection.
> pub struct Context {
> db: DbConnection,
> }
>
> impl juniper::Context for Context {}
>
> // Our GraphQL user type.
> // `#[derive(EagerLoading)]` takes care of generating all the boilerplate code.
> #[derive(Clone, EagerLoading)]
> // You need to set the context and error type.
> #[eager_loading(
> context = Context,
> error = Box<dyn Error>,
>
> // These match the default so you wouldn't have to specify them
> model = models::User,
> id = i32,
> root_model_field = user,
> )]
> pub struct User {
> // This user model is used to resolve `User.id`
> user: models::User,
>
> // Setup a "has one" association between a user and a country.
> //
> // We could also have used `#[has_one(default)]` here.
> #[has_one(
> foreign_key_field = country_id,
> root_model_field = country,
> graphql_field = country,
> )]
> country: HasOne<Country>,
> }
>
> // And the GraphQL country type.
> #[derive(Clone, EagerLoading)]
> #[eager_loading(context = Context, error = Box<dyn Error>)]
> pub struct Country {
> country: models::Country,
> }
>
> // The root query GraphQL type.
> pub struct Query;
>
> impl QueryFields for Query {
> // The resolver for `Query.allUsers`.
> fn field_all_users(
> &self,
> executor: &Executor<'_, Context>,
> trail: &QueryTrail<'_, User, Walked>,
> ) -> FieldResult<Vec<User>> {
> let ctx = executor.context();
>
> // Load the model users.
> let user_models = ctx.db.load_all_users();
>
> // Turn the model users into GraphQL users.
> let mut users = User::from_db_models(&user_models);
>
> // Perform the eager loading.
> // `trail` is used to only eager load the fields that are requested. Because
> // we're using `QueryTrail`s from "juniper_from_schema" it would be a compile
> // error if we eager loaded associations that aren't requested in the query.
> User::eager_load_all_children_for_each(&mut users, &user_models, ctx, trail)?;
>
> Ok(users)
> }
> }
>
> impl UserFields for User {
> fn field_id(
> &self,
> executor: &Executor<'_, Context>,
> ) -> FieldResult<&i32> {
> Ok(&self.user.id)
> }
>
> fn field_country(
> &self,
> executor: &Executor<'_, Context>,
> trail: &QueryTrail<'_, Country, Walked>,
> ) -> FieldResult<&Country> {
> // This will unwrap the country from the `HasOne` or return an error if the
> // country wasn't loaded, or wasn't found in the database.
> Ok(self.country.try_unwrap()?)
> }
> }
>
> impl CountryFields for Country {
> fn field_id(
> &self,
> executor: &Executor<'_, Context>,
> ) -> FieldResult<&i32> {
> Ok(&self.country.id)
> }
> }
> #
> # fn main() {}
> ```
For more details, check out the [`juniper-eager-loading` documentation][`juniper-eager-loading`].
## Full example
For a full example using eager loading in [Juniper] check out the [`davidpdrsn/graphql-app-example` repository][10].
[`juniper-eager-loading`]: https://docs.rs/juniper-eager-loading
[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Redis]: https://redis.io
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Language.Fields
[10]: https://github.com/davidpdrsn/graphql-app-example
[11]: https://docs.rs/juniper-eager-loading/latest/juniper_eager_loading#how-this-library-works-at-a-high-level
[12]: https://docs.rs/juniper-eager-loading/latest/juniper_eager_loading#a-real-example

132
book/src/advanced/implicit_and_explicit_null.md
View file

@ -1,101 +1,89 @@
# Implicit and explicit null
Implicit and explicit `null`
============================
There are two ways that a client can submit a null argument or field in a query.
> [GraphQL] has two semantically different ways to represent the lack of a value:
> - Explicitly providing the literal value: **null**.
> - Implicitly not providing a value at all.
They can use a null literal:
There are two ways that a client can submit a [`null` value][0] as an [argument][5] or a [field][4] in a [GraphQL] query:
1. Either use an explicit `null` literal:
```graphql
{
field(arg: null)
}
```
2. Or simply omit the [argument][5], so the implicit default `null` value kicks in:
```graphql
{
field
}
```
```graphql
{
field(arg: null)
}
```
Or they can simply omit the argument:
```graphql
{
field
}
```
The former is an explicit null and the latter is an implicit null.
There are some situations where it's useful to know which one the user provided.
For example, let's say your business logic has a function that allows users to
perform a "patch" operation on themselves. Let's say your users can optionally
have favorite and least favorite numbers, and the input for that might look
like this:
There are some situations where it's useful to know which one exactly has been provided.
For example, let's say we have a function that allows users to perform a "patch" operation on themselves. Let's say our users can optionally have favorite and least favorite numbers, and the input for that might look like this:
```rust
/// Updates user attributes. Fields that are `None` are left as-is.
pub struct UserPatch {
/// If `Some`, updates the user's favorite number.
pub favorite_number: Option<Option<i32>>,
/// Updates user attributes. Fields that are [`None`] are left as-is.
struct UserPatch {
/// If [`Some`], updates the user's favorite number.
favorite_number: Option<Option<i32>>,
/// If `Some`, updates the user's least favorite number.
pub least_favorite_number: Option<Option<i32>>,
/// If [`Some`], updates the user's least favorite number.
least_favorite_number: Option<Option<i32>>,
}
#
# fn main() {}
```
To set a user's favorite number to 7, you would set `favorite_number` to
`Some(Some(7))`. In GraphQL, that might look like this:
To set a user's favorite number to 7, we would set `favorite_number` to `Some(Some(7))`. In [GraphQL], that might look like this:
```graphql
mutation { patchUser(patch: { favoriteNumber: 7 }) }
```
To unset the user's favorite number, you would set `favorite_number` to
`Some(None)`. In GraphQL, that might look like this:
To unset the user's favorite number, we would set `favorite_number` to `Some(None)`. In [GraphQL], that might look like this:
```graphql
mutation { patchUser(patch: { favoriteNumber: null }) }
```
If you want to leave the user's favorite number alone, you would set it to
`None`. In GraphQL, that might look like this:
And if we want to leave the user's favorite number alone, just set it to `None`. In [GraphQL], that might look like this:
```graphql
mutation { patchUser(patch: {}) }
```
The last two cases rely on being able to distinguish between explicit and implicit null.
In Juniper, this can be done using the `Nullable` type:
The last two cases rely on being able to distinguish between [explicit and implicit `null`][1].
Unfortunately, plain `Option` is not capable to distinguish them. That's why in [Juniper], this can be done using the [`Nullable`] type:
```rust
# extern crate juniper;
use juniper::{FieldResult, Nullable};
use juniper::{graphql_object, FieldResult, GraphQLInputObject, Nullable};
#[derive(juniper::GraphQLInputObject)]
#[derive(GraphQLInputObject)]
struct UserPatchInput {
pub favorite_number: Nullable<i32>,
pub least_favorite_number: Nullable<i32>,
favorite_number: Nullable<i32>,
least_favorite_number: Nullable<i32>,
}
impl Into<UserPatch> for UserPatchInput {
fn into(self) -> UserPatch {
UserPatch {
// The `explicit` function transforms the `Nullable` into an
// `Option<Option<T>>` as expected by the business logic layer.
favorite_number: self.favorite_number.explicit(),
least_favorite_number: self.least_favorite_number.explicit(),
}
}
impl From<UserPatchInput> for UserPatch {
fn from(input: UserPatchInput) -> Self {
Self {
// The `explicit()` function transforms the `Nullable` into an
// `Option<Option<T>>` as expected by the business logic layer.
favorite_number: input.favorite_number.explicit(),
least_favorite_number: input.least_favorite_number.explicit(),
}
}
}
# pub struct UserPatch {
# pub favorite_number: Option<Option<i32>>,
# pub least_favorite_number: Option<Option<i32>>,
# struct UserPatch {
# favorite_number: Option<Option<i32>>,
# least_favorite_number: Option<Option<i32>>,
# }
#
# struct Session;
# impl Session {
# fn patch_user(&self, _patch: UserPatch) -> FieldResult<()> { Ok(()) }
# }
#
struct Context {
session: Session,
}
@ -103,15 +91,27 @@ impl juniper::Context for Context {}
struct Mutation;
#[juniper::graphql_object(context = Context)]
#[graphql_object]
#[graphql(context = Context)]
impl Mutation {
fn patch_user(ctx: &Context, patch: UserPatchInput) -> FieldResult<bool> {
fn patch_user(patch: UserPatchInput, ctx: &Context) -> FieldResult<bool> {
ctx.session.patch_user(patch.into())?;
Ok(true)
}
}
#
# fn main() {}
```
This type functions much like `Option`, but has two empty variants so you can
distinguish between implicit and explicit null.
[`Nullable`]: https://docs.rs/juniper/latest/juniper/enum.Nullable.html
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Null-Value
[1]: https://spec.graphql.org/October2021#sel-EAFdRDHAAEJDAoBxzT
[4]: https://spec.graphql.org/October2021#sec-Language.Fields
[5]: https://spec.graphql.org/October2021#sec-Language.Arguments

17
book/src/advanced/index.md
View file

@ -1,11 +1,10 @@
# Advanced Topics
Advanced topics
===============
The chapters below cover some more advanced scenarios.
The chapters below cover some more advanced topics.
- [Introspection](introspection.md)
- [Non-struct objects](non_struct_objects.md)
- [Implicit and explicit null](implicit_and_explicit_null.md)
- [Objects and generics](objects_and_generics.md)
- [Multiple operations per request](multiple_ops_per_request.md)
- [Dataloaders](dataloaders.md)
- [Subscriptions](subscriptions.md)
- [Implicit and explicit `null`](implicit_and_explicit_null.md)
- [N+1 problem](n_plus_1.md)
- [DataLoader](dataloader.md)
- [Look-ahead](lookahead.md)
- [Eager loading](eager_loading.md)

82
book/src/advanced/introspection.md
View file

@ -1,82 +0,0 @@
# Introspection
GraphQL defines a special built-in top-level field called `__schema`. Querying
for this field allows one to [introspect the schema](https://graphql.org/learn/introspection/)
at runtime to see what queries and mutations the GraphQL server supports.
Because introspection queries are just regular GraphQL queries, Juniper supports
them natively. For example, to get all the names of the types supported one
could execute the following query against Juniper:
```graphql
{
__schema {
types {
name
}
}
}
```
## Schema introspection output as JSON
Many client libraries and tools in the GraphQL ecosystem require a complete
representation of the server schema. Often this representation is in JSON and
referred to as `schema.json`. A complete representation of the schema can be
produced by issuing a specially crafted introspection query.
Juniper provides a convenience function to introspect the entire schema. The
result can then be converted to JSON for use with tools and libraries such as
[graphql-client](https://github.com/graphql-rust/graphql-client):
```rust
# #![allow(unused_variables)]
# extern crate juniper;
# extern crate serde_json;
use juniper::{
graphql_object, EmptyMutation, EmptySubscription, FieldResult,
GraphQLObject, IntrospectionFormat,
};
// Define our schema.
#[derive(GraphQLObject)]
struct Example {
id: String,
}
struct Context;
impl juniper::Context for Context {}
struct Query;
#[graphql_object(context = Context)]
impl Query {
fn example(id: String) -> FieldResult<Example> {
unimplemented!()
}
}
type Schema = juniper::RootNode<
'static,
Query,
EmptyMutation<Context>,
EmptySubscription<Context>
>;
fn main() {
// Create a context object.
let ctx = Context;
// Run the built-in introspection query.
let (res, _errors) = juniper::introspect(
&Schema::new(Query, EmptyMutation::new(), EmptySubscription::new()),
&ctx,
IntrospectionFormat::default(),
).unwrap();
// Convert introspection result to json.
let json_result = serde_json::to_string_pretty(&res);
assert!(json_result.is_ok());
}
```

229
book/src/advanced/lookahead.md Normal file
View file

@ -0,0 +1,229 @@
Look-ahead
==========
> In backtracking algorithms, **look ahead** is the generic term for a subprocedure that attempts to foresee the effects of choosing a branching variable to evaluate one of its values. The two main aims of look-ahead are to choose a variable to evaluate next and to choose the order of values to assign to it.
In [GraphQL], look-ahead machinery allows us to introspect the currently [executed][1] [GraphQL operation][2] to see which [fields][3] has been actually selected by it.
In [Juniper], it's represented by the [`Executor::look_ahead()`][20] method.
```rust
# extern crate juniper;
# use juniper::{graphql_object, Executor, GraphQLObject, ScalarValue};
#
# type UserId = i32;
#
#[derive(GraphQLObject)]
struct Person {
id: UserId,
name: String,
}
struct Query;
#[graphql_object]
// NOTICE: Specifying `ScalarValue` as custom named type parameter,
// so its name is similar to the one used in methods.
#[graphql(scalar = S: ScalarValue)]
impl Query {
fn persons<S: ScalarValue>(executor: &Executor<'_, '_, (), S>) -> Vec<Person> {
// Let's see which `Person`'s fields were selected in the client query.
for field_name in executor.look_ahead().children().names() {
dbg!(field_name);
}
// ...
# unimplemented!()
}
}
```
> **TIP**: `S: ScalarValue` type parameter on the method is required here to keep the [`Executor`] being generic over [`ScalarValue`] types. We, instead, could have used the [`DefaultScalarValue`], which is the default [`ScalarValue`] type for the [`Executor`], and make our code more ergonomic, but less flexible and generic.
> ```rust
> # extern crate juniper;
> # use juniper::{graphql_object, DefaultScalarValue, Executor, GraphQLObject};
> #
> # type UserId = i32;
> #
> # #[derive(GraphQLObject)]
> # struct Person {
> # id: UserId,
> # name: String,
> # }
> #
> # struct Query;
> #
> #[graphql_object]
> #[graphql(scalar = DefaultScalarValue)]
> impl Query {
> fn persons(executor: &Executor<'_, '_, ()>) -> Vec<Person> {
> for field_name in executor.look_ahead().children().names() {
> dbg!(field_name);
> }
> // ...
> # unimplemented!()
> }
> }
> ```
## N+1 problem
Naturally, look-ahead machinery allows us to solve [the N+1 problem](n_plus_1.md) by introspecting the requested fields and performing loading in batches eagerly, before actual resolving of those fields:
```rust
# extern crate anyhow;
# extern crate juniper;
# use std::collections::HashMap;
# use anyhow::anyhow;
# use juniper::{graphql_object, Executor, GraphQLObject, ScalarValue};
#
# type CultId = i32;
# type UserId = i32;
#
# struct Repository;
#
# impl juniper::Context for Repository {}
#
# impl Repository {
# async fn load_cult_by_id(&self, cult_id: CultId) -> anyhow::Result<Option<Cult>> { unimplemented!() }
# async fn load_cults_by_ids(&self, cult_ids: &[CultId]) -> anyhow::Result<HashMap<CultId, Cult>> { unimplemented!() }
# async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
# }
#
# enum Either<L, R> {
# Absent(L),
# Loaded(R),
# }
#
#[derive(Clone, GraphQLObject)]
struct Cult {
id: CultId,
name: String,
}
struct Person {
id: UserId,
name: String,
cult: Either<CultId, Cult>,
}
#[graphql_object]
#[graphql(context = Repository)]
impl Person {
fn id(&self) -> CultId {
self.id
}
fn name(&self) -> &str {
self.name.as_str()
}
async fn cult(&self, #[graphql(ctx)] repo: &Repository) -> anyhow::Result<Cult> {
match &self.cult {
Either::Loaded(cult) => Ok(cult.clone()),
Either::Absent(cult_id) => {
// Effectively performs the following SQL query:
// SELECT id, name FROM cults WHERE id = ${cult_id} LIMIT 1
repo.load_cult_by_id(*cult_id)
.await?
.ok_or_else(|| anyhow!("No cult exists for ID `{cult_id}`"))
}
}
}
}
struct Query;
#[graphql_object]
#[graphql(context = Repository, scalar = S: ScalarValue)]
impl Query {
async fn persons<S: ScalarValue>(
#[graphql(ctx)] repo: &Repository,
executor: &Executor<'_, '_, Repository, S>,
) -> anyhow::Result<Vec<Person>> {
// Effectively performs the following SQL query:
// SELECT id, name, cult_id FROM persons
let mut persons = repo.load_all_persons().await?;
// If the `Person.cult` field has been requested.
if executor.look_ahead()
.children()
.iter()
.any(|sel| sel.field_original_name() == "cult")
{
// Gather `Cult.id`s to load eagerly.
let cult_ids = persons
.iter()
.filter_map(|p| {
match &p.cult {
Either::Absent(cult_id) => Some(*cult_id),
// If for some reason a `Cult` is already loaded,
// then just skip it.
Either::Loaded(_) => None,
}
})
.collect::<Vec<_>>();
// Load the necessary `Cult`s eagerly.
// Effectively performs the following SQL query:
// SELECT id, name FROM cults WHERE id IN (${cult_id1}, ${cult_id2}, ...)
let cults = repo.load_cults_by_ids(&cult_ids).await?;
// Populate `persons` with the loaded `Cult`s, so they do not perform
// any SQL queries on resolving.
for p in &mut persons {
let Either::Absent(cult_id) = &p.cult else { continue; };
p.cult = Either::Loaded(
cults.get(cult_id)
.ok_or_else(|| anyhow!("No cult exists for ID `{cult_id}`"))?
.clone(),
);
}
}
Ok(persons)
}
}
```
And so, performing a [GraphQL query which lead to N+1 problem](n_plus_1.md)
```graphql
query {
persons {
id
name
cult {
id
name
}
}
}
```
will lead to efficient [SQL] queries, just as expected:
```sql
SELECT id, name, cult_id FROM persons;
SELECT id, name FROM cults WHERE id IN (1, 2, 3, 4);
```
## More features
See more available look-ahead features in the API docs of the [`LookAheadSelection`][21] and the [`LookAheadChildren`][22].
[`DefaultScalarValue`]: https://docs.rs/juniper/latest/juniper/enum.DefaultScalarValue.html
[`Executor`]: https://docs.rs/juniper/latest/juniper/executor/struct.Executor.html
[`ScalarValue`]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[SQL]: https://en.wikipedia.org/wiki/SQL
[1]: https://spec.graphql.org/October2021#sec-Execution
[2]: https://spec.graphql.org/October2021#sec-Language.Operations\
[3]: https://spec.graphql.org/October2021#sec-Language.Fields
[20]: https://docs.rs/juniper/latest/juniper/executor/struct.Executor.html#method.look_ahead
[21]: https://docs.rs/juniper/latest/juniper/executor/struct.LookAheadSelection.html
[22]: https://docs.rs/juniper/latest/juniper/executor/struct.LookAheadChildren.html

73
book/src/advanced/multiple_ops_per_request.md
View file

@ -1,73 +0,0 @@
# Multiple operations per request
The GraphQL standard generally assumes there will be one server request for each client operation you want to perform (such as a query or mutation). This is conceptually simple but has the potential to be inefficient.
Some client libraries such as [apollo-link-batch-http](https://www.apollographql.com/docs/link/links/batch-http.html) have added the ability to batch operations in a single HTTP request to save network round-trips and potentially increase performance. There are some [tradeoffs](https://blog.apollographql.com/batching-client-graphql-queries-a685f5bcd41b) that should be considered before batching requests.
Juniper's server integration crates support multiple operations in a single HTTP request using JSON arrays. This makes them compatible with client libraries that support batch operations without any special configuration.
Server integration crates maintained by others are **not required** to support batch requests. Batch requests aren't part of the official GraphQL specification.
Assuming an integration supports batch requests, for the following GraphQL query:
```graphql
{
hero {
name
}
}
```
The json data to POST to the server for an individual request would be:
```json
{
"query": "{hero{name}}"
}
```
And the response would be of the form:
```json
{
"data": {
"hero": {
"name": "R2-D2"
}
}
}
```
If you wanted to run the same query twice in a single HTTP request, the batched json data to POST to the server would be:
```json
[
{
"query": "{hero{name}}"
},
{
"query": "{hero{name}}"
}
]
```
And the response would be of the form:
```json
[
{
"data": {
"hero": {
"name": "R2-D2"
}
}
},
{
"data": {
"hero": {
"name": "R2-D2"
}
}
}
]
```

111
book/src/advanced/n_plus_1.md Normal file
View file

@ -0,0 +1,111 @@
N+1 problem
===========
A common issue with [GraphQL] server implementations is how the [resolvers][2] query their datasource. With a naive and straightforward approach we quickly run into the N+1 problem, resulting in a large number of unnecessary database queries or [HTTP] requests.
```rust
# extern crate anyhow;
# extern crate juniper;
# use anyhow::anyhow;
# use juniper::{graphql_object, GraphQLObject};
#
# type CultId = i32;
# type UserId = i32;
#
# struct Repository;
#
# impl juniper::Context for Repository {}
#
# impl Repository {
# async fn load_cult_by_id(&self, cult_id: CultId) -> anyhow::Result<Option<Cult>> { unimplemented!() }
# async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
# }
#
#[derive(GraphQLObject)]
struct Cult {
id: CultId,
name: String,
}
struct Person {
id: UserId,
name: String,
cult_id: CultId,
}
#[graphql_object]
#[graphql(context = Repository)]
impl Person {
fn id(&self) -> CultId {
self.id
}
fn name(&self) -> &str {
self.name.as_str()
}
async fn cult(&self, #[graphql(ctx)] repo: &Repository) -> anyhow::Result<Cult> {
// Effectively performs the following SQL query:
// SELECT id, name FROM cults WHERE id = ${cult_id} LIMIT 1
repo.load_cult_by_id(self.cult_id)
.await?
.ok_or_else(|| anyhow!("No cult exists for ID `{}`", self.cult_id))
}
}
struct Query;
#[graphql_object]
#[graphql(context = Repository)]
impl Query {
async fn persons(#[graphql(ctx)] repo: &Repository) -> anyhow::Result<Vec<Person>> {
// Effectively performs the following SQL query:
// SELECT id, name, cult_id FROM persons
repo.load_all_persons().await
}
}
```
Let's say we want to list a bunch of `cult`s `persons` were in:
```graphql
query {
persons {
id
name
cult {
id
name
}
}
}
```
Once the `persons` [list][1] has been [resolved][2], a separate [SQL] query is run to find the `cult` of each `Person`. We can see how this could quickly become a problem.
```sql
SELECT id, name, cult_id FROM persons;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 2;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 3;
SELECT id, name FROM cults WHERE id = 4;
SELECT id, name FROM cults WHERE id = 1;
SELECT id, name FROM cults WHERE id = 2;
-- and so on...
```
There are several ways how this problem may be resolved in [Juniper]. The most common ones are:
- [DataLoader](dataloader.md)
- [Look-ahead machinery](lookahead.md)
- [Eager loading](eager_loading.md)
[GraphQL]: https://graphql.org
[HTTP]: https://en.wikipedia.org/wiki/HTTP
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[SQL]: https://en.wikipedia.org/wiki/SQL
[1]: https://spec.graphql.org/October2021#sec-List
[2]: https://spec.graphql.org/October2021#sec-Executing-Fields

58
book/src/advanced/non_struct_objects.md
View file

@ -1,58 +0,0 @@
# Non-struct objects
Up until now, we've only looked at mapping structs to GraphQL objects. However,
any Rust type can be mapped into a GraphQL object. In this chapter, we'll look
at enums, but traits will work too - they don't _have_ to be mapped into GraphQL
interfaces.
Using `Result`-like enums can be a useful way of reporting e.g. validation
errors from a mutation:
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject};
# #[derive(juniper::GraphQLObject)] struct User { name: String }
#
#[derive(GraphQLObject)]
struct ValidationError {
field: String,
message: String,
}
# #[allow(dead_code)]
enum SignUpResult {
Ok(User),
Error(Vec<ValidationError>),
}
#[graphql_object]
impl SignUpResult {
fn user(&self) -> Option<&User> {
match *self {
SignUpResult::Ok(ref user) => Some(user),
SignUpResult::Error(_) => None,
}
}
fn error(&self) -> Option<&Vec<ValidationError>> {
match *self {
SignUpResult::Ok(_) => None,
SignUpResult::Error(ref errors) => Some(errors)
}
}
}
#
# fn main() {}
```
Here, we use an enum to decide whether a user's input data was valid or not, and
it could be used as the result of e.g. a sign up mutation.
While this is an example of how you could use something other than a struct to
represent a GraphQL object, it's also an example on how you could implement
error handling for "expected" errors - errors like validation errors. There are
no hard rules on how to represent errors in GraphQL, but there are
[some](https://github.com/facebook/graphql/issues/117#issuecomment-170180628)
[comments](https://github.com/graphql/graphql-js/issues/560#issuecomment-259508214)
from one of the authors of GraphQL on how they intended "hard" field errors to
be used, and how to model expected errors.

66
book/src/advanced/objects_and_generics.md
View file

@ -1,66 +0,0 @@
# Objects and generics
Yet another point where GraphQL and Rust differs is in how generics work. In
Rust, almost any type could be generic - that is, take type parameters. In
GraphQL, there are only two generic types: lists and non-nullables.
This poses a restriction on what you can expose in GraphQL from Rust: no generic
structs can be exposed - all type parameters must be bound. For example, you can
not make e.g. `Result<T, E>` into a GraphQL type, but you _can_ make e.g.
`Result<User, String>` into a GraphQL type.
Let's make a slightly more compact but generic implementation of [the last
chapter](non_struct_objects.md):
```rust
# extern crate juniper;
# #[derive(juniper::GraphQLObject)] struct User { name: String }
# #[derive(juniper::GraphQLObject)] struct ForumPost { title: String }
#[derive(juniper::GraphQLObject)]
struct ValidationError {
field: String,
message: String,
}
# #[allow(dead_code)]
struct MutationResult<T>(Result<T, Vec<ValidationError>>);
#[juniper::graphql_object(
name = "UserResult",
)]
impl MutationResult<User> {
fn user(&self) -> Option<&User> {
self.0.as_ref().ok()
}
fn error(&self) -> Option<&Vec<ValidationError>> {
self.0.as_ref().err()
}
}
#[juniper::graphql_object(
name = "ForumPostResult",
)]
impl MutationResult<ForumPost> {
fn forum_post(&self) -> Option<&ForumPost> {
self.0.as_ref().ok()
}
fn error(&self) -> Option<&Vec<ValidationError>> {
self.0.as_ref().err()
}
}
# fn main() {}
```
Here, we've made a wrapper around `Result` and exposed some concrete
instantiations of `Result<T, E>` as distinct GraphQL objects. The reason we
needed the wrapper is of Rust's rules for when you can derive a trait - in this
case, both `Result` and Juniper's internal GraphQL trait are from third-party
sources.
Because we're using generics, we also need to specify a name for our
instantiated types. Even if Juniper _could_ figure out the name,
`MutationResult<User>` wouldn't be a valid GraphQL type name.

175
book/src/advanced/subscriptions.md
View file

@ -1,175 +0,0 @@
# Subscriptions
### How to achieve realtime data with GraphQL subscriptions
GraphQL subscriptions are a way to push data from the server to clients requesting real-time messages
from the server. Subscriptions are similar to queries in that they specify a set of fields to be delivered to the client,
but instead of immediately returning a single answer a result is sent every time a particular event happens on the
server.
In order to execute subscriptions you need a coordinator (that spawns connections)
and a GraphQL object that can be resolved into a stream--elements of which will then
be returned to the end user. The [`juniper_subscriptions`][juniper_subscriptions] crate
provides a default connection implementation. Currently subscriptions are only supported on the `master` branch. Add the following to your `Cargo.toml`:
```toml
[dependencies]
juniper = "0.16.0"
juniper_subscriptions = "0.17.0"
```
### Schema Definition
The `Subscription` is just a GraphQL object, similar to the query root and mutations object that you defined for the
operations in your [Schema][Schema]. For subscriptions all fields/operations should be async and should return a [Stream][Stream].
This example shows a subscription operation that returns two events, the strings `Hello` and `World!`
sequentially:
```rust
# extern crate futures;
# extern crate juniper;
# use std::pin::Pin;
# use futures::Stream;
# use juniper::{graphql_object, graphql_subscription, FieldError};
#
# #[derive(Clone)]
# pub struct Database;
# impl juniper::Context for Database {}
# pub struct Query;
# #[graphql_object(context = Database)]
# impl Query {
# fn hello_world() -> &'static str {
# "Hello World!"
# }
# }
pub struct Subscription;
type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
#[graphql_subscription(context = Database)]
impl Subscription {
async fn hello_world() -> StringStream {
let stream = futures::stream::iter(vec![
Ok(String::from("Hello")),
Ok(String::from("World!"))
]);
Box::pin(stream)
}
}
#
# fn main () {}
```
### Coordinator
Subscriptions require a bit more resources than regular queries and provide a great vector for DOS attacks. This can can bring down a server easily if not handled correctly. The [`SubscriptionCoordinator`][SubscriptionCoordinator] trait provides coordination logic to enable functionality like DOS attack mitigation and resource limits.
The [`SubscriptionCoordinator`][SubscriptionCoordinator] contains the schema and can keep track of opened connections, handle subscription
start and end, and maintain a global subscription id for each subscription. Each time a connection is established,
the [`SubscriptionCoordinator`][SubscriptionCoordinator] spawns a [`SubscriptionConnection`][SubscriptionConnection]. The [`SubscriptionConnection`][SubscriptionConnection] handles a single connection, providing resolver logic for a client stream as well as reconnection
and shutdown logic.
While you can implement [`SubscriptionCoordinator`][SubscriptionCoordinator] yourself, Juniper contains a simple and generic implementation called [`Coordinator`][Coordinator]. The `subscribe`
operation returns a [`Future`][Future] with an `Item` value of a `Result<Connection, GraphQLError>`,
where [`Connection`][Connection] is a `Stream` of values returned by the operation and [`GraphQLError`][GraphQLError] is the error when the subscription fails.
```rust
# #![allow(dead_code)]
# extern crate futures;
# extern crate juniper;
# extern crate juniper_subscriptions;
# extern crate serde_json;
# use juniper::{
# http::GraphQLRequest,
# graphql_object, graphql_subscription,
# DefaultScalarValue, EmptyMutation, FieldError,
# RootNode, SubscriptionCoordinator,
# };
# use juniper_subscriptions::Coordinator;
# use futures::{Stream, StreamExt};
# use std::pin::Pin;
#
# #[derive(Clone)]
# pub struct Database;
#
# impl juniper::Context for Database {}
#
# impl Database {
# fn new() -> Self {
# Self
# }
# }
#
# pub struct Query;
#
# #[graphql_object(context = Database)]
# impl Query {
# fn hello_world() -> &'static str {
# "Hello World!"
# }
# }
#
# pub struct Subscription;
#
# type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
#
# #[graphql_subscription(context = Database)]
# impl Subscription {
# async fn hello_world() -> StringStream {
# let stream =
# futures::stream::iter(vec![Ok(String::from("Hello")), Ok(String::from("World!"))]);
# Box::pin(stream)
# }
# }
type Schema = RootNode<'static, Query, EmptyMutation<Database>, Subscription>;
fn schema() -> Schema {
Schema::new(Query, EmptyMutation::new(), Subscription)
}
async fn run_subscription() {
let schema = schema();
let coordinator = Coordinator::new(schema);
let req: GraphQLRequest<DefaultScalarValue> = serde_json::from_str(
r#"{
"query": "subscription { helloWorld }"
}"#,
)
.unwrap();
let ctx = Database::new();
let mut conn = coordinator.subscribe(&req, &ctx).await.unwrap();
while let Some(result) = conn.next().await {
println!("{}", serde_json::to_string(&result).unwrap());
}
}
#
# fn main() { }
```
### Web Integration and Examples
Currently there is an example of subscriptions with [warp][warp], but it still in an alpha state.
GraphQL over [WS][WS] is not fully supported yet and is non-standard.
- [Warp Subscription Example](https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples/subscription.rs)
- [Small Example](https://github.com/graphql-rust/juniper/tree/master/juniper_subscriptions/examples/basic.rs)
[juniper_subscriptions]: https://github.com/graphql-rust/juniper/tree/master/juniper_subscriptions
[Stream]: https://docs.rs/futures/0.3.4/futures/stream/trait.Stream.html
<!-- TODO: Fix these links when the documentation for the `juniper_subscriptions` are defined in the docs. --->
[Coordinator]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Coordinator.html
[SubscriptionCoordinator]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionCoordinator.html
[Connection]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Connection.html
[SubscriptionConnection]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionConnection.html
<!--- --->
[Future]: https://docs.rs/futures/0.3.4/futures/future/trait.Future.html
[warp]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp
[WS]: https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
[GraphQLError]: https://docs.rs/juniper/0.14.2/juniper/enum.GraphQLError.html
[Schema]: ../schema/schemas_and_mutations.md

83
book/src/introduction.md Normal file
View file

@ -0,0 +1,83 @@
Introduction
============
> [GraphQL] is a query language for APIs and a runtime for fulfilling those queries with your existing data. [GraphQL] provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
[Juniper] is a library for creating [GraphQL] servers in [Rust]. Build type-safe and fast API servers with minimal boilerplate and configuration (we do try to make declaring and resolving [GraphQL] schemas as convenient as possible as [Rust] will allow).
[Juniper] doesn't include a web server itself, instead, it provides building blocks to make integration with existing web servers straightforward. It optionally provides a pre-built integration for some widely used web server frameworks in [Rust] ecosystem.
- [Cargo crate](https://crates.io/crates/juniper)
- [API reference][`juniper`]
## Features
[Juniper] supports the full GraphQL query language according to the [specification (October 2021)][GraphQL spec].
> **NOTE**: As an exception to other [GraphQL] libraries for other languages, [Juniper] builds non-`null` types by default. A field of type `Vec<Episode>` will be converted into `[Episode!]!`. The corresponding Rust type for a `null`able `[Episode]` would be `Option<Vec<Option<Episode>>>` instead.
## Integrations
### Types
[Juniper] provides out-of-the-box integration for some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature]:
- [`bigdecimal`]
- [`bson`]
- [`chrono`], [`chrono-tz`]
- [`rust_decimal`]
- [`time`]
- [`url`]
- [`uuid`]
### Web server frameworks
- [`actix-web`] ([`juniper_actix`] crate)
- [`axum`] ([`juniper_axum`] crate)
- [`hyper`] ([`juniper_hyper`] crate)
- [`rocket`] ([`juniper_rocket`] crate)
- [`warp`] ([`juniper_warp`] crate)
## API stability
[Juniper] has not reached 1.0 yet, thus some API instability should be expected.
[`actix-web`]: https://docs.rs/actix-web
[`axum`]: https://docs.rs/axum
[`bigdecimal`]: https://docs.rs/bigdecimal
[`bson`]: https://docs.rs/bson
[`chrono`]: https://docs.rs/chrono
[`chrono-tz`]: https://docs.rs/chrono-tz
[`juniper`]: https://docs.rs/juniper
[`juniper_actix`]: https://docs.rs/juniper_actix
[`juniper_axum`]: https://docs.rs/juniper_axum
[`juniper_hyper`]: https://docs.rs/juniper_hyper
[`juniper_rocket`]: https://docs.rs/juniper_rocket
[`juniper_warp`]: https://docs.rs/juniper_warp
[`hyper`]: https://docs.rs/hyper
[`rocket`]: https://docs.rs/rocket
[`rust_decimal`]: https://docs.rs/rust_decimal
[`time`]: https://docs.rs/time
[`url`]: https://docs.rs/url
[`uuid`]: https://docs.rs/uuid
[`warp`]: https://docs.rs/warp
[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
[GraphQL]: https://graphql.org
[GraphQL spec]: https://spec.graphql.org/October2021
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org

155
book/src/quickstart.md
View file

@ -1,8 +1,14 @@
# Quickstart
Quickstart
==========
This page will give you a short introduction to the concepts in [Juniper].
**[Juniper] follows a [code-first] approach to define a [GraphQL] schema.**
> **TIP**: For a [schema-first] approach, consider using a [`juniper-from-schema`] crate for generating a [`juniper`]-based code from a [schema] file.
This page will give you a short introduction to the concepts in Juniper.
Juniper follows a [code-first approach][schema_approach] to defining GraphQL schemas. If you would like to use a [schema-first approach][schema_approach] instead, consider [juniper-from-schema][] for generating code from a schema file.
## Installation
@ -11,22 +17,21 @@ Juniper follows a [code-first approach][schema_approach] to defining GraphQL sch
juniper = "0.16.0"
```
## Schema example
Exposing simple enums and structs as GraphQL is just a matter of adding a custom
derive attribute to them. Juniper includes support for basic Rust types that
naturally map to GraphQL features, such as `Option<T>`, `Vec<T>`, `Box<T>`,
`String`, `f64`, and `i32`, references, and slices.
For more advanced mappings, Juniper provides multiple macros to map your Rust
types to a GraphQL schema. The most important one is the
[graphql_object][graphql_object] procedural macro that is used for declaring an object with
resolvers, which you will use for the `Query` and `Mutation` roots.
## Schema
Exposing simple enums and structs as [GraphQL] types is just a matter of adding a custom [derive attribute] to them. [Juniper] includes support for basic [Rust] types that naturally map to [GraphQL] features, such as `Option<T>`, `Vec<T>`, `Box<T>`, `Arc<T>`, `String`, `f64`, `i32`, references, slices and arrays.
For more advanced mappings, [Juniper] provides multiple macros to map your [Rust] types to a [GraphQL schema][schema]. The most important one is the [`#[graphql_object]` attribute][2] that is used for declaring a [GraphQL object] with resolvers (typically used for declaring [`Query` and `Mutation` roots][1]).
```rust
# #![allow(unused_variables)]
# # ![allow(unused_variables)]
# extern crate juniper;
#
# use std::fmt::Display;
#
use juniper::{
graphql_object, EmptySubscription, FieldResult, GraphQLEnum,
GraphQLInputObject, GraphQLObject, ScalarValue,
@ -56,7 +61,6 @@ struct Human {
}
// There is also a custom derive for mapping GraphQL input objects.
#[derive(GraphQLInputObject)]
#[graphql(description = "A humanoid creature in the Star Wars universe")]
struct NewHuman {
@ -65,52 +69,58 @@ struct NewHuman {
home_planet: String,
}
// Now, we create our root Query and Mutation types with resolvers by using the
// object macro.
// Objects can have contexts that allow accessing shared state like a database
// pool.
// Now, we create our root `Query` and `Mutation` types with resolvers by using
// the `#[graphql_object]` attribute.
// Resolvers can have a context that allows accessing shared state like a
// database pool.
struct Context {
// Use your real database pool here.
pool: DatabasePool,
db: DatabasePool,
}
// To make our context usable by Juniper, we have to implement a marker trait.
// To make our `Context` usable by `juniper`, we have to implement a marker
// trait.
impl juniper::Context for Context {}
struct Query;
#[graphql_object(
// Here we specify the context type for the object.
// We need to do this in every type that
// needs access to the context.
context = Context,
)]
// Here we specify the context type for the object.
// We need to do this in every type that needs access to the `Context`.
#[graphql_object]
#[graphql(context = Context)]
impl Query {
fn apiVersion() -> &'static str {
// Note, that the field name will be automatically converted to the
// `camelCased` variant, just as GraphQL conventions imply.
fn api_version() -> &'static str {
"1.0"
}
// Arguments to resolvers can either be simple types or input objects.
// To gain access to the context, we specify a argument
// that is a reference to the Context type.
// Juniper automatically injects the correct context here.
fn human(context: &Context, id: String) -> FieldResult<Human> {
// Get a db connection.
let connection = context.pool.get_connection()?;
// Execute a db query.
fn human(
// Arguments to resolvers can either be simple scalar types, enums or
// input objects.
id: String,
// To gain access to the `Context`, we specify a `context`-named
// argument referring the correspondent `Context` type, and `juniper`
// will inject it automatically.
context: &Context,
) -> FieldResult<Human> {
// Get a `db` connection.
let conn = context.db.get_connection()?;
// Execute a `db` query.
// Note the use of `?` to propagate errors.
let human = connection.find_human(&id)?;
let human = conn.find_human(&id)?;
// Return the result.
Ok(human)
}
}
// Now, we do the same for our Mutation type.
// Now, we do the same for our `Mutation` type.
struct Mutation;
#[graphql_object(
#[graphql_object]
#[graphql(
context = Context,
// If we need to use `ScalarValue` parametrization explicitly somewhere
// in the object definition (like here in `FieldResult`), we could
@ -118,42 +128,48 @@ struct Mutation;
scalar = S: ScalarValue + Display,
)]
impl Mutation {
fn createHuman<S: ScalarValue + Display>(context: &Context, new_human: NewHuman) -> FieldResult<Human, S> {
let db = context.pool.get_connection().map_err(|e| e.map_scalar_value())?;
fn create_human<S: ScalarValue + Display>(
new_human: NewHuman,
context: &Context,
) -> FieldResult<Human, S> {
let db = context.db.get_connection().map_err(|e| e.map_scalar_value())?;
let human: Human = db.insert_human(&new_human).map_err(|e| e.map_scalar_value())?;
Ok(human)
}
}
// A root schema consists of a query, a mutation, and a subscription.
// Request queries can be executed against a RootNode.
// Root schema consists of a query, a mutation, and a subscription.
// Request queries can be executed against a `RootNode`.
type Schema = juniper::RootNode<'static, Query, Mutation, EmptySubscription<Context>>;
#
# fn main() {
# let _ = Schema::new(Query, Mutation, EmptySubscription::new());
# _ = Schema::new(Query, Mutation, EmptySubscription::new());
# }
```
We now have a very simple but functional schema for a GraphQL server!
Now we have a very simple but functional schema for a [GraphQL] server!
To actually serve the schema, see the guides for our various [server integrations](./servers/index.md).
To actually serve the [schema], see the guides for our various [server integrations](serve/index.md).
Juniper is a library that can be used in many contexts--it does not require a server and it does not have a dependency on a particular transport or serialization format. You can invoke the executor directly to get a result for a query:
## Executor
You can invoke `juniper::execute` directly to run a GraphQL query:
## Execution
[Juniper] is a library that can be used in many contexts: it doesn't require a server, nor it has a dependency on a particular transport or serialization format. You can invoke the `juniper::execute()` directly to get a result for a [GraphQL] query:
```rust
# // Only needed due to 2018 edition because the macro is not accessible.
# #[macro_use] extern crate juniper;
use juniper::{
graphql_object, EmptyMutation, EmptySubscription, FieldResult,
GraphQLEnum, Variables, graphql_value,
graphql_object, graphql_value, EmptyMutation, EmptySubscription,
GraphQLEnum, Variables,
};
#[derive(GraphQLEnum, Clone, Copy)]
enum Episode {
// Note, that the enum value will be automatically converted to the
// `SCREAMING_SNAKE_CASE` variant, just as GraphQL conventions imply.
NewHope,
Empire,
Jedi,
@ -166,22 +182,21 @@ impl juniper::Context for Ctx {}
struct Query;
#[graphql_object(context = Ctx)]
#[graphql_object]
#[graphql(context = Ctx)]
impl Query {
fn favoriteEpisode(context: &Ctx) -> FieldResult<Episode> {
Ok(context.0)
fn favorite_episode(context: &Ctx) -> Episode {
context.0
}
}
// A root schema consists of a query, a mutation, and a subscription.
// Request queries can be executed against a RootNode.
type Schema = juniper::RootNode<'static, Query, EmptyMutation<Ctx>, EmptySubscription<Ctx>>;
fn main() {
// Create a context object.
// Create a context.
let ctx = Ctx(Episode::NewHope);
// Run the executor.
// Run the execution.
let (res, _errors) = juniper::execute_sync(
"query { favoriteEpisode }",
None,
@ -190,20 +205,28 @@ fn main() {
&ctx,
).unwrap();
// Ensure the value matches.
assert_eq!(
res,
graphql_value!({
"favoriteEpisode": "NEW_HOPE",
})
}),
);
}
```
[juniper-from-schema]: https://github.com/davidpdrsn/juniper-from-schema
[schema_approach]: https://blog.logrocket.com/code-first-vs-schema-first-development-graphql/
[hyper]: servers/hyper.md
[warp]: servers/warp.md
[rocket]: servers/rocket.md
[tutorial]: ./tutorial.html
[graphql_object]: https://docs.rs/juniper/latest/juniper/macro.graphql_object.html
[`juniper`]: https://docs.rs/juniper
[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
[code-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#code-only
[derive attribute]: https://doc.rust-lang.org/stable/reference/attributes/derive.html#derive
[GraphQL]: https://graphql.org
[GraphQL object]: https://spec.graphql.org/October2021#sec-Objects
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[schema]: https://graphql.org/learn/schema
[schema-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#schema-first
[1]: https://spec.graphql.org/October2021#sec-Root-Operation-Types
[2]: https://docs.rs/juniper/latest/juniper/macro.graphql_object.html

185
book/src/schema/index.md Normal file
View file

@ -0,0 +1,185 @@
Schema
======
**[Juniper] follows a [code-first] approach to define a [GraphQL] schema.**
> **TIP**: For a [schema-first] approach, consider using a [`juniper-from-schema`] crate for generating a [`juniper`]-based code from a [schema] file.
[GraphQL schema][0] consists of three [object types][4]: a [query root][1], a [mutation root][2], and a [subscription root][3].
> The **query** root operation type must be provided and must be an [Object][4] type.
>
> The **mutation** root operation type is optional; if it is not provided, the service does not support mutations. If it is provided, it must be an [Object][4] type.
>
> Similarly, the **subscription** root operation type is also optional; if it is not provided, the service does not support subscriptions. If it is provided, it must be an [Object][4] type.
>
> The **query**, **mutation**, and **subscription** root types must all be different types if provided.
In [Juniper], the [`RootNode`] type represents a [schema][0]. When the [schema][0] is first created, [Juniper] will traverse the entire object graph and register all types it can find. This means that if we [define a GraphQL object](../types/objects/index.md) somewhere but never use or reference it, it won't be exposed in a [GraphQL schema][0].
Both [query][1] and [mutation][2] objects are regular [GraphQL objects][4], defined like [any other object in Juniper](../types/objects/index.md). The [mutation][2] and [subscription][3] objects, however, are optional, since [schemas][0] can be read-only and do not require [subscriptions][3].
> **TIP**: If [mutation][2]/[subscription][3] functionality is not needed, consider using the predefined [`EmptyMutation`]/[`EmptySubscription`] types for stubbing them in a [`RootNode`].
```rust
# extern crate juniper;
# use juniper::{
# graphql_object, EmptySubscription, FieldResult, GraphQLObject, RootNode,
# };
#
#[derive(GraphQLObject)]
struct User {
name: String,
}
struct Query;
#[graphql_object]
impl Query {
fn user_with_username(username: String) -> FieldResult<Option<User>> {
// Look up user in database...
# unimplemented!()
}
}
struct Mutation;
#[graphql_object]
impl Mutation {
fn sign_up_user(name: String, email: String) -> FieldResult<User> {
// Validate inputs and save user in database...
# unimplemented!()
}
}
type Schema = RootNode<'static, Query, Mutation, EmptySubscription>;
#
# fn main() {}
```
> **NOTE**: It's considered a [good practice][5] to name [query][1], [mutation][2], and [subscription][3] root types as `Query`, `Mutation`, and `Subscription` respectively.
The usage of [subscriptions][3] is a little different from the [mutation][2] and [query][1] [objects][4], so they are discussed in the [separate chapter](subscriptions.md).
## Export
Many tools in [GraphQL] ecosystem require a [schema] definition to operate on. With [Juniper] we can export our [GraphQL schema][0] defined in [Rust] code either represented in the [GraphQL schema language][6] or in [JSON].
### SDL (schema definition language)
To generate an [SDL (schema definition language)][6] representation of a [GraphQL schema][0] defined in [Rust] code, the [`as_sdl()` method][20] should be used for the direct extraction (requires enabling the `schema-language` [Juniper] feature):
```rust
# extern crate juniper;
# use juniper::{
# graphql_object, EmptyMutation, EmptySubscription, FieldResult, RootNode,
# };
#
struct Query;
#[graphql_object]
impl Query {
fn hello(&self) -> FieldResult<&str> {
Ok("hello world")
}
}
fn main() {
// Define our schema in Rust.
let schema = RootNode::new(
Query,
EmptyMutation::<()>::new(),
EmptySubscription::<()>::new(),
);
// Convert the Rust schema into the GraphQL SDL schema.
let result = schema.as_sdl();
let expected = "\
schema {
query: Query
}
type Query {
hello: String!
}
";
# #[cfg(not(target_os = "windows"))]
assert_eq!(result, expected);
}
```
### JSON
To export a [GraphQL schema][0] defined in [Rust] code as [JSON] (often referred to as `schema.json`), the specially crafted [introspection query][21] should be issued. [Juniper] provides a [convenience `introspect()` function][22] to [introspect](introspection.md) the entire [schema][0], which result can be serialized into [JSON]:
```rust
# extern crate juniper;
# extern crate serde_json;
# use juniper::{
# graphql_object, EmptyMutation, EmptySubscription, GraphQLObject,
# IntrospectionFormat, RootNode,
# };
#
#[derive(GraphQLObject)]
struct Example {
id: String,
}
struct Query;
#[graphql_object]
impl Query {
fn example(id: String) -> Example {
unimplemented!()
}
}
type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
fn main() {
// Run the built-in introspection query.
let (res, _errors) = juniper::introspect(
&Schema::new(Query, EmptyMutation::new(), EmptySubscription::new()),
&(),
IntrospectionFormat::default(),
).unwrap();
// Serialize the introspection result into JSON.
let json_result = serde_json::to_string_pretty(&res);
assert!(json_result.is_ok());
}
```
> **TIP**: We still can convert the generated [JSON] into a [GraphQL schema language][6] representation by using tools like [`graphql-json-to-sdl` command line utility][30].
[`EmptyMutation`]: https://docs.rs/juniper/latest/juniper/struct.EmptyMutation.html
[`EmptySubscription`]: https://docs.rs/juniper/latest/juniper/struct.EmptySubscription.html
[`juniper`]: https://docs.rs/juniper
[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
[`RootNode`]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html
[code-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#code-only
[schema-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#schema-first
[GraphQL]: https://graphql.org
[JSON]: https://www.json.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[schema]: https://graphql.org/learn/schema
[0]: https://spec.graphql.org/October2021#sec-Schema
[1]: https://spec.graphql.org/October2021#sel-FAHTRFCAACChCtpG
[2]: https://spec.graphql.org/October2021#sel-FAHTRHCAACCuE9yD
[3]: https://spec.graphql.org/October2021#sel-FAHTRJCAACC3EhsX
[4]: https://spec.graphql.org/October2021#sec-Objects
[5]: https://spec.graphql.org/October2021#sec-Root-Operation-Types.Default-Root-Operation-Type-Names
[6]: https://graphql.org/learn/schema#type-language
[20]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html#method.as_sdl
[21]: https://docs.rs/crate/juniper/latest/source/src/introspection/query.graphql
[22]: https://docs.rs/juniper/latest/juniper/fn.introspect.html
[30]: https://npmjs.com/package/graphql-json-to-sdl

83
book/src/schema/introspection.md Normal file
View file

@ -0,0 +1,83 @@
Introspection
=============
> The [schema introspection][1] system is accessible from the meta-fields `__schema` and `__type` which are accessible from the type of the root of a query operation.
> ```graphql
> __schema: __Schema!
> __type(name: String!): __Type
> ```
> Like all meta-fields, these are implicit and do not appear in the fields list in the root type of the query operation.
[GraphQL] provides [introspection][0], allowing to see what [queries][2], [mutations][3] and [subscriptions][4] a [GraphQL] server supports at runtime.
Because [introspection][0] queries are just regular [GraphQL queries][2], [Juniper] supports them natively. For example, to get all the names of the types supported, we could [execute][5] the following [query][2] against [Juniper]:
```graphql
{
__schema {
types {
name
}
}
}
```
## Disabling
> Disabling introspection in production is a widely debated topic, but we believe it’s one of the first things you can do to harden your GraphQL API in production.
[Some security requirements and considerations][10] may mandate to disable [GraphQL schema introspection][1] in production environments. In [Juniper] this can be achieved by using the [`RootNode::disable_introspection()`][9] method:
```rust
# extern crate juniper;
# use juniper::{
# graphql_object, graphql_vars, EmptyMutation, EmptySubscription, GraphQLError,
# RootNode,
# };
#
pub struct Query;
#[graphql_object]
impl Query {
fn some() -> bool {
true
}
}
type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
fn main() {
let schema = Schema::new(Query, EmptyMutation::new(), EmptySubscription::new())
.disable_introspection();
let query = "query { __schema { queryType { name } } }";
match juniper::execute_sync(query, None, &schema, &graphql_vars! {}, &()) {
Err(GraphQLError::ValidationError(errs)) => {
assert_eq!(
errs.first().unwrap().message(),
"GraphQL introspection is not allowed, but the operation contained `__schema`",
);
}
res => panic!("expected `ValidationError`, returned: {res:#?}"),
}
}
```
> **NOTE**: Attempt to execute an [introspection query][1] results in [validation][11] error, rather than [execution][5] error.
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[0]: https://spec.graphql.org/October2021#sec-Introspection
[1]: https://spec.graphql.org/October2021#sec-Schema-Introspection
[2]: https://spec.graphql.org/October2021#sel-GAFRJBABABF_jB
[3]: https://spec.graphql.org/October2021#sel-GAFRJDABABI5C
[4]: https://spec.graphql.org/October2021#sel-GAFRJFABABMvpN
[5]: https://spec.graphql.org/October2021#sec-Execution
[9]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html#method.disable_introspection
[10]: https://www.apollographql.com/blog/why-you-should-disable-graphql-introspection-in-production
[11]: https://spec.graphql.org/October2021#sec-Validation

119
book/src/schema/schemas_and_mutations.md
View file

@ -1,119 +0,0 @@
# Schemas
Juniper follows a [code-first approach][schema_approach] to defining GraphQL schemas. If you would like to use a [schema-first approach][schema_approach] instead, consider [juniper-from-schema][] for generating code from a schema file.
A schema consists of three types: a query object, a mutation object, and a subscription object.
These three define the root query fields, mutations and subscriptions of the schema, respectively.
The usage of subscriptions is a little different from the mutation and query objects, so there is a specific [section][section] that discusses them.
Both query and mutation objects are regular GraphQL objects, defined like any
other object in Juniper. The mutation and subscription objects, however, are optional since schemas
can be read-only and do not require subscriptions. If mutation/subscription functionality is not needed, consider using [EmptyMutation][EmptyMutation]/[EmptySubscription][EmptySubscription].
In Juniper, the `RootNode` type represents a schema. When the schema is first created,
Juniper will traverse the entire object graph
and register all types it can find. This means that if you define a GraphQL
object somewhere but never reference it, it will not be exposed in a schema.
## The query root
The query root is just a GraphQL object. You define it like any other GraphQL
object in Juniper, most commonly using the `graphql_object` proc macro:
```rust
# #![allow(unused_variables)]
# extern crate juniper;
# use juniper::{graphql_object, FieldResult, GraphQLObject};
# #[derive(GraphQLObject)] struct User { name: String }
struct Root;
#[graphql_object]
impl Root {
fn userWithUsername(username: String) -> FieldResult<Option<User>> {
// Look up user in database...
# unimplemented!()
}
}
#
# fn main() { }
```
## Mutations
Mutations are _also_ just GraphQL objects. Each mutation is a single field
that performs some mutating side-effect such as updating a database.
```rust
# #![allow(unused_variables)]
# extern crate juniper;
# use juniper::{graphql_object, FieldResult, GraphQLObject};
# #[derive(GraphQLObject)] struct User { name: String }
struct Mutations;
#[graphql_object]
impl Mutations {
fn signUpUser(name: String, email: String) -> FieldResult<User> {
// Validate inputs and save user in database...
# unimplemented!()
}
}
#
# fn main() { }
```
# Converting a Rust schema to the [GraphQL Schema Language][schema_language]
Many tools in the GraphQL ecosystem require the schema to be defined in the [GraphQL Schema Language][schema_language]. You can generate a [GraphQL Schema Language][schema_language] representation of your schema defined in Rust using the `schema-language` feature (on by default):
```rust
# extern crate juniper;
use juniper::{
graphql_object, EmptyMutation, EmptySubscription, FieldResult, RootNode,
};
struct Query;
#[graphql_object]
impl Query {
fn hello(&self) -> FieldResult<&str> {
Ok("hello world")
}
}
fn main() {
// Define our schema in Rust.
let schema = RootNode::new(
Query,
EmptyMutation::<()>::new(),
EmptySubscription::<()>::new(),
);
// Convert the Rust schema into the GraphQL Schema Definition Language.
let result = schema.as_sdl();
let expected = "\
schema {
query: Query
}
type Query {
hello: String!
}
";
# #[cfg(not(target_os = "windows"))]
assert_eq!(result, expected);
}
```
Note the `schema-language` feature may be turned off if you do not need this functionality to reduce dependencies and speed up
compile times.
[schema_language]: https://graphql.org/learn/schema/#type-language
[juniper-from-schema]: https://github.com/davidpdrsn/juniper-from-schema
[schema_approach]: https://blog.logrocket.com/code-first-vs-schema-first-development-graphql/
[section]: ../advanced/subscriptions.md
[EmptyMutation]: https://docs.rs/juniper/0.14.2/juniper/struct.EmptyMutation.html
<!--TODO: Fix This URL when the EmptySubscription become available in the Documentation -->
[EmptySubscription]: https://docs.rs/juniper/0.14.2/juniper/struct.EmptySubscription.html

176
book/src/schema/subscriptions.md Normal file
View file

@ -0,0 +1,176 @@
Subscriptions
=============
[GraphQL subscriptions][9] are a way to push data from a server to clients requesting real-time messages from a server. [Subscriptions][9] are similar to [queries][7] in that they specify a set of fields to be delivered to a client, but instead of immediately returning a single answer a result is sent every time a particular event happens on a server.
In order to execute [subscriptions][9] in [Juniper], we need a coordinator (spawning long-lived connections) and a [GraphQL object][4] with [fields][5] resolving into a [`Stream`] of elements which will then be returned to a client. The [`juniper_subscriptions` crate][30] provides a default implementation of these abstractions.
The [subscription root][3] is just a [GraphQL object][4], similar to the [query root][1] and [mutations root][2] that we define for operations in our [GraphQL schema][0]. For [subscriptions][9] all fields should be `async` and return a [`Stream`] of some [GraphQL type][6] values, rather than direct values.
```rust
# extern crate futures;
# extern crate juniper;
# use std::pin::Pin;
# use futures::Stream;
# use juniper::{graphql_object, graphql_subscription, FieldError};
#
# #[derive(Clone)]
# pub struct Database;
#
# impl juniper::Context for Database {}
#
# pub struct Query;
#
# #[graphql_object]
# #[graphql(context = Database)]
# impl Query {
# fn hello_world() -> &'static str {
# "Hello World!"
# }
# }
#
type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
pub struct Subscription;
#[graphql_subscription]
#[graphql(context = Database)]
impl Subscription {
// This subscription operation emits two values sequentially:
// the `String`s "Hello" and "World!".
async fn hello_world() -> StringStream {
let stream = futures::stream::iter([
Ok(String::from("Hello")),
Ok(String::from("World!")),
]);
Box::pin(stream)
}
}
#
# fn main () {}
```
## Coordinator
[GraphQL subscriptions][9] require a bit more resources than regular [queries][7] and provide a great vector for [DoS attacks][20]. This can can bring down a server easily if not handled correctly. The [`SubscriptionCoordinator` trait][`SubscriptionCoordinator`] provides coordination logic to enable functionality like [DoS attacks][20] mitigation and resource limits.
The [`SubscriptionCoordinator`] contains the [schema][0] and can keep track of opened connections, handle [subscription][9] start and end, and maintain a global ID for each [subscription][9]. Each time a connection is established, the [`SubscriptionCoordinator`] spawns a [32], which handles a single connection, providing resolver logic for a client stream as well as reconnection and shutdown logic.
While we can implement [`SubscriptionCoordinator`] ourselves, [Juniper] contains a simple and generic implementation called [`Coordinator`]. The `subscribe` method returns a [`Future`] resolving into a `Result<Connection, GraphQLError>`, where [`Connection`] is a [`Stream`] of [values][10] returned by the operation, and a [`GraphQLError`] is the error when the [subscription operation][9] fails.
```rust
# extern crate futures;
# extern crate juniper;
# extern crate juniper_subscriptions;
# extern crate serde_json;
# use std::pin::Pin;
# use futures::{Stream, StreamExt as _};
# use juniper::{
# http::GraphQLRequest,
# graphql_object, graphql_subscription,
# DefaultScalarValue, EmptyMutation, FieldError,
# RootNode, SubscriptionCoordinator,
# };
# use juniper_subscriptions::Coordinator;
#
# #[derive(Clone)]
# pub struct Database;
#
# impl juniper::Context for Database {}
#
# impl Database {
# fn new() -> Self {
# Self
# }
# }
#
# pub struct Query;
#
# #[graphql_object]
# #[graphql(context = Database)]
# impl Query {
# fn hello_world() -> &'static str {
# "Hello World!"
# }
# }
#
# type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
#
# pub struct Subscription;
#
# #[graphql_subscription]
# #[graphql(context = Database)]
# impl Subscription {
# async fn hello_world() -> StringStream {
# let stream = futures::stream::iter([
# Ok(String::from("Hello")),
# Ok(String::from("World!")),
# ]);
# Box::pin(stream)
# }
# }
#
type Schema = RootNode<'static, Query, EmptyMutation<Database>, Subscription>;
fn schema() -> Schema {
Schema::new(Query, EmptyMutation::new(), Subscription)
}
async fn run_subscription() {
let schema = schema();
let coordinator = Coordinator::new(schema);
let db = Database::new();
let req: GraphQLRequest<DefaultScalarValue> = serde_json::from_str(
r#"{
"query": "subscription { helloWorld }"
}"#,
).unwrap();
let mut conn = coordinator.subscribe(&req, &db).await.unwrap();
while let Some(result) = conn.next().await {
println!("{}", serde_json::to_string(&result).unwrap());
}
}
#
# fn main() {}
```
## WebSocket
For information about serving [GraphQL subscriptions][9] over [WebSocket], see the ["Serving" chapter](../serve/index.md#websocket).
[`Coordinator`]: https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Coordinator.html
[`Connection`]: https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Connection.html
[`Future`]: https://doc.rust-lang.org/stable/std/future/trait.Future.html
[`GraphQLError`]: https://docs.rs/juniper/latest/juniper/enum.GraphQLError.html
[`Stream`]: https://docs.rs/futures/latest/futures/stream/trait.Stream.html
[`SubscriptionCoordinator`]: https://docs.rs/juniper/latest/juniper/trait.SubscriptionCoordinator.html
[`SubscriptionConnection`]: https://docs.rs/juniper/latest/juniper/trait.SubscriptionConnection.html
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[WebSocket]: https://en.wikipedia.org/wiki/WebSocket
[0]: https://spec.graphql.org/October2021#sec-Schema
[1]: https://spec.graphql.org/October2021#sel-FAHTRFCAACChCtpG
[2]: https://spec.graphql.org/October2021#sel-FAHTRHCAACCuE9yD
[3]: https://spec.graphql.org/October2021#sel-FAHTRJCAACC3EhsX
[4]: https://spec.graphql.org/October2021#sec-Objects
[5]: https://spec.graphql.org/October2021#sec-Language.Fields
[6]: https://spec.graphql.org/October2021#sec-Types
[7]: https://spec.graphql.org/October2021#sec-Query
[8]: https://spec.graphql.org/October2021#sec-Mutation
[9]: https://spec.graphql.org/October2021#sec-Subscription
[10]: https://spec.graphql.org/October2021#sec-Values
[20]: https://en.wikipedia.org/wiki/Denial-of-service_attack
[30]: https://docs.rs/juniper_subscriptions

81
book/src/serve/batching.md Normal file
View file

@ -0,0 +1,81 @@
Batching
========
The [GraphQL] standard generally assumes that there will be one server request per each client operation to perform (such as a query or mutation). This is conceptually simple but potentially inefficient.
Some client libraries (such as [`apollo-link-batch-http`][1]) have the ability to batch operations in a single [HTTP] request to save network round-trips and potentially increase performance. There are [some tradeoffs][3], though, that should be considered before [batching operations][2].
[Juniper]'s [server integration crates](index.md#officially-supported) support [batching multiple operations][2] in a single [HTTP] request out-of-the-box via [JSON] arrays. This makes them compatible with client libraries that support [batch operations][2] without any special configuration.
> **NOTE**: If you use a custom server integration, it's **not a hard requirement** to support [batching][2], as it's not a part of the [official GraphQL specification][0].
Assuming an integration supports [operations batching][2], for the following GraphQL query:
```graphql
{
hero {
name
}
}
```
The [JSON] `data` to [POST] for an individual request would be:
```json
{
"query": "{hero{name}}"
}
```
And the response would be in the form:
```json
{
"data": {
"hero": {
"name": "R2-D2"
}
}
}
```
However, if we want to run the same query twice in a single [HTTP] request, the batched [JSON] `data` to [POST] would be:
```json
[
{
"query": "{hero{name}}"
},
{
"query": "{hero{name}}"
}
]
```
And then, the response would be in the following array form:
```json
[
{
"data": {
"hero": {
"name": "R2-D2"
}
}
},
{
"data": {
"hero": {
"name": "R2-D2"
}
}
}
]
```
[GraphQL]: https://graphql.org
[HTTP]: https://en.wikipedia.org/wiki/HTTP
[JSON]: https://www.json.org
[Juniper]: https://docs.rs/juniper
[POST]: https://en.wikipedia.org/wiki/POST_(HTTP)
[0]: https://spec.graphql.org/October2021
[1]: https://www.apollographql.com/docs/link/links/batch-http.html
[2]: https://www.apollographql.com/blog/batching-client-graphql-queries
[3]: https://www.apollographql.com/blog/batching-client-graphql-queries#what-are-the-tradeoffs-with-batching

69
book/src/serve/index.md Normal file
View file

@ -0,0 +1,69 @@
Serving
=======
Once we have built a [GraphQL schema][1], the next obvious step would be to serve it, so clients can interact with our [GraphQL] API. Usually, [GraphQL] APIs are served via [HTTP].
## Web server frameworks
Though the [`juniper`] crate doesn't provide a built-in [HTTP] server, the surrounding ecosystem does.
### Officially supported
[Juniper] officially supports the following widely used and adopted web server frameworks in [Rust] ecosystem:
- [`actix-web`] ([`juniper_actix`] crate)
- [`axum`] ([`juniper_axum`] crate)
- [`hyper`] ([`juniper_hyper`] crate)
- [`rocket`] ([`juniper_rocket`] crate)
- [`warp`] ([`juniper_warp`] crate)
See their API docs and usage examples (accessible from API docs) for further details of how they should be used.
> **NOTE**: All the officially supported web server framework integrations provide a simple and convenient way for exposing [GraphiQL] and/or [GraphQL Playground] with the [GraphQL schema][1] along. These powerful tools ease the development process by enabling you to explore and send client requests to the [GraphQL] API under development.
## WebSocket
> **NOTE**: [WebSocket] is a crucial part for serving [GraphQL subscriptions][2] over [HTTP].
There are two widely adopted protocols for serving [GraphQL] over [WebSocket]:
1. [Legacy `graphql-ws` GraphQL over WebSocket Protocol][ws-old], formerly used by [Apollo] and the [`subscriptions-transport-ws` npm package], and now being deprecated.
2. [New `graphql-transport-ws` GraphQL over WebSocket Protocol][ws-new], provided by the [`graphql-ws` npm package] and being used by [Apollo] as for now.
In the [Juniper] ecosystem, both implementations are provided by the [`juniper_graphql_ws`] crate. Most of the [officially supported web server framework integrations](#officially-supported) are able to serve a [GraphQL schema][1] over [WebSocket] (including [subscriptions][2]) and even support [auto-negotiation of the correct protocol based on the `Sec-Websocket-Protocol` HTTP header value][3]. See their API docs and usage examples (accessible from API docs) for further details of how to do so.
[`actix-web`]: https://docs.rs/actix-web
[`axum`]: https://docs.rs/axum
[`graphql-ws` npm package]: https://npmjs.com/package/graphql-ws
[`juniper`]: https://docs.rs/juniper
[`juniper_actix`]: https://docs.rs/juniper_actix
[`juniper_axum`]: https://docs.rs/juniper_axum
[`juniper_graphql_ws`]: https://docs.rs/juniper_graphql_ws
[`juniper_rocket`]: https://docs.rs/juniper_rocket
[`juniper_warp`]: https://docs.rs/juniper_warp
[`hyper`]: https://docs.rs/hyper
[`rocket`]: https://docs.rs/rocket
[`subscriptions-transport-ws` npm package]: https://npmjs.com/package/subscriptions-transport-ws
[`warp`]: https://docs.rs/warp
[Apollo]: https://www.apollographql.com
[GraphiQL]: https://github.com/graphql/graphiql
[GraphQL]: https://graphql.org
[GraphQL Playground]: https://github.com/prisma/graphql-playground
[HTTP]: https://en.wikipedia.org/wiki/HTTP
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[WebSocket]: https://en.wikipedia.org/wiki/WebSocket
[ws-new]: https://github.com/enisdenjo/graphql-ws/blob/v5.14.0/PROTOCOL.md
[ws-old]: https://github.com/apollographql/subscriptions-transport-ws/blob/v0.11.0/PROTOCOL.md
[1]: ../schema/index.md
[2]: ../schema/subscriptions.md
[3]: https://developer.mozilla.org/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols

28
book/src/servers/hyper.md
View file

@ -1,28 +0,0 @@
# Integrating with Hyper
[Hyper] is a fast HTTP implementation that many other Rust web frameworks
leverage. It offers asynchronous I/O via the tokio runtime and works on
Rust's stable channel.
Hyper is not a higher-level web framework and accordingly
does not include ergonomic features such as simple endpoint routing,
baked-in HTTP responses, or reusable middleware. For GraphQL, those aren't
large downsides as all POSTs and GETs usually go through a single endpoint with
a few clearly-defined response payloads.
Juniper's Hyper integration is contained in the [`juniper_hyper`][juniper_hyper] crate:
!FILENAME Cargo.toml
```toml
[dependencies]
juniper = "0.16.0"
juniper_hyper = "0.9.0"
```
Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL] handler.
[graphiql]: https://github.com/graphql/graphiql
[hyper]: https://hyper.rs/
[juniper_hyper]: https://github.com/graphql-rust/juniper/tree/master/juniper_hyper
[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_hyper/examples/hyper_server.rs

16
book/src/servers/index.md
View file

@ -1,16 +0,0 @@
# Adding A Server
To allow using Juniper with the HTTP server of your choice,
it does **not** come with a built in HTTP server.
To actually get a server up and running, there are multiple official and
third-party integration crates that will get you there.
- [Official Server Integrations](official.md)
- [Warp](warp.md)
- [Rocket](rocket.md)
- [Hyper](hyper.md)
- [Third Party Integrations](third-party.md)
- [Actix-Web](https://github.com/actix/examples/tree/master/graphql/juniper)
- [Finchers](https://github.com/finchers-rs/finchers-juniper)
- [Tsukuyomi](https://github.com/tsukuyomi-rs/tsukuyomi/tree/master/examples/juniper)

8
book/src/servers/official.md
View file

@ -1,8 +0,0 @@
# Official Server Integrations
Juniper provides official integration crates for several popular Rust server
libraries.
- [Warp](warp.md)
- [Rocket](rocket.md)
- [Hyper](hyper.md)

22
book/src/servers/rocket.md
View file

@ -1,22 +0,0 @@
# Integrating with Rocket
[Rocket] is a web framework for Rust that makes it simple to write fast web applications without sacrificing flexibility or type safety. All with minimal code. Rocket
does not work on Rust's stable channel and instead requires the nightly
channel.
Juniper's Rocket integration is contained in the [`juniper_rocket`][juniper_rocket] crate:
!FILENAME Cargo.toml
```toml
[dependencies]
juniper = "0.16.0"
juniper_rocket = "0.9.0"
```
Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL] handler.
[graphiql]: https://github.com/graphql/graphiql
[rocket]: https://rocket.rs/
[juniper_rocket]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket
[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_rocket/examples/simple.rs

5
book/src/servers/third-party.md
View file

@ -1,5 +0,0 @@
# Other Examples
These examples are not officially maintained by Juniper developers.
- [Actix Web](https://github.com/actix/examples/tree/HEAD/graphql/juniper) | [Actix Web (advanced)](https://github.com/actix/examples/tree/HEAD/graphql/juniper-advanced)

24
book/src/servers/warp.md
View file

@ -1,24 +0,0 @@
# Integrating with Warp
[Warp] is a super-easy, composable, web server framework for warp speeds.
The fundamental building block of warp is the Filter: they can be combined and composed to express rich requirements on requests. Warp is built on [Hyper] and works on
Rust's stable channel.
Juniper's Warp integration is contained in the [`juniper_warp`][juniper_warp] crate:
!FILENAME Cargo.toml
```toml
[dependencies]
juniper = "0.16.0"
juniper_warp = "0.8.0"
```
Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL]/[GraphQL Playground] handlers with subscriptions support.
[GraphiQL]: https://github.com/graphql/graphiql
[GraphQL Playground]: https://github.com/prisma/graphql-playground
[hyper]: https://hyper.rs/
[warp]: https://crates.io/crates/warp
[juniper_warp]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp
[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_warp/examples/subscription.rs

156
book/src/types/enums.md
View file

@ -1,73 +1,151 @@
# Enums
Enums
=====
Enums in GraphQL are string constants grouped together to represent a set of
possible values. Simple Rust enums can be converted to GraphQL enums by using a
custom derive attribute:
> [GraphQL enum][0] types, like [scalar][1] types, also represent leaf values in a GraphQL type system. However [enum][0] types describe the set of possible values.
>
> [Enums][0] are not references for a numeric value, but are unique values in their own right. They may serialize as a string: the name of the represented value.
With [Juniper] a [GraphQL enum][0] may be defined by using the [`#[derive(GraphQLEnum)]`][2] attribute on a [Rust enum][3] as long as its variants do not have any fields:
```rust
# extern crate juniper;
#[derive(juniper::GraphQLEnum)]
# use juniper::GraphQLEnum;
#
#[derive(GraphQLEnum)]
enum Episode {
NewHope,
Empire,
Jedi,
}
#
# fn main() {}
```
Juniper converts all enum variants to uppercase, so the corresponding string
values for these variants are `NEWHOPE`, `EMPIRE`, and `JEDI`, respectively. If
you want to override this, you can use the `graphql` attribute, similar to how
it works when [defining objects](objects/defining_objects.md):
### Renaming
By default, [enum][3] variants are converted from [Rust]'s standard `PascalCase` naming convention into [GraphQL]'s `SCREAMING_SNAKE_CASE` convention:
```rust
# extern crate juniper;
#[derive(juniper::GraphQLEnum)]
# use juniper::GraphQLEnum;
#
#[derive(GraphQLEnum)]
enum Episode {
#[graphql(name="NEW_HOPE")]
NewHope,
NewHope, // exposed as `NEW_HOPE` in GraphQL schema
Empire, // exposed as `EMPIRE` in GraphQL schema
Jedi, // exposed as `JEDI` in GraphQL schema
}
#
# fn main() {}
```
We can override the name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::GraphQLEnum;
#
#[derive(GraphQLEnum)]
#[graphql(name = "WrongEpisode")] // now exposed as `WrongEpisode` in GraphQL schema
enum Episode {
#[graphql(name = "LAST_HOPE")]
NewHope, // exposed as `LAST_HOPE` in GraphQL schema
Empire,
Jedi,
}
#
# fn main() {}
```
## Documentation and deprecation
Just like when defining objects, the type itself can be renamed and documented,
while individual enum variants can be renamed, documented, and deprecated:
Or provide a different renaming policy for all the [enum][3] variants:
```rust
# extern crate juniper;
#[derive(juniper::GraphQLEnum)]
#[graphql(name="Episode", description="An episode of Star Wars")]
# use juniper::GraphQLEnum;
#
#[derive(GraphQLEnum)]
#[graphql(rename_all = "none")] // disables any renaming
enum Episode {
NewHope, // exposed as `NewHope` in GraphQL schema
Empire, // exposed as `Empire` in GraphQL schema
Jedi, // exposed as `Jedi` in GraphQL schema
}
#
# fn main() {}
```
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
### Documentation and deprecation
Just like when [defining GraphQL objects](objects/index.md#documentation), the [GraphQL enum][0] type and its values could be [documented][4] and [deprecated][5] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
```rust
# extern crate juniper;
# use juniper::GraphQLEnum;
#
/// This doc comment is visible only in Rust API docs.
#[derive(GraphQLEnum)]
#[graphql(description = "An episode of Star Wars")]
enum StarWarsEpisode {
#[graphql(deprecated="We don't really talk about this one")]
ThePhantomMenace,
#[graphql(name="NEW_HOPE")]
/// This doc comment is visible only in Rust API docs.
#[graphql(description = "This description is visible only in GraphQL schema.")]
NewHope,
#[graphql(description="Arguably the best one in the trilogy")]
/// This doc comment is visible only in Rust API docs.
#[graphql(desc = "Arguably the best one in the trilogy.")]
// ^^^^ shortcut for a `description` argument
Empire,
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
Jedi,
#[deprecated(note = "Only visible in Rust.")]
#[graphql(deprecated = "We don't really talk about this one.")]
// ^^^^^^^^^^ takes precedence over Rust's `#[deprecated]` attribute
ThePhantomMenace, // has no description in GraphQL schema
}
#
# fn main() {}
```
> **NOTE**: Only [GraphQL object][6]/[interface][7] fields and [GraphQL enum][0] values can be [deprecated][5].
### Ignoring
By default, all [enum][3] variants are included in the generated [GraphQL enum][0] type as values. To prevent including a specific variant, annotate it with the `#[graphql(ignore)]` attribute:
```rust
# #![allow(dead_code)]
# extern crate juniper;
# use juniper::GraphQLEnum;
#
#[derive(GraphQLEnum)]
enum Episode<T> {
NewHope,
Empire,
Jedi,
#[graphql(ignore)]
Legends(T), // cannot be queried from GraphQL
#[graphql(skip)]
// ^^^^ alternative naming, up to your preference
CloneWars(T), // cannot be queried from GraphQL
}
#
# fn main() {}
```
## Supported Macro Attributes (Derive)
> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLEnum)]`][2] attribute.
| Name of Attribute | Container Support | Field Support |
|-------------------|:-----------------:|:----------------:|
| context | ✔ | ? |
| deprecated | ✔ | ✔ |
| description | ✔ | ✔ |
| interfaces | ? | ✘ |
| name | ✔ | ✔ |
| noasync | ✔ | ? |
| scalar | ✘ | ? |
| skip | ? | ✘ |
| ✔: supported | ✘: not supported | ?: not available |
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Enums
[1]: https://spec.graphql.org/October2021#sec-Scalars
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLEnum.html
[3]: https://doc.rust-lang.org/reference/items/enumerations.html
[4]: https://spec.graphql.org/October2021#sec-Descriptions
[5]: https://spec.graphql.org/October2021#sec--deprecated
[6]: https://spec.graphql.org/October2021#sec-Objects
[7]: https://spec.graphql.org/October2021#sec-Interfaces
[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute

40
book/src/types/index.md
View file

@ -1,20 +1,28 @@
# Type System
Type system
===========
Most of the work in working with juniper consists of mapping the
GraphQL type system to the Rust types your application uses.
Most of the work in working with [Juniper] consists of mapping the [GraphQL type system][0] to the [Rust] types our application uses.
Juniper provides some convenient abstractions that try to make this process
as painless as possible.
[Juniper] provides some convenient abstractions making this process as painless as possible.
Find out more in the individual chapters below.
Find out more in the individual chapters below:
- [Objects](objects/index.md)
- [Complex fields](objects/complex_fields.md)
- [Context](objects/Context.md)
- [Error handling](objects/error/index.md)
- [Field errors](objects/error/field.md)
- [Schema errors](objects/error/schema.md)
- [Generics](objects/generics.md)
- [Interfaces](interfaces.md)
- [Unions](unions.md)
- [Enums](enums.md)
- [Input objects](input_objects.md)
- [Scalars](scalars.md)
- [Defining objects](objects/defining_objects.md)
- [Complex fields](objects/complex_fields.md)
- [Using contexts](objects/using_contexts.md)
- [Error handling](objects/error_handling.md)
- [Other types](other-index.md)
- [Enums](enums.md)
- [Interfaces](interfaces.md)
- [Input objects](input_objects.md)
- [Scalars](scalars.md)
- [Unions](unions.md)
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Type-System

169
book/src/types/input_objects.md
View file

@ -1,62 +1,163 @@
# Input objects
Input objects
=============
Input objects are complex data structures that can be used as arguments to
GraphQL fields. In Juniper, you can define input objects using a custom derive
attribute, similar to simple objects and enums:
> [Fields][4] may accept [arguments][5] to configure their behavior. These inputs are often [scalars][12] or [enums][10], but they sometimes need to represent more complex values.
>
> A [GraphQL input object][0] defines a set of input fields; the input fields are either [scalars][12], [enums][10], or other [input objects][0]. This allows [arguments][5] to accept arbitrarily complex structs.
In [Juniper], defining a [GraphQL input object][0] is quite straightforward and similar to how [trivial GraphQL objects are defined](objects/index.md) - by using the [`#[derive(GraphQLInputObject)]` attribute][2] on a [Rust struct][struct]:
```rust
# #![allow(unused_variables)]
# extern crate juniper;
#[derive(juniper::GraphQLInputObject)]
# use juniper::{graphql_object, GraphQLInputObject, GraphQLObject};
#
#[derive(GraphQLInputObject)]
struct Coordinate {
latitude: f64,
longitude: f64
}
struct Root;
# #[derive(juniper::GraphQLObject)] struct User { name: String }
# #[derive(GraphQLObject)] struct User { name: String }
#[juniper::graphql_object]
#[graphql_object]
impl Root {
fn users_at_location(coordinate: Coordinate, radius: f64) -> Vec<User> {
// Send coordinate to database
// ...
# unimplemented!()
# unimplemented!()
}
}
#
# fn main() {}
```
## Documentation and renaming
Just like the [other](objects/defining_objects.md) [derives](enums.md), you can rename
and add documentation to both the type and the fields:
### Renaming
Just as with [defining GraphQL objects](objects/index.md#renaming), by default [struct] fields are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
```rust
# #![allow(unused_variables)]
# extern crate juniper;
#[derive(juniper::GraphQLInputObject)]
#[graphql(name="Coordinate", description="A position on the globe")]
struct WorldCoordinate {
#[graphql(name="lat", description="The latitude")]
latitude: f64,
#[graphql(name="long", description="The longitude")]
longitude: f64
# use juniper::GraphQLInputObject;
#
#[derive(GraphQLInputObject)]
struct Person {
first_name: String, // exposed as `firstName` in GraphQL schema
last_name: String, // exposed as `lastName` in GraphQL schema
}
struct Root;
# #[derive(juniper::GraphQLObject)] struct User { name: String }
#[juniper::graphql_object]
impl Root {
fn users_at_location(coordinate: WorldCoordinate, radius: f64) -> Vec<User> {
// Send coordinate to database
// ...
# unimplemented!()
}
}
#
# fn main() {}
```
We can override the name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::GraphQLInputObject;
#
#[derive(GraphQLInputObject)]
#[graphql(name = "WebPerson")] // now exposed as `WebPerson` in GraphQL schema
struct Person {
name: String,
age: i32,
#[graphql(name = "websiteURL")]
website_url: Option<String>, // now exposed as `websiteURL` in GraphQL schema
}
#
# fn main() {}
```
Or provide a different renaming policy for all the [struct] fields:
```rust
# extern crate juniper;
# use juniper::GraphQLInputObject;
#
#[derive(GraphQLInputObject)]
#[graphql(rename_all = "none")] // disables any renaming
struct Person {
name: String,
age: i32,
website_url: Option<String>, // exposed as `website_url` in GraphQL schema
}
#
# fn main() {}
```
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
### Documentation
Similarly, [GraphQL descriptions][7] may be provided by either using [Rust doc comments][6] or with the `#[graphql(description = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::GraphQLInputObject;
#
/// This doc comment is visible only in Rust API docs.
#[derive(GraphQLInputObject)]
#[graphql(description = "This description is visible only in GraphQL schema.")]
struct Person {
/// This doc comment is visible only in Rust API docs.
#[graphql(desc = "This description is visible only in GraphQL schema.")]
// ^^^^ shortcut for a `description` argument
name: String,
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
age: i32,
}
#
# fn main() {}
```
> **NOTE**: As of [October 2021 GraphQL specification][spec], [GraphQL input object][0]'s fields **cannot be** [deprecated][9].
### Ignoring
By default, all [struct] fields are included into the generated [GraphQL input object][0] type. To prevent inclusion of a specific field annotate it with the `#[graphql(ignore)]` attribute:
> **WARNING**: Ignored fields must either implement `Default` or be annotated with the `#[graphql(default = <expression>)]` argument.
```rust
# extern crate juniper;
# use juniper::GraphQLInputObject;
#
enum System {
Cartesian,
}
#[derive(GraphQLInputObject)]
struct Point2D {
x: f64,
y: f64,
#[graphql(ignore, default = System::Cartesian)]
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^
// This attribute is required, as we need to be able to construct
// a `Point2D` value from the `{ x: 0.0, y: 0.0 }` GraphQL input value,
// received from client-side.
system: System,
// `Default::default()` value is used, if no
// `#[graphql(default = <expression>)]` is specified.
#[graphql(skip)]
// ^^^^ alternative naming, up to your preference
shift: f64,
}
#
# fn main() {}
```
> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLInputObject)]`][2] attribute.
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[struct]: https://doc.rust-lang.org/reference/items/structs.html
[spec]: https://spec.graphql.org/October2021
[0]: https://spec.graphql.org/October2021#sec-Input-Objects
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLInputObject.html
[4]: https://spec.graphql.org/October2021#sec-Language.Fields
[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
[7]: https://spec.graphql.org/October2021#sec-Descriptions
[9]: https://spec.graphql.org/October2021#sec--deprecated
[10]: https://spec.graphql.org/October2021#sec-Enums
[12]: https://spec.graphql.org/October2021#sec-Scalars

637
book/src/types/interfaces.md
View file

@ -1,76 +1,45 @@
Interfaces
==========
[GraphQL interfaces][1] map well to interfaces known from common object-oriented languages such as Java or C#, but Rust, unfortunately, has no concept that maps perfectly to them. The nearest analogue of [GraphQL interfaces][1] are Rust traits, and the main difference is that in GraphQL an [interface type][1] serves both as an _abstraction_ and a _boxed value (downcastable to concrete implementers)_, while in Rust, a trait is an _abstraction only_ and _to represent such a boxed value a separate type is required_, like enum or trait object, because Rust trait doesn't represent a type itself, and so can have no values. This difference imposes some unintuitive and non-obvious corner cases when we try to express [GraphQL interfaces][1] in Rust, but on the other hand gives you full control over which type is backing your interface, and how it's resolved.
> [GraphQL interfaces][0] represent a list of named [fields][4] and their [arguments][5]. [GraphQL objects][10] and [interfaces][0] can then implement these [interfaces][0] which requires that the implementing type will define all [fields][4] defined by those [interfaces][0].
For implementing [GraphQL interfaces][1] Juniper provides the `#[graphql_interface]` macro.
[GraphQL interfaces][0] map well to interfaces known from common object-oriented languages such as Java or C#, but [Rust], unfortunately, has no concept that maps perfectly to them. The nearest analogue of [GraphQL interfaces][0] are [Rust traits][20], but the main difference is that in [GraphQL] an [interface type][0] serves both as an _abstraction_ and a _boxed value (dispatchable to concrete implementers)_, while in [Rust], a [trait][20] is an _abstraction only_, and _to represent such a boxed value a separate type is required_, like a [trait object][21] or an [enum][22] consisting of implementer types, because [Rust trait][20] doesn't represent a type itself, and so, can have no values.
Another notable difference is that [GraphQL interfaces][0] are more like [structurally-typed][30] contracts: they _only declare a list of [fields][4]_ a [GraphQL] type should already have. [Rust traits][20], on the other hand, are [type classes][31], which don't really care about existing methods, but, rather, _require to provide implementations for required methods_ despite the fact whether the type already has such methods or not. This difference makes the [trait implementation][23] not a good fit for expressing a [GraphQL interface][0] implementation, because _we don't really need to implement any [fields][4]_, the [GraphQL] type implementing a [GraphQL interface][0] has those [fields][4] already. _We only need to check that [fields'][4] signatures match_.
That's why [Juniper] takes the following approach to represent [GraphQL interfaces][0], which consists of two parts:
1. Either a [struct][24], or a [trait][20] (in case [fields][4] have [arguments][5]), which acts only as a blueprint describing the required list of [fields][4], and is not used in runtime at all.
2. An auto-generated [enum][22], representing a dispatchable value-type for the [GraphQL interfaces][0], which may be referred and returned by other [fields][4].
## Traits
Defining a trait is mandatory for defining a [GraphQL interface][1], because this is the _obvious_ way we describe an _abstraction_ in Rust. All [interface][1] fields are defined as computed ones via trait methods.
This may be done by using either the [`#[graphql_interface]` attribute][3] or the [`#[derive(GraphQLInterface)]`][2]:
```rust
# extern crate juniper;
use juniper::graphql_interface;
# use juniper::{graphql_interface, GraphQLInterface, GraphQLObject};
#
// By default a `CharacterValue` enum is generated by macro to represent
// values of this GraphQL interface.
#[derive(GraphQLInterface)]
#[graphql(for = Human)] // enumerating all implementers is mandatory
struct Character {
id: String,
}
// Using a trait to describe the required fields is fine too.
#[graphql_interface]
trait Character {
fn id(&self) -> &str;
}
#
# fn main() {}
```
However, to return values of such [interface][1], we should provide its implementers and the Rust type representing a _boxed value of this trait_. The last one can be represented in two flavors: enum and [trait object][2].
### Enum values (default)
By default, Juniper generates an enum representing the values of the defined [GraphQL interface][1], and names it straightforwardly, `{Interface}Value`.
```rust
# extern crate juniper;
use juniper::{graphql_interface, GraphQLObject};
#[graphql_interface(for = [Human, Droid])] // enumerating all implementers is mandatory
trait Character {
fn id(&self) -> &str;
#[graphql(enum = HasHomeEnum, for = Human)]
// ^^^^ the generated value-type enum can be renamed, if required
trait HasHome {
fn home_planet(&self) -> &str;
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue)] // notice enum name, NOT trait name
#[graphql(impl = [CharacterValue, HasHomeEnum])]
// ^^^^^^^^^^^^^^ ^^^^^^^^^^^
// Notice the enum type names, neither the trait name nor the struct name
// is used to refer the GraphQL interface.
struct Human {
id: String,
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue)]
struct Droid {
id: String,
}
#
# fn main() {}
```
Also, enum name can be specified explicitly, if desired.
```rust
# extern crate juniper;
use juniper::{graphql_interface, GraphQLObject};
#[graphql_interface(enum = CharacterInterface, for = Human)]
trait Character {
fn id(&self) -> &str;
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterInterface)]
struct Human {
id: String,
home_planet: String,
id: String, // also resolves `Character.id` field
home_planet: String, // also resolves `HasHome.homePlanet` field
}
#
# fn main() {}
@ -79,18 +48,19 @@ struct Human {
### Interfaces implementing other interfaces
GraphQL allows implementing interfaces on other interfaces in addition to objects.
[GraphQL] allows implementing [interfaces][0] on other [interfaces][0] in addition to [objects][10]:
```rust
# extern crate juniper;
use juniper::{graphql_interface, graphql_object, ID};
#[graphql_interface(for = [HumanValue, Luke])]
# use juniper::{graphql_object, GraphQLInterface, ID};
#
#[derive(GraphQLInterface)]
#[graphql(for = [HumanValue, Luke])]
struct Node {
id: ID,
}
#[graphql_interface(impl = NodeValue, for = Luke)]
#[derive(GraphQLInterface)]
#[graphql(impl = NodeValue, for = Luke)]
struct Human {
id: ID,
home_planet: String,
@ -100,15 +70,16 @@ struct Luke {
id: ID,
}
#[graphql_object(impl = [HumanValue, NodeValue])]
#[graphql_object]
#[graphql(impl = [HumanValue, NodeValue])]
impl Luke {
fn id(&self) -> &ID {
&self.id
}
// As `String` and `&str` aren't distinguished by
// GraphQL spec, you can use them interchangeably.
// Same is applied for `Cow<'a, str>`.
// As `String` and `&str` aren't distinguished by GraphQL spec and
// represent the same `!String` GraphQL scalar, we can use them
// interchangeably. The same is applied for `Cow<'a, str>`.
// ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
fn home_planet() -> &'static str {
"Tatooine"
@ -118,78 +89,84 @@ impl Luke {
# fn main() {}
```
> __NOTE:__ Every interface has to specify all other interfaces/objects it implements or implemented for. Missing one of `for = ` or `impl = ` attributes is a compile-time error.
```compile_fail
# extern crate juniper;
use juniper::{graphql_interface, GraphQLObject};
#[derive(GraphQLObject)]
pub struct ObjA {
id: String,
}
#[graphql_interface(for = ObjA)]
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at
// 'Failed to implement interface `Character` on `ObjA`: missing interface reference in implementer's `impl` attribute.'
struct Character {
id: String,
}
fn main() {}
```
> **NOTE**: Every [interface][0] has to specify all other [interfaces][0]/[objects][0] it implements or implemented for. Missing one of `for = ` or `impl = ` attribute arguments is a **compile-time error**.
> ```rust,compile_fail
> # extern crate juniper;
> # use juniper::{GraphQLInterface, GraphQLObject};
> #
> #[derive(GraphQLObject)]
> pub struct ObjA {
> id: String,
> }
>
> #[derive(GraphQLInterface)]
> #[graphql(for = ObjA)]
> // ^^^^^^^^^^ the evaluated program panicked at
> // 'Failed to implement interface `Character` on `ObjA`: missing interface
> // reference in implementer's `impl` attribute.'
> struct Character {
> id: String,
> }
> #
> # fn main() {}
> ```
### GraphQL subtyping and additional `null`able fields
### Subtyping and additional `null`able arguments
GraphQL allows implementers (both objects and other interfaces) to return "subtypes" instead of an original value. Basically, this allows you to impose additional bounds on the implementation.
[GraphQL] allows implementers (both [objects][10] and other [interfaces][0]) to return "subtypes" instead of an original value. Basically, this allows to impose additional bounds on the implementation.
Valid "subtypes" are:
- interface implementer instead of an interface itself:
- [interface][0] implementer instead of an [interface][0] itself:
- `I implements T` in place of a `T`;
- `Vec<I implements T>` in place of a `Vec<T>`.
- non-null value in place of a nullable:
- [non-`null`][6] value in place of a `null`able:
- `T` in place of a `Option<T>`;
- `Vec<T>` in place of a `Vec<Option<T>>`.
These rules are recursively applied, so `Vec<Vec<I implements T>>` is a valid "subtype" of a `Option<Vec<Option<Vec<Option<T>>>>>`.
Also, GraphQL allows implementers to add `null`able fields, which aren't present on an original interface.
Also, [GraphQL] allows implementers to add `null`able [field arguments][5], which aren't present on an original interface.
```rust
# extern crate juniper;
use juniper::{graphql_interface, graphql_object, ID};
#[graphql_interface(for = [HumanValue, Luke])]
# use juniper::{graphql_interface, graphql_object, GraphQLInterface, ID};
#
#[derive(GraphQLInterface)]
#[graphql(for = [HumanValue, Luke])]
struct Node {
id: ID,
}
#[graphql_interface(for = HumanConnectionValue)]
#[derive(GraphQLInterface)]
#[graphql(for = HumanConnectionValue)]
struct Connection {
nodes: Vec<NodeValue>,
}
#[graphql_interface(impl = NodeValue, for = Luke)]
#[derive(GraphQLInterface)]
#[graphql(impl = NodeValue, for = Luke)]
struct Human {
id: ID,
home_planet: String,
}
#[graphql_interface(impl = ConnectionValue)]
#[derive(GraphQLInterface)]
#[graphql(impl = ConnectionValue)]
struct HumanConnection {
nodes: Vec<HumanValue>,
// ^^^^^^^^^^ notice not `NodeValue`
// This can happen, because every `Human` is a `Node` too, so we are just
// imposing additional bounds, which still can be resolved with
// `... on Connection { nodes }`.
// This can happen, because every `Human` is a `Node` too, so we just
// impose additional bounds, which still can be resolved with
// `... on Connection { nodes }` syntax.
}
struct Luke {
id: ID,
}
#[graphql_object(impl = [HumanValue, NodeValue])]
#[graphql_object]
#[graphql(impl = [HumanValue, NodeValue])]
impl Luke {
fn id(&self) -> &ID {
&self.id
@ -197,13 +174,13 @@ impl Luke {
fn home_planet(language: Option<String>) -> &'static str {
// ^^^^^^^^^^^^^^
// Notice additional `null`able field, which is missing on `Human`.
// Resolving `...on Human { homePlanet }` will provide `None` for this
// argument.
// Notice additional `null`able field argument, which is missing on
// `Human`. Resolving `...on Human { homePlanet }` will provide `None`
// for this argument (default argument value).
match language.as_deref() {
None | Some("en") => "Tatooine",
Some("ko") => "타투인",
_ => todo!(),
_ => unimplemented!(),
}
}
}
@ -211,271 +188,229 @@ impl Luke {
# fn main() {}
```
Violating GraphQL "subtyping" or additional nullable field rules is a compile-time error.
> **NOTE**: Violating [GraphQL] "subtyping" or additional `null`able [argument][5] rules is a **compile-time error**.
>
> ```rust,compile_fail
> # extern crate juniper;
> # use juniper::{graphql_object, GraphQLInterface};
> #
> pub struct ObjA {
> id: String,
> }
>
> #[graphql_object]
> #[graphql(impl = CharacterValue)]
> impl ObjA {
> fn id(&self, is_present: bool) -> &str {
> // ^^ the evaluated program panicked at
> // 'Failed to implement interface `Character` on `ObjA`: Field `id`: Argument
> // `isPresent` of type `Boolean!` isn't present on the interface and so has
> // to be nullable.'
> is_present.then_some(&self.id).unwrap_or("missing")
> }
> }
>
> #[derive(GraphQLInterface)]
> #[graphql(for = ObjA)]
> struct Character {
> id: String,
> }
> #
> # fn main() {}
> ```
>
> ```rust,compile_fail
> # extern crate juniper;
> # use juniper::{GraphQLInterface, GraphQLObject};
> #
> #[derive(GraphQLObject)]
> #[graphql(impl = CharacterValue)]
> pub struct ObjA {
> id: Vec<String>,
> // ^^ the evaluated program panicked at
> // 'Failed to implement interface `Character` on `ObjA`: Field `id`:
> // implementer is expected to return a subtype of interface's return
> // object: `[String!]!` is not a subtype of `String!`.'
> }
>
> #[derive(GraphQLInterface)]
> #[graphql(for = ObjA)]
> struct Character {
> id: String,
> }
> #
> # fn main() {}
> ```
```compile_fail
### Default arguments
[Similarly to GraphQL object fields](objects/complex_fields.md#default-arguments), [GraphQL arguments][4] of [interfaces][0] are able to have default values, though [Rust] doesn't have such notion:
```rust
# extern crate juniper;
use juniper::{graphql_interface, graphql_object};
# use juniper::graphql_interface;
#
#[graphql_interface]
trait Person {
fn field1(
// Default value can be any valid Rust expression, including a function
// call, etc.
#[graphql(default = true)]
arg1: bool,
// If default expression is not specified, then the `Default::default()`
// value is used.
#[graphql(default)]
arg2: i32,
) -> String;
}
#
# fn main() {}
```
pub struct ObjA {
id: String,
### Renaming
Just as with [defining GraphQL objects](objects/index.md#renaming), by default, [fields][4] are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
We can override the name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::{graphql_interface, GraphQLInterface};
#
#[derive(GraphQLInterface)]
#[graphql(name = "CharacterInterface")]
struct Character { // exposed as `CharacterInterface` in GraphQL schema
#[graphql(name = "myCustomFieldName")]
renamed_field: bool, // exposed as `myCustomFieldName` in GraphQL schema
}
#[graphql_object(impl = CharacterValue)]
impl ObjA {
fn id(&self, is_present: bool) -> &str {
// ^^ the evaluated program panicked at
// 'Failed to implement interface `Character` on `ObjA`: Field `id`: Argument `isPresent` of type `Boolean!`
// isn't present on the interface and so has to be nullable.'
is_present.then_some(&self.id).unwrap_or("missing")
}
#[graphql_interface]
#[graphql(name = "PersonInterface")]
trait Person { // exposed as `PersonInterface` in GraphQL schema
#[graphql(name = "myCustomFieldName")]
fn renamed_field( // exposed as `myCustomFieldName` in GraphQL schema
#[graphql(name = "myArgument")]
renamed_argument: bool, // exposed as `myArgument` in GraphQL schema
) -> bool;
}
#
# fn main() {}
```
#[graphql_interface(for = ObjA)]
Or provide a different renaming policy for all the defined [fields][4]:
```rust
# extern crate juniper;
# use juniper::graphql_interface;
#
#[graphql_interface]
#[graphql(rename_all = "none")] // disables any renaming
trait Person {
fn renamed_field( // exposed as `renamed_field` in GraphQL schema
renamed_argument: bool, // exposed as `renamed_argument` in GraphQL schema
) -> bool;
}
#
# fn main() {}
```
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
### Documentation and deprecation
Similarly, [GraphQL fields][4] of [interfaces][0] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
```rust
# extern crate juniper;
# use juniper::graphql_interface;
#
/// This doc comment is visible only in Rust API docs.
#[graphql_interface]
#[graphql(description = "This description overwrites the one from doc comment.")]
trait Person {
/// This doc comment is visible only in Rust API docs.
#[graphql(description = "This description is visible only in GraphQL schema.")]
fn empty() -> &'static str;
#[graphql(desc = "This description is visible only in GraphQL schema.")]
// ^^^^ shortcut for a `description` argument
fn field(
#[graphql(desc = "This description is visible only in GraphQL schema.")]
arg: bool,
) -> bool;
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
#[graphql(deprecated = "Just because.")]
fn deprecated_graphql() -> bool;
// Standard Rust's `#[deprecated]` attribute works too!
#[deprecated(note = "Reason is optional, btw!")]
fn deprecated_standard() -> bool; // has no description in GraphQL schema
}
#
# fn main() {}
```
> **NOTE**: Only [GraphQL interface][0]/[object][10] fields and [GraphQL enum][11] values can be [deprecated][9].
### Ignoring
By default, all [struct][24] fields or [trait][20] methods are considered as [GraphQL fields][4]. If a helper method is needed, or it should be ignored for some reason, then it should be marked with the `#[graphql(ignore)]` attribute:
```rust
# #![allow(dead_code)]
# extern crate juniper;
# use std::marker::PhantomPinned;
# use juniper::{graphql_interface, GraphQLInterface};
#
#[derive(GraphQLInterface)]
struct Character {
id: String,
}
#
# fn main() {}
```
```compile_fail
# extern crate juniper;
use juniper::{graphql_interface, GraphQLObject};
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue)]
pub struct ObjA {
id: Vec<String>,
// ^^ the evaluated program panicked at
// 'Failed to implement interface `Character` on `ObjA`: Field `id`: implementer is expected to return a subtype of
// interface's return object: `[String!]!` is not a subtype of `String!`.'
id: i32,
#[graphql(ignore)]
_pin: PhantomPinned,
}
#[graphql_interface(for = ObjA)]
struct Character {
id: String,
}
#
# fn main() {}
```
#[graphql_interface]
trait Person {
fn name(&self) -> &str;
fn age(&self) -> i32;
### Ignoring trait methods
We may want to omit some trait methods to be assumed as [GraphQL interface][1] fields and ignore them.
```rust
# extern crate juniper;
use juniper::{graphql_interface, GraphQLObject};
#[graphql_interface(for = Human)]
trait Character {
fn id(&self) -> &str;
#[graphql(ignore)] // or `#[graphql(skip)]`, your choice
fn ignored(&self) -> u32 { 0 }
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue)]
struct Human {
id: String,
}
#
# fn main() {}
```
### Fields, arguments and interface customization
Similarly to [GraphQL objects][5] Juniper allows to fully customize [interface][1] fields and their arguments.
```rust
# #![allow(deprecated)]
# extern crate juniper;
use juniper::graphql_interface;
// Renames the interface in GraphQL schema.
#[graphql_interface(name = "MyCharacter")]
// Describes the interface in GraphQL schema.
#[graphql_interface(description = "My own character.")]
// Usual Rust docs are supported too as GraphQL interface description,
// but `description` attribute argument takes precedence over them, if specified.
/// This doc is absent in GraphQL schema.
trait Character {
// Renames the field in GraphQL schema.
#[graphql(name = "myId")]
// Deprecates the field in GraphQL schema.
// Usual Rust `#[deprecated]` attribute is supported too as field deprecation,
// but `deprecated` attribute argument takes precedence over it, if specified.
#[graphql(deprecated = "Do not use it.")]
// Describes the field in GraphQL schema.
#[graphql(description = "ID of my own character.")]
// Usual Rust docs are supported too as field description,
// but `description` attribute argument takes precedence over them, if specified.
/// This description is absent in GraphQL schema.
fn id(
&self,
// Renames the argument in GraphQL schema.
#[graphql(name = "myNum")]
// Describes the argument in GraphQL schema.
#[graphql(description = "ID number of my own character.")]
// Specifies the default value for the argument.
// The concrete value may be omitted, and the `Default::default` one
// will be used in such case.
#[graphql(default = 5)]
num: i32,
) -> &str;
}
#
# fn main() {}
```
Renaming policies for all [GraphQL interface][1] fields and arguments are supported as well:
```rust
# #![allow(deprecated)]
# extern crate juniper;
use juniper::graphql_interface;
#[graphql_interface(rename_all = "none")] // disables any renaming
trait Character {
// Now exposed as `my_id` and `my_num` in the schema
fn my_id(&self, my_num: i32) -> &str;
}
#
# fn main() {}
```
### Custom context
If a [`Context`][6] is required in a trait method to resolve a [GraphQL interface][1] field, specify it as an argument.
```rust
# extern crate juniper;
# use std::collections::HashMap;
use juniper::{graphql_interface, GraphQLObject};
struct Database {
humans: HashMap<String, Human>,
}
impl juniper::Context for Database {}
#[graphql_interface(for = Human)] // look, ma, context type is inferred! ＼(^o^)／
trait Character { // while still can be specified via `Context = ...` attribute argument
// If a field argument is named `context` or `ctx`, it's automatically assumed
// as a context argument.
fn id(&self, context: &Database) -> Option<&str>;
// Otherwise, you may mark it explicitly as a context argument.
fn name(&self, #[graphql(context)] db: &Database) -> Option<&str>;
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue, Context = Database)]
struct Human {
id: String,
name: String,
}
#
# fn main() {}
```
### Using executor and explicit generic scalar
If an [`Executor`][4] is required in a trait method to resolve a [GraphQL interface][1] field, specify it as an argument.
This requires to explicitly parametrize over [`ScalarValue`][3], as [`Executor`][4] does so.
```rust
# extern crate juniper;
use juniper::{graphql_interface, graphql_object, Executor, ScalarValue};
#[graphql_interface(for = Human, Scalar = S)] // notice specifying `ScalarValue` as existing type parameter
trait Character<S: ScalarValue> {
// If a field argument is named `executor`, it's automatically assumed
// as an executor argument.
fn id<'a>(&self, executor: &'a Executor<'_, '_, (), S>) -> &'a str;
// Otherwise, you may mark it explicitly as an executor argument.
fn name<'b>(
&'b self,
#[graphql(executor)] another: &Executor<'_, '_, (), S>,
) -> &'b str;
fn home_planet(&self) -> &str;
}
struct Human {
id: String,
name: String,
home_planet: String,
}
#[graphql_object(scalar = S: ScalarValue, impl = CharacterValue<S>)]
impl Human {
async fn id<'a, S>(&self, executor: &'a Executor<'_, '_, (), S>) -> &'a str
where
S: ScalarValue,
{
executor.look_ahead().field_name()
#[graphql(ignore)]
fn hidden_from_graphql(&self) {
// Ignored methods are allowed to have a default implementation!
}
async fn name<'b, S>(&'b self, #[graphql(executor)] _: &Executor<'_, '_, (), S>) -> &'b str {
&self.name
}
fn home_planet<'c, S>(&'c self, #[graphql(executor)] _: &Executor<'_, '_, (), S>) -> &'c str {
// Executor may not be present on the trait method ^^^^^^^^^^^^^^^^^^^^^^^^
&self.home_planet
}
#[graphql(skip)]
// ^^^^ alternative naming, up to your preference
fn also_hidden_from_graphql(&self);
}
#
# fn main() {}
```
## `ScalarValue` considerations
By default, `#[graphql_interface]` macro generates code, which is generic over a [`ScalarValue`][3] type. This may introduce a problem when at least one of [GraphQL interface][1] implementers is restricted to a concrete [`ScalarValue`][3] type in its implementation. To resolve such problem, a concrete [`ScalarValue`][3] type should be specified.
```rust
# extern crate juniper;
use juniper::{graphql_interface, DefaultScalarValue, GraphQLObject};
#[graphql_interface(for = [Human, Droid])]
#[graphql_interface(scalar = DefaultScalarValue)] // removing this line will fail compilation
trait Character {
fn id(&self) -> &str;
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue, Scalar = DefaultScalarValue)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
#[graphql(impl = CharacterValue, Scalar = DefaultScalarValue)]
struct Droid {
id: String,
primary_function: String,
}
#
# fn main() {}
```
> **TIP**: See more available features in the API docs of the [`#[graphql_interface]`][3] attribute.
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[1]: https://spec.graphql.org/October2021#sec-Interfaces
[2]: https://doc.rust-lang.org/reference/types/trait-object.html
[3]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
[4]: https://docs.rs/juniper/latest/juniper/struct.Executor.html
[5]: https://spec.graphql.org/October2021#sec-Objects
[6]: https://docs.rs/juniper/0.14.2/juniper/trait.Context.html
[0]: https://spec.graphql.org/October2021#sec-Interfaces
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLInterface.html
[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_interface.html
[4]: https://spec.graphql.org/October2021#sec-Language.Fields
[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
[6]: https://spec.graphql.org/October2021#sec-Non-Null
[7]: https://spec.graphql.org/October2021#sec-Descriptions
[9]: https://spec.graphql.org/October2021#sec--deprecated
[10]: https://spec.graphql.org/October2021#sec-Objects
[11]: https://spec.graphql.org/October2021#sec-Enums
[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
[20]: https://doc.rust-lang.org/reference/items/traits.html#traits
[21]: https://doc.rust-lang.org/reference/types/trait-object.html#trait-objects
[22]: https://doc.rust-lang.org/reference/items/enumerations.html#enumerations
[23]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementations
[24]: https://doc.rust-lang.org/reference/items/structs.html
[30]: https://en.wikipedia.org/wiki/Structural_type_system
[31]: https://en.wikipedia.org/wiki/Type_class

357
book/src/types/objects/complex_fields.md
View file

@ -1,15 +1,169 @@
# Complex fields
Complex fields
==============
If you've got a struct that can't be mapped directly to GraphQL, that contains
computed fields or circular structures, you have to use a more powerful tool:
the `#[graphql_object]` procedural macro. This macro lets you define GraphQL object
fields in a Rust `impl` block for a type. Note, that GraphQL fields are defined in
this `impl` block by default. If you want to define normal methods on the struct,
you have to do so either in a separate "normal" `impl` block, or mark them with
`#[graphql(ignore)]` attribute to be omitted by the macro. Continuing with the
example from the last chapter, this is how you would define `Person` using the
macro:
Using a plain [Rust struct][struct] for representing a [GraphQL object][0] is easy and trivial but does not cover every case. What if we need to express something non-trivial as a [GraphQL field][4], such as:
- Calling non-trivial logic while [executing][1] the [field][4] (like querying database, etc.).
- Accepting [field arguments][5].
- Defining a circular [GraphQL object][0], where one of its [fields][4] returns the type itself.
- Using some other (non-[struct]) [Rust] type to represent a [GraphQL object][0].
To support these more complicated use cases, we need a way to define a [GraphQL field][4] as a function. In [Juniper] this is achievable by placing the [`#[graphql_object]` attribute][3] on an [`impl` block][6], which turns its methods into [GraphQL fields][4]:
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject};
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
struct House {
inhabitants: Vec<Person>,
}
// Defines the `House` GraphQL object.
#[graphql_object]
impl House {
// Creates the field `inhabitantWithName(name: String!)`,
// returning a `null`able `Person`.
fn inhabitant_with_name(&self, name: String) -> Option<&Person> {
self.inhabitants.iter().find(|p| p.name == name)
}
}
#
# fn main() {}
```
> **NOTE**: To access global data such as database connections or authentication information, a _context_ is used. To learn more about this, see the ["Context" chapter](context.md).
### Default arguments
Though [Rust] doesn't have the notion of default arguments, [GraphQL arguments][4] are able to have default values. These default values are used when a GraphQL operation doesn't specify the argument explicitly. In [Juniper], defining a default value for a [GraphQL argument][4] is enabled by the `#[graphql(default)]` attribute:
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
#[graphql_object]
impl Person {
fn field1(
// Default value can be any valid Rust expression, including a function
// call, etc.
#[graphql(default = true)]
arg1: bool,
// If default expression is not specified, then the `Default::default()`
// value is used.
#[graphql(default)]
arg2: i32,
) -> String {
format!("{arg1} {arg2}")
}
}
#
# fn main() {}
```
### Renaming
Like with the [`#[derive(GraphQLObject)]` attribute on structs](index.md#renaming), [field][4] names are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention.
We can override the name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
#[graphql_object]
#[graphql(name = "PersonObject")]
impl Person { // exposed as `PersonObject` in GraphQL schema
#[graphql(name = "myCustomFieldName")]
fn renamed_field( // exposed as `myCustomFieldName` in GraphQL schema
#[graphql(name = "myArgument")]
renamed_argument: bool, // exposed as `myArgument` in GraphQL schema
) -> bool {
renamed_argument
}
}
#
# fn main() {}
```
Or provide a different renaming policy for all the defined [fields][4]:
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
#[graphql_object]
#[graphql(rename_all = "none")] // disables any renaming
impl Person {
fn renamed_field( // exposed as `renamed_field` in GraphQL schema
renamed_argument: bool, // exposed as `renamed_argument` in GraphQL schema
) -> bool {
renamed_argument
}
}
#
# fn main() {}
```
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
### Documentation and deprecation
Similarly, [GraphQL fields][4] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
/// This doc comment is visible only in Rust API docs.
#[graphql_object]
#[graphql(description = "This description overwrites the one from doc comment.")]
impl Person {
/// This doc comment is visible only in Rust API docs.
#[graphql(description = "This description is visible only in GraphQL schema.")]
fn empty() -> &'static str {
""
}
#[graphql(desc = "This description is visible only in GraphQL schema.")]
// ^^^^ shortcut for a `description` argument
fn field(
#[graphql(desc = "This description is visible only in GraphQL schema.")]
arg: bool,
) -> bool {
arg
}
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
#[graphql(deprecated = "Just because.")]
fn deprecated_graphql() -> bool {
true
}
// Standard Rust's `#[deprecated]` attribute works too!
#[deprecated(note = "Reason is optional, btw!")]
fn deprecated_standard() -> bool { // has no description in GraphQL schema
false
}
}
#
# fn main() {}
```
> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
### Ignoring
By default, all methods of an [`impl` block][6] are exposed as [GraphQL fields][4]. If a method should not be exposed as a [GraphQL field][4], it should be defined in a separate [`impl` block][6] or marked with the `#[graphql(ignore)]` attribute:
```rust
# #![allow(dead_code)]
# extern crate juniper;
@ -32,175 +186,44 @@ impl Person {
#[graphql(ignore)]
pub fn hidden_from_graphql(&self) {
// [...]
// whatever goes...
}
#[graphql(skip)]
// ^^^^ alternative naming, up to your preference
pub fn also_hidden_from_graphql(&self) {
// whatever goes...
}
}
impl Person {
pub fn hidden_from_graphql2(&self) {
// [...]
}
}
#
# fn main() { }
```
While this is a bit more verbose, it lets you write any kind of function in the
field resolver. With this syntax, fields can also take arguments:
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject};
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
struct House {
inhabitants: Vec<Person>,
}
#[graphql_object]
impl House {
// Creates the field `inhabitantWithName(name)`, returning a nullable `Person`.
fn inhabitant_with_name(&self, name: String) -> Option<&Person> {
self.inhabitants.iter().find(|p| p.name == name)
pub fn not_even_considered_for_graphql(&self) {
// whatever goes...
}
}
#
# fn main() {}
```
To access global data such as database connections or authentication
information, a _context_ is used. To learn more about this, see the next
chapter: [Using contexts](using_contexts.md).
> **TIP**: See more available features in the API docs of the [`#[graphql_object]`][3] attribute.
## Description, renaming, and deprecation
Like with the derive attribute, field names will be converted from `snake_case`
to `camelCase`. If you need to override the conversion, you can simply rename
the field. Also, the type name can be changed with an alias:
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
/// Doc comments are used as descriptions for GraphQL.
#[graphql_object(
// With this attribute you can change the public GraphQL name of the type.
name = "PersonObject",
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[struct]: https://doc.rust-lang.org/reference/items/structs.html
// You can also specify a description here, which will overwrite
// a doc comment description.
description = "...",
)]
impl Person {
/// A doc comment on the field will also be used for GraphQL.
#[graphql(
// Or provide a description here.
description = "...",
)]
fn doc_comment(&self) -> &str {
""
}
// Fields can also be renamed if required.
#[graphql(name = "myCustomFieldName")]
fn renamed_field() -> bool {
true
}
// Deprecations also work as you'd expect.
// Both the standard Rust syntax and a custom attribute is accepted.
#[deprecated(note = "...")]
fn deprecated_standard() -> bool {
false
}
#[graphql(deprecated = "...")]
fn deprecated_graphql() -> bool {
true
}
}
#
# fn main() { }
```
Or provide a different renaming policy on a `impl` block for all its fields:
```rust
# extern crate juniper;
# use juniper::graphql_object;
struct Person;
#[graphql_object(rename_all = "none")] // disables any renaming
impl Person {
// Now exposed as `renamed_field` in the schema
fn renamed_field() -> bool {
true
}
}
#
# fn main() {}
```
## Customizing arguments
Method field arguments can also be customized.
They can have custom descriptions and default values.
```rust
# extern crate juniper;
# use juniper::graphql_object;
#
struct Person;
#[graphql_object]
impl Person {
fn field1(
&self,
#[graphql(
// Arguments can also be renamed if required.
name = "arg",
// Set a default value which will be injected if not present.
// The default can be any valid Rust expression, including a function call, etc.
default = true,
// Set a description.
description = "The first argument..."
)]
arg1: bool,
// If default expression is not specified then `Default::default()` value is used.
#[graphql(default)]
arg2: i32,
) -> String {
format!("{arg1} {arg2}")
}
}
#
# fn main() { }
```
Provide a different renaming policy on a `impl` block also implies for arguments:
```rust
# extern crate juniper;
# use juniper::graphql_object;
struct Person;
#[graphql_object(rename_all = "none")] // disables any renaming
impl Person {
// Now exposed as `my_arg` in the schema
fn field(my_arg: bool) -> bool {
my_arg
}
}
#
# fn main() {}
```
## More features
These, and more features, are described more thoroughly in [the reference documentation](https://docs.rs/juniper/latest/juniper/attr.graphql_object.html).
[0]: https://spec.graphql.org/October2021#sec-Objects
[1]: https://spec.graphql.org/October2021#sec-Execution
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLObject.html
[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_object.html
[4]: https://spec.graphql.org/October2021#sec-Language.Fields
[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
[6]: https://doc.rust-lang.org/reference/items/implementations.html#inherent-implementations
[7]: https://spec.graphql.org/October2021#sec-Descriptions
[9]: https://spec.graphql.org/October2021#sec--deprecated
[10]: https://spec.graphql.org/October2021#sec-Enums
[11]: https://spec.graphql.org/October2021#sec-Interfaces
[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute

156
book/src/types/objects/context.md Normal file
View file

@ -0,0 +1,156 @@
Context
=======
_Context_ is a feature in [Juniper] that lets [field][4] resolvers access global data, most commonly database connections or authentication information.
Let's say that we have a simple `User`s database in a `HashMap`:
```rust
# #![allow(dead_code)]
# use std::collections::HashMap;
#
struct Database {
users: HashMap<i32, User>,
}
struct User {
id: i32,
name: String,
friend_ids: Vec<i32>,
}
#
# fn main() {}
```
We would like to define a `friends` [field][4] on `User` that returns a list of `User` [objects][0]. In order to write such a [field][4] we need to query a `Database`. To accomplish this we must first mark the `Database` as a valid context type and then assign it to the `User` [object][0]. To gain access to the context in the `friends` [field][4], we need to specify an argument with the same type as the specified context:
```rust
# extern crate juniper;
# use std::collections::HashMap;
# use juniper::graphql_object;
#
struct Database {
users: HashMap<i32, User>,
}
// Mark the `Database` as a valid context type for Juniper.
impl juniper::Context for Database {}
struct User {
id: i32,
name: String,
friend_ids: Vec<i32>,
}
#[graphql_object]
#[graphql(context = Database)] // assign `Database` as the context type
impl User {
// Inject the `Database` context by specifying an argument with the
// context type:
// - the type must be a reference;
// - the name of the argument SHOULD be `context` (or `ctx`).
fn friends<'db>(&self, context: &'db Database) -> Vec<&'db User> {
// ^^^^^^^ or `ctx`, up to your preference
self.friend_ids.iter()
.map(|id| {
context.users.get(&id).expect("could not find `User` with ID")
})
.collect()
}
fn friend<'db>(
&self,
id: i32,
// Alternatively, the context argument may be marked with an attribute,
// and thus, named arbitrary.
#[graphql(context)] db: &'db Database,
// ^^^^^^^ or `ctx`, up to your preference
) -> Option<&'db User> {
self.friend_ids.contains(&id).then(|| {
db.users.get(&id).expect("could not find `User` with ID")
})
}
fn name(&self) -> &str {
self.name.as_str()
}
fn id(&self) -> i32 {
self.id
}
}
#
# fn main() {}
```
### Mutating and mutable references
Context cannot be a mutable reference as [fields][4] may be resolved concurrently. If something in the context requires a mutable reference, the context type should leverage the [_interior mutability_ pattern][5] (e.g. use `RwLock`, `RefCell` or similar).
For example, when using async runtime with [work stealing][6] (like [`tokio`]), which obviously requires thread safety in addition, we will need to use a corresponding async version of `RwLock`:
```rust
# extern crate juniper;
# extern crate tokio;
# use std::collections::HashMap;
# use juniper::graphql_object;
use tokio::sync::RwLock;
struct Database {
requested_count: HashMap<i32, i32>,
}
// Since we cannot directly implement `juniper::Context`
// for `RwLock`, we use the newtype idiom.
struct DatabaseContext(RwLock<Database>);
impl juniper::Context for DatabaseContext {}
struct User {
id: i32,
name: String
}
#[graphql_object]
#[graphql(context = DatabaseContext)]
impl User {
async fn times_requested<'db>(&self, ctx: &'db DatabaseContext) -> i32 {
// Acquire a mutable reference and `.await` if async `RwLock` is used,
// which is necessary if context consists of async operations like
// querying remote databases.
// Obtain base type.
let DatabaseContext(db) = ctx;
// If context is immutable use `.read()` on `RwLock` instead.
let mut db = db.write().await;
// Perform a mutable operation.
db.requested_count
.entry(self.id)
.and_modify(|e| *e += 1)
.or_insert(1)
.clone()
}
fn name(&self) -> &str {
self.name.as_str()
}
fn id(&self) -> i32 {
self.id
}
}
#
# fn main() {}
```
> **TIP**: Replace `tokio::sync::RwLock` with `std::sync::RwLock` (or similar) if you don't intend to use async resolving.
[`tokio`]: https://docs.rs/tokio
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Objects
[4]: https://spec.graphql.org/October2021#sec-Language.Fields
[5]: https://doc.rust-lang.org/reference/interior-mutability.html#interior-mutability
[6]: https://en.wikipedia.org/wiki/Work_stealing

216
book/src/types/objects/defining_objects.md
View file

@ -1,216 +0,0 @@
# Defining objects
While any type in Rust can be exposed as a GraphQL object, the most common one
is a struct.
There are two ways to create a GraphQL object in Juniper. If you've got a simple
struct you want to expose, the easiest way is to use the custom derive
attribute. The other way is described in the [Complex fields](complex_fields.md)
chapter.
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
#
# fn main() {}
```
This will create a GraphQL object type called `Person`, with two fields: `name`
of type `String!`, and `age` of type `Int!`. Because of Rust's type system,
everything is exported as non-null by default. If you need a nullable field, you
can use `Option<T>`.
We should take advantage of the
fact that GraphQL is self-documenting and add descriptions to the type and
fields. Juniper will automatically use associated doc comments as GraphQL
descriptions:
!FILENAME GraphQL descriptions via Rust doc comments
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
/// Information about a person
struct Person {
/// The person's full name, including both first and last names
name: String,
/// The person's age in years, rounded down
age: i32,
}
#
# fn main() {}
```
Objects and fields without doc comments can instead set a `description`
via the `graphql` attribute. The following example is equivalent to the above:
!FILENAME GraphQL descriptions via attribute
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
#[graphql(description = "Information about a person")]
struct Person {
#[graphql(description = "The person's full name, including both first and last names")]
name: String,
#[graphql(description = "The person's age in years, rounded down")]
age: i32,
}
#
# fn main() {}
```
Descriptions set via the `graphql` attribute take precedence over Rust
doc comments. This enables internal Rust documentation and external GraphQL
documentation to differ:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
#[graphql(description = "This description shows up in GraphQL")]
/// This description shows up in RustDoc
struct Person {
#[graphql(description = "This description shows up in GraphQL")]
/// This description shows up in RustDoc
name: String,
/// This description shows up in both RustDoc and GraphQL
age: i32,
}
#
# fn main() {}
```
## Relationships
You can only use the custom derive attribute under these circumstances:
- The annotated type is a `struct`,
- Every struct field is either
- A primitive type (`i32`, `f64`, `bool`, `String`, `juniper::ID`), or
- A valid custom GraphQL type, e.g. another struct marked with this attribute,
or
- A container/reference containing any of the above, e.g. `Vec<T>`, `Box<T>`,
`Option<T>`
Let's see what that means for building relationships between objects:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
#[derive(GraphQLObject)]
struct House {
address: Option<String>, // Converted into String (nullable)
inhabitants: Vec<Person>, // Converted into [Person!]!
}
#
# fn main() {}
```
Because `Person` is a valid GraphQL type, you can have a `Vec<Person>` in a
struct and it'll be automatically converted into a list of non-nullable `Person`
objects.
## Renaming fields
By default, struct fields are converted from Rust's standard `snake_case` naming
convention into GraphQL's `camelCase` convention:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
first_name: String, // Would be exposed as firstName in the GraphQL schema
last_name: String, // Exposed as lastName
}
#
# fn main() {}
```
You can override the name by using the `graphql` attribute on individual struct
fields:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
#[graphql(name = "websiteURL")]
website_url: Option<String>, // now exposed as `websiteURL` in the schema
}
#
# fn main() {}
```
Or provide a different renaming policy on a struct for all its fields:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
#[graphql(rename_all = "none")] // disables any renaming
struct Person {
name: String,
age: i32,
website_url: Option<String>, // now exposed as `website_url` in the schema
}
#
# fn main() {}
```
## Deprecating fields
To deprecate a field, you specify a deprecation reason using the `graphql`
attribute:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
#[graphql(deprecated = "Please use the name field instead")]
first_name: String,
}
#
# fn main() {}
```
The `name`, `description`, and `deprecation` arguments can of course be
combined. Some restrictions from the GraphQL spec still applies though; you can
only deprecate object fields and enum values.
## Ignoring fields
By default, all fields in a `GraphQLObject` are included in the generated GraphQL type. To prevent including a specific field, annotate the field with `#[graphql(ignore)]`:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
#[graphql(ignore)]
# #[allow(dead_code)]
password_hash: String, // cannot be queried or modified from GraphQL
}
#
# fn main() {}
```

183
book/src/types/objects/error/field.md Normal file
View file

@ -0,0 +1,183 @@
Field errors
============
[Rust] provides [two ways of dealing with errors][11]:
- [`Result<T, E>`][12] for recoverable errors;
- [`panic!`][13] for unrecoverable errors.
[Juniper] does not do anything about panicking, it naturally bubbles up to the surrounding code/framework and can be dealt with there.
For recoverable errors, [Juniper] works well with the [built-in `Result` type][12]. You can use the [`?` operator][14] and things will work as you expect them to:
```rust
# extern crate juniper;
# use std::{fs::File, io::Read, path::PathBuf, str};
# use juniper::{graphql_object, FieldResult};
#
struct Example {
filename: PathBuf,
}
#[graphql_object]
impl Example {
fn contents(&self) -> FieldResult<String> {
let mut file = File::open(&self.filename)?;
let mut contents = String::new();
file.read_to_string(&mut contents)?;
Ok(contents)
}
fn foo() -> FieldResult<Option<String>> {
// Some invalid bytes.
let invalid = vec![128, 223];
Ok(Some(str::from_utf8(&invalid)?.to_string()))
}
}
#
# fn main() {}
```
[`FieldResult<T>`][21] is an alias for [`Result<T, FieldError>`][22], which is the [error type][1] all fallible [fields][6] must return. By using the [`?` operator][14], any type that implements the [`Display` trait][15] (which most of the error types out there do) can be automatically converted into a [`FieldError`][22].
> **TIP**: If a custom conversion into a [`FieldError`][22] is needed (to [fill up `extensions`][2], for example), the [`IntoFieldError` trait][23] should be implemented.
> **NOTE**: [`FieldError`][22]s are [GraphQL field errors][1] and are [not visible][9] in a [GraphQL schema][8] in any way.
## Error payloads, `null`, and partial errors
[Juniper]'s error behavior conforms to the [GraphQL specification][0].
When a [field][6] returns an [error][11], the [field][6]'s result is replaced by `null`, and an additional `errors` object is created at the top level of the [response][7], and the [execution][5] is resumed.
Let's run the following query against the previous example:
```graphql
{
example {
contents
foo
}
}
```
If `str::from_utf8` results in a `std::str::Utf8Error`, then the following will be returned:
```json
{
"data": {
"example": {
"contents": "<Contents of the file>",
"foo": null
}
},
"errors": [{
"message": "invalid utf-8 sequence of 2 bytes from index 0",
"locations": [{"line": 2, "column": 4}]
}]
}
```
> Since [`Non-Null` type][4] [fields][5] cannot be **null**, [field errors][1] are propagated to be handled by the parent [field][5]. If the parent [field][5] may be **null** then it resolves to **null**, otherwise if it is a [`Non-Null` type][4], the [field error][1] is further propagated to its parent [field][5].
For example, with the following query:
```graphql
{
example {
contents
}
}
```
If the `File::open()` above results in a `std::io::ErrorKind::PermissionDenied`, the following ill be returned:
```json
{
"data": null,
"errors": [{
"message": "Permission denied (os error 13)",
"locations": [{"line": 2, "column": 4}]
}]
}
```
## Additional information
Sometimes it's desirable to return additional structured error information to clients. This can be accomplished by implementing the [`IntoFieldError` trait][23]:
```rust
# #[macro_use] extern crate juniper;
# use juniper::{graphql_object, FieldError, IntoFieldError, ScalarValue};
#
enum CustomError {
WhateverNotSet,
}
impl<S: ScalarValue> IntoFieldError<S> for CustomError {
fn into_field_error(self) -> FieldError<S> {
match self {
Self::WhateverNotSet => FieldError::new(
"Whatever does not exist",
graphql_value!({
"type": "NO_WHATEVER"
}),
),
}
}
}
struct Example {
whatever: Option<bool>,
}
#[graphql_object]
impl Example {
fn whatever(&self) -> Result<bool, CustomError> {
if let Some(value) = self.whatever {
return Ok(value);
}
Err(CustomError::WhateverNotSet)
}
}
#
# fn main() {}
```
And the specified structured error information will be included into the [error's `extensions`][2]:
```json
{
"errors": [{
"message": "Whatever does not exist",
"locations": [{"line": 2, "column": 4}],
"extensions": {
"type": "NO_WHATEVER"
}
}]
}
```
> **NOTE**: This pattern is particularly useful when it comes to instrumentation of returned [field errors][1] with custom error codes or additional diagnostics (like stack traces or tracing IDs).
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Handling-Field-Errors
[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
[2]: https://spec.graphql.org/October2021#sel-GAPHRPZCAACCC_7Q
[4]: https://spec.graphql.org/October2021#sec-Non-Null
[5]: https://spec.graphql.org/October2021#sec-Execution
[6]: https://spec.graphql.org/October2021#sec-Language.Fields
[7]: https://spec.graphql.org/October2021#sec-Response
[8]: https://graphql.org/learn/schema
[9]: https://spec.graphql.org/October2021#sec-Introspection
[11]: https://doc.rust-lang.org/book/ch09-00-error-handling.html
[12]: https://doc.rust-lang.org/stable/std/result/enum.Result.html
[13]: https://doc.rust-lang.org/stable/std/macro.panic.html
[14]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator
[15]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
[21]: https://docs.rs/juniper/latest/juniper/executor/type.FieldResult.html
[22]: https://docs.rs/juniper/latest/juniper/executor/struct.FieldError.html
[23]: https://docs.rs/juniper/latest/juniper/executor/trait.IntoFieldError.html

26
book/src/types/objects/error/index.md Normal file
View file

@ -0,0 +1,26 @@
Error handling
==============
Error handling in [GraphQL] can be done in multiple ways. We will cover the two different error handling models mostly used:
1. [Implicit field results](field.md).
2. [Explicit errors backend by GraphQL schema](schema.md).
Choosing the right error handling method depends on the requirements of the application and the concrete error happening. Investigating both approaches is beneficial.
## Comparison
The [first approach](field.md) (where every error is a [field error][1]) is easier to implement. However, clients won't know what errors may occur and instead will have to infer what happens from the [error message][2]. This is brittle and could change over time due to either clients or server changing. Therefore, extensive integration testing between clients and server is required to maintain the implicit contract between the two.
[Encoding non-critical errors in a GraphQL schema](schema.md) makes the contract between clients and the server explicit. This allows clients to understand and handle these errors correctly and the server to know when changes are potentially breaking clients. However, encoding this error information into a [GraphQL schema][8] requires additional code and up-front definition of non-critical errors.
[GraphQL]: https://graphql.org
[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
[2]: https://spec.graphql.org/October2021/#sel-GAPHRPDCAACCyD57Z
[8]: https://graphql.org/learn/schema

336
book/src/types/objects/error/schema.md Normal file
View file

@ -0,0 +1,336 @@
Schema errors
=============
[Rust]'s model of errors can be adapted for [GraphQL]. [Rust]'s panic is similar to a [field error][1] - the whole query is aborted and nothing can be extracted (except for error related information).
Not all errors require this strict handling. Recoverable or partial errors can be put into a [GraphQL schema][8], so the client can intelligently handle them.
To implement this approach, all errors must be partitioned into two classes:
- _Critical_ errors that cannot be fixed by clients (e.g. a database error).
- _Recoverable_ errors that can be fixed by clients (e.g. invalid input data).
Critical errors are returned from resolvers as [field errors][1] (from the [previous chapter](field.md)). Recoverable errors are part of a [GraphQL schema][8] and can be handled gracefully by clients. Similar to [Rust], [GraphQL] allows similar error models with [unions][9] (see ["Unions" chapter](../../unions.md)).
### Example: Simple
In this example, basic input validation is implemented with [GraphQL types][7]. [Strings][5] are used to identify the problematic [field][6] name. Errors for a particular [field][6] are also returned as a [string][5].
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationError {
field: String,
message: String,
}
#[derive(GraphQLObject)]
pub struct ValidationErrors {
errors: Vec<ValidationError>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationErrors),
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn add_item(&self, name: String, quantity: i32) -> GraphQLResult {
let mut errors = Vec::new();
if !(10 <= name.len() && name.len() <= 100) {
errors.push(ValidationError {
field: "name".into(),
message: "between 10 and 100".into(),
});
}
if !(1 <= quantity && quantity <= 10) {
errors.push(ValidationError {
field: "quantity".into(),
message: "between 1 and 10".into(),
});
}
if errors.is_empty() {
GraphQLResult::Ok(Item { name, quantity })
} else {
GraphQLResult::Err(ValidationErrors { errors })
}
}
}
#
# fn main() {}
```
Each function may have a different return type and depending on the input parameters a new result type may be required. For example, adding a `User` would require a new result type containing the variant `Ok(User)`instead of `Ok(Item)`.
> **NOTE**: In this example the returned [string][5] contains a server-side localized error message. However, it is also
possible to return a unique string identifier and have the client present a localized string to its users.
The client can send a mutation request and handle the resulting errors in the following manner:
```graphql
{
mutation {
addItem(name: "", quantity: 0) {
... on Item {
name
}
... on ValidationErrors {
errors {
field
message
}
}
}
}
}
```
> **NOTE**: A useful side effect of this approach is to have partially successful queries or mutations. If one resolver fails, the results of the successful resolvers are not discarded.
### Example: Complex
Instead of using [strings][5] to propagate errors, it is possible to use [GraphQL type system][7] to describe the errors more precisely.
For each fallible [input argument][4] we create a [field][6] in a [GraphQL object][10]. The [field][6] is set if the validation for that particular [argument][4] fails.
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationError {
name: Option<String>,
quantity: Option<String>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationError),
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn add_item(&self, name: String, quantity: i32) -> GraphQLResult {
let mut error = ValidationError {
name: None,
quantity: None,
};
if !(10 <= name.len() && name.len() <= 100) {
error.name = Some("between 10 and 100".into());
}
if !(1 <= quantity && quantity <= 10) {
error.quantity = Some("between 1 and 10".into());
}
if error.name.is_none() && error.quantity.is_none() {
GraphQLResult::Ok(Item { name, quantity })
} else {
GraphQLResult::Err(error)
}
}
}
#
# fn main() {}
```
> **NOTE**: We will likely want some kind of code generation to reduce repetition as the number of types required is significantly larger than before. Each resolver function has a custom `ValidationResult` which contains only [fields][6] provided by the function.
So, all the expected errors are handled directly inside the query. Additionally, all non-critical errors are known in advance by both the server and the client:
```graphql
{
mutation {
addItem {
... on Item {
name
}
... on ValidationErrorsItem {
name
quantity
}
}
}
}
```
### Example: Complex with critical errors
Our examples so far have only included non-critical errors. Providing errors inside a [GraphQL schema][8] still allows us to return unexpected critical errors when they occur.
In the following example, a theoretical database could fail and would generate errors. Since it is not common for a database to fail, the corresponding error is returned as a [critical error][1]:
```rust
# extern crate juniper;
# use juniper::{graphql_object, graphql_value, FieldError, GraphQLObject, GraphQLUnion, ScalarValue};
#
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationErrorItem {
name: Option<String>,
quantity: Option<String>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationErrorItem),
}
pub enum ApiError {
Database,
}
impl<S: ScalarValue> juniper::IntoFieldError<S> for ApiError {
fn into_field_error(self) -> FieldError<S> {
match self {
Self::Database => FieldError::new(
"Internal database error",
graphql_value!({"type": "DATABASE"}),
),
}
}
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn add_item(&self, name: String, quantity: i32) -> Result<GraphQLResult, ApiError> {
let mut error = ValidationErrorItem {
name: None,
quantity: None,
};
if !(10 <= name.len() && name.len() <= 100) {
error.name = Some("between 10 and 100".into());
}
if !(1 <= quantity && quantity <= 10) {
error.quantity = Some("between 1 and 10".into());
}
if error.name.is_none() && error.quantity.is_none() {
Ok(GraphQLResult::Ok(Item { name, quantity }))
} else {
Ok(GraphQLResult::Err(error))
}
}
}
#
# fn main() {}
```
### Example: Shopify API
The [Shopify API] implements a similar approach. Their API is a good reference to explore this approach in a real world application.
### Example: Non-struct [objects][10]
Up until now, we've only looked at mapping [structs][20] to [GraphQL objects][10]. However, any [Rust] type can be exposed a [GraphQL object][10].
Using `Result`-like [enums][1] can be a useful way of reporting validation errors from a mutation:
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject};
#
#[derive(GraphQLObject)]
struct User {
name: String,
}
#[derive(GraphQLObject)]
struct ValidationError {
field: String,
message: String,
}
enum SignUpResult {
Ok(User),
Error(Vec<ValidationError>),
}
#[graphql_object]
impl SignUpResult {
fn user(&self) -> Option<&User> {
match self {
Self::Ok(user) => Some(user),
Self::Error(_) => None,
}
}
fn error(&self) -> Option<&[ValidationError]> {
match self {
Self::Ok(_) => None,
Self::Error(errs) => Some(errs.as_slice())
}
}
}
#
# fn main() {}
```
Here, we use an [enum][21] to decide whether a client's input data is valid or not, and it could be used as the result of e.g. a `signUp` mutation:
```graphql
{
mutation {
signUp(name: "wrong") {
user {
name
}
error {
field
message
}
}
}
}
```
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[Shopify API]: https://shopify.dev/docs/admin-api/graphql/reference
[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
[4]: https://spec.graphql.org/October2021#sec-Language.Arguments
[5]: https://spec.graphql.org/October2021#sec-String
[6]: https://spec.graphql.org/October2021#sec-Language.Fields
[7]: https://spec.graphql.org/October2021#sec-Types
[8]: https://graphql.org/learn/schema
[9]: https://spec.graphql.org/October2021#sec-Unions
[10]: https://spec.graphql.org/October2021#sec-Objects
[20]: https://doc.rust-lang.org/reference/items/structs.html
[21]: https://doc.rust-lang.org/reference/items/enumerations.html

467
book/src/types/objects/error_handling.md
View file

@ -1,467 +0,0 @@
# Error handling
Error handling in GraphQL can be done in multiple ways. In the
following two different error handling models are discussed: field
results and GraphQL schema backed errors. Each approach has its
advantages. Choosing the right error handling method depends on the
requirements of the application--investigating both approaches is
beneficial.
## Field Results
Rust
[provides](https://doc.rust-lang.org/book/second-edition/ch09-00-error-handling.html)
two ways of dealing with errors: `Result<T, E>` for recoverable errors and
`panic!` for unrecoverable errors. Juniper does not do anything about panicking;
it will bubble up to the surrounding framework and hopefully be dealt with
there.
For recoverable errors, Juniper works well with the built-in `Result` type, you
can use the `?` operator and things will generally just work as you expect them to:
```rust
# extern crate juniper;
use std::{
str,
path::PathBuf,
fs::{File},
io::{Read},
};
use juniper::{graphql_object, FieldResult};
struct Example {
filename: PathBuf,
}
#[graphql_object]
impl Example {
fn contents(&self) -> FieldResult<String> {
let mut file = File::open(&self.filename)?;
let mut contents = String::new();
file.read_to_string(&mut contents)?;
Ok(contents)
}
fn foo() -> FieldResult<Option<String>> {
// Some invalid bytes.
let invalid = vec![128, 223];
Ok(Some(str::from_utf8(&invalid)?.to_string()))
}
}
#
# fn main() {}
```
`FieldResult<T>` is an alias for `Result<T, FieldError>`, which is the error
type all fields must return. By using the `?` operator or `try!` macro, any type
that implements the `Display` trait - which are most of the error types out
there - those errors are automatically converted into `FieldError`.
## Error payloads, `null`, and partial errors
Juniper's error behavior conforms to the [GraphQL specification](https://spec.graphql.org/October2021#sec-Handling-Field-Errors).
When a field returns an error, the field's result is replaced by `null`, an
additional `errors` object is created at the top level of the response, and the
execution is resumed. For example, with the previous example and the following
query:
```graphql
{
example {
contents
foo
}
}
```
If `str::from_utf8` resulted in a `std::str::Utf8Error`, the following would be
returned:
!FILENAME Response for nullable field with error
```json
{
"data": {
"example": {
contents: "<Contents of the file>",
foo: null
}
},
"errors": [
"message": "invalid utf-8 sequence of 2 bytes from index 0",
"locations": [{ "line": 2, "column": 4 }])
]
}
```
If an error is returned from a non-null field, such as the
example above, the `null` value is propagated up to the first nullable parent
field, or the root `data` object if there are no nullable fields.
For example, with the following query:
```graphql
{
example {
contents
}
}
```
If `File::open()` above resulted in `std::io::ErrorKind::PermissionDenied`, the
following would be returned:
!FILENAME Response for non-null field with error and no nullable parent
```json
{
"errors": [
"message": "Permission denied (os error 13)",
"locations": [{ "line": 2, "column": 4 }])
]
}
```
### Structured errors
Sometimes it is desirable to return additional structured error information
to clients. This can be accomplished by implementing [`IntoFieldError`](https://docs.rs/juniper/latest/juniper/trait.IntoFieldError.html):
```rust
# #[macro_use] extern crate juniper;
# use juniper::{graphql_object, FieldError, IntoFieldError, ScalarValue};
#
enum CustomError {
WhateverNotSet,
}
impl<S: ScalarValue> IntoFieldError<S> for CustomError {
fn into_field_error(self) -> FieldError<S> {
match self {
CustomError::WhateverNotSet => FieldError::new(
"Whatever does not exist",
graphql_value!({
"type": "NO_WHATEVER"
}),
),
}
}
}
struct Example {
whatever: Option<bool>,
}
#[graphql_object]
impl Example {
fn whatever(&self) -> Result<bool, CustomError> {
if let Some(value) = self.whatever {
return Ok(value);
}
Err(CustomError::WhateverNotSet)
}
}
#
# fn main() {}
```
The specified structured error information is included in the [`extensions`](https://spec.graphql.org/October2021#sec-Errors) key:
```json
{
"errors": [{
"message": "Whatever does not exist",
"locations": [{"line": 2, "column": 4}],
"extensions": {
"type": "NO_WHATEVER"
}
}]
}
```
## Errors Backed by GraphQL's Schema
Rust's model of errors can be adapted for GraphQL. Rust's panic is
similar to a `FieldError`--the whole query is aborted and nothing can
be extracted (except for error related information).
Not all errors require this strict handling. Recoverable or partial errors can be put
into the GraphQL schema so the client can intelligently handle them.
To implement this approach, all errors must be partitioned into two error classes:
* Critical errors that cannot be fixed by the user (e.g. a database error).
* Recoverable errors that can be fixed by the user (e.g. invalid input data).
Critical errors are returned from resolvers as `FieldErrors` (from the previous section). Non-critical errors are part of the GraphQL schema and can be handled gracefully by clients. Similar to Rust, GraphQL allows similar error models with unions (see Unions).
### Example Input Validation (simple)
In this example, basic input validation is implemented with GraphQL
types. Strings are used to identify the problematic field name. Errors
for a particular field are also returned as a string. In this example
the string contains a server-side localized error message. However, it is also
possible to return a unique string identifier and have the client present a localized string to the user.
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationError {
field: String,
message: String,
}
#[derive(GraphQLObject)]
pub struct ValidationErrors {
errors: Vec<ValidationError>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationErrors),
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn addItem(&self, name: String, quantity: i32) -> GraphQLResult {
let mut errors = Vec::new();
if !(10 <= name.len() && name.len() <= 100) {
errors.push(ValidationError {
field: "name".into(),
message: "between 10 and 100".into(),
});
}
if !(1 <= quantity && quantity <= 10) {
errors.push(ValidationError {
field: "quantity".into(),
message: "between 1 and 10".into(),
});
}
if errors.is_empty() {
GraphQLResult::Ok(Item { name, quantity })
} else {
GraphQLResult::Err(ValidationErrors { errors })
}
}
}
#
# fn main() {}
```
Each function may have a different return type and depending on the input
parameters a new result type is required. For example, adding a user
requires a new result type which contains the variant `Ok(User)`
instead of `Ok(Item)`.
The client can send a mutation request and handle the
resulting errors as shown in the following example:
```graphql
{
mutation {
addItem(name: "", quantity: 0) {
... on Item {
name
}
... on ValidationErrors {
errors {
field
message
}
}
}
}
}
```
A useful side effect of this approach is to have partially successful
queries or mutations. If one resolver fails, the results of the
successful resolvers are not discarded.
### Example Input Validation (complex)
Instead of using strings to propagate errors, it is possible to use
GraphQL's type system to describe the errors more precisely.
For each fallible input variable a field in a GraphQL object is created. The
field is set if the validation for that particular field fails. You will likely want some kind of code generation to reduce repetition as the number of types required is significantly larger than
before. Each resolver function has a custom `ValidationResult` which
contains only fields provided by the function.
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationError {
name: Option<String>,
quantity: Option<String>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationError),
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn addItem(&self, name: String, quantity: i32) -> GraphQLResult {
let mut error = ValidationError {
name: None,
quantity: None,
};
if !(10 <= name.len() && name.len() <= 100) {
error.name = Some("between 10 and 100".into());
}
if !(1 <= quantity && quantity <= 10) {
error.quantity = Some("between 1 and 10".into());
}
if error.name.is_none() && error.quantity.is_none() {
GraphQLResult::Ok(Item { name, quantity })
} else {
GraphQLResult::Err(error)
}
}
}
#
# fn main() {}
```
```graphql
{
mutation {
addItem {
... on Item {
name
}
... on ValidationErrorsItem {
name
quantity
}
}
}
}
```
Expected errors are handled directly inside the query. Additionally, all
non-critical errors are known in advance by both the server and the client.
### Example Input Validation (complex with critical error)
Our examples so far have only included non-critical errors. Providing
errors inside the GraphQL schema still allows you to return unexpected critical
errors when they occur.
In the following example, a theoretical database could fail
and would generate errors. Since it is not common for the database to
fail, the corresponding error is returned as a critical error:
```rust
# extern crate juniper;
#
use juniper::{graphql_object, graphql_value, FieldError, GraphQLObject, GraphQLUnion, ScalarValue};
#[derive(GraphQLObject)]
pub struct Item {
name: String,
quantity: i32,
}
#[derive(GraphQLObject)]
pub struct ValidationErrorItem {
name: Option<String>,
quantity: Option<String>,
}
#[derive(GraphQLUnion)]
pub enum GraphQLResult {
Ok(Item),
Err(ValidationErrorItem),
}
pub enum ApiError {
Database,
}
impl<S: ScalarValue> juniper::IntoFieldError<S> for ApiError {
fn into_field_error(self) -> FieldError<S> {
match self {
ApiError::Database => FieldError::new(
"Internal database error",
graphql_value!({
"type": "DATABASE"
}),
),
}
}
}
pub struct Mutation;
#[graphql_object]
impl Mutation {
fn addItem(&self, name: String, quantity: i32) -> Result<GraphQLResult, ApiError> {
let mut error = ValidationErrorItem {
name: None,
quantity: None,
};
if !(10 <= name.len() && name.len() <= 100) {
error.name = Some("between 10 and 100".into());
}
if !(1 <= quantity && quantity <= 10) {
error.quantity = Some("between 1 and 10".into());
}
if error.name.is_none() && error.quantity.is_none() {
Ok(GraphQLResult::Ok(Item { name, quantity }))
} else {
Ok(GraphQLResult::Err(error))
}
}
}
#
# fn main() {}
```
## Additional Material
The [Shopify API](https://shopify.dev/docs/admin-api/graphql/reference)
implements a similar approach. Their API is a good reference to
explore this approach in a real world application.
# Comparison
The first approach discussed above--where every error is a critical error defined by `FieldResult` --is easier to implement. However, the client does not know what errors may occur and must instead infer what happened from the error string. This is brittle and could change over time due to either the client or server changing. Therefore, extensive integration testing between the client and server is required to maintain the implicit contract between the two.
Encoding non-critical errors in the GraphQL schema makes the contract between the client and the server explicit. This allows the client to understand and handle these errors correctly and the server to know when changes are potentially breaking clients. However, encoding this error information into the GraphQL schema requires additional code and up-front definition of non-critical errors.

78
book/src/types/objects/generics.md Normal file
View file

@ -0,0 +1,78 @@
Generics
========
Yet another point where [GraphQL] and [Rust] differs is in how generics work:
- In [Rust], almost any type could be generic - that is, take type parameters.
- In [GraphQL], there are only two generic types: [lists][1] and [non-`null`ables][2].
This poses a restriction on what we can expose in [GraphQL] from [Rust]: no generic structs can be exposed - all type parameters must be bound. For example, we cannot expose `Result<T, E>` as a [GraphQL type][0], but we _can_ expose `Result<User, String>` as a [GraphQL type][0].
Let's make a slightly more compact but generic implementation of [the last schema error example](error/schema.md#example-non-struct-objects):
```rust
# extern crate juniper;
# use juniper::{graphql_object, GraphQLObject};
#
#[derive(GraphQLObject)]
struct User {
name: String,
}
#[derive(GraphQLObject)]
struct ForumPost {
title: String,
}
#[derive(GraphQLObject)]
struct ValidationError {
field: String,
message: String,
}
struct MutationResult<T>(Result<T, Vec<ValidationError>>);
#[graphql_object]
#[graphql(name = "UserResult")]
impl MutationResult<User> {
fn user(&self) -> Option<&User> {
self.0.as_ref().ok()
}
fn error(&self) -> Option<&[ValidationError]> {
self.0.as_ref().err().map(Vec::as_slice)
}
}
#[graphql_object]
#[graphql(name = "ForumPostResult")]
impl MutationResult<ForumPost> {
fn forum_post(&self) -> Option<&ForumPost> {
self.0.as_ref().ok()
}
fn error(&self) -> Option<&[ValidationError]> {
self.0.as_ref().err().map(Vec::as_slice)
}
}
#
# fn main() {}
```
Here, we've made a wrapper around a `Result` and exposed some concrete instantiations of `Result<T, E>` as distinct [GraphQL objects][3].
> **NOTE**: The reason we needed the wrapper is of [Rust]'s [orphan rules][10] (both the `Result` and [Juniper]'s internal traits are from third-party sources).
> **NOTE**: Because we're using generics, we also need to specify a `name` for our instantiated [GraphQL types][0]. Even if [Juniper] _could_ figure out the name, `MutationResult<User>` wouldn't be a [valid GraphQL type name][4]. And, also, two different [GraphQL types][0] cannot have the same `MutationResult` name, inferred by default.
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[0]: https://spec.graphql.org/October2021#sec-Types
[1]: https://spec.graphql.org/October2021#sec-List
[2]: https://spec.graphql.org/October2021#sec-Non-Null
[3]: https://spec.graphql.org/October2021#sec-Objects
[4]: https://spec.graphql.org/October2021#sec-Names
[10]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementation-coherence

228
book/src/types/objects/index.md Normal file
View file

@ -0,0 +1,228 @@
Objects
=======
> [GraphQL objects][0] represent a list of named fields, each of which yield a value of a specific type.
When declaring a [GraphQL schema][schema], most of the time we deal with [GraphQL objects][0], because they are the only place where we actually define the behavior once [schema] gets [executed][1].
There are two ways to define a [GraphQL object][0] in [Juniper]:
1. The easiest way, suitable for trivial cases, is to use the [`#[derive(GraphQLObject)]` attribute][2] on a [struct], as described below.
2. The other way, using the [`#[graphql_object]` attribute][3], is described in the ["Complex fields" chapter](complex_fields.md).
## Trivial
While any type in [Rust] can be exposed as a [GraphQL object][0], the most common one is a [struct]:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
#
# fn main() {}
```
This creates a [GraphQL object][0] type called `Person`, with two fields: `name` of type `String!`, and `age` of type `Int!`. Because of [Rust]'s type system, everything is exported as [non-`null`][4] by default.
> **TIP**: If a `null`able field is required, the most obvious way is to use `Option`. Or [`Nullable`] for distinguishing between [explicit and implicit `null`s][14].
### Documentation
We should take advantage of the fact that [GraphQL] is [self-documenting][5] and add descriptions to the defined [GraphQL object][0] type and its fields. [Juniper] will automatically use associated [Rust doc comments][6] as [GraphQL descriptions][7]:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
/// Information about a person.
#[derive(GraphQLObject)]
struct Person {
/// The person's full name, including both first and last names.
name: String,
/// The person's age in years, rounded down.
age: i32,
}
#
# fn main() {}
```
If using [Rust doc comments][6] is not desired (for example, when we want to keep [Rust] API docs and GraphQL schema descriptions different), the `#[graphql(description = "...")]` attribute can be used instead, which takes precedence over [Rust doc comments][6]:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
/// This doc comment is visible only in Rust API docs.
#[derive(GraphQLObject)]
#[graphql(description = "This description is visible only in GraphQL schema.")]
struct Person {
/// This doc comment is visible only in Rust API docs.
#[graphql(desc = "This description is visible only in GraphQL schema.")]
// ^^^^ shortcut for a `description` argument
name: String,
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
age: i32,
}
#
# fn main() {}
```
### Renaming
By default, [struct] fields are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
struct Person {
first_name: String, // exposed as `firstName` in GraphQL schema
last_name: String, // exposed as `lastName` in GraphQL schema
}
#
# fn main() {}
```
We can override the name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
#[graphql(name = "WebPerson")] // now exposed as `WebPerson` in GraphQL schema
struct Person {
name: String,
age: i32,
#[graphql(name = "websiteURL")]
website_url: Option<String>, // now exposed as `websiteURL` in GraphQL schema
}
#
# fn main() {}
```
Or provide a different renaming policy for all the [struct] fields:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
#[graphql(rename_all = "none")] // disables any renaming
struct Person {
name: String,
age: i32,
website_url: Option<String>, // exposed as `website_url` in GraphQL schema
}
#
# fn main() {}
```
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
### Deprecation
To [deprecate][9] a [GraphQL object][0] field, either the `#[graphql(deprecated = "...")]` attribute, or [Rust's `#[deprecated]` attribute][13], should be used:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
#[graphql(deprecated = "Please use the `name` field instead.")]
first_name: String,
#[deprecated(note = "Please use the `name` field instead.")]
last_name: String,
}
#
# fn main() {}
```
> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
### Ignoring
By default, all [struct] fields are included into the generated [GraphQL object][0] type. To prevent inclusion of a specific field annotate it with the `#[graphql(ignore)]` attribute:
```rust
# #![allow(dead_code)]
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
#[graphql(ignore)]
password_hash: String, // cannot be queried from GraphQL
#[graphql(skip)]
// ^^^^ alternative naming, up to your preference
is_banned: bool, // cannot be queried from GraphQL
}
#
# fn main() {}
```
> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLObject)]`][2] attribute.
## Relationships
[GraphQL object][0] fields can be of any [GraphQL] type, except [input objects][8].
Let's see what it means to build relationships between [objects][0]:
```rust
# extern crate juniper;
# use juniper::GraphQLObject;
#
#[derive(GraphQLObject)]
struct Person {
name: String,
age: i32,
}
#[derive(GraphQLObject)]
struct House {
address: Option<String>, // converted into `String` (`null`able)
inhabitants: Vec<Person>, // converted into `[Person!]!`
}
#
# fn main() {}
```
Because `Person` is a valid [GraphQL] type, we can have a `Vec<Person>` in a [struct], and it'll be automatically converted into a [list][12] of [non-`null`able][4] `Person` [objects][0].
[`Nullable`]: https://docs.rs/juniper/latest/juniper/enum.Nullable.html
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
[schema]: https://graphql.org/learn/schema
[struct]: https://doc.rust-lang.org/reference/items/structs.html
[0]: https://spec.graphql.org/October2021#sec-Objects
[1]: https://spec.graphql.org/October2021#sec-Execution
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLObject.html
[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_object.html
[4]: https://spec.graphql.org/October2021#sec-Non-Null
[5]: https://spec.graphql.org/October2021#sec-Introspection
[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
[7]: https://spec.graphql.org/October2021#sec-Descriptions
[8]: https://spec.graphql.org/October2021#sec-Input-Objects
[9]: https://spec.graphql.org/October2021#sec--deprecated
[10]: https://spec.graphql.org/October2021#sec-Enums
[11]: https://spec.graphql.org/October2021#sec-Interfaces
[12]: https://spec.graphql.org/October2021#sec-List
[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
[14]: https://spec.graphql.org/October2021#sel-EAFdRDHAAEJDAoBxzT

150
book/src/types/objects/using_contexts.md
View file

@ -1,150 +0,0 @@
# Using contexts
The context type is a feature in Juniper that lets field resolvers access global
data, most commonly database connections or authentication information. The
context is usually created from a _context factory_. How this is defined is
specific to the framework integration you're using, so check out the
documentation for [Rocket](../../servers/rocket.md) integration.
In this chapter, we'll show you how to define a context type and use it in field
resolvers. Let's say that we have a simple user database in a `HashMap`:
```rust
# #![allow(dead_code)]
# use std::collections::HashMap;
#
struct Database {
users: HashMap<i32, User>,
}
struct User {
id: i32,
name: String,
friend_ids: Vec<i32>,
}
#
# fn main() { }
```
We would like a `friends` field on `User` that returns a list of `User` objects.
In order to write such a field though, the database must be queried.
To solve this, we mark the `Database` as a valid context type and assign it to
the user object.
To gain access to the context, we need to specify an argument with the same
type as the specified `Context` for the type:
```rust
# extern crate juniper;
# use std::collections::HashMap;
# use juniper::graphql_object;
#
// This struct represents our context.
struct Database {
users: HashMap<i32, User>,
}
// Mark the Database as a valid context type for Juniper
impl juniper::Context for Database {}
struct User {
id: i32,
name: String,
friend_ids: Vec<i32>,
}
// Assign Database as the context type for User
#[graphql_object(context = Database)]
impl User {
// Inject the context by specifying an argument with the context type.
// Note:
// - the type must be a reference
// - the name of the argument SHOULD be `context`
fn friends<'db>(&self, context: &'db Database) -> Vec<&'db User> {
// Use the database to lookup users
self.friend_ids.iter()
.map(|id| context.users.get(id).expect("Could not find user with ID"))
.collect()
}
fn name(&self) -> &str {
self.name.as_str()
}
fn id(&self) -> i32 {
self.id
}
}
#
# fn main() { }
```
You only get an immutable reference to the context, so if you want to affect
change to the execution, you'll need to use [interior
mutability](https://doc.rust-lang.org/book/first-edition/mutability.html#interior-vs-exterior-mutability)
using e.g. `RwLock` or `RefCell`.
## Dealing with mutable references
Context cannot be specified by a mutable reference, because concurrent fields resolving may be performed. If you have something in your context that requires access by mutable reference, then you need to leverage the [interior mutability][1] for that.
For example, when using async runtime with [work stealing][2] (like `tokio`), which obviously requires thread safety in addition, you will need to use a corresponding async version of `RwLock`:
```rust
# extern crate juniper;
# extern crate tokio;
# use std::collections::HashMap;
# use juniper::graphql_object;
use tokio::sync::RwLock;
struct Database {
requested_count: HashMap<i32, i32>,
}
// Since we cannot directly implement juniper::Context
// for RwLock we use the newtype idiom
struct DatabaseContext(RwLock<Database>);
impl juniper::Context for DatabaseContext {}
struct User {
id: i32,
name: String
}
#[graphql_object(context=DatabaseContext)]
impl User {
async fn times_requested<'db>(&self, context: &'db DatabaseContext) -> i32 {
// Acquire a mutable reference and await if async RwLock is used,
// which is necessary if context consists async operations like
// querying remote databases.
// Obtain base type
let DatabaseContext(context) = context;
// If context is immutable use .read() on RwLock.
let mut context = context.write().await;
// Perform a mutable operation.
context.requested_count.entry(self.id).and_modify(|e| { *e += 1 }).or_insert(1).clone()
}
fn name(&self) -> &str {
self.name.as_str()
}
fn id(&self) -> i32 {
self.id
}
}
#
# fn main() { }
```
Replace `tokio::sync::RwLock` with `std::sync::RwLock` (or similar) if you don't intend to use async resolving.
[1]: https://doc.rust-lang.org/book/ch15-05-interior-mutability.html
[2]: https://en.wikipedia.org/wiki/Work_stealing

11
book/src/types/other-index.md
View file

@ -1,11 +0,0 @@
# Other Types
The GraphQL type system provides several types in addition to objects.
Find out more about each type below:
- [Enums](enums.md)
- [Interfaces](interfaces.md)
- [Input objects](input_objects.md)
- [Scalars](scalars.md)
- [Unions](unions.md)

370
book/src/types/scalars.md
View file

@ -1,118 +1,88 @@
# Scalars
Scalars
=======
Scalars are the primitive types at the leaves of a GraphQL query: numbers,
strings, and booleans. You can create custom scalars to other primitive values,
but this often requires coordination with the client library intended to consume
the API you're building.
Since any value going over the wire is eventually transformed into JSON, you're
also limited in the data types you can use.
There are two ways to define custom scalars.
* For simple scalars that just wrap a primitive type, you can use the newtype pattern with
a custom derive.
* For more advanced use cases with custom validation, you can use
the `graphql_scalar` proc macro.
## Built-in scalars
Juniper has built-in support for:
* `i32` as `Int`
* `f64` as `Float`
* `String` and `&str` as `String`
* `bool` as `Boolean`
* `juniper::ID` as `ID`. This type is defined [in the
spec](https://spec.graphql.org/October2021#sec-ID) as a type that is serialized
as a string but can be parsed from both a string and an integer.
Note that there is no built-in support for `i64`/`u64`, as the GraphQL spec [doesn't define any built-in scalars for `i64`/`u64` by default](https://spec.graphql.org/October2021#sec-Int). You may wish to leverage a [custom GraphQL scalar](#custom-scalars) in your schema to support them.
**Third party types**:
Juniper has built-in support for a few additional types from common third party
crates. They are enabled via features that are on by default.
* uuid::Uuid
* chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime}
* chrono_tz::Tz;
* time::{Date, OffsetDateTime, PrimitiveDateTime, Time, UtcOffset}
* url::Url
* bson::oid::ObjectId
[GraphQL scalars][0] represent primitive leaf values in a GraphQL type system: numbers, strings, and booleans.
## Custom scalars
## Built-in
### `#[graphql(transparent)]` attribute
[Juniper] provides support for all the [built-in scalars][5].
Often, you might need a custom scalar that just wraps an existing type.
| [Rust] types | [GraphQL] scalar |
|------------------|------------------|
| `bool` | `Boolean` |
| `i32` | `Int` |
| `f64` | `Float` |
| `String`, `&str` | `String` |
| `juniper::ID` | [`ID`] |
This can be done with the newtype pattern and a custom derive, similar to how
serde supports this pattern with `#[serde(transparent)]`.
> **NOTE**: [`ID`] scalar is [defined in the GraphQL spec][`ID`] as a type that is serialized as a string, but can be parsed from both a string and an integer.
> **TIP**: There is no built-in support for `i64`, `u64`, or other [Rust] integer types, as the [GraphQL spec doesn't define any built-in scalars for them][1] by default. Instead, to be supported, they should be defined as [custom scalars](#custom) in a [GraphQL schema][schema].
## Custom
We can create [custom scalars][2] for other primitive values, but they are still [limited in the data types for representation][1], and only introduce additional semantic meaning. This, also, often requires coordination with the client library, intended to consume the API we're building.
[Custom scalars][2] can be defined in [Juniper] by using either [`#[derive(GraphQLScalar)]`][8] or [`#[graphql_scalar]`][9] attributes, which do work pretty much the same way (except, [`#[derive(GraphQLScalar)]`][8] cannot be used on [type aliases][4]).
### Transparent delegation
Quite often, we want to create a [custom GraphQL scalar][2] type by just wrapping an existing one, inheriting all its behavior. In [Rust], this is often called as ["newtype pattern"][3]. This may be achieved by providing a `#[graphql(transparent)]` attribute to the definition:
```rust
# extern crate juniper;
# use juniper::{graphql_scalar, GraphQLScalar};
#
#[derive(juniper::GraphQLScalar)]
#[derive(GraphQLScalar)]
#[graphql(transparent)]
pub struct UserId(i32);
#[derive(juniper::GraphQLObject)]
struct User {
id: UserId,
}
#
# fn main() {}
```
`#[derive(GraphQLScalar)]` is mostly interchangeable with `#[graphql_scalar]`
attribute:
```rust
# extern crate juniper;
# use juniper::graphql_scalar;
#
#[graphql_scalar(transparent)]
pub struct UserId {
// Using `#[graphql_scalar]` attribute here makes no difference, and is fully
// interchangeable with `#[derive(GraphQLScalar)]`. It's only up to the
// personal preference - which one to use.
#[graphql_scalar]
#[graphql(transparent)]
pub struct MessageId {
value: i32,
}
#[derive(juniper::GraphQLObject)]
struct User {
id: UserId,
}
#
# fn main() {}
```
That's it, now the `UserId` and `MessageId` [scalars][0] can be used in [GraphQL schema][schema].
That's it, you can now use `UserId` in your schema.
The macro also allows for more customization:
We may also customize the definition, to provide more information about our [custom scalar][2] in [GraphQL schema][schema]:
```rust
# extern crate juniper;
/// You can use a doc comment to specify a description.
#[derive(juniper::GraphQLScalar)]
# use juniper::GraphQLScalar;
#
/// You can use a Rust doc comment to specify a description in GraphQL schema.
#[derive(GraphQLScalar)]
#[graphql(
transparent,
// Overwrite the GraphQL type name.
// Overwrite the name of this type in the GraphQL schema.
name = "MyUserId",
// Specify a custom description.
// A description in the attribute will overwrite a doc comment.
description = "My user id description",
// Specifying a type description via attribute takes precedence over the
// Rust doc comment, which allows to separate Rust API docs from GraphQL
// schema descriptions, if required.
description = "Actual description.",
// Optional specification URL.
specified_by_url = "https://tools.ietf.org/html/rfc4122",
)]
pub struct UserId(i32);
pub struct UserId(String);
#
# fn main() {}
```
All the methods used from newtype's field can be replaced with attributes:
### `#[graphql(to_output_with = <fn>)]` attribute
### Resolving
In case we need to customize [resolving][7] of a [custom GraphQL scalar][2] value (change the way it gets executed), the `#[graphql(to_output_with = <fn path>)]` attribute is the way to do so:
```rust
# extern crate juniper;
# use juniper::{GraphQLScalar, ScalarValue, Value};
@ -123,14 +93,17 @@ struct Incremented(i32);
/// Increments [`Incremented`] before converting into a [`Value`].
fn to_output<S: ScalarValue>(v: &Incremented) -> Value<S> {
Value::from(v.0 + 1)
let inc = v.0 + 1;
Value::from(inc)
}
#
# fn main() {}
```
### `#[graphql(from_input_with = <fn>)]` attribute
### Input value parsing
Customization of a [custom GraphQL scalar][2] value parsing is possible via `#[graphql(from_input_with = <fn path>)]` attribute:
```rust
# extern crate juniper;
# use juniper::{GraphQLScalar, InputValue, ScalarValue};
@ -140,8 +113,8 @@ fn to_output<S: ScalarValue>(v: &Incremented) -> Value<S> {
struct UserId(String);
impl UserId {
/// Checks whether [`InputValue`] is `String` beginning with `id: ` and
/// strips it.
/// Checks whether the [`InputValue`] is a [`String`] beginning with `id: `
/// and strips it.
fn from_input<S>(input: &InputValue<S>) -> Result<Self, String>
where
S: ScalarValue
@ -164,13 +137,15 @@ impl UserId {
# fn main() {}
```
### `#[graphql(parse_token_with = <fn>]` or `#[graphql(parse_token(<types>)]` attributes
### Token parsing
Customization of which tokens a [custom GraphQL scalar][0] type should be parsed from, is possible via `#[graphql(parse_token_with = <fn path>)]` or `#[graphql(parse_token(<types>)]` attributes:
```rust
# extern crate juniper;
# use juniper::{
# GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
# ScalarValue, ScalarToken, Value
# ScalarValue, ScalarToken, Value,
# };
#
#[derive(GraphQLScalar)]
@ -178,32 +153,26 @@ impl UserId {
to_output_with = to_output,
from_input_with = from_input,
parse_token_with = parse_token,
// ^^^^^^^^^^^^^^^^ Can be replaced with `parse_token(String, i32)`
// which tries to parse as `String` and then as `i32`
// if prior fails.
)]
// ^^^^^^^^^^^^^^^^ Can be replaced with `parse_token(String, i32)`, which
// tries to parse as `String` first, and then as `i32` if
// prior fails.
enum StringOrInt {
String(String),
Int(i32),
}
fn to_output<S>(v: &StringOrInt) -> Value<S>
where
S: ScalarValue
{
fn to_output<S: ScalarValue>(v: &StringOrInt) -> Value<S> {
match v {
StringOrInt::String(s) => Value::scalar(s.to_owned()),
StringOrInt::Int(i) => Value::scalar(*i),
}
}
fn from_input<S>(v: &InputValue<S>) -> Result<StringOrInt, String>
where
S: ScalarValue
{
fn from_input<S: ScalarValue>(v: &InputValue<S>) -> Result<StringOrInt, String> {
v.as_string_value()
.map(|s| StringOrInt::String(s.into()))
.or_else(|| v.as_int_value().map(|i| StringOrInt::Int(i)))
.or_else(|| v.as_int_value().map(StringOrInt::Int))
.ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
}
@ -214,27 +183,62 @@ fn parse_token<S: ScalarValue>(value: ScalarToken<'_>) -> ParseScalarResult<S> {
#
# fn main() {}
```
> **NOTE**: Once we provide all 3 custom functions, there is no sense to follow [newtype pattern][3] anymore, as nothing left to inherit.
> __NOTE:__ As you can see, once you provide all 3 custom resolvers, there
> is no need to follow `newtype` pattern.
### `#[graphql(with = <path>)]` attribute
Instead of providing all custom resolvers, you can provide path to the `to_output`,
`from_input`, `parse_token` functions.
Path can be simply `with = Self` (default path where macro expects resolvers to be),
in case there is an impl block with custom resolvers:
### Full behavior
Instead of providing all custom functions separately, it's possible to provide a module holding the appropriate `to_output()`, `from_input()` and `parse_token()` functions via `#[graphql(with = <module path>)]` attribute:
```rust
# extern crate juniper;
# use juniper::{
# GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
# ScalarValue, ScalarToken, Value
# ScalarValue, ScalarToken, Value,
# };
#
#[derive(GraphQLScalar)]
// #[graphql(with = Self)] <- default behaviour
#[graphql(with = string_or_int)]
enum StringOrInt {
String(String),
Int(i32),
}
mod string_or_int {
use super::*;
pub(super) fn to_output<S: ScalarValue>(v: &StringOrInt) -> Value<S> {
match v {
StringOrInt::String(s) => Value::scalar(s.to_owned()),
StringOrInt::Int(i) => Value::scalar(*i),
}
}
pub(super) fn from_input<S: ScalarValue>(v: &InputValue<S>) -> Result<StringOrInt, String> {
v.as_string_value()
.map(|s| StringOrInt::String(s.into()))
.or_else(|| v.as_int_value().map(StringOrInt::Int))
.ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
}
pub(super) fn parse_token<S: ScalarValue>(t: ScalarToken<'_>) -> ParseScalarResult<S> {
<String as ParseScalarValue<S>>::from_str(t)
.or_else(|_| <i32 as ParseScalarValue<S>>::from_str(t))
}
}
#
# fn main() {}
```
A regular `impl` block is also suitable for that:
```rust
# extern crate juniper;
# use juniper::{
# GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
# ScalarValue, ScalarToken, Value,
# };
#
#[derive(GraphQLScalar)]
// #[graphql(with = Self)] <- default behaviour, so can be omitted
enum StringOrInt {
String(String),
Int(i32),
@ -250,7 +254,7 @@ impl StringOrInt {
fn from_input<S>(v: &InputValue<S>) -> Result<Self, String>
where
S: ScalarValue,
S: ScalarValue
{
v.as_string_value()
.map(|s| Self::String(s.into()))
@ -260,7 +264,7 @@ impl StringOrInt {
fn parse_token<S>(value: ScalarToken<'_>) -> ParseScalarResult<S>
where
S: ScalarValue,
S: ScalarValue
{
<String as ParseScalarValue<S>>::from_str(value)
.or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
@ -270,17 +274,19 @@ impl StringOrInt {
# fn main() {}
```
Or it can be path to a module, where custom resolvers are located.
At the same time, any custom function still may be specified separately, if required:
```rust
# extern crate juniper;
# use juniper::{
# GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
# ScalarValue, ScalarToken, Value
# GraphQLScalar, InputValue, ParseScalarResult, ScalarValue,
# ScalarToken, Value
# };
#
#[derive(GraphQLScalar)]
#[graphql(with = string_or_int)]
#[graphql(
with = string_or_int,
parse_token(String, i32)
)]
enum StringOrInt {
String(String),
Int(i32),
@ -309,61 +315,22 @@ mod string_or_int {
.ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
}
pub(super) fn parse_token<S>(value: ScalarToken<'_>) -> ParseScalarResult<S>
where
S: ScalarValue,
{
<String as ParseScalarValue<S>>::from_str(value)
.or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
}
// No need in `parse_token()` function.
}
#
# fn main() {}
```
Also, you can partially override `#[graphql(with)]` attribute with other custom scalars.
> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLScalar)]`][8] and [`#[graphql_scalar]`][9] attributes.
```rust
# extern crate juniper;
# use juniper::{GraphQLScalar, InputValue, ParseScalarResult, ScalarValue, ScalarToken, Value};
#
#[derive(GraphQLScalar)]
#[graphql(parse_token(String, i32))]
enum StringOrInt {
String(String),
Int(i32),
}
impl StringOrInt {
fn to_output<S>(&self) -> Value<S>
where
S: ScalarValue,
{
match self {
Self::String(s) => Value::scalar(s.to_owned()),
Self::Int(i) => Value::scalar(*i),
}
}
fn from_input<S>(v: &InputValue<S>) -> Result<Self, String>
where
S: ScalarValue,
{
v.as_string_value()
.map(|s| Self::String(s.into()))
.or_else(|| v.as_int_value().map(Self::Int))
.ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
}
}
#
# fn main() {}
```
### Using foreign types as scalars
## Foreign
For implementing custom scalars on foreign types there is `#[graphql_scalar]` attribute macro.
For implementing [custom scalars][2] on foreign types there is [`#[graphql_scalar]`][9] attribute.
> __NOTE:__ To satisfy [orphan rules] you should provide local [`ScalarValue`] implementation.
> **NOTE**: To satisfy [orphan rules], we should provide a local [`ScalarValue`] implementation.
```rust
# extern crate juniper;
@ -391,10 +358,10 @@ use juniper::{graphql_scalar, InputValue, ScalarValue, Value};
with = date_scalar,
parse_token(String),
scalar = CustomScalarValue,
// ^^^^^^^^^^^^^^^^^ Local `ScalarValue` implementation.
)]
// ^^^^^^^^^^^^^^^^^ local `ScalarValue` implementation
type Date = date::Date;
// ^^^^^^^^^^ Type from another crate.
// ^^^^^^^^^^ type from another crate
mod date_scalar {
use super::*;
@ -413,5 +380,78 @@ mod date_scalar {
# fn main() {}
```
[orphan rules]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
### Supported out-of-the-box
[Juniper] provides out-of-the-box [GraphQL scalar][0] implementations for some very common [Rust] crates. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature].
| [Rust] type | [GraphQL] scalar | [Cargo feature] |
|-----------------------------|------------------|------------------|
| [`BigDecimal`] | `BigDecimal` | [`bigdecimal`] |
| [`bson::oid::ObjectId`] | `ObjectId` | [`bson`] |
| [`bson::DateTime`] | `UtcDateTime` | [`bson`] |
| [`chrono::NaiveDate`] | [`Date`] | [`chrono`] |
| [`chrono::NaiveTime`] | [`LocalTime`] | [`chrono`] |
| [`chrono::NaiveDateTime`] | `LocalDateTime` | [`chrono`] |
| [`chrono::DateTime`] | [`DateTime`] | [`chrono`] |
| [`chrono_tz::Tz`] | `TimeZone` | [`chrono-tz`] |
| [`Decimal`] | `Decimal` | [`rust_decimal`] |
| [`time::Date`] | [`Date`] | [`time`] |
| [`time::Time`] | [`LocalTime`] | [`time`] |
| [`time::PrimitiveDateTime`] | `LocalDateTime` | [`time`] |
| [`time::OffsetDateTime`] | [`DateTime`] | [`time`] |
| [`time::UtcOffset`] | [`UtcOffset`] | [`time`] |
| [`Url`] | `Url` | [`url`] |
| [`Uuid`] | `Uuid` | [`uuid`] |
[`bigdecimal`]: https://docs.rs/bigdecimal
[`BigDecimal`]: https://docs.rs/bigdecimal/latest/bigdecimal/struct.BigDecimal.html
[`bson`]: https://docs.rs/bson
[`bson::DateTime`]: https://docs.rs/bson/latest/bson/struct.DateTime.html
[`bson::oid::ObjectId`]: https://docs.rs/bson/latest/bson/oid/struct.ObjectId.html
[`chrono`]: https://docs.rs/chrono
[`chrono::DateTime`]: https://docs.rs/chrono/latest/chrono/struct.DateTime.html
[`chrono::NaiveDate`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDate.html
[`chrono::NaiveDateTime`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDateTime.html
[`chrono::NaiveTime`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveTime.html
[`chrono-tz`]: https://docs.rs/chrono-tz
[`chrono_tz::Tz`]: https://docs.rs/chrono-tz/latest/chrono_tz/enum.Tz.html
[`Date`]: https://graphql-scalars.dev/docs/scalars/date
[`DateTime`]: https://graphql-scalars.dev/docs/scalars/date-time
[`Decimal`]: https://docs.rs/rust_decimal/latest/rust_decimal/struct.Decimal.html
[`ID`]: https://spec.graphql.org/October2021#sec-ID
[`LocalTime`]: https://graphql-scalars.dev/docs/scalars/local-time
[`rust_decimal`]: https://docs.rs/rust_decimal
[`ScalarValue`]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
[`serde`]: https://docs.rs/serde
[`time`]: https://docs.rs/time
[`time::Date`]: https://docs.rs/time/latest/time/struct.Date.html
[`time::PrimitiveDateTime`]: https://docs.rs/time/latest/time/struct.PrimitiveDateTime.html
[`time::Time`]: https://docs.rs/time/latest/time/struct.Time.html
[`time::UtcOffset`]: https://docs.rs/time/latest/time/struct.UtcOffset.html
[`time::OffsetDateTime`]: https://docs.rs/time/latest/time/struct.OffsetDateTime.html
[`url`]: https://docs.rs/url
[`Url`]: https://docs.rs/url/latest/url/struct.Url.html
[`UtcOffset`]: https://graphql-scalars.dev/docs/scalars/utc-offset
[`uuid`]: https://docs.rs/uuid
[`Uuid`]: https://docs.rs/uuid/latest/uuid/struct.Uuid.html
[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[orphan rules]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
[Rust]: https://www.rust-lang.org
[schema]: https://graphql.org/learn/schema
[0]: https://spec.graphql.org/October2021#sec-Scalars
[1]: https://spec.graphql.org/October2021#sel-FAHXJDCAACKB1qb
[2]: https://spec.graphql.org/October2021#sec-Scalars.Custom-Scalars
[3]: https://rust-unofficial.github.io/patterns/patterns/behavioural/newtype.html
[4]: https://doc.rust-lang.org/reference/items/type-aliases.html
[5]: https://spec.graphql.org/October2021/#sec-Scalars.Built-in-Scalars
[6]: https://serde.rs/container-attrs.html#transparent
[7]: https://spec.graphql.org/October2021#sec-Value-Resolution
[8]: https://docs.rs/juniper/latest/juniper/derive.GraphQLScalar.html
[9]: https://docs.rs/juniper/latest/juniper/attr.graphql_scalar.html

531
book/src/types/unions.md
View file

@ -1,25 +1,17 @@
Unions
======
From the server's point of view, [GraphQL unions][1] are somewhat similar to [interfaces][5] - the main difference is that they don't contain fields on their own.
> [GraphQL unions][0] represent an object that could be one of a list of [GraphQL object][10] types, but provides for no guaranteed fields between those types. They also differ from [interfaces][12] in that [object][10] types declare what [interfaces][12] they implement, but are not aware of what [unions][0] contain them.
The most obvious and straightforward way to represent a [GraphQL union][1] in Rust is enum. However, we also can do so either with trait or a regular struct. That's why, for implementing [GraphQL unions][1] Juniper provides:
- `#[derive(GraphQLUnion)]` macro for enums and structs.
- `#[graphql_union]` for traits.
## Enums
Most of the time, we just need a trivial and straightforward Rust enum to represent a [GraphQL union][1].
From the server's point of view, [GraphQL unions][0] are somewhat similar to [interfaces][12]: the main difference is that they don't contain fields on their own, and so, we only need to represent a value, _dispatchable_ into concrete [objects][10].
Obviously, the most straightforward approach to express [GraphQL unions][0] in [Rust] is to use [enums][22]. In [Juniper] this may be done by using [`#[derive(GraphQLInterface)]`][2] attribute on them:
```rust
# extern crate juniper;
# extern crate derive_more;
use derive_more::From;
use juniper::{GraphQLObject, GraphQLUnion};
# extern crate juniper;
# use derive_more::From;
# use juniper::{GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
struct Human {
id: String,
@ -33,6 +25,7 @@ struct Droid {
}
#[derive(From, GraphQLUnion)]
// ^^^^ only for convenience, and may be omitted
enum Character {
Human(Human),
Droid(Droid),
@ -42,22 +35,93 @@ enum Character {
```
### Ignoring enum variants
### Renaming
In some rare situations we may want to omit exposing an enum variant in the GraphQL schema.
Just as with [renaming GraphQL objects](objects/index.md#renaming), we can override the default [union][0] name by using the `#[graphql(name = "...")]` attribute:
```rust
# extern crate juniper;
# use juniper::{GraphQLObject, GraphQLUnion};
#
# #[derive(GraphQLObject)]
# struct Human {
# id: String,
# home_planet: String,
# }
#
# #[derive(GraphQLObject)]
# struct Droid {
# id: String,
# primary_function: String,
# }
#
#[derive(GraphQLUnion)]
#[graphql(name = "CharacterUnion")]
enum Character { // exposed as `CharacterUnion` in GraphQL schema
Human(Human),
Droid(Droid),
}
#
# fn main() {}
```
> **NOTE**: Unlike [Rust enum variants][22], [GraphQL union members][0] don't have any special names aside from the ones provided by [objects][10] themselves, and so, obviously, **cannot be renamed**.
### Documentation
Similarly to [documenting GraphQL objects](objects/index.md#documentation), we can [document][7] a [GraphQL union][0] via `#[graphql(description = "...")]` attribute or [Rust doc comments][6]:
```rust
# extern crate juniper;
# use juniper::{GraphQLObject, GraphQLUnion};
#
# #[derive(GraphQLObject)]
# struct Human {
# id: String,
# home_planet: String,
# }
#
# #[derive(GraphQLObject)]
# struct Droid {
# id: String,
# primary_function: String,
# }
#
/// This doc comment is visible in both Rust API docs and GraphQL schema
/// descriptions.
#[derive(GraphQLUnion)]
enum Character {
/// This doc comment is visible only in Rust API docs.
Human(Human),
/// This doc comment is visible only in Rust API docs.
Droid(Droid),
}
/// This doc comment is visible only in Rust API docs.
#[derive(GraphQLUnion)]
#[graphql(description = "This description overwrites the one from doc comment.")]
// ^^^^^^^^^^^ or `desc` shortcut, up to your preference
enum Person {
/// This doc comment is visible only in Rust API docs.
Human(Human),
}
#
# fn main() {}
```
> **NOTE**: Unlike [Rust enum variants][22], [GraphQL union members][0] don't have any special constructors aside from the provided [objects][10] directly, and so, **cannot be [documented][7]**, but rather reuse [object descriptions][7] "as is".
### Ignoring
In some rare situations we may want to omit exposing an [enum][22] variant in a [GraphQL schema][1]. [Similarly to GraphQL enums](enums.md#ignoring), we can just annotate the variant with the `#[graphql(ignore)]` attribute.
As an example, let's consider the situation where we need to bind some type parameter `T` for doing interesting type-level stuff in our resolvers. To achieve this we need to have `PhantomData<T>`, but we don't want it exposed in the GraphQL schema.
> __WARNING__:
> It's the _library user's responsibility_ to ensure that ignored enum variant is _never_ returned from resolvers, otherwise resolving the GraphQL query will __panic at runtime__.
```rust
# extern crate juniper;
# extern crate derive_more;
# extern crate juniper;
# use std::marker::PhantomData;
use derive_more::From;
use juniper::{GraphQLObject, GraphQLUnion};
# use derive_more::From;
# use juniper::{GraphQLObject, GraphQLUnion};
#
#[derive(GraphQLObject)]
struct Human {
id: String,
@ -75,417 +139,30 @@ enum Character<S> {
Human(Human),
Droid(Droid),
#[from(ignore)]
#[graphql(ignore)] // or `#[graphql(skip)]`, your choice
#[graphql(ignore)]
// ^^^^^^ or `skip`, up to your preference
_State(PhantomData<S>),
}
#
# fn main() {}
```
> **WARNING**: It's the _library user's responsibility_ to ensure that ignored [enum][22] variant is **never** returned from resolvers, otherwise resolving the [GraphQL] query will **panic in runtime**.
> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLUnion)]`][2] attribute.
### External resolver functions
If some custom logic is needed to resolve a [GraphQL union][1] variant, you may specify an external function to do so:
```rust
# #![allow(dead_code)]
# extern crate juniper;
use juniper::{GraphQLObject, GraphQLUnion};
#[derive(GraphQLObject)]
#[graphql(Context = CustomContext)]
struct Human {
id: String,
home_planet: String,
}
[GraphQL]: https://graphql.org
[Juniper]: https://docs.rs/juniper
[Rust]: https://www.rust-lang.org
#[derive(GraphQLObject)]
#[graphql(Context = CustomContext)]
struct Droid {
id: String,
primary_function: String,
}
pub struct CustomContext {
droid: Droid,
}
impl juniper::Context for CustomContext {}
#[derive(GraphQLUnion)]
#[graphql(Context = CustomContext)]
enum Character {
Human(Human),
#[graphql(with = Character::droid_from_context)]
Droid(Droid),
}
impl Character {
// NOTICE: The function signature must contain `&self` and `&Context`,
// and return `Option<&VariantType>`.
fn droid_from_context<'c>(&self, ctx: &'c CustomContext) -> Option<&'c Droid> {
Some(&ctx.droid)
}
}
#
# fn main() {}
```
With an external resolver function we can even declare a new [GraphQL union][1] variant where the Rust type is absent in the initial enum definition. The attribute syntax `#[graphql(on VariantType = resolver_fn)]` follows the [GraphQL syntax for dispatching union variants](https://spec.graphql.org/October2021#example-f8163).
```rust
# #![allow(dead_code)]
# extern crate juniper;
use juniper::{GraphQLObject, GraphQLUnion};
#[derive(GraphQLObject)]
#[graphql(Context = CustomContext)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
#[graphql(Context = CustomContext)]
struct Droid {
id: String,
primary_function: String,
}
#[derive(GraphQLObject)]
#[graphql(Context = CustomContext)]
struct Ewok {
id: String,
is_funny: bool,
}
pub struct CustomContext {
ewok: Ewok,
}
impl juniper::Context for CustomContext {}
#[derive(GraphQLUnion)]
#[graphql(Context = CustomContext)]
#[graphql(on Ewok = Character::ewok_from_context)]
enum Character {
Human(Human),
Droid(Droid),
#[graphql(ignore)] // or `#[graphql(skip)]`, your choice
Ewok,
}
impl Character {
fn ewok_from_context<'c>(&self, ctx: &'c CustomContext) -> Option<&'c Ewok> {
if let Self::Ewok = self {
Some(&ctx.ewok)
} else {
None
}
}
}
#
# fn main() {}
```
## Structs
Using Rust structs as [GraphQL unions][1] is very similar to using enums, with the nuance that specifying an external resolver function is the only way to declare a [GraphQL union][1] variant.
```rust
# extern crate juniper;
# use std::collections::HashMap;
use juniper::{GraphQLObject, GraphQLUnion};
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Droid {
id: String,
primary_function: String,
}
struct Database {
humans: HashMap<String, Human>,
droids: HashMap<String, Droid>,
}
impl juniper::Context for Database {}
#[derive(GraphQLUnion)]
#[graphql(
Context = Database,
on Human = Character::get_human,
on Droid = Character::get_droid,
)]
struct Character {
id: String,
}
impl Character {
fn get_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human>{
ctx.humans.get(&self.id)
}
fn get_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid>{
ctx.droids.get(&self.id)
}
}
#
# fn main() {}
```
## Traits
To use a Rust trait definition as a [GraphQL union][1] you need to use the `#[graphql_union]` macro. [Rust doesn't allow derive macros on traits](https://doc.rust-lang.org/stable/reference/procedural-macros.html#derive-macros), so using `#[derive(GraphQLUnion)]` on traits doesn't work.
> __NOTICE__:
> A __trait has to be [object safe](https://doc.rust-lang.org/stable/reference/items/traits.html#object-safety)__, because schema resolvers will need to return a [trait object](https://doc.rust-lang.org/stable/reference/types/trait-object.html) to specify a [GraphQL union][1] behind it.
```rust
# extern crate juniper;
use juniper::{graphql_union, GraphQLObject};
#[derive(GraphQLObject)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
struct Droid {
id: String,
primary_function: String,
}
#[graphql_union]
trait Character {
// NOTICE: The method signature must contain `&self` and return `Option<&VariantType>`.
fn as_human(&self) -> Option<&Human> { None }
fn as_droid(&self) -> Option<&Droid> { None }
}
impl Character for Human {
fn as_human(&self) -> Option<&Human> { Some(&self) }
}
impl Character for Droid {
fn as_droid(&self) -> Option<&Droid> { Some(&self) }
}
#
# fn main() {}
```
### Custom context
If a [`Context`][6] is required in a trait method to resolve a [GraphQL union][1] variant, specify it as an argument.
```rust
# #![allow(unused_variables)]
# extern crate juniper;
# use std::collections::HashMap;
use juniper::{graphql_union, GraphQLObject};
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Droid {
id: String,
primary_function: String,
}
struct Database {
humans: HashMap<String, Human>,
droids: HashMap<String, Droid>,
}
impl juniper::Context for Database {}
#[graphql_union(context = Database)]
trait Character {
// NOTICE: The method signature may optionally contain `&Context`.
fn as_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> { None }
fn as_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid> { None }
}
impl Character for Human {
fn as_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> {
ctx.humans.get(&self.id)
}
}
impl Character for Droid {
fn as_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid> {
ctx.droids.get(&self.id)
}
}
#
# fn main() {}
```
### Ignoring trait methods
As with enums, we may want to omit some trait methods to be assumed as [GraphQL union][1] variants and ignore them.
```rust
# extern crate juniper;
use juniper::{graphql_union, GraphQLObject};
#[derive(GraphQLObject)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
struct Droid {
id: String,
primary_function: String,
}
#[graphql_union]
trait Character {
fn as_human(&self) -> Option<&Human> { None }
fn as_droid(&self) -> Option<&Droid> { None }
#[graphql(ignore)] // or `#[graphql(skip)]`, your choice
fn id(&self) -> &str;
}
impl Character for Human {
fn as_human(&self) -> Option<&Human> { Some(&self) }
fn id(&self) -> &str { self.id.as_str() }
}
impl Character for Droid {
fn as_droid(&self) -> Option<&Droid> { Some(&self) }
fn id(&self) -> &str { self.id.as_str() }
}
#
# fn main() {}
```
### External resolver functions
Similarly to enums and structs, it's not mandatory to use trait methods as [GraphQL union][1] variant resolvers. Instead, custom functions may be specified:
```rust
# extern crate juniper;
# use std::collections::HashMap;
use juniper::{graphql_union, GraphQLObject};
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
#[graphql(Context = Database)]
struct Droid {
id: String,
primary_function: String,
}
struct Database {
humans: HashMap<String, Human>,
droids: HashMap<String, Droid>,
}
impl juniper::Context for Database {}
#[graphql_union(context = Database)]
#[graphql_union(
on Human = DynCharacter::get_human,
on Droid = get_droid,
)]
trait Character {
#[graphql(ignore)] // or `#[graphql(skip)]`, your choice
fn id(&self) -> &str;
}
impl Character for Human {
fn id(&self) -> &str { self.id.as_str() }
}
impl Character for Droid {
fn id(&self) -> &str { self.id.as_str() }
}
// The trait object is always `Send` and `Sync`.
type DynCharacter<'a> = dyn Character + Send + Sync + 'a;
impl<'a> DynCharacter<'a> {
fn get_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> {
ctx.humans.get(self.id())
}
}
// External resolver function doesn't have to be a method of a type.
// It's only a matter of the function signature to match the requirements.
fn get_droid<'db>(ch: &DynCharacter<'_>, ctx: &'db Database) -> Option<&'db Droid> {
ctx.droids.get(ch.id())
}
#
# fn main() {}
```
## `ScalarValue` considerations
By default, `#[derive(GraphQLUnion)]` and `#[graphql_union]` macros generate code, which is generic over a [`ScalarValue`][2] type. This may introduce a problem when at least one of [GraphQL union][1] variants is restricted to a concrete [`ScalarValue`][2] type in its implementation. To resolve such problem, a concrete [`ScalarValue`][2] type should be specified:
```rust
# #![allow(dead_code)]
# extern crate juniper;
use juniper::{DefaultScalarValue, GraphQLObject, GraphQLUnion};
#[derive(GraphQLObject)]
#[graphql(Scalar = DefaultScalarValue)]
struct Human {
id: String,
home_planet: String,
}
#[derive(GraphQLObject)]
struct Droid {
id: String,
primary_function: String,
}
#[derive(GraphQLUnion)]
#[graphql(Scalar = DefaultScalarValue)] // removing this line will fail compilation
enum Character {
Human(Human),
Droid(Droid),
}
#
# fn main() {}
```
[1]: https://spec.graphql.org/October2021#sec-Unions
[2]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
[5]: https://spec.graphql.org/October2021#sec-Interfaces
[6]: https://docs.rs/juniper/0.14.2/juniper/trait.Context.html
[0]: https://spec.graphql.org/October2021#sec-Unions
[1]: https://graphql.org/learn/schema
[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLUnion.html
[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
[7]: https://spec.graphql.org/October2021#sec-Descriptions
[10]: https://spec.graphql.org/October2021#sec-Objects
[11]: https://spec.graphql.org/October2021#sec-Enums
[12]: https://spec.graphql.org/October2021#sec-Interfaces
[22]: https://doc.rust-lang.org/reference/items/enumerations.html#enumerations

2
juniper/CHANGELOG.md
View file

@ -68,6 +68,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
- Made `LookAheadSelection::arguments()` returning iterator over `LookAheadArgument`.
- Made `LookAheadSelection::children()` returning `LookAheadChildren`.
- Added `Span` to `Arguments` and `LookAheadArguments`. ([#1206], [#1209])
- Disabled `bson`, `url`, `uuid` and `schema-language` [Cargo feature]s by default. ([#1230])
### Added
@ -164,6 +165,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
[#1215]: /../../pull/1215
[#1227]: /../../pull/1227
[#1228]: /../../pull/1228
[#1230]: /../../pull/1230
[#1237]: /../../pull/1237
[#1239]: /../../pull/1239
[#1246]: /../../pull/1246

8
juniper/Cargo.toml
View file

@ -13,7 +13,7 @@ authors = [
"Kai Ren <tyranron@gmail.com>",
]
documentation = "https://docs.rs/juniper"
homepage = "https://graphql-rust.github.io"
homepage = "https://graphql-rust.github.io/juniper"
repository = "https://github.com/graphql-rust/juniper"
readme = "README.md"
categories = ["asynchronous", "web-programming", "web-programming::http-server"]
@ -25,12 +25,6 @@ all-features = true
rustdoc-args = ["--cfg", "docsrs"]
[features]
default = [
"bson",
"schema-language",
"url",
"uuid",
]
anyhow = ["dep:anyhow"]
backtrace = ["anyhow?/backtrace"]
bigdecimal = ["dep:bigdecimal", "dep:num-bigint", "dep:ryu"]

22
juniper/README.md
View file

@ -42,20 +42,19 @@ As an exception to other [GraphQL] libraries for other languages, [Juniper] buil
## Integrations
### Data types
### Types
[Juniper] has automatic integration with some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically:
- [`bigdecimal`] (feature gated)
[Juniper] provides out-of-the-box integration for some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature]:
- [`bigdecimal`]
- [`bson`]
- [`chrono`] (feature gated)
- [`chrono-tz`] (feature gated)
- [`rust_decimal`] (feature gated)
- [`time`] (feature gated)
- [`chrono`], [`chrono-tz`]
- [`rust_decimal`]
- [`time`]
- [`url`]
- [`uuid`]
### Web servers
### Web server frameworks
- [`actix-web`] ([`juniper_actix`] crate)
- [`axum`] ([`juniper_axum`] crate)
@ -66,7 +65,7 @@ As an exception to other [GraphQL] libraries for other languages, [Juniper] buil
## API Stability
## API stability
[Juniper] has not reached 1.0 yet, thus some API instability should be expected.
@ -98,13 +97,14 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`url`]: https://docs.rs/url
[`uuid`]: https://docs.rs/uuid
[`warp`]: https://docs.rs/warp
[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
[Facebook]: https://facebook.com
[GraphiQL]: https://github.com/graphql/graphiql
[GraphQL]: http://graphql.org
[GraphQL Playground]: https://github.com/graphql/graphql-playground
[Juniper]: https://docs.rs/juniper
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Juniper Book edge]: https://graphql-rust.github.io/juniper/master
[Rust]: https://www.rust-lang.org
[1]: https://graphql-rust.github.io/quickstart.html
[1]: https://graphql-rust.github.io/juniper/quickstart.html

107
juniper/release.toml
View file

@ -1,34 +1,3 @@
[[pre-release-replacements]]
file = "../book/src/advanced/dataloaders.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/advanced/subscriptions.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/quickstart.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/servers/hyper.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/servers/rocket.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/servers/warp.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../juniper_actix/Cargo.toml"
exactly = 2
@ -89,3 +58,79 @@ file = "README.md"
exactly = 2
search = "graphql-rust/juniper/blob/[^/]+/"
replace = "graphql-rust/juniper/blob/{{crate_name}}-v{{version}}/"
[[pre-release-replacements]]
file = "../book/src/quickstart.md"
exactly = 1
search = "juniper = \"[^\"]+\""
replace = "juniper = \"{{version}}\""
[[pre-release-replacements]]
file = "../book/src/quickstart.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/advanced/implicit_and_explicit_null.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/advanced/lookahead.md"
exactly = 6
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/schema/index.md"
exactly = 5
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/schema/introspection.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/schema/subscriptions.md"
exactly = 3
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/enums.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/input_objects.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/interfaces.md"
exactly = 2
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/scalars.md"
exactly = 3
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/unions.md"
exactly = 1
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/objects/complex_fields.md"
exactly = 2
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/objects/index.md"
exactly = 3
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"
[[pre-release-replacements]]
file = "../book/src/types/objects/error/field.md"
exactly = 3
search = "docs.rs/juniper/[^/]+/"
replace = "docs.rs/juniper/{{version}}/"

2
juniper/src/executor/look_ahead.rs
View file

@ -441,6 +441,8 @@ impl<'a, S> LookAheadChildren<'a, S> {
}
/// Returns the possibly aliased names of the top-level children from the current [selection].
///
/// [selection]: https://spec.graphql.org/October2021#sec-Selection-Sets
pub fn names(&self) -> impl DoubleEndedIterator<Item = &'a str> + '_ {
self.children.iter().map(|sel| sel.field_name())
}

2
juniper/src/schema/model.rs
View file

@ -184,7 +184,7 @@ where
/// }
/// }
///
/// type Schema = RootNode<'static, Query, EmptyMutation<()>, EmptySubscription<()>>;
/// type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
///
/// let schema = Schema::new(Query, EmptyMutation::new(), EmptySubscription::new())
/// .disable_introspection();

2
juniper_actix/README.md
View file

@ -43,7 +43,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`juniper_actix`]: https://docs.rs/juniper_actix
[`juniper_warp`]: https://docs.rs/juniper_warp
[GraphQL]: http://graphql.org
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Rust]: https://www.rust-lang.org
[1]: https://github.com/graphql-rust/juniper/blob/master/juniper_actix/examples/subscription.rs

2
juniper_axum/README.md
View file

@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`juniper`]: https://docs.rs/juniper
[`juniper_axum`]: https://docs.rs/juniper_axum
[GraphQL]: http://graphql.org
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Rust]: https://www.rust-lang.org
[1]: https://github.com/graphql-rust/juniper/blob/master/juniper_axum/examples/simple.rs

44
juniper_codegen/src/lib.rs
View file

@ -200,13 +200,17 @@ use self::common::diagnostic::{self, ResultExt as _};
/// struct Point2D {
/// x: f64,
/// y: f64,
/// #[graphql(ignore)]
/// shift: f64, // `Default::default()` impl is used.
/// #[graphql(skip, default = System::Cartesian)]
/// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^
/// // This attribute is required, as we need to be to construct `Point2D`
/// // from `{ x: 0.0, y: 0.0 }` GraphQL input.
/// #[graphql(ignore, default = System::Cartesian)]
/// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^
/// // This attribute is required, as we need to be able to construct
/// // a `Point2D` value from the `{ x: 0.0, y: 0.0 }` GraphQL input value,
/// // received from client-side.
/// system: System,
/// // `Default::default()` value is used, if no
/// // `#[graphql(default = <expression>)]` is specified.
/// #[graphql(skip)]
/// // ^^^^ alternative naming, up to your preference
/// shift: f64,
/// }
/// ```
///
@ -320,6 +324,9 @@ pub fn derive_input_object(input: TokenStream) -> TokenStream {
/// Jedi,
/// #[graphql(ignore)]
/// Legends(T),
/// #[graphql(skip)]
/// // ^^^^ alternative naming, up to your preference
/// CloneWars(T),
/// }
/// ```
///
@ -358,10 +365,10 @@ pub fn derive_enum(input: TokenStream) -> TokenStream {
///
/// # Transparent delegation
///
/// Sometimes, you want to create a custom [GraphQL scalar][0] type by just
/// Quite often we want to create a custom [GraphQL scalar][0] type by just
/// wrapping an existing one, inheriting all its behavior. In Rust, this is
/// often called as ["`Newtype` pattern"][1]. This may be achieved by providing
/// a `#[graphql(transparent)]` attribute to the definition:
/// often called as ["newtype pattern"][1]. This is achieved by annotating
/// the definition with the `#[graphql(transparent)]` attribute:
/// ```rust
/// # use juniper::{GraphQLObject, GraphQLScalar};
/// #
@ -502,10 +509,10 @@ pub fn derive_enum(input: TokenStream) -> TokenStream {
/// .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
/// }
/// ```
/// > __NOTE:__ Once we provide all 3 custom functions, there is no sense to
/// > follow [`Newtype` pattern][1] anymore.
/// > __NOTE:__ Once we provide all 3 custom functions, there is no sense in
/// > following the [newtype pattern][1] anymore.
///
/// # All at once
/// # Full behavior
///
/// Instead of providing all custom functions separately, it's possible to
/// provide a module holding the appropriate `to_output()`, `from_input()` and
@ -693,7 +700,7 @@ pub fn derive_scalar(input: TokenStream) -> TokenStream {
/// # Foreign types
///
/// Additionally, `#[graphql_scalar]` can be used directly on foreign types via
/// type alias, without using [`Newtype` pattern][1].
/// type alias, without using the [newtype pattern][1].
///
/// > __NOTE:__ To satisfy [orphan rules] you should provide local
/// > [`ScalarValue`] implementation.
@ -746,7 +753,7 @@ pub fn derive_scalar(input: TokenStream) -> TokenStream {
/// }
/// }
/// #
/// # fn main() { }
/// # fn main() {}
/// ```
///
/// [0]: https://spec.graphql.org/October2021#sec-Scalars
@ -1350,9 +1357,9 @@ pub fn graphql_interface(attr: TokenStream, body: TokenStream) -> TokenStream {
/// }
/// ```
///
/// For more info and possibilities see [`#[graphql_interface]`] macro.
/// For more info and possibilities see [`#[graphql_interface]`][0] macro.
///
/// [`#[graphql_interface]`]: crate::graphql_interface
/// [0]: crate::graphql_interface
/// [1]: https://spec.graphql.org/October2021#sec-Interfaces
#[proc_macro_derive(GraphQLInterface, attributes(graphql))]
pub fn derive_interface(body: TokenStream) -> TokenStream {
@ -1461,6 +1468,9 @@ pub fn derive_interface(body: TokenStream) -> TokenStream {
/// id: String,
/// #[graphql(ignore)]
/// home_planet: String,
/// #[graphql(skip)]
/// // ^^^^ alternative naming, up to your preference
/// password_hash: String,
/// }
/// ```
///
@ -1576,7 +1586,7 @@ pub fn derive_object(body: TokenStream) -> TokenStream {
///
/// // This method is useful only to define GraphQL fields, but is not
/// // a field itself, so we ignore it in schema.
/// #[graphql(ignore)]
/// #[graphql(ignore)] // or `#[graphql(skip)]`, up to your preference
/// fn build_full_name(&self) -> String {
/// format!("{} {}", self.first_name, self.last_name)
/// }

2
juniper_hyper/README.md
View file

@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`juniper`]: https://docs.rs/juniper
[`juniper_hyper`]: https://docs.rs/juniper_hyper
[GraphQL]: http://graphql.org
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Rust]: https://www.rust-lang.org
[1]: https://github.com/graphql-rust/juniper/blob/master/juniper_hyper/examples/hyper_server.rs

6
juniper_hyper/release.toml
View file

@ -1,9 +1,3 @@
[[pre-release-replacements]]
file = "../book/src/servers/hyper.md"
exactly = 1
search = "juniper_hyper = \"[^\"]+\""
replace = "juniper_hyper = \"{{version}}\""
[[pre-release-replacements]]
file = "CHANGELOG.md"
max = 1

2
juniper_rocket/README.md
View file

@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`juniper_rocket`]: https://docs.rs/juniper_rocket
[`rocket`]: https://docs.rs/rocket
[GraphQL]: http://graphql.org
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Rust]: https://www.rust-lang.org
[1]: https://github.com/graphql-rust/juniper/blob/master/juniper_rocket/examples/simple.rs

6
juniper_rocket/release.toml
View file

@ -1,9 +1,3 @@
[[pre-release-replacements]]
file = "../book/src/servers/rocket.md"
exactly = 1
search = "juniper_rocket = \"[^\"]+\""
replace = "juniper_rocket = \"{{version}}\""
[[pre-release-replacements]]
file = "CHANGELOG.md"
max = 1

12
juniper_subscriptions/release.toml
View file

@ -1,9 +1,3 @@
[[pre-release-replacements]]
file = "../book/src/advanced/subscriptions.md"
exactly = 1
search = "juniper_subscriptions = \"[^\"]+\""
replace = "juniper_subscriptions = \"{{version}}\""
[[pre-release-replacements]]
file = "../juniper_graphql_ws/Cargo.toml"
exactly = 1
@ -22,3 +16,9 @@ file = "README.md"
exactly = 3
search = "graphql-rust/juniper/blob/[^/]+/"
replace = "graphql-rust/juniper/blob/{{crate_name}}-v{{version}}/"
[[pre-release-replacements]]
file = "../book/src/schema/subscriptions.md"
exactly = 2
search = "docs.rs/juniper_subscriptions/[^/]+/"
replace = "docs.rs/juniper_subscriptions/{{version}}/"

2
juniper_warp/README.md
View file

@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
[`juniper_warp`]: https://docs.rs/juniper_warp
[`warp`]: https://docs.rs/warp
[GraphQL]: http://graphql.org
[Juniper Book]: https://graphql-rust.github.io
[Juniper Book]: https://graphql-rust.github.io/juniper
[Rust]: https://www.rust-lang.org
[1]: https://github.com/graphql-rust/juniper/blob/master/juniper_warp/examples/subscription.rs

6
juniper_warp/release.toml
View file

@ -1,9 +1,3 @@
[[pre-release-replacements]]
file = "../book/src/servers/warp.md"
exactly = 1
search = "juniper_warp = \"[^\"]+\""
replace = "juniper_warp = \"{{version}}\""
[[pre-release-replacements]]
file = "CHANGELOG.md"
max = 1

24
tests/codegen/fail/input-object/derive_incompatible_field_type.stderr
View file

@ -10,9 +10,9 @@ error[E0277]: the trait bound `ObjectA: IsInputType<__S>` is not satisfied
<f64 as IsInputType<__S>>
<Object as IsInputType<__S>>
<Box<T> as IsInputType<S>>
<uuid::Uuid as IsInputType<__S>>
<url::Url as IsInputType<__S>>
<bson::datetime::DateTime as IsInputType<__S>>
<juniper::schema::model::DirectiveLocation as IsInputType<__S>>
<Arc<T> as IsInputType<S>>
<Vec<T> as IsInputType<S>>
and $N others
error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
@ -30,9 +30,9 @@ error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
<f64 as FromInputValue<__S>>
<Object as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
and $N others
note: required by a bound in `Registry::<'r, S>::arg`
--> $WORKSPACE/juniper/src/executor/mod.rs
@ -55,9 +55,9 @@ error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
<f64 as FromInputValue<__S>>
<Object as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
and $N others
= note: this error originates in the derive macro `GraphQLInputObject` (in Nightly builds, run with -Z macro-backtrace for more info)
@ -73,8 +73,8 @@ error[E0277]: the trait bound `ObjectA: ToInputValue<_>` is not satisfied
<f64 as ToInputValue<__S>>
<Object as ToInputValue<__S>>
<Box<T> as ToInputValue<S>>
<uuid::Uuid as ToInputValue<__S>>
<url::Url as ToInputValue<__S>>
<bson::datetime::DateTime as ToInputValue<__S>>
<juniper::schema::model::DirectiveLocation as ToInputValue<__S>>
<Arc<T> as ToInputValue<S>>
<Vec<T> as ToInputValue<S>>
and $N others
= note: this error originates in the derive macro `GraphQLInputObject` (in Nightly builds, run with -Z macro-backtrace for more info)

6
tests/codegen/fail/interface/struct/attr_field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<CharacterValueEnum as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

6
tests/codegen/fail/interface/struct/derive_field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<CharacterValueEnum as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

12
tests/codegen/fail/interface/trait/argument_non_input_type.stderr
View file

@ -9,10 +9,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
<i32 as IsInputType<__S>>
<f64 as IsInputType<__S>>
<Box<T> as IsInputType<S>>
<uuid::Uuid as IsInputType<__S>>
<url::Url as IsInputType<__S>>
<bson::datetime::DateTime as IsInputType<__S>>
<juniper::schema::model::DirectiveLocation as IsInputType<__S>>
<Arc<T> as IsInputType<S>>
<Vec<T> as IsInputType<S>>
<TypeKind as IsInputType<__S>>
and $N others
error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@ -29,10 +29,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others
note: required by a bound in `Registry::<'r, S>::arg`
--> $WORKSPACE/juniper/src/executor/mod.rs

14
tests/codegen/fail/interface/trait/argument_wrong_default_array.stderr
View file

@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
|
= help: the following other types implement trait `From<T>`:
<[bool; N] as From<Mask<T, N>>>
<[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
<[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
<[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
<[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
<[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
<[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
<[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
<[T; N] as From<Simd<T, N>>>
<[T; 1] as From<(T,)>>
<[T; 2] as From<(T, T)>>
<[T; 3] as From<(T, T, T)>>
<[T; 4] as From<(T, T, T, T)>>
<[T; 5] as From<(T, T, T, T, T)>>
<[T; 6] as From<(T, T, T, T, T, T)>>
and $N others
= note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
= note: this error originates in the attribute macro `graphql_interface` (in Nightly builds, run with -Z macro-backtrace for more info)

6
tests/codegen/fail/interface/trait/field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<CharacterValueEnum as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

24
tests/codegen/fail/object/argument_non_input_type.stderr
View file

@ -9,10 +9,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
<i32 as IsInputType<__S>>
<f64 as IsInputType<__S>>
<Box<T> as IsInputType<S>>
<uuid::Uuid as IsInputType<__S>>
<url::Url as IsInputType<__S>>
<bson::datetime::DateTime as IsInputType<__S>>
<juniper::schema::model::DirectiveLocation as IsInputType<__S>>
<Arc<T> as IsInputType<S>>
<Vec<T> as IsInputType<S>>
<TypeKind as IsInputType<__S>>
and $N others
error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@ -29,10 +29,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others
note: required by a bound in `Registry::<'r, S>::arg`
--> $WORKSPACE/juniper/src/executor/mod.rs
@ -54,10 +54,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others
= note: this error originates in the attribute macro `graphql_object` (in Nightly builds, run with -Z macro-backtrace for more info)
@ -72,8 +72,8 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others

14
tests/codegen/fail/object/argument_wrong_default_array.stderr
View file

@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
|
= help: the following other types implement trait `From<T>`:
<[bool; N] as From<Mask<T, N>>>
<[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
<[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
<[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
<[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
<[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
<[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
<[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
<[T; N] as From<Simd<T, N>>>
<[T; 1] as From<(T,)>>
<[T; 2] as From<(T, T)>>
<[T; 3] as From<(T, T, T)>>
<[T; 4] as From<(T, T, T, T)>>
<[T; 5] as From<(T, T, T, T, T)>>
<[T; 6] as From<(T, T, T, T, T, T)>>
and $N others
= note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
= note: this error originates in the attribute macro `graphql_object` (in Nightly builds, run with -Z macro-backtrace for more info)

6
tests/codegen/fail/object/attr_field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<ObjA as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

6
tests/codegen/fail/object/derive_field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<ObjA as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

24
tests/codegen/fail/subscription/argument_non_input_type.stderr
View file

@ -17,10 +17,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
<i32 as IsInputType<__S>>
<f64 as IsInputType<__S>>
<Box<T> as IsInputType<S>>
<uuid::Uuid as IsInputType<__S>>
<url::Url as IsInputType<__S>>
<bson::datetime::DateTime as IsInputType<__S>>
<juniper::schema::model::DirectiveLocation as IsInputType<__S>>
<Arc<T> as IsInputType<S>>
<Vec<T> as IsInputType<S>>
<TypeKind as IsInputType<__S>>
and $N others
error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@ -37,10 +37,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others
note: required by a bound in `Registry::<'r, S>::arg`
--> $WORKSPACE/juniper/src/executor/mod.rs
@ -62,10 +62,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others
= note: this error originates in the attribute macro `graphql_subscription` (in Nightly builds, run with -Z macro-backtrace for more info)
@ -80,8 +80,8 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
<i32 as FromInputValue<__S>>
<f64 as FromInputValue<__S>>
<Box<T> as FromInputValue<S>>
<uuid::Uuid as FromInputValue<__S>>
<url::Url as FromInputValue<__S>>
<bson::datetime::DateTime as FromInputValue<__S>>
<juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
<Arc<T> as FromInputValue<S>>
<Vec<T> as FromInputValue<S>>
<TypeKind as FromInputValue<__S>>
and $N others

14
tests/codegen/fail/subscription/argument_wrong_default_array.stderr
View file

@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
|
= help: the following other types implement trait `From<T>`:
<[bool; N] as From<Mask<T, N>>>
<[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
<[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
<[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
<[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
<[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
<[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
<[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
<[T; N] as From<Simd<T, N>>>
<[T; 1] as From<(T,)>>
<[T; 2] as From<(T, T)>>
<[T; 3] as From<(T, T, T)>>
<[T; 4] as From<(T, T, T, T)>>
<[T; 5] as From<(T, T, T, T, T)>>
<[T; 6] as From<(T, T, T, T, T, T)>>
and $N others
= note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
= note: this error originates in the attribute macro `graphql_subscription` (in Nightly builds, run with -Z macro-backtrace for more info)

6
tests/codegen/fail/subscription/field_non_output_return_type.stderr
View file

@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
<f64 as IsOutputType<__S>>
<ObjA as IsOutputType<__S>>
<Box<T> as IsOutputType<S>>
<uuid::Uuid as IsOutputType<__S>>
<url::Url as IsOutputType<__S>>
<bson::datetime::DateTime as IsOutputType<__S>>
<juniper::meta::Field<'a, S> as IsOutputType<S>>
<Argument<'a, S> as IsOutputType<S>>
<EnumValue as IsOutputType<__S>>
and $N others

2
tests/integration/Cargo.toml
View file

@ -11,7 +11,7 @@ derive_more = "0.99"
fnv = "1.0"
futures = "0.3"
itertools = "0.12"
juniper = { path = "../../juniper" }
juniper = { path = "../../juniper", features = ["chrono"] }
juniper_subscriptions = { path = "../../juniper_subscriptions" }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"