graphql 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 290e890d0a805c3587000af2fbbacf910cf8baf0
-  data.tar.gz: 745511749686efb279e0ee7b7af2484d0ccd82ed
+  metadata.gz: 6184108ff2ba0151d12bfaeb02feeacbdeba74cc
+  data.tar.gz: 2a9cb034382d28f96a7e29024814848b63596a49
 SHA512:
-  metadata.gz: 81ba92e0aed50365b5ccd78ab02c035bc0a1ae212669f7d5c668cbe7fec3e48158f9a53a5859b2ece3ebc54d3634187635477a85cf50f2b8d24a822476517b53
-  data.tar.gz: 3a46fb67c848c7b85768979071d28df3b2e21e29087395b5a3ab2297d0660bd51ba84c628678e098a1faae392ef9a4e30d8be0007575ef32468f98c2c043badf
+  metadata.gz: 7bb555f0b19ce78ea3f79ba7388f31509c26e2518fc1c207a25e83bcdd4f38e3670194bcb26a1447dc134a5949e58d10e12da79846bb2b3fb4dab0d688561a8a
+  data.tar.gz: 695837ba820b7709453584800eaa6d3f4082edc9d443055ab52d42e0db3b895189c2c10113a04d43e44c70726365621b99a878cc68a371acd85b46aeb05b925a

data/lib/graphql.rb

@@ -5,20 +5,21 @@ require "parslet"
 require "singleton"
 
 module GraphQL
-  autoload(:Call,             "graphql/call")
-  autoload(:Connection,       "graphql/connection")
-  autoload(:Field,            "graphql/field")
-  autoload(:FieldDefiner,     "graphql/field_definer")
-  autoload(:Node,             "graphql/node")
-  autoload(:Parser,           "graphql/parser")
-  autoload(:Query,            "graphql/query")
-  autoload(:RootCall,         "graphql/root_call")
+  autoload(:Call,                     "graphql/call")
+  autoload(:Connection,               "graphql/connection")
+  autoload(:Field,                    "graphql/field")
+  autoload(:FieldDefiner,             "graphql/field_definer")
+  autoload(:Node,                     "graphql/node")
+  autoload(:Parser,                   "graphql/parser")
+  autoload(:Query,                    "graphql/query")
+  autoload(:RootCall,                 "graphql/root_call")
   autoload(:RootCallArgument,         "graphql/root_call_argument")
-  autoload(:RootCallArgumentDefiner,         "graphql/root_call_argument_definer")
-  autoload(:Schema,           "graphql/schema")
-  autoload(:Transform,        "graphql/transform")
-  autoload(:VERSION,          "graphql/version")
+  autoload(:RootCallArgumentDefiner,  "graphql/root_call_argument_definer")
+  autoload(:Schema,                   "graphql/schema")
+  autoload(:Transform,                "graphql/transform")
+  autoload(:VERSION,                  "graphql/version")
 
+  # These objects are used for introspections (eg, responding to `schema()` calls).
   module Introspection
     autoload(:CallNode,             "graphql/introspection/call_node")
     autoload(:Connection,           "graphql/introspection/connection")
@@ -31,7 +32,7 @@ module GraphQL
     autoload(:TypeNode,             "graphql/introspection/type_node")
   end
 
-
+  # These objects are skinny wrappers for going from the AST to actual {Node} and {Field} instances.
   module Syntax
     autoload(:Call,       "graphql/syntax/call")
     autoload(:Field,      "graphql/syntax/field")
@@ -40,6 +41,7 @@ module GraphQL
     autoload(:Variable,   "graphql/syntax/variable")
   end
 
+  # These fields wrap Ruby data types and some GraphQL internal values.
   module Types
     autoload(:BooleanField,     "graphql/types/boolean_field")
     autoload(:ConnectionField,  "graphql/types/connection_field")
@@ -49,35 +51,41 @@ module GraphQL
     autoload(:StringField,      "graphql/types/string_field")
     autoload(:TypeField,        "graphql/types/type_field")
   end
-
+  # @abstract
+  # Base class for all errors, so you can rescue from all graphql errors at once.
   class Error < RuntimeError; end
+  # This node doesn't have a field with that name.
   class FieldNotDefinedError < Error
     def initialize(class_name, field_name)
       super("#{class_name}##{field_name} was requested, but it isn't defined. Defined fields are: #{SCHEMA.field_names}")
     end
   end
+  # There's no Node defined for that kind of object.
   class NodeNotDefinedError < Error
     def initialize(node_name)
       super("#{node_name} was requested but was not found. Defined nodes are: #{SCHEMA.type_names}")
     end
   end
+  # This node doesn't have a connection with that name.
   class  ConnectionNotDefinedError < Error
     def initialize(node_name)
       super("#{node_name} was requested but was not found. Defined connections are: #{SCHEMA.connection_names}")
     end
   end
+  # The root call of this query isn't in the schema.
   class RootCallNotDefinedError < Error
     def initialize(name)
       super("Call '#{name}' was requested but was not found. Defined calls are: #{SCHEMA.call_names}")
     end
   end
+  # The query couldn't be parsed.
   class SyntaxError < Error
     def initialize(line, col, string)
       lines = string.split("\n")
       super("Syntax Error at (#{line}, #{col}), check usage: #{string}")
     end
   end
-
+  # This root call takes different arguments.
   class RootCallArgumentError < Error
     def initialize(declaration, actual)
       super("Wrong type for #{declaration.name}: expected a #{declaration.type} but got #{actual}")
@@ -85,6 +93,7 @@ module GraphQL
   end
 
   PARSER = Parser.new
+  # This singleton contains all defined nodes and fields.
   SCHEMA = Schema.instance
   TRANSFORM = Transform.new
   # preload these so they're in SCHEMA

data/lib/graphql/call.rb

@@ -1,3 +1,4 @@
+# Created by {Field.call}, used internally by GraphQL.
 class GraphQL::Call
   attr_reader :name, :lambda
   def initialize(name:, lambda:)

data/lib/graphql/connection.rb

@@ -1,3 +1,44 @@
+# {Connection}s wrap collections of objects.
+#
+# Out of the box, the only field it has is `edges`, which provides access to the members of the collection.
+#
+# You can define a custom {Connection} to use. This allows you to define fields at the collection level (rather than the item level)
+#
+# Custom fields can access the collection as {Field#items}.
+#
+# @example
+#   class UpvotesConnection < GraphQL::Collection
+#     field.number(:count)
+#     field.boolean(:any)
+#
+#     def count
+#       items.count
+#     end
+#
+#     def any
+#       items.any?
+#     end
+#   end
+#
+#   # Then, this connection will be used for connections whose names match:
+#   class PostNode < GraphQL::Node
+#     field.connection(:upvotes)
+#     # ^^ uses `UpvotesConnection` based on naming convention
+#   end
+#
+#   # And you can use the fields in a query:
+#   <<QUERY
+#   find_post(10) {
+#     title,
+#     upvotes {
+#       count,
+#       any,
+#       edges {
+#         node { created_at }
+#       }
+#     }
+#   }
+#   QUERY
 class GraphQL::Connection < GraphQL::Node
   exposes "Array"
   field.any(:edges)
@@ -10,6 +51,7 @@ class GraphQL::Connection < GraphQL::Node
     @query = query
   end
 
+  # Returns the members of the collection, after any calls on the corresponding {Field} have been applied
   def items
     @target
   end
@@ -34,6 +76,8 @@ class GraphQL::Connection < GraphQL::Node
     end
 
     attr_accessor :default_connection
+    # Call this to make a the class the default connection
+    # when one isn't found by name.
     def default_connection!
       GraphQL::Connection.default_connection = self
     end

data/lib/graphql/field.rb

@@ -1,3 +1,42 @@
+# {Field}s are used to safely lookup values on {Node}s. When you define a custom field, you can access it from {Node.field}
+#
+# `graphql` has built-in fields for some Ruby data types:
+# - `boolean`: {Types::BooleanField}
+# - `number`: {Types::NumberField}
+# - `string`: {Types::StringField}
+#
+# You can define custom fields that allow you to control how values are exposed.
+# - {Field.type} defines how it can be used inside {Node.field} calls.
+# - {Field.call} defines calls that can mutate the value before it is added to the response.
+#
+# @example
+#   # For example, an `AddressField` which wraps a string but exposes address-specific information
+#   class AddressField < GraphQL::Field
+#     type :address
+#     # ^^ now you can use it with `field.address` in node definitions
+#
+#     # calls can modify the value:
+#     # eg, get the numbers at the beginning:
+#     call :house_number, -> (prev_value) { prev_value[/^\d*/]}
+#     # get everything after a space:
+#     call :street_name,  -> (prev_value) { prev_value[/\s.*$/].strip }
+#   end
+#
+#   # Then, use it in a node definition:
+#   class HouseNode < GraphQL::Node
+#     exposes("House")
+#     # create an `AddressField` for this node called `street_address`:
+#     field.address(:street_address)
+#   end
+#
+#   # Then, use the field in queries:
+#   <<QUERY
+#   find_house(1) {
+#     street_address,
+#     street_address.house_number() as number,
+#     street_address.street_name() as street,
+#   }
+#   QUERY
 class GraphQL::Field
   attr_reader :query, :owner, :calls, :fields
   def initialize(query: nil, owner: nil, calls: [], fields: [])
@@ -8,7 +47,7 @@ class GraphQL::Field
   end
 
   def raw_value
-    owner.send(method)
+    owner.send(name)
   end
 
   def as_result
@@ -43,8 +82,6 @@ class GraphQL::Field
     end
   end
 
-  def method; name; end
-
   class << self
     def inherited(child_class)
       GraphQL::SCHEMA.add_field(child_class)
@@ -72,7 +109,18 @@ class GraphQL::Field
         super
       end
     end
-
+    # @param [Symbol] type_name the name used for getting this field from the {GraphQL::SCHEMA}.
+    # Defines the name used for getting fields of this type from the schema.
+    # @example
+    #   # define the field with its type:
+    #   class IPAddressField < GraphQL::Field
+    #     type :ip_address
+    #   end
+    #
+    #   # then, attach fields of this type to your nodes:
+    #   class ServerNode < GraphQL::Field
+    #     field.ip_address(:static_ip_address)
+    #   end
     def type(value_type_name)
       @value_type = value_type_name.to_s
       GraphQL::SCHEMA.add_field(self)
@@ -103,14 +151,31 @@ class GraphQL::Field
     rescue NoMethodError
       {}
     end
+    # @param [String] name the identifier for this call
+    # @param [lambda] operation the transformation this call makes
+    #
+    # Define a call that can be made on this field.
+    # The `lambda` receives arguments:
+    # - 1: `previous_value` -- the value of this field
+    # - *: arguments passed in the query (as strings)
+    #
+    # @example
+    #   # upcase a string field:
+    #   call :upcase, -> (prev_value) { prev_value.upcase }
+    # @example
+    #   # tests a number field:
+    #   call :greater_than, -> (prev_value, test_value) { prev_value > test_value.to_f }
+    #   # (`test_value` is passed in as a string)
+    def call(name, lambda)
+      _calls[name.to_s] = GraphQL::Call.new(name: name.to_s, lambda: lambda)
+    end
+
+    private
 
     def _calls
       @calls ||= {}
     end
 
-    def call(name, lambda)
-      _calls[name.to_s] = GraphQL::Call.new(name: name.to_s, lambda: lambda)
-    end
   end
 
   type :any

data/lib/graphql/field_definer.rb

@@ -1,9 +1,13 @@
+# Every {Node} class has a {FieldDefiner} instance that
+# enables the `field.{something}` API.
 class GraphQL::FieldDefiner
   attr_reader :owner_class
   def initialize(owner_class)
     @owner_class = owner_class
   end
 
+  # `method_name` is used as a field type and looked up against {GraphQL::SCHEMA}.
+  # `args[0]` is the name for the field of that type.
   def method_missing(method_name, *args, &block)
     type = GraphQL::SCHEMA.get_field(method_name)
     if type.present?
@@ -13,6 +17,8 @@ class GraphQL::FieldDefiner
     end
   end
 
+  private
+
   def create_field(field_name, type: nil, description: nil)
     field_name = field_name.to_s
     field_class = GraphQL::Field.create_class({

data/lib/graphql/parser.rb

@@ -1,3 +1,6 @@
+# Parser is a [parslet](http://kschiess.github.io/parslet/) parser for parsing queries.
+#
+# If it failes to parse, a {SyntaxError} is raised.
 class GraphQL::Parser < Parslet::Parser
   root(:query)
   rule(:query) { node.repeat.as(:nodes) >> variable.repeat.as(:variables) }

data/lib/graphql/query.rb

@@ -7,7 +7,9 @@
 #   result = query.as_result
 
 class GraphQL::Query
-  attr_reader :query_string, :root, :context
+  # This is the object passed to {#initialize} as `context:`
+  attr_reader :context
+  attr_reader :query_string, :root
 
   # @param [String] query_string the string to be parsed
   # @param [Object] context an object which will be available to all nodes and fields in the schema

data/lib/graphql/root_call.rb

@@ -34,6 +34,8 @@
 #
 class GraphQL::RootCall
   attr_reader :query, :arguments
+
+  # Validates arguments against declared {.argument}s
   def initialize(query:, syntax_arguments:)
     @query = query
 
@@ -46,18 +48,23 @@ class GraphQL::RootCall
           syntax_arg
         end
 
-      self.class.typecast(idx, value)
+      typecast(idx, value)
     end
   end
 
+  # @param [Array] args (splat) all args provided in query string (as strings)
+  # This method is invoked with the arguments provided to the query.
+  # It should do work and return values matching the {.returns} declarations
   def execute!(*args)
     raise NotImplementedError, "Do work in this method"
   end
 
+  # The object passed to {Query#initialize} as `context`
   def context
     query.context
   end
 
+  # Executes the call, validates the return values against declared {.returns}, then returns the return values.
   def as_result
     return_declarations = self.class.return_declarations
     raise "#{self.class.name} must declare returns" unless return_declarations.present?
@@ -123,7 +130,10 @@ class GraphQL::RootCall
     end
 
     # @return [GraphQL::RootCallArgumentDefiner] definer
-    # Use this object to declare arguments.
+    # Use this object to declare arguments. They must be declared in order
+    # @example
+    #   argument.string("post_title")
+    #   argument.object("comment_data") # allows a JSON object
     def argument
       @argument ||= GraphQL::RootCallArgumentDefiner.new(self)
     end
@@ -138,39 +148,42 @@ class GraphQL::RootCall
     rescue NoMethodError
       own
     end
+  end
 
-    def argument_for_index(idx)
-      if arguments.first.any_number
-        arguments.first
-      else
-        arguments[idx]
-      end
-    end
+  private
 
-    TYPE_CHECKS = {
-      "object" => Hash,
-      "number" => Numeric,
-      "string" => String,
-    }
+  TYPE_CHECKS = {
+    "object" => Hash,
+    "number" => Numeric,
+    "string" => String,
+  }
 
-    def typecast(idx, value)
-      arg_dec = argument_for_index(idx)
-      expected_type = arg_dec.type
-      expected_type_class = TYPE_CHECKS[expected_type]
+  def argument_for_index(idx)
+    if self.class.arguments.first.any_number
+      self.class.arguments.first
+    else
+      self.class.arguments[idx]
+    end
+  end
 
-      if expected_type == "string"
-        parsed_value = value
-      else
-        parsed_value = JSON.parse('{ "value" : ' + value + '}')["value"]
-      end
+  def typecast(idx, value)
+    arg_dec = argument_for_index(idx)
+    expected_type = arg_dec.type
+    expected_type_class = TYPE_CHECKS[expected_type]
 
-      if !parsed_value.is_a?(expected_type_class)
-        raise GraphQL::RootCallArgumentError.new(arg_dec, value)
-      end
+    if expected_type == "string"
+      parsed_value = value
+    else
+      parsed_value = JSON.parse('{ "value" : ' + value + '}')["value"]
+    end
 
-      parsed_value
-    rescue JSON::ParserError
+    if !parsed_value.is_a?(expected_type_class)
       raise GraphQL::RootCallArgumentError.new(arg_dec, value)
     end
+
+    parsed_value
+  rescue JSON::ParserError
+    raise GraphQL::RootCallArgumentError.new(arg_dec, value)
   end
+
 end

data/lib/graphql/root_call_argument.rb

@@ -1,3 +1,4 @@
+# Created by {RootCall.argument}, used internally by GraphQL
 class GraphQL::RootCallArgument
   attr_reader :type, :name, :any_number
   def initialize(type:, name:, any_number: false)

data/lib/graphql/root_call_argument_definer.rb

@@ -1,3 +1,4 @@
+# Enables the {RootCall.argument} API, used internall by GraphQL
 class GraphQL::RootCallArgumentDefiner
   ARGUMENT_TYPES = [:string, :object, :number]
 

data/lib/graphql/schema.rb

@@ -1,6 +1,6 @@
 # {GraphQL::SCHEMA} keeps track of defined nodes, fields and calls.
+#
 # Although you don't interact with it directly, it responds to queries for `schema()` and `__type__` info.
-
 class GraphQL::Schema
   include Singleton
   attr_reader :types, :calls, :fields, :class_names, :connections

data/lib/graphql/transform.rb

@@ -1,3 +1,4 @@
+# {Transform} is a [parslet](http://kschiess.github.io/parslet/) transform for for turning the AST into objects in {GraphQL::Syntax}.
 class GraphQL::Transform < Parslet::Transform
   # query
   rule(nodes: sequence(:n), variables: sequence(:v)) { GraphQL::Syntax::Query.new(nodes: n, variables: v)}

data/lib/graphql/version.rb

@@ -1,3 +1,3 @@
 module GraphQL
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/readme.md

@@ -3,30 +3,31 @@
 [![Build Status](https://travis-ci.org/rmosolgo/graphql-ruby.svg?branch=master)](https://travis-ci.org/rmosolgo/graphql-ruby)
 [![Gem Version](https://badge.fury.io/rb/graphql.svg)](https://rubygems.org/gems/graphql)
 [![Dependency Status](https://gemnasium.com/rmosolgo/graphql-ruby.svg)](https://gemnasium.com/rmosolgo/graphql-ruby)
+[![Code Climate](https://codeclimate.com/github/rmosolgo/graphql-ruby/badges/gpa.svg)](https://codeclimate.com/github/rmosolgo/graphql-ruby)
+[![Test Coverage](https://codeclimate.com/github/rmosolgo/graphql-ruby/badges/coverage.svg)](https://codeclimate.com/github/rmosolgo/graphql-ruby)
+![image](https://cloud.githubusercontent.com/assets/2231765/6424458/d5fd3896-beae-11e4-892a-77e135e6bf37.png)
 
+Create a GraphQL interface by implementing [__nodes__](#nodes) and [__calls__](#calls), then running [__queries__](#queries).
 
-Create a GraphQL interface by implementing _nodes_ and _connections_, then running queries.
+API Docs: <http://rubydoc.info/gems/graphql>
 
 ## To do:
 
-
 - Allow a default connection class, or some way to infer connection from name
   - right now, `Introspection::Connection` isn't getting used, only `ApplicationConnection` is.
-
 - How do you express failure? HTTP response? `errors` key?
-- Handle blank objects in nested calls
+- Handle blank objects in nested calls (how? wait for spec)
 - Implement calls as arguments
 - double-check how to handle `pals.first(3) { count }`
 - Implement call argument introspection (wait for spec)
 - For fields that return objects, can they be queried _without_ other fields? Or must they always have fields?
-- __document__ (wait for spec)
 
 ## Example Implementation
 
 - See test implementation in [`/spec/support/dummy_app/nodes.rb`](https://github.com/rmosolgo/graphql/blob/master/spec/support/nodes.rb)
 - See `graphql-ruby-demo` with Rails on [github](https://github.com/rmosolgo/graphql-ruby-demo) or [heroku](http://graphql-ruby-demo.herokuapp.com/)
 
-![gql](https://cloud.githubusercontent.com/assets/2231765/6217972/5d24edda-b5ce-11e4-9e07-3548304af862.png)
+<a href="http://graphql-ruby-demo.herokuapp.com/" target="_blank"><img src="https://cloud.githubusercontent.com/assets/2231765/6217972/5d24edda-b5ce-11e4-9e07-3548304af862.png" style="max-width: 800px;"/></a>
 
 
 ## Usage
@@ -147,4 +148,3 @@ result
 ```
 
 You could do something like this [inside a Rails controller](https://github.com/rmosolgo/graphql-ruby-demo/blob/master/app/controllers/queries_controller.rb#L5).
-

data/spec/graphql/field_spec.rb

@@ -9,11 +9,8 @@ describe GraphQL::Field do
     it 'is present' do
       assert_equal field.name, "high_fives"
     end
-  end
-
-  describe '#method' do
     it 'defaults to name' do
-      assert_equal "high_fives", field.method
+      assert_equal "high_fives", field.name
     end
   end
 

data/spec/spec_helper.rb

@@ -1,3 +1,6 @@
+require "codeclimate-test-reporter"
+CodeClimate::TestReporter.start
+
 require 'date'
 require "minitest/autorun"
 require "minitest/focus"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Robert Mosolgo
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.2
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -204,7 +218,7 @@ files:
 - spec/spec_helper.rb
 - spec/support/dummy_app.rb
 - spec/support/nodes.rb
-homepage: http://github.com/rmosolgo/graphql
+homepage: http://github.com/rmosolgo/graphql-ruby
 licenses:
 - MIT
 metadata: {}