Merge pull request #35 from tomhoule/readme-update

Get the README in shape for initial release

Author: tomhoule

Cargo.toml

@@ -2,9 +2,11 @@
 name = "graphql_client"
 version = "0.0.1"
 authors = ["Tom Houlé <tom@tomhoule.com>"]
-description = "A work-in-progress generic graphql client"
+description = "Typed GraphQL requests and responses"
 repository = "https://github.com/tomhoule/graphql-client"
 license = "Apache-2.0 OR MIT"
+keywords = ["graphql", "gql", "api", "web", "webassembly", "wasm"]
+categories = ["network-programming", "web-programming", "wasm"]
 
 [dependencies]
 failure = "0.1"
@@ -20,6 +22,7 @@ serde_json = "1.0"
 [workspace]
 members = [
     ".",
+    "examples/example_module",
     "examples/github",
     "graphql_query_derive",
     "graphql_client_cli",

README.md

@@ -1,45 +1,77 @@
-NOTE: This is a WIP - I plan to write proper documentation and make a formal release soon.
+# graphql_client
 
-Derive Rust code to safely interact with queries written in the GraphQL query language.
+[![Build Status](https://travis-ci.org/tomhoule/graphql-client.svg?branch=master)](https://travis-ci.org/tomhoule/graphql-client)
+[![docs](https://docs.rs/graphql_client/badge.svg)](https://docs.rs/graphql_client/0.0.1/graphql_client/)
+[![crates.io](https://img.shields.io/crates/v/graphql_client.svg)](https://crates.io/crates/graphql_client)
 
-This library does not provide any networking, caching or other client functionality, it is just meant to make it easy to interact with a GraphQL query and the corresponding response in a strongly typed way. Building a client can be as simple as this:
+Derive Rust code to safely and ergonomically manipulate GraphQL queries.
+
+This library does not provide any networking, caching or other client functionality yet, it is just meant to make it easy to interact with a GraphQL query and the corresponding response in a strongly typed way. Making a request can be as simple as this:
 
 ```rust
 #[derive(GraphQLQuery)]
-#[gql(
-    query = "/graphql/queries/my_query.graphql",
-    schema = "/graphql/schema.graphql"
+#[graphql(
+    // The paths are relative to the directory where your `Cargo.toml` is located.
+    query_path = "src/graphql/queries/my_query.graphql",
+    schema_path = "src/graphql/schema.json"
 )]
 struct MyQuery;
+```
 
+```rust
 fn perform_my_query(variables: &my_query::Variables) -> Result<(), failure::Error> {
     let body = MyQuery::expand(variables);
     let client = reqwest::Client::new();
-    let res: HttpResponse<graphql_client::Response<my_query::ResponseData>> = client.post("/graphql", body)?;
-    println!("{:#?}", res.body);
+    let mut res: HttpResponse<graphql_client::Response<my_query::ResponseData>> = client.post("/graphql").json(&body).send()?;
+    println!("{:#?}", res.text());
+    Ok(())
 }
 ```
 
+The GraphQL schema language (`.graphql`) and `schema.json` are both supported as sources for the schema.
+
+`serde_derive` needs to be visible in the context of the `GraphQLQuery` derive (add it as an `extern crate`).
+
 ## Features
 
-* Strongly typed query variables
-* Strongly typed response
+- Strongly typed query variables
+- Strongly typed responses
+- Works in the browser (WebAssembly)
+
+Integration with different HTTP libraries is planned, although building one yourself is trivial (just send the constructed request payload as JSON with a POST request to a GraphQL endpoint, modulo authentication).
 
-### Planned features
+There is an embryonic CLI for downloading schemas - the plan is to make it something similar to `apollo-codegen`.
 
-* Strongly typed subscriptions
-* Query string minification (e.g. for embedding in a browser wasm app, and for minimizing payload size)
-* A command line interface in addition to the custom derive for generating code and downloading schemas
 
-## What is generated?
+## What is generated?
 
-* A module named after the struct under derive, which contains:
-  * A `ResponseData` struct implementing `serde::Deserialize`
-  * A `Variables` struct meant to contain the variables expected by the query
-* An impl for the `GraphQLQuery` trait for the struct under derive
+- A module named after the struct under derive, which contains:
+  - A `ResponseData` struct implementing `serde::Deserialize`
+  - A `Variables` struct meant to contain the variables expected by the query
+- An impl for the `GraphQLQuery` trait for the struct under derive
 
-See the example generated module for a full example.
+See the [example generated module](https://www.tomhoule.com/docs/example_module/) for more details.
 
 ## Examples
 
 See the examples directory in this project.
+
+## Code of conduct
+
+Anyone who interacts with this project in any space, including but not limited to
+this GitHub repository, must follow our [code of conduct](https://github.com/tomhoule/graphql-client/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under either of these:
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   https://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+   https://opensource.org/licenses/MIT)
+
+### Contributing
+
+Unless you explicitly state otherwise, any contribution you intentionally submit
+for inclusion in the work, as defined in the Apache-2.0 license, shall be
+dual-licensed as above, without any additional terms or conditions.

examples/call_from_js/Cargo.toml

@@ -3,6 +3,9 @@ name = "call_from_js"
 version = "0.1.0"
 authors = ["Tom Houlé <tom@tomhoule.com>"]
 
+[profile.release]
+lto = "thin"
+
 [lib]
 crate-type = ["cdylib"]
 
@@ -15,4 +18,4 @@ serde_json = "1.0.22"
 lazy_static = "1.0.1"
 
 [workspace]
-members = ["."]
+members = ["."]

examples/call_from_js/build.sh

@@ -1,9 +1,11 @@
 set -ex
 
-cargo +nightly build --target wasm32-unknown-unknown
+export CARGO_INCREMENTAL=0
+
+cargo +nightly build --target wasm32-unknown-unknown --release
 
 wasm-bindgen \
-  ../../target/wasm32-unknown-unknown/debug/call_from_js.wasm --out-dir .
+  ./target/wasm32-unknown-unknown/release/call_from_js.wasm --out-dir .
 
 npm install
 npm run serve

examples/call_from_js/src/lib.rs

@@ -18,7 +18,7 @@ use wasm_bindgen::prelude::*;
 use graphql_client::*;
 
 #[derive(GraphQLQuery)]
-#[gql(schema_path = "schema.json", query_path = "src/puppy_smiles.graphql")]
+#[graphql(schema_path = "schema.json", query_path = "src/puppy_smiles.graphql")]
 struct PuppySmiles;
 
 #[wasm_bindgen]

examples/example_module/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "example_module"
+version = "0.1.0"
+authors = ["Tom Houlé <tom@tomhoule.com>"]
+
+[dependencies]
+serde = "1.0.69"
+serde_derive = "1.0.69"
+graphql_client = { path = "../.."}

examples/example_module/src/lib.rs

@@ -0,0 +1,11 @@
+extern crate serde;
+#[macro_use]
+extern crate serde_derive;
+#[macro_use]
+extern crate graphql_client;
+
+#[derive(GraphQLQuery)]
+#[graphql(
+    schema_path = "../github/src/schema.graphql", query_path = "../github/src/query_1.graphql"
+)]
+pub struct ExampleModule;

examples/github/src/main.rs

@@ -18,7 +18,7 @@ use graphql_client::*;
 use structopt::StructOpt;
 
 #[derive(GraphQLQuery)]
-#[gql(schema_path = "src/schema.graphql", query_path = "src/query_1.graphql")]
+#[graphql(schema_path = "src/schema.graphql", query_path = "src/query_1.graphql")]
 struct Query1;
 
 #[derive(StructOpt)]

graphql_client_cli/README.md

@@ -1 +1,3 @@
-https://developer.deutschebahn.com/free1bahnql/graphql
+# GraphQL client CLI
+
+This is still a WIP, the main use for it now is to download the `schema.json` from a GraphQL endpoint, which you can also do with [apollo-codegen](https://github.com/apollographql/apollo-cli).

graphql_client_cli/src/main.rs

@@ -13,7 +13,7 @@ use std::path::PathBuf;
 use structopt::StructOpt;
 
 #[derive(GraphQLQuery)]
-#[gql(
+#[graphql(
     schema_path = "src/introspection_schema.graphql", query_path = "src/introspection_query.graphql"
 )]
 struct IntrospectionQuery;