Rework Book

.github/workflows/ci.yml

@@ -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:

README.md

@@ -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

benches/Cargo.toml

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

book/book.toml

@@ -1,16 +1,19 @@
 [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]
 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"

book/src/SUMMARY.md

@@ -1,39 +1,28 @@
-- [Introduction](README.md)
-- [Quickstart](quickstart.md)
-
-- [Type System](types/index.md)
+# Summary
 
-  - [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)
+- [Introduction](introduction.md)
+- [Quickstart](quickstart.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)

book/src/advanced/dataloader.md

@@ -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