graphql 1.8.0 → 1.12.12

data/lib/graphql/types/iso_8601_date.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    # This scalar takes `Date`s and transmits them as strings,
+    # using ISO 8601 format.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :published_at, GraphQL::Types::ISO8601Date, null: false
+    #
+    #     argument :deliver_at, GraphQL::Types::ISO8601Date, null: false
+    #
+    # Alternatively, use this built-in scalar as inspiration for your
+    # own Date type.
+    class ISO8601Date < GraphQL::Schema::Scalar
+      description "An ISO 8601-encoded date"
+
+      # @param value [Date,Time,DateTime,String]
+      # @return [String]
+      def self.coerce_result(value, _ctx)
+        Date.parse(value.to_s).iso8601
+      end
+
+      # @param str_value [String]
+      # @return [Date]
+      def self.coerce_input(str_value, _ctx)
+        Date.iso8601(str_value)
+      rescue ArgumentError, TypeError
+        # Invalid input
+        nil
+      end
+    end
+  end
+end

data/lib/graphql/types/iso_8601_date_time.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module GraphQL
+  module Types
+    # This scalar takes `Time`s and transmits them as strings,
+    # using ISO 8601 format.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :created_at, GraphQL::Types::ISO8601DateTime, null: false
+    #
+    #     argument :deliver_at, GraphQL::Types::ISO8601DateTime, null: false
+    #
+    # Alternatively, use this built-in scalar as inspiration for your
+    # own DateTime type.
+    class ISO8601DateTime < GraphQL::Schema::Scalar
+      description "An ISO 8601-encoded datetime"
+
+      # It's not compatible with Rails' default,
+      # i.e. ActiveSupport::JSON::Encoder.time_precision (3 by default)
+      DEFAULT_TIME_PRECISION = 0
+
+      # @return [Integer]
+      def self.time_precision
+        @time_precision || DEFAULT_TIME_PRECISION
+      end
+
+      # @param [Integer] value
+      def self.time_precision=(value)
+        @time_precision = value
+      end
+
+      # @param value [Time,Date,DateTime,String]
+      # @return [String]
+      def self.coerce_result(value, _ctx)
+        case value
+        when Date
+          return value.to_time.iso8601(time_precision)
+        when ::String
+          return Time.parse(value).iso8601(time_precision)
+        else
+          # Time, DateTime or compatible is given:
+          return value.iso8601(time_precision)
+        end
+      rescue StandardError => error
+        raise GraphQL::Error, "An incompatible object (#{value.class}) was given to #{self}. Make sure that only Times, Dates, DateTimes, and well-formatted Strings are used with this type. (#{error.message})"
+      end
+
+      # @param str_value [String]
+      # @return [Time]
+      def self.coerce_input(str_value, _ctx)
+        Time.iso8601(str_value)
+      rescue ArgumentError, TypeError
+        begin
+          Date.iso8601(str_value).to_time
+        rescue ArgumentError, TypeError
+          # Invalid input
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    # An untyped JSON scalar that maps to Ruby hashes, arrays, strings, integers, floats, booleans and nils.
+    # This should be used judiciously because it subverts the GraphQL type system.
+    #
+    # Use it for fields or arguments as follows:
+    #
+    #     field :template_parameters, GraphQL::Types::JSON, null: false
+    #
+    #     argument :template_parameters, GraphQL::Types::JSON, null: false
+    #
+    class JSON < GraphQL::Schema::Scalar
+      description "Represents untyped JSON"
+
+      def self.coerce_input(value, _context)
+        value
+      end
+
+      def self.coerce_result(value, _context)
+        value
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/base_connection.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      # Use this to implement Relay connections, or take it as inspiration
+      # for Relay classes in your own app.
+      #
+      # You may wish to copy this code into your own base class,
+      # so you can extend your own `BaseObject` instead of `GraphQL::Schema::Object`.
+      #
+      # @example Implementation a connection and edge
+      #   # Given some object in your app ...
+      #   class Types::Post < BaseObject
+      #   end
+      #
+      #   # Make a couple of base classes:
+      #   class Types::BaseEdge < GraphQL::Types::Relay::BaseEdge; end
+      #   class Types::BaseConnection < GraphQL::Types::Relay::BaseConnection; end
+      #
+      #   # Then extend them for the object in your app
+      #   class Types::PostEdge < Types::BaseEdge
+      #     node_type(Types::Post)
+      #   end
+      #   class Types::PostConnection < Types::BaseConnection
+      #     edge_type(Types::PostEdge)
+      #     edges_nullable(true)
+      #     edge_nullable(true)
+      #     node_nullable(true)
+      #     has_nodes_field(true)
+      #   end
+      #
+      # @see Relay::BaseEdge for edge types
+      class BaseConnection < Schema::Object
+        include ConnectionBehaviors
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/base_edge.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      # A class-based definition for Relay edges.
+      #
+      # Use this as a parent class in your app, or use it as inspiration for your
+      # own base `Edge` class.
+      #
+      # For example, you may want to extend your own `BaseObject` instead of the
+      # built-in `GraphQL::Schema::Object`.
+      #
+      # @example Making a UserEdge type
+      #   # Make a base class for your app
+      #   class Types::BaseEdge < GraphQL::Types::Relay::BaseEdge
+      #   end
+      #
+      #   # Then extend your own base class
+      #   class Types::UserEdge < Types::BaseEdge
+      #     node_type(Types::User)
+      #   end
+      #
+      # @see {Relay::BaseConnection} for connection types
+      class BaseEdge < GraphQL::Schema::Object
+        include Types::Relay::EdgeBehaviors
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/connection_behaviors.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module ConnectionBehaviors
+        extend Forwardable
+        def_delegators :@object, :cursor_from_node, :parent
+
+        def self.included(child_class)
+          child_class.extend(ClassMethods)
+          child_class.extend(Relay::DefaultRelay)
+          child_class.default_relay(true)
+          child_class.has_nodes_field(true)
+          child_class.node_nullable(true)
+          child_class.edges_nullable(true)
+          child_class.edge_nullable(true)
+          add_page_info_field(child_class)
+        end
+
+        module ClassMethods
+          # @return [Class]
+          attr_reader :node_type
+
+          # @return [Class]
+          attr_reader :edge_class
+
+          # Configure this connection to return `edges` and `nodes` based on `edge_type_class`.
+          #
+          # This method will use the inputs to create:
+          # - `edges` field
+          # - `nodes` field
+          # - description
+          #
+          # It's called when you subclass this base connection, trying to use the
+          # class name to set defaults. You can call it again in the class definition
+          # to override the default (or provide a value, if the default lookup failed).
+          def edge_type(edge_type_class, edge_class: GraphQL::Relay::Edge, node_type: edge_type_class.node_type, nodes_field: self.has_nodes_field, node_nullable: self.node_nullable, edges_nullable: self.edges_nullable, edge_nullable: self.edge_nullable)
+            # Set this connection's graphql name
+            node_type_name = node_type.graphql_name
+
+            @node_type = node_type
+            @edge_type = edge_type_class
+            @edge_class = edge_class
+
+            field :edges, [edge_type_class, null: edge_nullable],
+              null: edges_nullable,
+              description: "A list of edges.",
+              legacy_edge_class: edge_class, # This is used by the old runtime only, for EdgesInstrumentation
+              connection: false
+
+            define_nodes_field(node_nullable) if nodes_field
+
+            description("The connection type for #{node_type_name}.")
+          end
+
+          # Filter this list according to the way its node type would scope them
+          def scope_items(items, context)
+            node_type.scope_items(items, context)
+          end
+
+          # Add the shortcut `nodes` field to this connection and its subclasses
+          def nodes_field(node_nullable: self.node_nullable)
+            define_nodes_field(node_nullable)
+          end
+
+          def authorized?(obj, ctx)
+            true # Let nodes be filtered out
+          end
+
+          def accessible?(ctx)
+            node_type.accessible?(ctx)
+          end
+
+          def visible?(ctx)
+            node_type.visible?(ctx)
+          end
+
+          # Set the default `node_nullable` for this class and its child classes. (Defaults to `true`.)
+          # Use `node_nullable(false)` in your base class to make non-null `node` and `nodes` fields.
+          def node_nullable(new_value = nil)
+            if new_value.nil?
+              defined?(@node_nullable) ? @node_nullable : superclass.node_nullable
+            else
+              @node_nullable = new_value
+            end
+          end
+
+          # Set the default `edges_nullable` for this class and its child classes. (Defaults to `true`.)
+          # Use `edges_nullable(false)` in your base class to make non-null `edges` fields.
+          def edges_nullable(new_value = nil)
+            if new_value.nil?
+              defined?(@edges_nullable) ? @edges_nullable : superclass.edges_nullable
+            else
+              @edges_nullable = new_value
+            end
+          end
+
+          # Set the default `edge_nullable` for this class and its child classes. (Defaults to `true`.)
+          # Use `edge_nullable(false)` in your base class to make non-null `edge` fields.
+          def edge_nullable(new_value = nil)
+            if new_value.nil?
+              defined?(@edge_nullable) ? @edge_nullable : superclass.edge_nullable
+            else
+              @edge_nullable = new_value
+            end
+          end
+
+          # Set the default `nodes_field` for this class and its child classes. (Defaults to `true`.)
+          # Use `nodes_field(false)` in your base class to prevent adding of a nodes field.
+          def has_nodes_field(new_value = nil)
+            if new_value.nil?
+              defined?(@nodes_field) ? @nodes_field : superclass.has_nodes_field
+            else
+              @nodes_field = new_value
+            end
+          end
+
+          private
+
+          def define_nodes_field(nullable)
+            field :nodes, [@node_type, null: nullable],
+              null: nullable,
+              description: "A list of nodes.",
+              connection: false
+          end
+        end
+
+        class << self
+          def add_page_info_field(obj_type)
+            obj_type.field :page_info, GraphQL::Types::Relay::PageInfo, null: false, description: "Information to aid in pagination."
+          end
+        end
+
+        # By default this calls through to the ConnectionWrapper's edge nodes method,
+        # but sometimes you need to override it to support the `nodes` field
+        def nodes
+          @object.edge_nodes
+        end
+
+        def edges
+          if @object.is_a?(GraphQL::Pagination::Connection)
+            @object.edges
+          elsif context.interpreter?
+            context.schema.after_lazy(object.edge_nodes) do |nodes|
+              nodes.map { |n| self.class.edge_class.new(n, object) }
+            end
+          else
+            # This is done by edges_instrumentation
+            @object.edge_nodes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/default_relay.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module DefaultRelay
+        def self.extended(child_class)
+          child_class.default_relay(true)
+        end
+
+        def default_relay(new_value)
+          @default_relay = new_value
+        end
+
+        def default_relay?
+          !!@default_relay
+        end
+
+        def to_graphql
+          type_defn = super
+          type_defn.default_relay = default_relay?
+          type_defn
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/edge_behaviors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module EdgeBehaviors
+        def self.included(child_class)
+          child_class.description("An edge in a connection.")
+          child_class.field(:cursor, String, null: false, description: "A cursor for use in pagination.")
+          child_class.extend(ClassMethods)
+          child_class.node_nullable(true)
+        end
+
+        module ClassMethods
+          # Get or set the Object type that this edge wraps.
+          #
+          # @param node_type [Class] A `Schema::Object` subclass
+          # @param null [Boolean]
+          def node_type(node_type = nil, null: self.node_nullable)
+            if node_type
+              @node_type = node_type
+              # Add a default `node` field
+              field :node, node_type, null: null, description: "The item at the end of the edge.", connection: false
+            end
+            @node_type
+          end
+
+          def authorized?(obj, ctx)
+            true
+          end
+
+          def accessible?(ctx)
+            node_type.accessible?(ctx)
+          end
+
+          def visible?(ctx)
+            node_type.visible?(ctx)
+          end
+
+          # Set the default `node_nullable` for this class and its child classes. (Defaults to `true`.)
+          # Use `node_nullable(false)` in your base class to make non-null `node` field.
+          def node_nullable(new_value = nil)
+            if new_value.nil?
+              defined?(@node_nullable) ? @node_nullable : superclass.node_nullable
+            else
+              @node_nullable = new_value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/has_node_field.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module HasNodeField
+        def self.included(child_class)
+          child_class.field(**field_options, &field_block)
+        end
+
+        class << self
+          def field_options
+            {
+              name: "node",
+              owner: nil,
+              type: GraphQL::Types::Relay::Node,
+              null: true,
+              description: "Fetches an object given its ID.",
+              relay_node_field: true,
+            }
+          end
+
+          def field_block
+            Proc.new {
+              argument :id, "ID!", required: true,
+                description: "ID of the object."
+
+              def resolve(obj, args, ctx)
+                ctx.schema.object_from_id(args[:id], ctx)
+              end
+
+              def resolve_field(obj, args, ctx)
+                resolve(obj, args, ctx)
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/has_nodes_field.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module HasNodesField
+        def self.included(child_class)
+          child_class.field(**field_options, &field_block)
+        end
+
+        class << self
+          def field_options
+            {
+              name: "nodes",
+              owner: nil,
+              type: [GraphQL::Types::Relay::Node, null: true],
+              null: false,
+              description: "Fetches a list of objects given a list of IDs.",
+              relay_nodes_field: true,
+            }
+          end
+
+          def field_block
+            Proc.new {
+              argument :ids, "[ID!]!", required: true,
+                description: "IDs of the objects."
+
+              def resolve(obj, args, ctx)
+                args[:ids].map { |id| ctx.schema.object_from_id(id, ctx) }
+              end
+
+              def resolve_field(obj, args, ctx)
+                resolve(obj, args, ctx)
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/node.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      # This can be used for Relay's `Node` interface,
+      # or you can take it as inspiration for your own implementation
+      # of the `Node` interface.
+      module Node
+        include GraphQL::Schema::Interface
+        include Types::Relay::NodeBehaviors
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/node_behaviors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Types
+    module Relay
+      module NodeBehaviors
+        def self.included(child_module)
+          child_module.extend(DefaultRelay)
+          child_module.description("An object with an ID.")
+          child_module.field(:id, ID, null: false, description: "ID of the object.")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/node_field.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      # This can be used for implementing `Query.node(id: ...)`,
+      # or use it for inspiration for your own field definition.
+      #
+      # @example Adding this field directly
+      #   add_field(GraphQL::Types::Relay::NodeField)
+      #
+      # @example Implementing a similar field in your own Query root
+      #
+      #   field :node, GraphQL::Types::Relay::Node, null: true,
+      #     description: "Fetches an object given its ID" do
+      #       argument :id, ID, required: true
+      #     end
+      #
+      #   def node(id:)
+      #     context.schema.object_from_id(id, context)
+      #   end
+      #
+      NodeField = GraphQL::Schema::Field.new(**HasNodeField.field_options, &HasNodeField.field_block)
+    end
+  end
+end

data/lib/graphql/types/relay/nodes_field.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      # This can be used for implementing `Query.nodes(ids: ...)`,
+      # or use it for inspiration for your own field definition.
+      #
+      # @example Adding this field directly
+      #   add_field(GraphQL::Types::Relay::NodesField)
+      #
+      # @example Implementing a similar field in your own Query root
+      #
+      #   field :nodes, [GraphQL::Types::Relay::Node, null: true], null: false,
+      #     description: Fetches a list of objects given a list of IDs." do
+      #       argument :ids, [ID], required: true
+      #     end
+      #
+      #   def nodes(ids:)
+      #     ids.map do |id|
+      #       context.schema.object_from_id(context, id)
+      #     end
+      #   end
+      #
+      NodesField = GraphQL::Schema::Field.new(**HasNodesField.field_options, &HasNodesField.field_block)
+    end
+  end
+end

data/lib/graphql/types/relay/page_info.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      # The return type of a connection's `pageInfo` field
+      class PageInfo < GraphQL::Schema::Object
+        include PageInfoBehaviors
+      end
+    end
+  end
+end

data/lib/graphql/types/relay/page_info_behaviors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module GraphQL
+  module Types
+    module Relay
+      module PageInfoBehaviors
+        def self.included(child_class)
+          child_class.extend GraphQL::Types::Relay::DefaultRelay
+
+          child_class.description "Information about pagination in a connection."
+          child_class.field :has_next_page, Boolean, null: false,
+            description: "When paginating forwards, are there more items?"
+
+          child_class.field :has_previous_page, Boolean, null: false,
+            description: "When paginating backwards, are there more items?"
+
+          child_class.field :start_cursor, String, null: true,
+            description: "When paginating backwards, the cursor to continue."
+
+          child_class.field :end_cursor, String, null: true,
+            description: "When paginating forwards, the cursor to continue."
+        end
+      end
+    end
+  end
+end

data/lib/graphql/types/relay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# behavior modules:
+require "graphql/types/relay/default_relay"
+require "graphql/types/relay/connection_behaviors"
+require "graphql/types/relay/edge_behaviors"
+require "graphql/types/relay/node_behaviors"
+require "graphql/types/relay/page_info_behaviors"
+require "graphql/types/relay/has_node_field"
+require "graphql/types/relay/has_nodes_field"
+
+# concrete classes based on the gem defaults:
+require "graphql/types/relay/page_info"
+require "graphql/types/relay/base_connection"
+require "graphql/types/relay/base_edge"
+require "graphql/types/relay/node"
+require "graphql/types/relay/node_field"
+require "graphql/types/relay/nodes_field"
+
+module GraphQL
+  module Types
+    # This module contains some types and fields that could support Relay conventions in GraphQL.
+    #
+    # You can use these classes out of the box if you want, but if you want to use your _own_
+    # GraphQL extensions along with the features in this code, you could also
+    # open up the source files and copy the relevant methods and configuration into
+    # your own classes.
+    #
+    # For example, the provided object types extend {Types::Relay::BaseObject},
+    # but you might want to:
+    #
+    # 1. Migrate the extensions from {Types::Relay::BaseObject} into _your app's_ base object
+    # 2. Copy {Relay::BaseConnection}, {Relay::BaseEdge}, etc into _your app_, and
+    #   change them to extend _your_ base object.
+    #
+    # Similarly, `BaseField`'s extensions could be migrated to your app
+    # and `Node` could be implemented to mix in your base interface module.
+    module Relay
+    end
+  end
+end