Accept user-defined metadata

Author: rmosolgo

guides/defining_your_schema.md

@@ -352,3 +352,40 @@ If the last value of `memo` (or the return of `.final_value`) is a `GraphQL::Ana
 `graphql-ruby` includes a few query analyzers:
 - `GraphQL::Analysis::QueryDepth` and `GraphQL::Analysis::QueryComplexity` for inspecting query depth and complexity
 - `GraphQL::Analysis::MaxQueryDepth` and `GraphQL::Analysis::MaxQueryComplexity` are used internally to implement `max_depth:` and `max_complexity:` options
+
+## Extending type and field definitions
+
+Types, fields, and arguments have a `metadata` hash which accepts values during definition.
+
+First, make a custom definition:
+
+```ruby
+GraphQL::ObjectType.accepts_definitions resolves_to_class_names: GraphQL::Define.assign_metadata_key(:resolves_to_class_names)
+# or:
+# GraphQL::Field.accepts_definitions(...)
+# GraphQL::Argument.accepts_definitions(...)
+```
+
+
+Then, use the custom definition:
+
+```ruby
+Post = GraphQL::ObjectType.define do
+  # ...
+  resolves_to_class_names ["Post", "StaffUpdate"]
+end
+```
+
+Access `type.metadata` later:
+
+```ruby
+SearchResultUnion = GraphQL::Union.define do
+  # ...
+  # Use the type's declared `resolves_to_class_names`
+  # to figure out if `obj` is a member of that type
+  resolve_type -> (obj, ctx) {
+    class_name = obj.class.name
+    possible_types.find { |type| type.metadata[:resolves_to_class_names].include?(class_name) }
+  }
+end
+```

lib/graphql/define.rb

@@ -3,8 +3,26 @@
 require "graphql/define/assign_enum_value"
 require "graphql/define/assign_global_id_field"
 require "graphql/define/assign_object_field"
-require "graphql/define/assignment_dictionary"
 require "graphql/define/defined_object_proxy"
 require "graphql/define/instance_definable"
 require "graphql/define/non_null_with_bang"
 require "graphql/define/type_definer"
+
+module GraphQL
+  module Define
+    # A helper for definitions that store their value in `#metadata`.
+    #
+    # @example Storing application classes with GraphQL types
+    #   # Make a custom definition
+    #   GraphQL::ObjectType.accepts_definitions(resolves_to_class_names: GraphQL::Define.assign_metadata_key(:resolves_to_class_names))
+    #
+    #   # After definition, read the key from metadata
+    #   PostType.metadata[:resolves_to_class_names] # => [...]
+    #
+    # @param [Object] the key to assign in metadata
+    # @return [#call(defn, value)] an assignment for `.accepts_definitions` which writes `key` to `#metadata`
+    def self.assign_metadata_key(key)
+      GraphQL::Define::InstanceDefinable::AssignMetadataKey.new(key)
+    end
+  end
+end

lib/graphql/define/assignment_dictionary.rb

@@ -1,22 +1,36 @@
 module GraphQL
   module Define
-    # This module provides the `.define { ... }` API for {GraphQL::BaseType}, {GraphQL::Field}, {GraphQL::Argument} and {GraphQL::Directive}.
+    # This module provides the `.define { ... }` API for
+    # {GraphQL::BaseType}, {GraphQL::Field} and others.
+    #
+    # Calling `.accepts_definitions(...)` creates:
+    #
+    # - a keyword to the `.define` method
+    # - a helper method in the `.define { ... }` block
+    #
+    # The `.define { ... }` block will be called lazily. To be sure it has been
+    # called, use the private method `#ensure_defined`. That will call the
+    # definition block if it hasn't been called already.
     #
     # The goals are:
+    #
     # - Minimal overhead in consuming classes
     # - Independence between consuming classes
     # - Extendable by third-party libraries without monkey-patching or other nastiness
     #
     # @example Make a class definable
     #   class Car
-    #     attr_accessor :make, :model, :all_wheel_drive
-    #
+    #     attr_accessor :make, :model
     #     accepts_definitions(
     #       # These attrs will be defined with plain setters, `{attr}=`
     #       :make, :model,
     #       # This attr has a custom definition which applies the config to the target
     #       doors: -> (car, doors_count) { doors_count.times { car.doors << Door.new } }
     #     )
+    #
+    #     def initialize
+    #       @doors = []
+    #     end
     #   end
     #
     #   # Create an instance with `.define`:
@@ -31,14 +45,17 @@ module Define
     #
     # @example Extending the definition of a class
     #   # Add some definitions:
-    #   Car.accepts_definitions(:all_wheel_drive)
+    #   Car.accepts_definitions(all_wheel_drive: GraphQL::Define.assign_metadata_key(:all_wheel_drive))
     #
     #   # Use it in a definition
     #   subaru_baja = Car.define do
     #     # ...
     #     all_wheel_drive true
     #   end
     #
+    #   # Access it from metadata
+    #   subaru_baja.metadata[:all_wheel_drive] # => true
+    #
     module InstanceDefinable
       def self.included(base)
         base.extend(ClassMethods)
@@ -50,6 +67,14 @@ def definition_proc=(defn_block)
         @definition_proc = defn_block
       end
 
+      # `metadata` can store arbitrary key-values with an object.
+      #
+      # @return [Hash<Object, Object>] Hash for user-defined storage
+      def metadata
+        ensure_defined
+        @metadata ||= {}
+      end
+
       private
 
       # Run the definition block if it hasn't been run yet.
@@ -91,7 +116,17 @@ def define(**kwargs, &block)
         # Each symbol in `accepts` will be assigned with `{key}=`.
         # The last entry in accepts may be a hash of name-proc pairs for custom definitions.
         def accepts_definitions(*accepts)
-          @own_dictionary = own_dictionary.merge(AssignmentDictionary.create(*accepts))
+          new_assignments = if accepts.last.is_a?(Hash)
+            accepts.pop.dup
+          else
+            {}
+          end
+
+          accepts.each do |key|
+            new_assignments[key] = AssignAttribute.new(key)
+          end
+
+          @own_dictionary = own_dictionary.merge(new_assignments)
         end
 
         # Define a reader and writer for each of `attr_names` which
@@ -125,6 +160,26 @@ def own_dictionary
           @own_dictionary ||= {}
         end
       end
+
+      class AssignMetadataKey
+        def initialize(key)
+          @key = key
+        end
+
+        def call(defn, value)
+          defn.metadata[@key] = value
+        end
+      end
+
+      class AssignAttribute
+        def initialize(attr_name)
+          @attr_assign_method = :"#{attr_name}="
+        end
+
+        def call(defn, value)
+          defn.public_send(@attr_assign_method, value)
+        end
+      end
     end
   end
 end

lib/graphql/define/instance_definable.rb

@@ -21,4 +21,8 @@
       GraphQL::ListType.new(of_type: !MilkType)
     )
   end
+
+  it "Accepts arbitrary metadata" do
+    assert_equal ["Cheese"], CheeseType.metadata[:class_names]
+  end
 end

spec/graphql/base_type_spec.rb

@@ -12,7 +12,7 @@ def self.call(plant, plant_range)
   class Vegetable
     include GraphQL::Define::InstanceDefinable
     lazy_defined_attr_accessor :name, :start_planting_on, :end_planting_on
-    accepts_definitions :name, plant_between: DefinePlantBetween
+    accepts_definitions :name, plant_between: DefinePlantBetween, color: GraphQL::Define.assign_metadata_key(:color)
 
     # definition added later:
     lazy_defined_attr_accessor :height
@@ -61,4 +61,11 @@ class Vegetable
       assert_equal Date.new(2000, 7, 1), okra.end_planting_on
     end
   end
+
+  describe "#metadata" do
+    it "gets values from definitions" do
+      arugula = Garden::Vegetable.define(name: "Arugula", color: :green)
+      assert_equal :green, arugula.metadata[:color]
+    end
+  end
 end

spec/graphql/define/instance_definable_spec.rb

@@ -17,7 +17,6 @@
     assert_equal(DairyProductUnion, field.type)
   end
 
-
   describe ".property " do
     let(:field) do
       GraphQL::Field.define do
@@ -107,4 +106,11 @@ def acts_like_default_resolver(field, old_prop, new_prop)
       assert_equal "Xyz", resolved_source
     end
   end
+
+  describe "#metadata" do
+    it "accepts user-defined metadata" do
+      similar_cheese_field = CheeseType.get_field("similarCheese")
+      assert_equal [:cheeses, :milks], similar_cheese_field.metadata[:joins]
+    end
+  end
 end

spec/graphql/field_spec.rb

@@ -2,6 +2,9 @@
 
 class NoSuchDairyError < StandardError; end
 
+GraphQL::Field.accepts_definitions(joins: GraphQL::Define.assign_metadata_key(:joins))
+GraphQL::BaseType.accepts_definitions(class_names: GraphQL::Define.assign_metadata_key(:class_names))
+
 EdibleInterface = GraphQL::InterfaceType.define do
   name "Edible"
   description "Something you can eat, yum"
@@ -26,6 +29,7 @@ class NoSuchDairyError < StandardError; end
 
 CheeseType = GraphQL::ObjectType.define do
   name "Cheese"
+  class_names ["Cheese"]
   description "Cultured dairy product"
   interfaces [EdibleInterface, AnimalProductInterface]
 
@@ -39,6 +43,8 @@ class NoSuchDairyError < StandardError; end
 
   # Or can define by block, `resolve ->` should override `property:`
   field :similarCheese, CheeseType, "Cheeses like this one", property: :this_should_be_overriden  do
+    # metadata test
+    joins [:cheeses, :milks]
     argument :source, !types[!DairyAnimalEnum]
     resolve -> (t, a, c) {
       # get the strings out: