graphql-client 0.0.19 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c087161bf28d989bf274ba68bf76223ff4cc7b84
-  data.tar.gz: 3054f8552e6e6a532ebd09a15e7f5914b8dfa994
+  metadata.gz: aeedc712dec17a0235ba00379f0a47b115d7b813
+  data.tar.gz: e143f70cb64be0f0fbddeb63d491db75293ef7e0
 SHA512:
-  metadata.gz: 4044f2bf520a94bcaf5f6a918baf4daa8eb72479f7fd9de12bacfe58f40a362f57d675207ef0a25d9508113ccc3a0985c2095fa4534385ab4d33b08db2592815
-  data.tar.gz: 8d19a14603c36df798b2280432d54e5dceb98d31a1d949c10bd2ac349b82dcf559359253e10b51a3d655f3e3cf22505f1b4ea97ff4a9acdf8e1992e91c462f9b
+  metadata.gz: f23928689fa9b1adde4574ef9ac26a60aa2919ca8122593f0425a27f9d6808883d18d8cc4cfc270c40921c88863d43fa5ce87a0565d2dfcda7df3a6c4c7d69f9
+  data.tar.gz: 5b5bdfcaf4b76a610448cdd80d1b3e391b97ee71f0f589bcc529fb6bda8df9f658e948f4eb122d7699f90755c4c9da155394d21275b6101bfbae23cb2faa845a

data/lib/graphql/client.rb

@@ -3,16 +3,21 @@ require "active_support/notifications"
 require "graphql"
 require "graphql/client/error"
 require "graphql/client/query_result"
-require "graphql/client/query"
 require "graphql/client/response"
 require "graphql/language/nodes/deep_freeze_ext"
 require "graphql/language/operation_slice"
 
 module GraphQL
+  # GraphQL Client helps build and execute queries against a GraphQL backend.
+  #
+  # A client instance SHOULD be configured with a schema to enable query
+  # validation. And SHOULD also be configured with a backend "execute" adapter
+  # to point at a remote GraphQL HTTP service or execute directly against a
+  # Schema object.
   class Client
     class ValidationError < Error; end
 
-    attr_reader :schema, :fetch
+    attr_reader :schema, :execute
 
     attr_accessor :document_tracking_enabled
 
@@ -31,13 +36,18 @@ module GraphQL
       end
     end
 
-    def initialize(schema: nil, fetch: nil)
+    def initialize(schema: nil, execute: nil)
       @schema = self.class.load_schema(schema)
-      @fetch = fetch
+      @execute = execute
       @document = GraphQL::Language::Nodes::Document.new(definitions: [])
       @document_tracking_enabled = false
     end
 
+    # Definitions are constructed by Client.parse and wrap a parsed AST of the
+    # query string as well as hold references to any external query definition
+    # dependencies.
+    #
+    # Definitions MUST be assigned to a constant.
     class Definition < Module
       def self.for(node:, **kargs)
         case node
@@ -86,21 +96,23 @@ module GraphQL
       attr_reader :document
 
       def new(*args)
-        query_result_class.new(*args)
+        type.new(*args)
       end
 
-      private
-
-      def query_result_class
-        @query_result_class ||= GraphQL::Client::QueryResult.wrap(definition_node, name: name)
+      def type
+        # TODO: Fix type indirection
+        @type ||= GraphQL::Client::QueryResult.wrap(definition_node, name: "#{name}.type")
       end
     end
 
+    # Specific operation definition subtype for queries, mutations or
+    # subscriptions.
     class OperationDefinition < Definition
       # Public: Alias for definition name.
       alias operation_name definition_name
     end
 
+    # Specific fragment definition subtype.
     class FragmentDefinition < Definition
     end
 
@@ -120,16 +132,16 @@ module GraphQL
           definition_dependencies.merge(fragment.document.definitions)
           "...#{fragment.definition_name}"
         else
-          if fragment
-            error = TypeError.new("expected #{const_name} to be a #{FragmentDefinition}, but was a #{fragment.class}")
-          else
-            error = NameError.new("uninitialized constant #{const_name}")
-          end
+          message = if fragment
+                      "expected #{const_name} to be a #{FragmentDefinition}, but was a #{fragment.class}"
+                    else
+                      "uninitialized constant #{const_name}"
+                    end
 
+          error = ValidationError.new(message)
           if filename && lineno
             error.set_backtrace(["#{filename}:#{lineno + match.pre_match.count("\n") + 1}"] + caller)
           end
-
           raise error
         end
       end
@@ -195,47 +207,48 @@ module GraphQL
     attr_reader :document
 
     def query(definition, variables: {}, context: {})
-      raise Error, "client network fetching not configured" unless fetch
+      raise Error, "client network execution not configured" unless execute
 
-      query = Query.new(definition.document,
-                        operation_name: definition.operation_name,
-                        variables: variables,
-                        context: context)
-
-      result = ActiveSupport::Notifications.instrument("query.graphql", query.payload) do
-        fetch.call(query)
+      unless definition.is_a?(OperationDefinition)
+        raise TypeError, "expected definition to be a #{OperationDefinition.name} but was #{document.class.name}"
       end
 
-      data, errors, extensions = result.values_at("data", "errors", "extensions")
-
-      if data && errors
-        PartialResponse.new(
-          data: definition.new(data),
-          errors: ResponseErrors.new(definition, errors),
-          extensions: extensions
+      document = definition.document
+      operation = definition.definition_node
+
+      payload = {
+        document: document,
+        operation_name: operation.name,
+        operation_type: operation.operation_type,
+        variables: variables,
+        context: context
+      }
+
+      result = ActiveSupport::Notifications.instrument("query.graphql", payload) do
+        execute.execute(
+          document: document,
+          operation_name: operation.name,
+          variables: variables,
+          context: context
         )
-      elsif data && !errors
-        SuccessfulResponse.new(
-          data: definition.new(data),
-          extensions: extensions
-        )
-      elsif !data && errors
-        FailedResponse.new(
-          errors: ResponseErrors.new(definition, errors),
-          extensions: extensions
-        )
-      else
-        raise Error, "invalid GraphQL response, expected data or errors"
       end
+
+      Response.for(definition, result)
     end
 
     IntrospectionDocument = GraphQL.parse(GraphQL::Introspection::INTROSPECTION_QUERY).deep_freeze
-    IntrospectionQuery = Query.new(IntrospectionDocument)
 
     def fetch_schema
-      fetch.call(IntrospectionQuery)
+      execute.execute(
+        document: IntrospectionDocument,
+        operation_name: "IntrospectionQuery",
+        variables: {},
+        context: {}
+      )
     end
 
+    # Internal: FragmentSpread and FragmentDefinition extension to allow its
+    # name to point to a lazily defined Proc instead of a static string.
     module LazyName
       def name
         @name.call

data/lib/graphql/client/error.rb

@@ -1,5 +1,7 @@
 module GraphQL
   class Client
-    class Error < StandardError; end
+    # Public: Abstract base class for all errors raised by GraphQL::Client.
+    class Error < StandardError
+    end
   end
 end

data/lib/graphql/client/http.rb

@@ -7,7 +7,7 @@ module GraphQL
     # Public: Basic HTTP network adapter.
     #
     #   GraphQL::Client::Client.new(
-    #     fetch: GraphQL::Client::HTTP.new("http://graphql-swapi.parseapp.com/")
+    #     execute: GraphQL::Client::HTTP.new("http://graphql-swapi.parseapp.com/")
     #   )
     #
     # Assumes GraphQL endpoint follows the express-graphql endpoint conventions.
@@ -20,7 +20,7 @@ module GraphQL
       # Public: Create HTTP adapter instance for a single GraphQL endpoint.
       #
       #   GraphQL::Client::HTTP.new("http://graphql-swapi.parseapp.com/") do
-      #     def headers(query)
+      #     def headers(context)
       #       { "User-Agent": "My Client" }
       #     end
       #   end
@@ -39,21 +39,22 @@ module GraphQL
 
       # Public: Extension point for subclasses to set custom request headers.
       #
-      # query - The GraphQL::Client::Query being sent
-      #
       # Returns Hash of String header names and values.
-      def headers(_)
+      def headers(_context)
         {}
       end
 
       # Public: Make an HTTP request for GraphQL query.
       #
-      # Implements Client's "fetch" adapter interface.
+      # Implements Client's "execute" adapter interface.
       #
-      # query - The GraphQL::Client::Query being sent
+      # document - The Query GraphQL::Language::Nodes::Document
+      # operation_name - The String operation definition name
+      # variables - Hash of query variables
+      # context - An arbitrary Hash of values which you can access
       #
       # Returns { "data" => ... , "errors" => ... } Hash.
-      def call(query)
+      def execute(document:, operation_name: nil, variables: {}, context: {})
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
 
@@ -61,12 +62,12 @@ module GraphQL
 
         request["Accept"] = "application/json"
         request["Content-Type"] = "application/json"
-        headers(query).each { |name, value| request[name] = value }
+        headers(context).each { |name, value| request[name] = value }
 
         body = {}
-        body["query"] = query.to_s
-        body["variables"] = JSON.generate(query.variables) if query.variables.any?
-        body["operationName"] = query.operation_name if query.operation_name
+        body["query"] = document.to_query_string
+        body["variables"] = JSON.generate(variables) if variables.any?
+        body["operationName"] = operation_name if operation_name
         request.body = JSON.generate(body)
 
         response = http.request(request)

data/lib/graphql/client/log_subscriber.rb

@@ -6,8 +6,8 @@ module GraphQL
     #
     # Logs GraphQL queries to Rails logger.
     #
-    #   QUERY (123ms) UsersController::ShowQuery
-    #   MUTATION (456ms) UsersController::UpdateMutation
+    #   UsersController::ShowQuery QUERY (123ms)
+    #   UsersController::UpdateMutation MUTATION (456ms)
     #
     # Enable GraphQL Client query logging.
     #
@@ -16,13 +16,10 @@ module GraphQL
     #
     class LogSubscriber < ActiveSupport::LogSubscriber
       def query(event)
-        # TODO: Colorize output
         info do
-          [
-            event.payload[:operation_type].upcase,
-            "(#{event.duration.round(1)}ms)",
-            event.payload[:operation_name].gsub("__", "::")
-          ].join(" ")
+          name = event.payload[:operation_name].gsub("__", "::")
+          type = event.payload[:operation_type].upcase
+          color("#{name} #{type} (#{event.duration.round(1)}ms)", nil, true)
         end
 
         debug do

data/lib/graphql/client/query_result.rb

@@ -4,6 +4,12 @@ require "set"
 
 module GraphQL
   class Client
+    # A QueryResult struct wraps data returned from a GraphQL response.
+    #
+    # Wrapping the JSON-like Hash allows access with nice Ruby accessor methods
+    # rather than using `obj["key"]` access.
+    #
+    # Wrappers also limit field visibility to fragment definitions.
     class QueryResult
       # Internal: Get QueryResult class for result of query.
       #
@@ -16,7 +22,7 @@ module GraphQL
           when Language::Nodes::FragmentSpread
           when Language::Nodes::Field
             field_name = selection.alias || selection.name
-            field_klass = selection.selections.any? ? wrap(selection, name: "#{name}.#{field_name}") : nil
+            field_klass = selection.selections.any? ? wrap(selection, name: "#{name}[:#{field_name}]") : nil
             fields[field_name] ? fields[field_name] |= field_klass : fields[field_name] = field_klass
           when Language::Nodes::InlineFragment
             wrap(selection, name: name).fields.each do |fragment_name, klass|
@@ -84,10 +90,12 @@ module GraphQL
 
       class << self
         attr_reader :source_node
-      end
 
-      class << self
         attr_reader :fields
+
+        def [](name)
+          fields[name]
+        end
       end
 
       def self.name
@@ -163,7 +171,14 @@ module GraphQL
       alias to_h data
 
       def inspect
-        ivars = self.class.fields.keys.map { |sym| "#{sym}=#{instance_variable_get("@#{sym}").inspect}" }
+        ivars = self.class.fields.keys.map do |sym|
+          value = instance_variable_get("@#{sym}")
+          if value.is_a?(QueryResult)
+            "#{sym}=#<#{value.class.name}>"
+          else
+            "#{sym}=#{value.inspect}"
+          end
+        end
         buf = "#<#{self.class.name}"
         buf << " " << ivars.join(" ") if ivars.any?
         buf << ">"

data/lib/graphql/client/railtie.rb

@@ -4,6 +4,13 @@ require "rails/railtie"
 
 module GraphQL
   class Client
+    # Optional Rails configuration for GraphQL::Client.
+    #
+    # Simply require this file to activate in the application.
+    #
+    #   # config/application.rb
+    #   require "graphql/client/railtie"
+    #
     class Railtie < Rails::Railtie
       config.graphql = ActiveSupport::OrderedOptions.new
       config.graphql.client = GraphQL::Client.new
@@ -29,6 +36,10 @@ module GraphQL
         require "graphql/client/view_module"
 
         path = app.paths["app/views"].first
+
+        # TODO: Accessing config.graphql.client during the initialization
+        # process seems error prone. The application may reassign
+        # config.graphql.client after this block is executed.
         client = config.graphql.client
 
         config.watchable_dirs[path] = [:erb]

data/lib/graphql/client/response.rb

@@ -6,6 +6,33 @@ module GraphQL
     #
     #   https://facebook.github.io/graphql/#sec-Response-Format
     class Response
+      # Internal: Initialize Response subclass.
+      def self.for(definition, result)
+        data, errors, extensions = result.values_at("data", "errors", "extensions")
+
+        if data && errors
+          PartialResponse.new(
+            data: definition.new(data),
+            errors: ResponseErrors.new(definition, errors),
+            extensions: extensions
+          )
+        elsif data && !errors
+          SuccessfulResponse.new(
+            data: definition.new(data),
+            extensions: extensions
+          )
+        elsif !data && errors
+          FailedResponse.new(
+            errors: ResponseErrors.new(definition, errors),
+            extensions: extensions
+          )
+        else
+          FailedResponse.new(
+            errors: ResponseErrors.new(definition, [{ "message" => "invalid GraphQL response" }])
+          )
+        end
+      end
+
       # Public: Hash of server specific extension metadata.
       attr_reader :extensions
 
@@ -15,6 +42,8 @@ module GraphQL
       end
     end
 
+    # Public: A successful response means the query executed without any errors
+    # and returned all the requested data.
     class SuccessfulResponse < Response
       # Public: Wrapped QueryResult of data returned from the server.
       #
@@ -30,12 +59,16 @@ module GraphQL
       end
     end
 
+    # Public: A partial response means the query executed with some errors but
+    # returned all non-nullable fields. PartialResponse is still considered a
+    # SuccessfulResponse as it returns data and the client may still proceed
+    # with its normal render flow.
     class PartialResponse < SuccessfulResponse
       # Public: Get partial failures from response.
       #
       #   https://facebook.github.io/graphql/#sec-Errors
       #
-      # Returns ResponseErrors collection object.
+      # Returns ResponseErrors collection object with zero or more errors.
       attr_reader :errors
 
       # Internal: Initialize PartialResponse.
@@ -45,12 +78,15 @@ module GraphQL
       end
     end
 
+    # Public: A failed response returns no data and at least one error message.
+    # Cases may likely be a query validation error, missing authorization,
+    # or internal server crash.
     class FailedResponse < Response
       # Public: Get errors from response.
       #
       #   https://facebook.github.io/graphql/#sec-Errors
       #
-      # Returns ResponseErrors collection object.
+      # Returns ResponseErrors collection object with one or more errors.
       attr_reader :errors
 
       # Internal: Initialize FailedResponse.
@@ -60,7 +96,16 @@ module GraphQL
       end
     end
 
+    # Public: An error received from the server on execution.
+    #
+    # Extends StandardError hierarchy so you may raise this instance.
+    #
+    # Examples
+    #
+    #   raise response.errors.first
+    #
     class ResponseError < Error
+      # Internal: Initialize ResponseError.
       def initialize(definition, error)
         @request_definition = definition
         @locations = error["locations"]
@@ -68,11 +113,20 @@ module GraphQL
       end
     end
 
+    # Public: A collection of errors received from the server on execution.
+    #
+    # Extends StandardError hierarchy so you may raise this instance.
+    #
+    # Examples
+    #
+    #   raise response.errors
+    #
     class ResponseErrors < Error
       include Enumerable
 
       attr_reader :errors
 
+      # Internal: Initialize ResponseErrors.
       def initialize(definition, errors)
         @request_definition = definition
         @errors = errors.map { |error| ResponseError.new(definition, error) }

data/lib/graphql/client/view_module.rb

@@ -4,6 +4,17 @@ require "graphql/client/erubis"
 
 module GraphQL
   class Client
+    # Allows a magic namespace to map to app/views/**/*.erb files to retrieve
+    # statically defined GraphQL definitions.
+    #
+    #   # app/views/users/show.html.erb
+    #   <%grapql
+    #     fragment UserFragment on User { }
+    #   %>
+    #
+    #   # Loads graphql section from app/views/users/show.html.erb
+    #   Views::Users::Show::UserFragment
+    #
     module ViewModule
       attr_accessor :client
 

data/lib/graphql/language/nodes/deep_freeze_ext.rb

@@ -3,6 +3,7 @@ require "graphql"
 module GraphQL
   module Language
     module Nodes
+      # :nodoc:
       class AbstractNode
         # Public: Freeze entire Node tree
         #

data/lib/graphql/language/operation_slice.rb

@@ -2,6 +2,8 @@ require "graphql"
 
 module GraphQL
   module Language
+    # Public: Document transformations to return a minimal document to represent
+    # operation.
     module OperationSlice
       # Public: Return's minimal document to represent operation.
       #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-client
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.20
 platform: ruby
 authors:
 - GitHub
@@ -118,7 +118,6 @@ files:
 - lib/graphql/client/erubis.rb
 - lib/graphql/client/http.rb
 - lib/graphql/client/log_subscriber.rb
-- lib/graphql/client/query.rb
 - lib/graphql/client/query_result.rb
 - lib/graphql/client/railtie.rb
 - lib/graphql/client/response.rb

data/lib/graphql/client/query.rb

@@ -1,65 +0,0 @@
-module GraphQL
-  class Client
-    class Query
-      # Internal: Construct Query.
-      #
-      # Avoid creating queries with this constructor, perfer using Client#query.
-      #
-      # document - A parsed GraphQL::Language::Nodes::Document of the query
-      # operation_name - String operation to execute
-      # variables - Hash of variables to execute with the operation
-      # context - Hash of metadata to pass to network adapter
-      def initialize(document, operation_name: nil, variables: {}, context: {})
-        @document = document
-        @operation_name = operation_name
-        @variables = variables
-        @context = context
-      end
-
-      # Public: A parsed GraphQL::Language::Nodes::Document of the query.
-      attr_reader :document
-
-      # Public: String name of operation to execute.
-      attr_reader :operation_name
-
-      # Public: Hash of variables to execute with the operation.
-      attr_reader :variables
-
-      # Public: Hash of contextual metadata.
-      attr_reader :context
-
-      # Public: Serialized query string
-      #
-      # Returns String.
-      def to_s
-        document.to_query_string
-      end
-
-      # Public: Get operation definition node.
-      #
-      # Returns GraphQL::Language::Nodes::OperationDefinition.
-      def operation
-        document.definitions.find { |node| node.name == operation_name }
-      end
-
-      # Public: Query operation type
-      #
-      # Returns "query", "mutation" or "subscription".
-      def operation_type
-        operation.operation_type
-      end
-
-      # Internal: Payload object to pass to ActiveSupport::Notifications.
-      #
-      # Returns Hash.
-      def payload
-        {
-          document: document,
-          operation_name: operation_name,
-          operation_type: operation_type,
-          variables: variables
-        }
-      end
-    end
-  end
-end