refactor(Relay) use nodes for connection items naming

Author: rmosolgo

CHANGELOG.md

@@ -8,6 +8,19 @@
 
 ### Bug fixes
 
+## 0.18.1 (7 Aug 2016)
+
+### Deprecations
+
+- Unify `Relay` naming around `nodes` as the items of a connection:
+  - `Relay::BaseConnection.connection_for_nodes` replaces `Relay::BaseConnection.connection_for_items`
+  - `Relay::BaseConnection#nodes` replaces `Relay::BaseConnection#object`
+
+### New features
+
+- Connection fields' `.resolve_proc` is an instance of `Relay::ConnectionResolve` #204
+- Types, fields and arguments can store arbitrary values in their `metadata` hashes #203
+
 ## 0.18.0 (4 Aug 2016)
 
 ### Breaking changes

guides/relay.md

@@ -295,11 +295,11 @@ Maybe you need to make a connection object yourself (for example, to return a co
 ```ruby
 items = [...]     # your collection objects
 args = {}         # stub out arguments for this connection object
-connection_class = GraphQL::Relay::BaseConnection.connection_for_items(items)
+connection_class = GraphQL::Relay::BaseConnection.connection_for_nodes(items)
 connection_class.new(items, args)
 ```
 
-`.connection_for_items` will return RelationConnection or ArrayConnection depending on `items`, then you can make a new connection
+`.connection_for_nodes` will return RelationConnection or ArrayConnection depending on `items`, then you can make a new connection
 
 ### Custom connections
 

lib/graphql/relay/array_connection.rb

@@ -18,7 +18,7 @@ def has_previous_page
 
       # apply first / last limit results
       def paged_nodes
-        @paged_nodes = begin
+        @paged_nodes ||= begin
           items = sliced_nodes
 
           if limit
@@ -31,10 +31,7 @@ def paged_nodes
 
       # Apply cursors to edges
       def sliced_nodes
-        @sliced_nodes ||= begin
-          items = object
-          items[starting_offset..-1]
-        end
+        @sliced_nodes ||= nodes[starting_offset..-1]
       end
 
       def index_from_cursor(cursor)

lib/graphql/relay/base_connection.rb

@@ -6,61 +6,71 @@ module Relay
     #   - {#paged_nodes}, which applies `first` & `last` limits
     #
     # In a subclass, you have access to
-    #   - {#object}, the object which the connection will wrap
+    #   - {#nodes}, the collection which the connection will wrap
     #   - {#first}, {#after}, {#last}, {#before} (arguments passed to the field)
     #   - {#max_page_size} (the specified maximum page size that can be returned from a connection)
     #
     class BaseConnection
+      extend Gem::Deprecate
+
       # Just to encode data in the cursor, use something that won't conflict
       CURSOR_SEPARATOR = "---"
 
       # Map of collection class names -> connection_classes
       # eg {"Array" => ArrayConnection}
       CONNECTION_IMPLEMENTATIONS = {}
 
-      # Find a connection implementation suitable for exposing `items`
-      #
-      # @param [Object] A collection of items (eg, Array, AR::Relation)
-      # @return [subclass of BaseConnection] a connection Class for wrapping `items`
-      def self.connection_for_items(items)
-        # We check class membership by comparing class names rather than
-        # identity to prevent this from being broken by Rails autoloading.
-        # Changes to the source file for ItemsClass in Rails apps cause it to be
-        # reloaded as a new object, so if we were to use `is_a?` here, it would
-        # no longer match any registered custom connection types.
-        ancestor_names = items.class.ancestors.map(&:name)
-        implementation = CONNECTION_IMPLEMENTATIONS.find do |items_class_name, connection_class|
-          ancestor_names.include? items_class_name
+      class << self
+        extend Gem::Deprecate
+
+        # Find a connection implementation suitable for exposing `nodes`
+        #
+        # @param [Object] A collection of nodes (eg, Array, AR::Relation)
+        # @return [subclass of BaseConnection] a connection Class for wrapping `nodes`
+        def connection_for_nodes(nodes)
+          # Check for class _names_ because classes can be redefined in Rails development
+          ancestor_names = nodes.class.ancestors.map(&:name)
+          implementation = CONNECTION_IMPLEMENTATIONS.find do |nodes_class_name, connection_class|
+            ancestor_names.include? nodes_class_name
+          end
+          if implementation.nil?
+            raise("No connection implementation to wrap #{nodes.class} (#{nodes})")
+          else
+            implementation[1]
+          end
         end
-        if implementation.nil?
-          raise("No connection implementation to wrap #{items.class} (#{items})")
-        else
-          implementation[1]
+
+        # Add `connection_class` as the connection wrapper for `nodes_class`
+        # eg, `RelationConnection` is the implementation for `AR::Relation`
+        # @param [Class] A class representing a collection (eg, Array, AR::Relation)
+        # @param [Class] A class implementing Connection methods
+        def register_connection_implementation(nodes_class, connection_class)
+          CONNECTION_IMPLEMENTATIONS[nodes_class.name] = connection_class
         end
-      end
 
-      # Add `connection_class` as the connection wrapper for `items_class`
-      # eg, `RelationConnection` is the implementation for `AR::Relation`
-      # @param [Class] A class representing a collection (eg, Array, AR::Relation)
-      # @param [Class] A class implementing Connection methods
-      def self.register_connection_implementation(items_class, connection_class)
-        CONNECTION_IMPLEMENTATIONS[items_class.name] = connection_class
+        # @deprecated use {#connection_for_nodes} instead
+        alias :connection_for_items :connection_for_nodes
+        deprecate(:connection_for_items, :connection_for_nodes, 2016, 9)
       end
 
-      attr_reader :object, :arguments, :max_page_size, :parent
+      attr_reader :nodes, :arguments, :max_page_size, :parent
 
-      # Make a connection, wrapping `object`
-      # @param The collection of results
+      # Make a connection, wrapping `nodes`
+      # @param [Object] The collection of nodes
       # @param Query arguments
       # @param max_page_size [Int] The maximum number of results to return
       # @param parent [Object] The object which this collection belongs to
-      def initialize(object, arguments, max_page_size: nil, parent: nil)
-        @object = object
+      def initialize(nodes, arguments, max_page_size: nil, parent: nil)
+        @nodes = nodes
         @arguments = arguments
         @max_page_size = max_page_size
         @parent = parent
       end
 
+      # @deprecated use {#nodes} instead
+      alias :object :nodes
+      deprecate(:object, :nodes, 2016, 9)
+
       # Provide easy access to provided arguments:
       METHODS_FROM_ARGUMENTS = [:first, :after, :last, :before, :order]
 
@@ -80,7 +90,7 @@ def initialize(object, arguments, max_page_size: nil, parent: nil)
         end
       end
 
-      # These are the items to render for this connection,
+      # These are the nodes to render for this connection,
       # probably wrapped by {GraphQL::Relay::Edge}
       def edge_nodes
         @edge_nodes ||= paged_nodes
@@ -127,11 +137,11 @@ def cursor_from_node(object)
       private
 
       def paged_nodes
-        raise NotImplementedError, "must return items for this connection after paging"
+        raise NotImplementedError, "must return nodes for this connection after paging"
       end
 
       def sliced_nodes
-        raise NotImplementedError, "must return  all items for this connection after chopping off first and last"
+        raise NotImplementedError, "must return  all nodes for this connection after chopping off first and last"
       end
     end
   end

lib/graphql/relay/connection_field.rb

@@ -1,11 +1,11 @@
 module GraphQL
   module Relay
-    # Provided a GraphQL field which returns a collection of items,
-    # `ConnectionField.create` modifies that field to expose those items
+    # Provided a GraphQL field which returns a collection of nodes,
+    # `ConnectionField.create` modifies that field to expose those nodes
     # as a collection.
     #
-    # The original resolve proc is used to fetch items,
-    # then a connection implementation is fetched with {BaseConnection.connection_for_items}.
+    # The original resolve proc is used to fetch nodes,
+    # then a connection implementation is fetched with {BaseConnection.connection_for_nodes}.
     class ConnectionField
       ARGUMENT_DEFINITIONS = [
           ["first", GraphQL::INT_TYPE, "Returns the first _n_ elements from the list."],
@@ -27,24 +27,15 @@ class ConnectionField
       # Turn A GraphQL::Field into a connection by:
       # - Merging in the default arguments
       # - Transforming its resolve function to return a connection object
-      # @param [GraphQL::Field] A field which returns items to be wrapped as a connection
-      # @param max_page_size [Integer] The maximum number of items which may be requested (if a larger page is requested, it is limited to this number)
-      # @return [GraphQL::Field] A field which serves a connections
+      # @param [GraphQL::Field] A field which returns nodes to be wrapped as a connection
+      # @param max_page_size [Integer] The maximum number of nodes which may be requested (if a larger page is requested, it is limited to this number)
+      # @return [GraphQL::Field] The same field, modified to resolve to a connection object
       def self.create(underlying_field, max_page_size: nil)
         underlying_field.arguments = DEFAULT_ARGUMENTS.merge(underlying_field.arguments)
         original_resolve = underlying_field.resolve_proc
-        underlying_field.resolve = get_connection_resolve(underlying_field.name, original_resolve, max_page_size: max_page_size)
+        underlying_field.resolve = GraphQL::Relay::ConnectionResolve.new(underlying_field.name, original_resolve, max_page_size: max_page_size)
         underlying_field
       end
-
-      private
-
-      # Wrap the original resolve proc
-      # so you capture its value, then wrap it in a
-      # connection implementation
-      def self.get_connection_resolve(field_name, underlying_resolve, max_page_size: nil)
-        GraphQL::Relay::ConnectionResolve.new(field_name, underlying_resolve, max_page_size: max_page_size)
-      end
     end
   end
 end

lib/graphql/relay/connection_resolve.rb

@@ -8,9 +8,9 @@ def initialize(field_name, underlying_resolve, max_page_size: nil)
       end
 
       def call(obj, args, ctx)
-        items = @underlying_resolve.call(obj, args, ctx)
-        connection_class = GraphQL::Relay::BaseConnection.connection_for_items(items)
-        connection_class.new(items, args, max_page_size: @max_page_size, parent: obj)
+        nodes = @underlying_resolve.call(obj, args, ctx)
+        connection_class = GraphQL::Relay::BaseConnection.connection_for_nodes(nodes)
+        connection_class.new(nodes, args, max_page_size: @max_page_size, parent: obj)
       end
     end
   end

lib/graphql/relay/relation_connection.rb

@@ -22,18 +22,12 @@ def has_previous_page
 
       # apply first / last limit results
       def paged_nodes
-        @paged_nodes ||= begin
-          items = sliced_nodes
-          items.limit(limit)
-        end
+        @paged_nodes ||= sliced_nodes.limit(limit)
       end
 
       # Apply cursors to edges
       def sliced_nodes
-        @sliced_nodes ||= begin
-          items = object
-          items.offset(starting_offset)
-        end
+        @sliced_nodes ||= nodes.offset(starting_offset)
       end
 
       def offset_from_cursor(cursor)

readme.md

@@ -142,4 +142,3 @@ If you're building a backend for [Relay](http://facebook.github.io/relay/), you'
   - Reduce duplication in ArrayConnection / RelationConnection
   - Improve API for creating edges (better RANGE_ADD support)
   - If the new edge isn't a member of the connection's objects, raise a nice error
-  - Rename `Connection#object` => `Connection#collection` with deprecation

spec/support/star_wars_schema.rb

@@ -47,7 +47,7 @@
   name "BasesConnectionWithTotalCount"
   field :totalCount do
     type types.Int
-    resolve -> (obj, args, ctx) { obj.object.count }
+    resolve -> (obj, args, ctx) { obj.nodes.count }
   end
 end
 
@@ -75,7 +75,7 @@ def upcased_parent_name
 
   field :totalCountTimes100 do
     type types.Int
-    resolve -> (obj, args, ctx) { obj.object.count * 100 }
+    resolve -> (obj, args, ctx) { obj.nodes.count * 100 }
   end
 end