graphql-client 0.0.22 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35d033dd34fc07b0321711ab80afe22a67d6bc24
-  data.tar.gz: fdc1351584a59b2fd907cb9231d3385f65c9ff7c
+  metadata.gz: 5601d2f7aa039d200df20fa117df18f06a5473f1
+  data.tar.gz: 73b673e1a522ade77581115a22e2e3c5d5cfdd9e
 SHA512:
-  metadata.gz: d7f52e410a8929897c9b22f14b19a1bce944a0133d41eb1fc1f6947124c7e9770415115fd9563af11b3b6cb80e4f33fe6a87e104a41dc4bcfc15e65448186f42
-  data.tar.gz: 535bc0149c5447b2004428bf92cc9e4806a5e84aa044e23e62c232fc9e0b3e5e0b66d8dba2b2a9eab8ed76e00925e7fca99ca4b1aed4057313a16a038806ea72
+  metadata.gz: af9d1074b12a2d82b45d4f90472a7d7f97061eda325787e4a43c726bda1041254e3e4db9fd91f0a25b4677c03851c4bbf9d660cff3aa11ffa1964951deb9552e
+  data.tar.gz: 5720e2af73259abec92963c3746c787821f547813282cf4dcac9ba32ee224b395684048690edb203c80cbb6513c045f47733588b0db15271a4f6a096ce441eed

data/README.md

@@ -1,25 +1,29 @@
 # graphql-client
 
-## Usage
+GraphQL Client is a Ruby library for declaring, composing and executing GraphQL queries.
 
-To work with the client, you'll need to pass two variables to the initializer:
+## Usage
 
-* You'll need to have access to a GraphQL schema. This can either be a JSON blob or simply a JSON file. Usually, you can generate this by executing an introspection query to a GraphQL server.
-* You can optionally define a method that executes your schema. Usually, this is going to be some kind of HTTP adapter.
+### Configuration
 
-Once you've got that, you can set up the client like this:
+Sample configuration for a GraphQL Client to query from the [SWAPI GraphQL Wrapper](https://github.com/graphql/swapi-graphql).
 
 ``` ruby
 require "graphql/client"
+require "graphql/client/http"
 
+# Star Wars API example wrapper
 module SWAPI
+  # Configure GraphQL endpoint using the basic HTTP network adapter.
   HTTP = GraphQL::Client::HTTP.new("http://graphql-swapi.parseapp.com/")
 
-  # Fetch latest schema on boot,
+  # Fetch latest schema on init, this will make a network request
   Schema = GraphQL::Client.load_schema(HTTP)
+
   # However, its smart to dump this to a JSON file and load from disk
   #
-  # GraphQL::Client.dump_schema(HTTP, "path/to/schema.json")
+  # Run in from a script or rake task
+  #   GraphQL::Client.dump_schema(SWAPI::HTTP, "path/to/schema.json")
   #
   # Schema = GraphQL::Client.load_schema("path/to/schema.json")
 
@@ -27,9 +31,111 @@ module SWAPI
 end
 ```
 
-Then, all you'll need to do is pass your GraphQL query to `SWAPI::Client.query` to fetch the response.
+### Defining Queries
+
+If you haven't already, [familiarize yourself with the GraphQL query syntax](http://graphql.org/docs/queries/). Queries are declared with the same syntax inside of a `<<-'GRAPHQL'` heredoc. There isn't any special query builder Ruby DSL.
+
+This client library encourages all GraphQL queries to be declared statically and assigned to a Ruby constant.
+
+``` ruby
+HeroNameQuery = SWAPI::Client.parse <<-'GRAPHQL'
+  query {
+    hero {
+      name
+    }
+  }
+GRAPHQL
+```
+
+Fragments are declared similarly.
+
+``` ruby
+HumanFragment = SWAPI::Client.parse <<-'GRAPHQL'
+  fragment on Human {
+    name
+    homePlanet
+  }
+GRAPHQL
+```
+
+To include a fragment in a query, reference the fragment by constant.
+
+``` ruby
+HeroNameQuery = SWAPI::Client.parse <<-'GRAPHQL'
+  {
+    luke: human(id: "1000") {
+      ...HumanFragment
+    }
+    leia: human(id: "1003") {
+      ...HumanFragment
+    }
+  }
+GRAPHQL
+```
+
+This works for namespaced constants.
+
+``` ruby
+module Hero
+  Query = SWAPI::Client.parse <<-'GRAPHQL'
+    {
+      luke: human(id: "1000") {
+        ...Human::Fragment
+      }
+      leia: human(id: "1003") {
+        ...Human::Fragment
+      }
+    }
+  GRAPHQL
+end
+```
+
+`::` is invalid in regular GraphQL syntax, but `#parse` makes an initial pass on the query string and resolves all the fragment spreads with [`constantize`](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-constantize).
+
+### Executing queries
+
+Pass the reference of a parsed query definition to `GraphQL::Client#query`. Data is returned back in a wrapped `GraphQL::QueryResult` struct that provides Ruby-ish accessors.
+
+``` ruby
+result = SWAPI::Client.query(Hero::Query)
+
+# The raw data is Hash of JSON values
+# result["data"]["luke"]["homePlanet"]
+
+# The wrapped result allows to you access data with Ruby methods
+result.data.luke.home_planet
+```
+
+### Rails ERB integration
+
+If you're using Ruby on Rails ERB templates, theres a ERB extension that allows static queries to be defined in the template itself.
+
+In standard Ruby you can simply assign queries and fragments to constants and they'll be available throughout the app. However, the contents of an ERB template is compiled into a Ruby method, and methods can't assign constants. So a new ERB tag was extended to declare static sections that include a GraphQL query.
+
+``` erb
+<%# app/views/humans/human.html.erb %>
+<%graphql
+  fragment HumanFragment on Human {
+    name
+    homePlanet
+  }
+%>
+
+<p><%= human.name %> lives on <%= human.home_planet %>.</p>
+```
+
+These `<%graphql` sections are simply ignored at runtime but make their definitions available through constants. The module namespacing is derived from the `.erb`'s path plus the definition name.
+
+```
+>> "views/humans/human".camelize
+=> "Views::Humans::Human"
+>> Views::Humans::Human::HumanFragment
+=> #<GraphQL::Client::FragmentDefinition>
+```
+
+## Examples
 
-You can also call `SWAPI::Client.parse` on a query to generate a validation against the GraphQL query.
+[github/github-graphql-rails-example](https://github.com/github/github-graphql-rails-example) is an example application using this library to implement views on the GitHub GraphQL API.
 
 ## Installation
 
@@ -41,4 +147,6 @@ gem 'graphql-client'
 
 ## See Also
 
-* [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) gem which supports 90% of the features this library provides. ❤️ @rmosolgo
+* [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) gem which implements 80% of what this library provides. ❤️ [@rmosolgo](https://github.com/rmosolgo)
+* [Facebook's GraphQL homepage](http://graphql.org/)
+* [Facebook's Relay homepage](https://facebook.github.io/relay/)

data/lib/graphql/client.rb

@@ -54,7 +54,7 @@ module GraphQL
       )
 
       if io
-        io = IO.new(io, "w") if io.is_a?(String)
+        io = File.open(io, "w") if io.is_a?(String)
         io.write(JSON.pretty_generate(result))
         io.close_write
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-client
 version: !ruby/object:Gem::Version
-  version: 0.0.22
+  version: 0.1.0
 platform: ruby
 authors:
 - GitHub
@@ -106,7 +106,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.42'
-description: "???"
+description: A Ruby library for declaring, composing and executing GraphQL queries
 email: engineering@github.com
 executables: []
 extensions: []