Write documentation + small API fixes

Author: weiznich

.gitignore

@@ -2,4 +2,3 @@
 **/target/
 **/*.rs.bk
 Cargo.lock
-*~

README.md

@@ -12,6 +12,8 @@ Wundergraph provides a platform to easily expose your database through a GraphQL
 For a full example application see the [example project](https://github.com/weiznich/wundergraph/tree/master/wundergraph_example/src/main.rs)
 
 ```rust
+#[macro_use] extern crate diesel;
+use wundergraph::prelude::*;
 
 table! {
     heros {
@@ -29,34 +31,29 @@ table! {
     }
 }
 
-#[derive(Clone, Debug, Identifiable, Hash, Eq, PartialEq, Queryable, WundergraphEntity,
-         WundergraphFilter, Associations)]
+#[derive(Clone, Debug, Identifiable, WundergraphEntity)]
 #[table_name = "heros"]
-#[belongs_to(Species, foreign_key = "species)]
 pub struct Hero {
     id: i32,
     name: String,
     hair_color: Option<String>,
     species: HasOne<i32, Species>,
 }
 
-#[derive(Clone, Debug, Identifiable, Hash, Eq, PartialEq, Queryable, WundergraphEntity,
-         WundergraphFilter)]
+#[derive(Clone, Debug, Identifiable, WundergraphEntity)]
 #[table_name = "species"]
 pub struct Species {
     id: i32,
     name: String,
-    #[diesel(default)]
-    heros: HasMany<Hero>,
+    heros: HasMany<Hero, heros::species>,
 }
 
-wundergraph_query_object!{
+wundergraph::query_object!{
     Query {
-        Heros(Hero, filter = HeroFilter),
-        Species(Species, filter = SpeciesFilter),
-    }
+       Hero,
+       Species,
+   }
 }
-
 ```
 
 ## License

clippy.toml

@@ -1,10 +1,11 @@
-cyclomatic-complexity-threshold = 30
+cognitive-complexity-threshold = 30
 doc-valid-idents = [
   "MiB", "GiB", "TiB", "PiB", "EiB",
   "DirectX", "OpenGL", "TrueType",
   "GPLv2", "GPLv3",
   "GitHub",
   "IPv4", "IPv6",
   "JavaScript", "NaN", "OAuth",
-  "SQLite", "PostgreSQL", "MySQL"
+  "SQLite", "PostgreSQL", "MySQL",
+  "GraphQL"
 ]

rust-toolchain

@@ -1 +1 @@
-nightly-2019-05-31
+nightly-2019-10-03

wundergraph/Cargo.toml

@@ -14,30 +14,30 @@ description = "A GraphQL ORM build on top of diesel"
 [dependencies]
 serde = "1"
 diesel = { version = "1.4", features = ["r2d2"]}
-juniper = "0.12"
+juniper = "0.14"
 indexmap = "1"
 wundergraph_derive = { path = "../wundergraph_derive" }
 uuid_internal = { version = "0.7", optional = true, package = "uuid" }
 chrono_internal = { version = "0.4", optional = true, package = "chrono" }
-failure = "0.1"
-log = "0.4"
+log = { version = "0.4", optional = true }
 paste = "0.1"
+thiserror = "1"
 
 [dev-dependencies]
 wundergraph_example = { path = "../wundergraph_example", default-features = false }
 wundergraph_bench = { path = "../wundergraph_bench", default-features = false }
 diesel_migrations = "1.4.0"
 serde_json = "1"
-criterion = "0.2"
+criterion = "0.3"
 lazy_static = "1"
-insta = "0.8"
+insta = "0.12"
 
 [features]
-default = ["postgres", "extras"]
-debug = ["wundergraph_derive/debug"]
+default = []
+debug = ["wundergraph_derive/debug", "log"]
 sqlite = ["diesel/sqlite", "wundergraph_derive/sqlite"]
 postgres = ["diesel/postgres", "wundergraph_derive/postgres"]
-extras = ["chrono", "uuid"]
+extras = ["uuid", "chrono"]
 uuid = ["uuid_internal", "diesel/uuidv07"]
 chrono = ["chrono_internal", "diesel/chrono"]
 

wundergraph/bench/queries.rs

@@ -28,10 +28,10 @@ use wundergraph_bench::Schema;
 const QUERIES: &[&str] = &[
     r#"query albums_tracks_genre_all {
   Albums {
-    id
+    album_id
     title
     tracks {
-      id
+      track_id
       name
       genre_id {
         name
@@ -40,11 +40,11 @@ const QUERIES: &[&str] = &[
   }
 }"#,
     r#"query albums_tracks_genre_some {
-  Albums(filter: {artist_id: {id: {eq: 127}}}) {
-    id
+  Albums(filter: {artist_id: {artist_id: {eq: 127}}}) {
+    album_id
     title
     tracks {
-      id
+      track_id
       name
       genre_id {
         name
@@ -54,7 +54,7 @@ const QUERIES: &[&str] = &[
 }"#,
     r#"query tracks_media_all {
   Tracks {
-    id
+    track_id
     name
     media_type_id {
       name
@@ -63,10 +63,10 @@ const QUERIES: &[&str] = &[
 }"#,
     r#"query tracks_media_some {
   Tracks (filter: {composer: {eq: "Kurt Cobain"}}){
-    id
+    track_id
     name
     album_id {
-      id
+      album_id
       title
     }
     media_type_id {
@@ -77,13 +77,13 @@ const QUERIES: &[&str] = &[
         r#"query artists_collaboration {
       Artists(filter: {albums: {tracks: {composer: {eq: "Ludwig van Beethoven"}}}})
       {
-        id
+        artist_id
         name
       }
     }"#,
     r#"query artistByArtistId {
-  Artists(filter: {id: {eq:3}}) {
-    id
+  Artists(filter: {artist_id: {eq:3}}) {
+    artist_id
     name
   }
 }"#,
@@ -95,7 +95,6 @@ fn query(
     ctx: &PooledConnection<ConnectionManager<DbConnection>>,
 ) {
     let res = helper::execute_query(&schema, &ctx, query);
-
     assert!(res.is_ok());
 }
 

wundergraph/src/context.rs

@@ -1,14 +1,18 @@
-use diesel::{r2d2, Connection};
+use diesel::Connection;
 
+/// A trait for types that could be used as context types for wundergraph
 pub trait WundergraphContext {
+
+    /// The underlying connection type
     type Connection: Connection + 'static;
+
+    /// Get a connection from the context
     fn get_connection(&self) -> &Self::Connection;
 }
 
-impl<Conn> WundergraphContext for r2d2::PooledConnection<r2d2::ConnectionManager<Conn>>
+impl<Conn> WundergraphContext for Conn
 where
     Conn: Connection + 'static,
-    Self: Connection<Backend = Conn::Backend>,
 {
     type Connection = Self;
 

wundergraph/src/diesel_ext.rs

@@ -1,10 +1,21 @@
+//! A module containing extension traits for various diesel types
 
 use diesel::backend::Backend;
 use diesel::expression::{AppearsOnTable, Expression, NonAggregate, SelectableExpression};
 use diesel::query_builder::{AstPass, QueryFragment, QueryId};
 use diesel::result::QueryResult;
 use diesel::sql_types::IntoNullable;
 
+/// A helper trait used when boxing filters
+///
+/// In Rust you cannot create a trait object with more than one trait.
+/// This type has all of the additional traits you would want when using
+/// `Box<Expression>` as a single trait object. This type is comparable to
+/// diesels `BoxableExpression`, but allows to use non select able expressions,
+/// which is mainly useful for constructing filters.
+///
+/// This is typically used as the return type of a function or as associated
+/// types in traits.
 pub trait BoxableFilter<QS, DB>
 where
     DB: Backend,
@@ -25,9 +36,12 @@ where
 {
 }
 
+/// A diesel helper type that indicates if null or some expression selected
 #[derive(Debug)]
 pub enum MaybeNull<T> {
+    /// Select the expression
     Expr(T),
+    /// Select a null value
     Null,
 }
 

wundergraph/src/error.rs

@@ -1,25 +1,40 @@
 //! This module contains all error handling related functionality in wundergraph
 
 use crate::scalar::WundergraphScalarValue;
+use thiserror::Error;
 
 /// The main error type of wundergraph
-#[derive(Debug, Fail)]
+#[derive(Debug, Error)]
 pub enum WundergraphError {
     /// Indicates that it was not possible to build a filter from the given
     /// graphql arguments
-    #[fail(display = "Could not build filter from arguments")]
+    #[error("Could not build filter from arguments")]
     CouldNotBuildFilterArgument,
     /// Indicates that a unknown database field name was passed into
     /// wundergraph
-    #[fail(display = "Requested unkown field {}", name)]
+    #[error("Requested unkown field {name}")]
     UnknownDatabaseField {
         ///The name of the unknown database field
         name: String,
     },
-    #[fail(display = "Could not build primary key filter from arguments")]
+    /// Indicates that a primary key filter could not be build from the
+    /// given arguments
+    #[error("Could not build primary key filter from arguments")]
     NoPrimaryKeyArgumentFound,
-    #[fail(display = "Failed to build a return value")]
+    /// Indicates that building a graphql return value failed
+    #[error("Failed to build a return value")]
     JuniperError {
+        /// Error returned from juniper
         inner: juniper::FieldError<WundergraphScalarValue>,
     },
+    /// Indicates that executing a database query failed
+    #[error("Failed to execute query")]
+    DieselError {
+        /// Error returned from diesel
+        #[from]
+        inner: diesel::result::Error,
+    },
 }
+
+/// Commonly used result type
+pub type Result<T> = std::result::Result<T, WundergraphError>;

wundergraph/src/graphql_type.rs

@@ -7,6 +7,8 @@ use diesel::QuerySource;
 use juniper::{meta, GraphQLType, Registry};
 use std::marker::PhantomData;
 
+/// A helper type to automatically provide `juniper::GraphQLObject` implementation
+/// for types that also implement `LoadingHandler`
 #[derive(Debug)]
 pub struct GraphqlWrapper<T, DB, Ctx>(T, PhantomData<(DB, Ctx)>);
 
@@ -40,6 +42,7 @@ where
     }
 }
 
+#[doc(hidden)]
 pub trait WundergraphGraphqlMapper<DB, Ctx> {
     type GraphQLType: GraphQLType<WundergraphScalarValue, TypeInfo = ()>;
 
@@ -58,6 +61,7 @@ where
     type GraphQLType = Self;
 }
 
+#[doc(hidden)]
 pub trait WundergraphGraphqlHelper<L, DB, Ctx> {
     fn object_meta<'r, T>(
         names: &[&str],
@@ -105,7 +109,7 @@ macro_rules! wundergraph_graphql_helper_impl {
                         &(),
                         &fields,
                     );
-                    if let Some(doc) = Loading::type_description() {
+                    if let Some(doc) = Loading::TYPE_DESCRIPTION {
                         ty = ty.description(doc);
                     }
                     meta::MetaType::Object(ty)