graphlyte 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97c3b9e1d17580b4d94cf3ffaa9f7291d8ff10c9441a9c2270a378daad39f977
-  data.tar.gz: f3586e4ea3a92e0ac462b92a17115a81a8c64e6643c296861072a23543ae2b92
+  metadata.gz: 50a30d874f185f08a1d8e9d7911056135927ec25a2f9e272b14dd50124aeea79
+  data.tar.gz: 97b938f8391811a7da0a29d855daea3812c7e97e953dd64fc5fa90fd98a10b8d
 SHA512:
-  metadata.gz: a4dd27faa45576150659090362b94f30297faad8a1a1d5758480e63359bd74e92a30960e70fad8aa446c60e1540dd384458590d5f6cc00eb49c9aa09b44d6659
-  data.tar.gz: 1887884979b8f92cc8c1b145c782363b7be9e907fc3541cee5e103a4e901d07261f1a6f69aa0aafcce337efda5e5de4a3950fa4803f17a074f4cc6bbd0555ace
+  metadata.gz: ebe479ecb5e89d21e0e193207cd72fa6891df00621882f0de1d9fa344655d8058ee566857fc12e3d7ea25d34c83f1b6fb6545ea30739e4473695ef875ef6661a
+  data.tar.gz: 7d1bc0754b536f724f4e9ef4f91b3d5411335e568227a4e77e171a45c5a5d719b4edf3c4f289504321f5662d8d25571d7041970fc0bf873e54a489f9698e1d0e

data/lib/graphlyte/data.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Graphlyte
+  # Very simplistic data-class. Inheritance is not modelled.
+  class Data
+    def self.attr_accessor(*names)
+      super
+      attributes.merge(names)
+    end
+
+    def self.attr_reader(*names)
+      super
+      attributes.merge(names)
+    end
+
+    def self.attributes
+      @attributes ||= [].to_set
+    end
+
+    # Permissive constructor: ignores unknown attributes
+    def initialize(**kwargs)
+      self.class.attributes.each do |arg|
+        send(:"#{arg}=", kwargs[arg]) if kwargs.key?(arg)
+      end
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) && state == other.send(:state)
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    def hash
+      state.hash
+    end
+
+    def dup
+      self.class.new(**self.class.attributes.to_h { [_1, dup_attribute(_1)] })
+    end
+
+    def inspect
+      "#<#{self.class} #{self.class.attributes.map { "@#{_1}=#{send(_1).inspect}" }.join(' ')}>"
+    end
+
+    private
+
+    def dup_attribute(attr)
+      value = send(attr)
+
+      case value
+      when Array
+        value.map(&:dup)
+      when Hash
+        value.transform_values(&:dup)
+      else
+        value.dup
+      end
+    end
+
+    def state
+      self.class.attributes.map { send _1 }
+    end
+  end
+end

data/lib/graphlyte/document.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative './syntax'
+require_relative './data'
+require_relative './serializer'
+require_relative './refinements/string_refinement'
+require_relative './editors/with_variables'
+
+module Graphlyte
+  # The representation of a GraphQL document.
+  #
+  # Documents can have multiple definitions, which can
+  # be queries, mutations, subscriptions (operations) or fragments.
+  #
+  # During execution, only one operation can be executed.
+  class Document < Graphlyte::Data
+    using Graphlyte::Refinements::StringRefinement
+    extend Forwardable
+
+    attr_accessor :definitions, :variables, :schema
+
+    def_delegators :@definitions, :length, :empty?
+
+    def initialize(**kwargs)
+      super
+      @definitions ||= []
+      @variables ||= {}
+      @var_name_counter = @variables.size + 1
+    end
+
+    def +(other)
+      return dup unless other
+
+      other = other.dup
+      doc = dup
+
+      defs = doc.definitions + other.definitions
+      vars = doc.variables.merge(other.variables) # TODO: detect conflicts?
+
+      self.class.new(definitions: defs, vars: vars)
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) && other.fragments == fragments && other.operations == operations
+    end
+
+    alias == eql?
+
+    def define(dfn)
+      @definitions << dfn
+    end
+
+    def add_fragments(frags)
+      current = fragments
+
+      frags.each do |frag|
+        @definitions << frag unless current[frag.name]
+      end
+    end
+
+    def declare(var)
+      if var.name.nil?
+        var.name = "var#{@var_name_counter}"
+        @var_name_counter += 1
+      end
+
+      parser = Graphlyte::Parser.new(tokens: Graphlyte::Lexer.lex(var.type))
+      parsed_type = parser.type_name! if var.type
+      current_def = @variables[var.name]
+
+      if current_def && current_def.type != parsed_type
+        msg = "Cannot re-declare #{var.name} at different types. #{current_def.type} != #{var.type}"
+        raise ArgumentError, msg
+      end
+
+      @variables[var.name] ||= Graphlyte::Syntax::VariableDefinition.new(
+        variable: var.name,
+        type: parsed_type
+      )
+
+      Syntax::VariableReference.new(var.name, parsed_type)
+    end
+
+    def fragments
+      definitions.select { _1.is_a?(Graphlyte::Syntax::Fragment) }.to_h { [_1.name, _1] }
+    end
+
+    def operations
+      @definitions.select { _1.is_a?(Graphlyte::Syntax::Operation) }.to_h { [_1.name, _1] }
+    end
+
+    def executable?
+      @definitions.all?(&:executable?)
+    end
+
+    def to_s
+      buff = []
+      write(buff)
+
+      buff.join
+    end
+
+    # More efficient for writing to files or streams - avoids building up the full string.
+    def write(io)
+      Graphlyte::Serializer.new(io).dump_definitions(definitions)
+    end
+
+    # Return this document as a JSON request body, suitable for posting to a server.
+    def request_body(operation = nil, **variables)
+      if operation.nil? && operations.size != 1
+        raise ArgumentError, 'Operation name is required when the document contains multiple operations'
+      end
+
+      variables.transform_keys! { _1.to_s.camelize }
+
+      doc = Editors::WithVariables.new(schema, operation, variables).edit(dup)
+
+      {
+        query: doc.to_s,
+        variables: variables,
+        operation: operation
+      }.compact.to_json
+    end
+
+    def variable_references
+      Editors::CollectVariableReferences.new.edit(self)[Syntax::Operation]
+    end
+  end
+end

data/lib/graphlyte/dsl.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative './syntax'
+require_relative './selection_builder'
+require_relative './refinements/string_refinement'
+require_relative './editors/infer_signature'
+
+module Graphlyte
+  # The DSL methods for query construction are defined here.
+  #
+  # The main methods are:
+  #
+  # - `var`: creates a fresh unique variable
+  # - `enum`: allows referring to enum values
+  # - `fragment`: creates a fragment that can be re-used in operations
+  # - `query`: creates a `Query` operation
+  # - `mutation`: creates a `Mutation` operation
+  class DSL
+    using Graphlyte::Refinements::StringRefinement
+
+    attr_reader :schema
+
+    def initialize(schema = nil)
+      @schema = schema
+    end
+
+    def var(type = nil, name = nil)
+      SelectionBuilder::Variable.new(type: type, name: name&.to_s&.camelize)
+    end
+
+    def enum(value)
+      Syntax::Value.new(value.to_sym, :ENUM)
+    end
+
+    def query(name = nil, doc = Document.new, &block)
+      op = Syntax::Operation.new(type: :query)
+      doc.define(op)
+
+      op.name = name
+      op.selection = SelectionBuilder.build(doc, &block)
+
+      Editors::InferSignature.new(@schema).edit(doc)
+
+      doc
+    end
+
+    def mutation(name = nil, doc = Document.new, &block)
+      op = Syntax::Operation.new(type: :mutation)
+      doc.define(op)
+
+      op.name = name
+      op.selection = SelectionBuilder.build(doc, &block)
+
+      # TODO: infer operation signatures (requires schema!)
+      doc
+    end
+
+    def fragment(fragment_name = nil, on:, doc: Document.new, &block)
+      frag = Graphlyte::Syntax::Fragment.new
+
+      frag.type_name = on
+      frag.selection = SelectionBuilder.build(doc, &block)
+
+      if fragment_name
+        frag.name = fragment_name
+      else
+        base = "#{on}Fields"
+        n = 1
+        frag.name = base
+
+        while doc.fragments[frag.name]
+          frag.name = "#{base}_#{n}"
+          n += 1
+        end
+      end
+
+      doc.fragments.each_value do |required|
+        frag.refers_to required
+      end
+
+      doc.define(frag)
+
+      frag
+    end
+  end
+end

data/lib/graphlyte/editor.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative './syntax'
+
+module Graphlyte
+  # Walk the document tree and edit or collect data.
+  #
+  # This is the general purpose recursive transformer for
+  # syntax trees, used to write various validation and
+  # transformation passes. See `lib/graphlyte/editors`
+  #
+  # Usage
+  #
+  # A fragment inliner:
+  #
+  #   inliner = Editor.new.on_fragment_spread do |spread, action|
+  #     action.replace action.document.fragments[spread.name].inline
+  #   end
+  #
+  #   inliner.edit(document)
+  #
+  # A variable renamer:
+  #
+  #   renamer = Editor.new.on_variable do |var|
+  #     var.variable = 'x' if var.variable == 'y'
+  #   end
+  #
+  #   renamer.edit(document)
+  #
+  # A string collector:
+  #
+  #   strings = []
+  #   collector = Editor.new.on_value do |value|
+  #     strings << value.value if value.type == :STRING
+  #   end
+  #
+  #   collector.edit(document)
+  #
+  class Editor
+    Deleted = Class.new(StandardError)
+
+    attr_accessor :direction
+
+    def initialize
+      @hooks = {}
+      @direction = :bottom_up
+    end
+
+    # The value passed to the handler blocks, in addition to the syntax node.
+    # Users can call methods on this object to edit the document in-place, as
+    # well as read information about the context of this node.
+    class Action
+      attr_reader :new_nodes, :path, :definition, :parent, :document
+
+      def initialize(old_node, path, parent, document)
+        @new_nodes = [old_node]
+        @definition = path.first
+        @path = path.dup.freeze
+        @parent = parent
+        @document = document
+      end
+
+      def replace(replacement)
+        @new_nodes = [replacement]
+      end
+
+      def insert_before(node)
+        @new_nodes = [node] + @new_nodes
+      end
+
+      def insert_after(node)
+        @new_nodes.push(node)
+      end
+
+      def delete
+        @new_nodes = []
+      end
+
+      def expand(new_nodes)
+        @new_nodes = new_nodes
+      end
+
+      def closest(node_type)
+        @path.reverse.find { _1.is_a?(node_type) }
+      end
+    end
+
+    # The class responsible for orchestration of the hooks. This class
+    # defines the recursion through the document.
+    Context = Struct.new(:document, :direction, :hooks, :path) do
+      def edit(object, &block)
+        parent = path.last
+        path.push(object)
+
+        processor = hooks[object.class]
+        action = Action.new(object, path, parent, document)
+
+        case direction
+        when :bottom_up
+          edit_bottom_up(object, processor, action, &block)
+        when :top_down
+          edit_top_down(object, processor, action, &block)
+        else
+          raise ArgumentError, "Unknown direction: #{direction}"
+        end
+
+        action.new_nodes
+      ensure
+        path.pop
+      end
+
+      def edit_top_down(object, processor, action)
+        processor&.call(object, action)
+        action.new_nodes = action.new_nodes.filter_map do |node|
+          yield node if block_given?
+          node
+        rescue Deleted
+          nil
+        end
+      end
+
+      def edit_bottom_up(object, processor, action)
+        yield object if block_given?
+        processor&.call(object, action)
+      rescue Deleted
+        action.new_nodes = []
+      end
+
+      def edit_variables(object)
+        return unless object.respond_to?(:variables)
+
+        object.variables = object.variables&.flat_map do |var|
+          edit(var) do |v|
+            edit_directives(v)
+            v.default_value = edit_value(v.default_value).first
+          end
+        end
+      end
+
+      def edit_directives(object)
+        return unless object.respond_to?(:directives)
+
+        object.directives = object.directives&.flat_map do |dir|
+          edit(dir) { |d| edit_arguments(d) }
+        end
+      end
+
+      def edit_arguments(object)
+        return unless object.respond_to?(:arguments)
+
+        object.arguments = object.arguments&.flat_map do |arg|
+          edit(arg) do |_a|
+            arg.value = edit_value(arg.value).first
+            raise Deleted if arg.value.nil?
+          end
+        end
+      end
+
+      def edit_value(object)
+        case object
+        when Array
+          [object.flat_map { edit_value(_1) }]
+        when Hash
+          [
+            object.to_a.flat_map do |(k, old_value)|
+              edit_value(old_value).take(1).map do |new_value|
+                [k, new_value]
+              end
+            end.to_h
+          ]
+        else
+          edit(object)
+        end
+      end
+
+      def edit_selection(object)
+        return unless object.respond_to?(:selection)
+
+        object.selection = object.selection&.flat_map do |selected|
+          edit(selected) do |s|
+            edit_arguments(s)
+            edit_directives(s)
+            edit_selection(s)
+          end
+        end
+      end
+
+      def edit_definition(object)
+        edit(object) do |o|
+          edit_variables(o)
+          edit_directives(o)
+          edit_selection(o)
+        end
+      end
+    end
+
+    def self.top_down
+      e = new
+      e.direction = :top_down
+
+      e
+    end
+
+    def self.bottom_up
+      new
+    end
+
+    def on_value(&block)
+      @hooks[Syntax::Value] = block
+      self
+    end
+
+    def on_argument(&block)
+      @hooks[Syntax::Argument] = block
+      self
+    end
+
+    def on_directive(&block)
+      @hooks[Syntax::Directive] = block
+      self
+    end
+
+    def on_operation(&block)
+      @hooks[Syntax::Operation] = block
+      self
+    end
+
+    def on_variable(&block)
+      on_variable_definition(&block)
+      on_variable_reference(&block)
+      self
+    end
+
+    def on_variable_definition(&block)
+      @hooks[Syntax::VariableDefinition] = block
+      self
+    end
+
+    def on_variable_reference(&block)
+      @hooks[Syntax::VariableReference] = block
+      self
+    end
+
+    # Selected nodes:
+
+    def on_field(&block)
+      @hooks[Syntax::Field] = block
+      self
+    end
+
+    def on_fragment(&block)
+      on_inline_fragment(&block)
+      on_fragment_definition(&block)
+      self
+    end
+
+    def on_fragment_spread(&block)
+      @hooks[Syntax::FragmentSpread] = block
+      self
+    end
+
+    def on_inline_fragment(&block)
+      @hooks[Syntax::InlineFragment] = block
+      self
+    end
+
+    def on_fragment_definition(&block)
+      @hooks[Syntax::Fragment] = block
+      self
+    end
+
+    # To edit specific nodes in a document (or isolated from a document)
+    # you will need a Context.
+    def context(document = nil)
+      Context.new(document, direction, @hooks.dup.freeze, [])
+    end
+
+    def edit(document)
+      c = context(document)
+
+      document.definitions = document.definitions.flat_map do |object|
+        c.edit_definition(object)
+      end
+
+      document
+    end
+  end
+end

data/lib/graphlyte/editors/annotate_types.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Graphlyte
+  module Editors
+    # Use a schema definition to annotate the type of each field and variable reference.
+    class AnnotateTypes
+      TypeCheckError = Class.new(StandardError)
+      TypeNotFound = Class.new(TypeCheckError)
+      FieldNotFound = Class.new(TypeCheckError)
+      CannotDetermineTypeName = Class.new(TypeCheckError)
+
+      def initialize(schema, recheck: false)
+        @schema = schema
+        @recheck = recheck
+      end
+
+      def edit(doc)
+        return if !recheck && doc.schema # Previously annotated
+
+        doc.schema = @schema
+        editor.edit(doc)
+      end
+
+      def editor
+        @editor ||=
+          Editor
+          .top_down
+          .on_field { |field, action| infer_field(field, action.parent, action.document) }
+          .on_variable_reference do |ref, action|
+            infer_ref(ref, action.closest(Syntax::Argument), action.closest(Syntax::Field))
+          end
+      end
+
+      # For now we are ignoring variables nested in input objects.
+      # TODO: encode input objects differently?
+      def infer_ref(ref, argument, field)
+        type = @schema.types[field.type.unpack]
+        arg = type.arguments[argument.name]
+        raise ArgumentNotFound, "#{type.name}.#{field.name}(#{argument.name})" unless arg
+
+        ref.inferred_type = Syntax::Type.from_type_ref(arg.type)
+      end
+
+      def infer_field(field, parent, document)
+        name = object_name(parent, document)
+        object_type = type(name)
+
+        raise FieldNotFound, "#{object_name}.#{field.name}" unless object_type.fields.key?(field.name)
+
+        field.type = Syntax::Type.from_type_ref(object_type.fields[field.name].type)
+      end
+
+      def type(name)
+        object_type = @schema.types[name]
+        raise TypeNotFound, object_name unless object_type
+
+        object_type
+      end
+
+      def object_name(parent, document)
+        case parent
+        when Syntax::FragmentSpread
+          fragment = document.fragments[parent.name]
+          raise CannotDetermineTypeName, parent unless fragment
+
+          fragment.type_name
+        when Syntax::InlineFragment, Syntax::Fragment
+          parent.type_name
+        when Syntax::Field
+          parent.type.unpack
+        end
+      end
+    end
+  end
+end

data/lib/graphlyte/editors/canonicalize.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../editor'
+require_relative '../syntax'
+require_relative './inline_fragments'
+
+module Graphlyte
+  module Editors
+    # Reduce the query to a canonical form.
+    class Canonicalize
+      def edit(doc)
+        doc = doc.dup
+        InlineFragments.new.edit(doc)
+        doc.definitions = doc.definitions.sort_by(&:name)
+        # TODO: we should also perform the selection Merge operation here.
+        order_argments.edit(doc)
+      end
+
+      def order_argments
+        Editor.new
+              .on_field { |field| field.arguments = field.arguments&.sort_by(&:name) }
+              .on_directive { |dir| dir.arguments = dir.arguments&.sort_by(&:name) }
+      end
+    end
+  end
+end