graphql 0.3.0 → 0.4.0

data/lib/graph_ql/schema/type_reducer.rb

@@ -13,6 +13,13 @@ class GraphQL::Schema::TypeReducer
     end
   end
 
+  # Reduce all of `types` and return the combined result
+  def self.find_all(types)
+    types.reduce({}) do |memo, type|
+      self.new(type, memo).result
+    end
+  end
+
   private
 
   def find_types(type, type_hash)

data/lib/graph_ql/static_validation/arguments_validator.rb

@@ -5,6 +5,7 @@ class GraphQL::StaticValidation::ArgumentsValidator
   def validate(context)
     visitor = context.visitor
     visitor[GraphQL::Nodes::Field] << -> (node, parent) {
+      return if context.skip_field?(node.name)
       field_defn = context.field_definition
       validate_node(node, field_defn, context)
     }

data/lib/graph_ql/static_validation/message.rb

@@ -8,12 +8,15 @@ class GraphQL::StaticValidation::Message
       GraphQL::StaticValidation::Message.new(message, line: node.line, col: node.col)
     end
   end
-  attr_reader :message, :line, :co
+  attr_reader :message, :line, :col
+
   def initialize(message, line: nil, col: nil)
     @message = message
     @line = line
     @col = col
   end
+
+  # A hash representation of this Message
   def to_h
     {
       "message" => message,

data/lib/graph_ql/static_validation/rules/fields_are_defined_on_type.rb

@@ -6,6 +6,7 @@ class GraphQL::StaticValidation::FieldsAreDefinedOnType
   def validate(context)
     visitor = context.visitor
     visitor[GraphQL::Nodes::Field] << -> (node, parent) {
+      return if context.skip_field?(node.name)
       parent_type = context.object_types[-2]
       parent_type = parent_type.kind.unwrap(parent_type)
       validate_field(context.errors, node, parent_type, parent)

data/lib/graph_ql/static_validation/rules/fields_have_appropriate_selections.rb

@@ -5,6 +5,7 @@ class GraphQL::StaticValidation::FieldsHaveAppropriateSelections
 
   def validate(context)
     context.visitor[GraphQL::Nodes::Field] << -> (node, parent)  {
+      return if context.skip_field?(node.name)
       field_defn = context.field_definition
       validate_field_selections(node, field_defn, context.errors)
     }

data/lib/graph_ql/static_validation/type_stack.rb

@@ -7,7 +7,25 @@ class GraphQL::StaticValidation::TypeStack
     GraphQL::Nodes::FragmentDefinition,
   ]
 
-  attr_reader :schema, :object_types, :field_definitions, :directive_definitions
+  # @return [GraphQL::Schema] the schema whose types are present in this document
+  attr_reader :schema
+
+  # When it enters an object (starting with query or mutation root), it's pushed on this stack.
+  # When it exits, it's popped off.
+  # @return [Array<GraphQL::ObjectType, GraphQL::Union, GraphQL::Interface>]
+  attr_reader :object_types
+
+  # When it enters a field, it's pushed on this stack (useful for nested fields, args).
+  # When it exits, it's popped off.
+  # @return [Array<GraphQL::Field>] fields which have been entered
+  attr_reader :field_definitions
+
+  # Directives are pushed on, then popped off while traversing the tree
+  # @return [Array<GraphQL::Node::Directive>] directives which have been entered
+  attr_reader :directive_definitions
+
+  # @param schema [GraphQL::Schema] the schema whose types to use when climbing this document
+  # @param visitor [GraphQL::Visitor] a visitor to follow & watch the types
   def initialize(schema, visitor)
     @schema = schema
     @object_types = []
@@ -61,7 +79,7 @@ class GraphQL::StaticValidation::TypeStack
       parent_type = stack.object_types.last
       parent_type = parent_type.kind.unwrap(parent_type)
       if parent_type.kind.fields?
-        field_class = parent_type.fields[node.name]
+        field_class = stack.schema.get_field(parent_type, node.name)
         stack.field_definitions.push(field_class)
         if !field_class.nil?
           next_object_type = field_class.type
@@ -92,8 +110,10 @@ class GraphQL::StaticValidation::TypeStack
     end
   end
 
+  # A no-op strategy (don't handle this node)
   class NullStrategy
-    def push(stack, node);  end
-    def pop(stack, node);   end
+    def self.new; self; end
+    def self.push(stack, node);  end
+    def self.pop(stack, node);   end
   end
 end

data/lib/graph_ql/static_validation/validator.rb

@@ -1,12 +1,23 @@
 # Initialized with a {GraphQL::Schema}, then it can validate {GraphQL::Nodes::Documents}s based on that schema.
 #
 # By default, it's used by {GraphQL::Query}
+#
+# @example Validate a query
+#   validator = GraphQL::StaticValidation::Validator.new(schema: MySchema)
+#   document = GraphQL.parse(query_string)
+#   errors = validator.validate(document)
+#
 class GraphQL::StaticValidation::Validator
+  # @param schema [GraphQL::Schema]
+  # @param rule [Array<#validate(context)>] a list of rules to use when validating
   def initialize(schema:, rules: GraphQL::StaticValidation::ALL_RULES)
     @schema = schema
     @rules = rules
   end
 
+  # Validate `document` against the schema. Returns an array of message hashes.
+  # @param document [GraphQL::Nodes::Document]
+  # @return [Array<Hash>]
   def validate(document)
     context = Context.new(@schema, document)
     @rules.each do |rules|
@@ -16,6 +27,16 @@ class GraphQL::StaticValidation::Validator
     context.errors.map(&:to_h)
   end
 
+  # The validation context gets passed to each validator.
+  #
+  # It exposes a {GraphQL::Visitor} where validators may add hooks. ({Visitor#visit} is called in {Validator#validate})
+  #
+  # It provides access to the schema & fragments which validators may read from.
+  #
+  # It holds a list of errors which each validator may add to.
+  #
+  # It also provides limited access to the {TypeStack} instance,
+  # which tracks state as you climb in and out of different fields.
   class Context
     attr_reader :schema, :document, :errors, :visitor, :fragments
     def initialize(schema, document)
@@ -40,5 +61,11 @@ class GraphQL::StaticValidation::Validator
     def directive_definition
       @type_stack.directive_definitions.last
     end
+
+    # Don't try to validate dynamic fields
+    # since they aren't defined by the type system
+    def skip_field?(field_name)
+      GraphQL::Schema::DYNAMIC_FIELDS.include?(field_name)
+    end
   end
 end

data/lib/graph_ql/transform.rb

@@ -0,0 +1,87 @@
+module GraphQL
+  # {Transform} is a [parslet](http://kschiess.github.io/parslet/) transform for for turning the AST into objects in {GraphQL::Nodes} objects.
+  class Transform < Parslet::Transform
+    def self.optional_sequence(name)
+      rule(name => simple(:val)) { [] }
+      rule(name => sequence(:val)) { val }
+    end
+
+    # Document
+    rule(document_parts: sequence(:p)) { Nodes::Document.new(parts: p, line: p.first.line, col: p.first.col)}
+
+    # Fragment Definition
+    rule(
+      fragment_keyword: simple(:kw),
+      fragment_name:  simple(:name),
+      type_condition: simple(:type),
+      directives:     sequence(:directives),
+      selections:     sequence(:selections)
+    ) { Nodes::FragmentDefinition.new(name: name.to_s, type: type.to_s, directives: directives, selections: selections, position_source: kw)}
+
+    rule(
+      fragment_spread_keyword: simple(:kw),
+      fragment_spread_name: simple(:n),
+      directives:           sequence(:d)
+    ) { Nodes::FragmentSpread.new(name: n.to_s, directives: d, position_source: kw)}
+
+    rule(
+      fragment_spread_keyword: simple(:kw),
+      inline_fragment_type: simple(:n),
+      directives: sequence(:d),
+      selections: sequence(:s),
+    ) { Nodes::InlineFragment.new(type: n.to_s, directives: d, selections: s, position_source: kw)}
+
+    # Operation Definition
+    rule(
+      operation_type: simple(:ot),
+      name:           simple(:n),
+      variables:      sequence(:v),
+      directives:     sequence(:d),
+      selections:     sequence(:s),
+    ) { Nodes::OperationDefinition.new(operation_type: ot.to_s, name: n.to_s, variables: v, directives: d, selections: s, position_source: ot) }
+    optional_sequence(:optional_variables)
+    rule(variable_name: simple(:n), variable_type: simple(:t), variable_optional_default_value: simple(:v)) { Nodes::Variable.new(name: n.name, type: t, default_value: v, line: n.line, col: n.col)}
+    rule(variable_name: simple(:n), variable_type: simple(:t), variable_optional_default_value: sequence(:v)) { Nodes::Variable.new(name: n.name, type: t, default_value: v, line: n.line, col: n.col)}
+    rule(variable_default_value: simple(:v) ) { v }
+    rule(variable_default_value: sequence(:v) ) { v }
+    # Query short-hand
+    rule(unnamed_selections: sequence(:s)) { Nodes::OperationDefinition.new(selections: s, operation_type: "query", name: nil, variables: [], directives: [], line: s.first.line, col: s.first.col)}
+
+    # Field
+    rule(
+      alias: simple(:a),
+      field_name: simple(:name),
+      field_arguments: sequence(:args),
+      directives: sequence(:dir),
+      selections: sequence(:sel)
+    ) { Nodes::Field.new(alias: a && a.to_s, name: name.to_s, arguments: args, directives: dir, selections: sel, position_source: [a, name].find { |part| !part.nil? }) }
+
+    rule(alias_name: simple(:a)) { a }
+    optional_sequence(:optional_field_arguments)
+    rule(field_argument_name: simple(:n), field_argument_value: simple(:v)) { Nodes::Argument.new(name: n.to_s, value: v, position_source: n)}
+    optional_sequence(:optional_selections)
+    optional_sequence(:optional_directives)
+
+    # Directive
+    rule(directive_name: simple(:name), directive_arguments: sequence(:args)) { Nodes::Directive.new(name: name.to_s, arguments: args, position_source: name ) }
+    rule(directive_argument_name: simple(:n), directive_argument_value: simple(:v)) { Nodes::Argument.new(name: n.to_s, value: v, position_source: n)}
+    optional_sequence(:optional_directive_arguments)
+
+    # Type Defs
+    rule(type_name: simple(:n))     { Nodes::TypeName.new(name: n.to_s, position_source: n) }
+    rule(list_type: simple(:t))     { Nodes::ListType.new(of_type: t, line: t.line, col: t.col)}
+    rule(non_null_type: simple(:t)) { Nodes::NonNullType.new(of_type: t, line: t.line, col: t.col)}
+
+    # Values
+    rule(array: sequence(:v)) { v }
+    rule(boolean: simple(:v)) { v == "true" ? true : false }
+    rule(input_object: sequence(:v)) { Nodes::InputObject.new(pairs: v, line: v.first.line, col: v.first.col) }
+    rule(input_object_name: simple(:n), input_object_value: simple(:v)) { Nodes::Argument.new(name: n.to_s, value: v, position_source: n)}
+    rule(int: simple(:v)) { v.to_i }
+    rule(float: simple(:v)) { v.to_f }
+    rule(string: simple(:v)) { v.to_s }
+    rule(variable: simple(:v)) { Nodes::VariableIdentifier.new(name: v.to_s, position_source: v) }
+    rule(enum: simple(:v)) { Nodes::Enum.new(name: v.to_s, position_source: v)}
+  end
+  TRANSFORM = GraphQL::Transform.new
+end

data/lib/graph_ql/type_kinds.rb

@@ -1,4 +1,6 @@
+# Type kinds are the basic categories which a type may belong to (`Object`, `Scalar`, `Union`...)
 module GraphQL::TypeKinds
+  # These objects are singletons, eg `GraphQL::TypeKinds::UNION`, `GraphQL::TypeKinds::SCALAR`.
   class TypeKind
     attr_reader :name
     def initialize(name, resolves: false, fields: false, wraps: false, input: false)
@@ -10,13 +12,19 @@ module GraphQL::TypeKinds
       @composite = fields? || resolves?
     end
 
+    # Does this TypeKind have multiple possible implementors?
     def resolves?;  @resolves;  end
+    # Does this TypeKind have queryable fields?
     def fields?;    @fields;    end
+    # Does this TypeKind modify another type?
     def wraps?;     @wraps;     end
+    # Is this TypeKind a valid query input?
     def input?;     @input;     end
     def to_s;       @name;      end
+    # Is this TypeKind composed of many values?
     def composite?; @composite; end
 
+    # Get the implementing type for `value` from `type` (no-op for TypeKinds which don't `resolves?`)
     def resolve(type, value)
       if resolves?
         type.resolve_type(value)
@@ -25,6 +33,7 @@ module GraphQL::TypeKinds
       end
     end
 
+    # Get the modified type for `type` (no-op for TypeKinds which don't `wraps?`)
     def unwrap(type)
       if wraps?
         wrapped_type = type.of_type

data/lib/graph_ql/{types/union.rb → union_type.rb}

@@ -1,5 +1,10 @@
-class GraphQL::Union
-  include GraphQL::NonNullWithBang
+# A collection of {ObjectType}s
+#
+# @example a union of types
+#   PetUnion = GraphQL::UnionType.new("Pet", "House pets", [DogType, CatType])
+#
+class GraphQL::UnionType
+  include GraphQL::DefinitionHelpers::NonNullWithBang
   attr_reader :name, :description, :possible_types
   def initialize(name, desc, types)
     @name = name
@@ -11,8 +16,7 @@ class GraphQL::Union
     GraphQL::TypeKinds::UNION
   end
 
-  # Find a type in this union for a given object.
-  # Reimplement if needed
+  # @see {InterfaceType#resolve_type}
   def resolve_type(object)
     type_name = object.class.name
     possible_types.find {|t| t.name == type_name}

data/lib/graph_ql/version.rb

@@ -1,3 +1,3 @@
 module GraphQL
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/graph_ql/{parser/visitor.rb → visitor.rb}

@@ -1,28 +1,44 @@
 # Depth-first traversal through the tree, calling hooks at each stop.
 #
-# @example: Create a visitor, add hooks, then search a document
+# @example Create a visitor, add hooks, then search a document
 #   total_field_count = 0
 #   visitor = GraphQL::Visitor.new
+#   # Whenever you find a field, increment the field count:
 #   visitor[GraphQL::Nodes::Field] << -> (node) { total_field_count += 1 }
+#   # When we finish, print the field count:
 #   visitor[GraphQL::Nodes::Document].leave << -> (node) { p total_field_count }
 #   visitor.visit(document)
 #   # => 6
 #
 class GraphQL::Visitor
+  # If any hook returns this value, the {Visitor} stops visiting this
+  # node right away
   SKIP = :_skip
 
-  attr_reader :enter, :leave
+  # @return [Array<Proc>] Hooks to call when entering _any_ node
+  attr_reader :enter
+  # @return [Array<Proc>] Hooks to call when leaving _any_ node
+  attr_reader :leave
+
   def initialize
     @visitors = {}
     @enter = []
     @leave = []
   end
 
+  # Get a {NodeVisitor} for `node_class`
+  # @param node_class [Class] The node class that you want to listen to
+  # @return [NodeVisitor]
+  #
+  # @example Run a hook whenever you enter a new Field
+  #   visitor[GraphQL::Nodes::Field] << -> (node, parent) { p "Here's a field" }
   def [](node_class)
     @visitors[node_class] ||= NodeVisitor.new
   end
 
-  # Apply built-up vistors to `document`
+  # Visit `root` and all children, applying hooks as you go
+  # @param root [GraphQL::Nodes::AbstractNode] some node to start parsing on
+  # @return [void]
   def visit(root, parent=nil)
     begin_visit(root, parent) &&
       root.children.reduce(true) { |memo, child| memo && visit(child, root) }
@@ -49,13 +65,22 @@ class GraphQL::Visitor
     hooks.reduce(true) { |memo, proc| memo && (proc.call(node, parent) != SKIP) }
   end
 
+  # Collect `enter` and `leave` hooks for classes in {GraphQL::Nodes}
+  #
+  # Access {NodeVisitor}s via {GraphQL::Visitor#[]}
   class NodeVisitor
-    attr_reader :enter, :leave
+    # @return [Array<Proc>] Hooks to call when entering a node of this type
+    attr_reader :enter
+    # @return [Array<Proc>] Hooks to call when leaving a node of this type
+    attr_reader :leave
+
     def initialize
       @enter = []
       @leave = []
     end
 
+    # Shorthand to add a hook to the {#enter} array
+    # @param hook [Proc] A hook to add
     def <<(hook)
       enter << hook
     end

data/lib/graphql.rb

@@ -3,6 +3,10 @@ require "parslet"
 require "singleton"
 
 module GraphQL
+  # Turn a query string into an AST
+  # @param string [String] a GraphQL query string
+  # @param as [Symbol] If you want to use this to parse some _piece_ of a document, pass the rule name (from {GraphQL::Parser::Parser})
+  # @return [GraphQL::Nodes::Document]
   def self.parse(string, as: nil)
     parser = as ? GraphQL::PARSER.send(as) : GraphQL::PARSER
     tree = parser.parse(string)
@@ -12,26 +16,33 @@ module GraphQL
     raise [line, col, string].join(", ")
   end
 
+  # Types & Fields that support GraphQL introspection queries
   module Introspection; end
 end
 
-def require_dir(dir)
-  Dir.glob(File.expand_path("../graph_ql/#{dir}/*.rb", __FILE__)).each do |file|
-    require file
-  end
-end
 # Order matters for these:
 
-require_dir('definition_helpers')
-require 'graph_ql/types/object_type'
-require_dir('types')
+require 'graph_ql/definition_helpers'
+require 'graph_ql/object_type'
+
+require 'graph_ql/enum_type'
+require 'graph_ql/input_object_type'
+require 'graph_ql/interface_type'
+require 'graph_ql/list_type'
+require 'graph_ql/non_null_type'
+require 'graph_ql/union_type'
 
+require 'graph_ql/argument'
 require 'graph_ql/field'
 require 'graph_ql/type_kinds'
 require 'graph_ql/introspection/typename_field'
 
-require 'graph_ql/scalars/scalar_type'
-require_dir('scalars')
+require 'graph_ql/scalar_type'
+require 'graph_ql/boolean_type'
+require 'graph_ql/float_type'
+require 'graph_ql/id_type'
+require 'graph_ql/int_type'
+require 'graph_ql/string_type'
 
 require 'graph_ql/introspection/input_value_type'
 require 'graph_ql/introspection/enum_value_type'
@@ -45,13 +56,19 @@ require 'graph_ql/introspection/enum_values_field'
 require 'graph_ql/introspection/interfaces_field'
 
 require 'graph_ql/introspection/type_type'
+require 'graph_ql/introspection/arguments_field'
 require 'graph_ql/introspection/field_type'
 
-require 'graph_ql/introspection/arguments_field'
 require 'graph_ql/introspection/directive_type'
 require 'graph_ql/introspection/schema_type'
+require 'graph_ql/introspection/schema_field'
+require 'graph_ql/introspection/type_by_name_field'
+require 'graph_ql/introspection/introspection_query'
 
+require 'graph_ql/nodes'
 require 'graph_ql/parser'
+require 'graph_ql/transform'
+require 'graph_ql/visitor'
 require 'graph_ql/directive'
 require 'graph_ql/schema'