elasticgraph-schema_definition 0.18.0.0

data/lib/elastic_graph/schema_definition/schema_elements/field_path.rb

@@ -0,0 +1,112 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Represents a potentially nested path to a field.
+      #
+      # @private
+      class FieldPath < Data.define(:first_part, :last_part, :path_parts)
+        # The type of the field (based purely on the last part; the parent parts aren't interesting here).
+        def type
+          last_part.type
+        end
+
+        def path
+          path_parts.map(&:name).join(".")
+        end
+
+        # The full path to the field in the index.
+        def path_in_index
+          path_parts.map(&:name_in_index).join(".")
+        end
+
+        # The full name of the field path, including the parent type name, such as "Widget.nested.some_field".
+        def fully_qualified_path
+          "#{first_part.parent_type.name}.#{path}"
+        end
+
+        # The full name of the field path in the index, including the parent type name, such as "Widget.nested.some_field".
+        def fully_qualified_path_in_index
+          "#{first_part.parent_type.name}.#{path_in_index}"
+        end
+
+        # The full description of the field path, including the parent type name, and field type,
+        # such as "Widget.nested.some_field: ID".
+        def full_description
+          "#{fully_qualified_path}: #{type.name}"
+        end
+
+        # We hide `new` because `FieldPath` is only intended to be instantiated from a `Resolver` instance.
+        # Importantly, `Resolver` provides an invariant that we want: a `FieldPath` is never instantiated
+        # with an empty list of path parts. (This is important for the steep type checking, so it can count
+        # on `last_part` being non-nil).
+        private_class_method :new
+
+        # Responsible for resolving a particular field path (given as a string) into a `FieldPath` object.
+        #
+        # Important: this class optimizes performance by memoizing some things based on the current state
+        # of the ElasticGraph schema. It's intended to be used AFTER the schema is fully defined (e.g.
+        # as part of dumping schema artifacts). Using it before the schema has fully been defined requires
+        # that you discard the instance after using it, as it won't be aware of additions to the schema
+        # and may yield inaccurate results.
+        class Resolver
+          def initialize
+            @indexing_fields_by_public_name_by_type = ::Hash.new do |hash, type|
+              hash[type] = type
+                .indexing_fields_by_name_in_index
+                .values
+                .to_h { |f| [f.name, f] }
+            end
+          end
+
+          # Resolves the given `path_string` relative to the given `type`.
+          # Returns `nil` if no field at that path can be found.
+          #
+          # Requires a block which will be called to determine if a parent field is valid to resolve through.
+          # For example, the caller may want to disallow all parent list fields, or disallow `nested` parent
+          # list fields while allowing `object` parent list fields.
+          def resolve_public_path(type, path_string)
+            field = nil # : Field?
+
+            path_parts = path_string.split(".").map do |field_name|
+              return nil unless type
+              return nil if field && !yield(field)
+              return nil unless (field = @indexing_fields_by_public_name_by_type.dig(type, field_name))
+              type = field.type.unwrap_list.as_object_type
+              field
+            end
+
+            return nil if path_parts.empty?
+
+            FieldPath.send(:new, path_parts.first, path_parts.last, path_parts)
+          end
+
+          # Determines the nested paths in the given `path_string`
+          # Returns `nil` if no field at that path can be found, and
+          # returns `[]` if no nested paths are found.
+          #
+          # Nested paths are represented as the full path to the nested fields
+          # For example: a `path_string` of "foo.bar.baz" might have
+          # nested paths ["foo", "foo.bar.baz"]
+          def determine_nested_paths(type, path_string)
+            field_path = resolve_public_path(type, path_string) { true }
+            return nil unless field_path
+
+            parts_so_far = [] # : ::Array[::String]
+            field_path.path_parts.filter_map do |field|
+              parts_so_far << field.name
+              parts_so_far.join(".") if field.nested?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/field_source.rb

@@ -0,0 +1,16 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # @private
+      FieldSource = ::Data.define(:relationship_name, :field_path)
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/graphql_sdl_enumerator.rb

@@ -0,0 +1,113 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Responsible for enumerating the SDL strings for all GraphQL types, both explicitly defined and derived.
+      #
+      # @private
+      class GraphQLSDLEnumerator
+        include ::Enumerable
+        # @dynamic schema_def_state
+        attr_reader :schema_def_state
+
+        def initialize(schema_def_state, all_types_except_root_query_type)
+          @schema_def_state = schema_def_state
+          @all_types_except_root_query_type = all_types_except_root_query_type
+        end
+
+        # Yields the SDL for each GraphQL type, including both explicitly defined
+        # GraphQL types and derived GraphqL types.
+        def each(&block)
+          all_types = enumerate_all_types.sort_by(&:name)
+          all_type_names = all_types.map(&:name).to_set
+
+          all_types.each do |type|
+            next if STOCK_GRAPHQL_SCALARS.include?(type.name)
+            yield type.to_sdl { |arg| all_type_names.include?(arg.value_type.fully_unwrapped.name) }
+          end
+        end
+
+        private
+
+        def enumerate_all_types
+          [root_query_type].compact + @all_types_except_root_query_type
+        end
+
+        def aggregation_efficiency_hints_for(derived_indexed_types)
+          return nil if derived_indexed_types.empty?
+
+          hints = derived_indexed_types.map do |type|
+            derived_indexing_type = @schema_def_state.types_by_name.fetch(type.destination_type_ref.name)
+            alternate_field_name = (_ = derived_indexing_type).plural_root_query_field_name
+            grouping_field = type.id_source
+
+            "  - The root `#{alternate_field_name}` field groups by `#{grouping_field}`"
+          end
+
+          <<~EOS
+            Note: aggregation queries are relatively expensive, and some fields have been pre-aggregated to allow
+            more efficient queries for some common aggregation cases:
+
+            #{hints.join("\n")}
+          EOS
+        end
+
+        def root_query_type
+          # Some of our tests need to define their own root `Query` type, so here we avoid
+          # generating `Query` if an sdl part exists that already defines it.
+          return nil if @schema_def_state.sdl_parts.flat_map { |sdl| sdl.lines }.any? { |line| line.start_with?("type Query") }
+
+          new_built_in_object_type "Query" do |t|
+            t.documentation "The query entry point for the entire schema."
+
+            @schema_def_state.types_by_name.values.select(&:indexed?).sort_by(&:name).each do |type|
+              # @type var indexed_type: Mixins::HasIndices & _Type
+              indexed_type = _ = type
+
+              t.relates_to_many(
+                indexed_type.plural_root_query_field_name,
+                indexed_type.name,
+                via: "ignore",
+                dir: :in,
+                singular: indexed_type.singular_root_query_field_name
+              ) do |f|
+                f.documentation "Fetches `#{indexed_type.name}`s based on the provided arguments."
+                indexed_type.root_query_fields_customizations&.call(f)
+              end
+
+              # Add additional efficiency hints to the aggregation field documentation if we have any such hints.
+              # This needs to be outside the `relates_to_many` block because `relates_to_many` adds its own "suffix" to
+              # the field documentation, and here we add another one.
+              if (agg_efficiency_hint = aggregation_efficiency_hints_for(indexed_type.derived_indexed_types))
+                agg_name = @schema_def_state.schema_elements.normalize_case("#{indexed_type.singular_root_query_field_name}_aggregations")
+                agg_field = t.graphql_fields_by_name.fetch(agg_name)
+                agg_field.documentation "#{agg_field.doc_comment}\n\n#{agg_efficiency_hint}"
+              end
+            end
+          end
+        end
+
+        def new_built_in_object_type(name, &block)
+          new_object_type name do |type|
+            @schema_def_state.built_in_types_customization_blocks.each do |customization_block|
+              customization_block.call(type)
+            end
+
+            block.call(type)
+          end
+        end
+
+        def new_object_type(name, &block)
+          @schema_def_state.factory.new_object_type(name, &block)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/input_field.rb

@@ -0,0 +1,31 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "delegate"
+require "elastic_graph/schema_definition/mixins/supports_default_value"
+require "elastic_graph/schema_definition/schema_elements/field"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # A decorator that wraps a `Field` in order to provide additional functionality that
+      # we need to support on fields on input types (but not on fields on return types).
+      #
+      # For example, fields on input types support default values, but return type fields do not.
+      #
+      # @private
+      class InputField < DelegateClass(Field)
+        prepend Mixins::SupportsDefaultValue
+
+        def to_sdl(type_structure_only: false, default_value_sdl: self.default_value_sdl, &arg_selector)
+          super(type_structure_only: type_structure_only, default_value_sdl: default_value_sdl, &arg_selector)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/input_type.rb

@@ -0,0 +1,60 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "delegate"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/schema_elements/type_with_subfields"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Represents a GraphQL `input` (used primarily for filtering).
+      #
+      # @private
+      class InputType < DelegateClass(TypeWithSubfields)
+        include Mixins::HasReadableToSAndInspect.new { |t| t.name }
+
+        def initialize(schema_def_state, name)
+          schema_def_state.factory.new_type_with_subfields(
+            :input, name,
+            wrapping_type: self,
+            field_factory: schema_def_state.factory.method(:new_input_field)
+          ) do |type|
+            # Here we clear `reserved_field_names` because those field names are reserved precisely for our usage
+            # here on input filters. If we don't set this to an empty set we'll get exceptions in `new_filter` above
+            # when we generate our standard filter operators.
+            #
+            # Note: we opt-out of the reserved field names here rather then opting in on the other `TypeWithSubfields`
+            # subtypes because this is the only case where we don't want the reserved field name check applied (but we
+            # have multiple subtypes where we do want it applied).
+            type.reserved_field_names = Set.new
+
+            super(type)
+            graphql_only true
+            yield self
+          end
+        end
+
+        def runtime_metadata(extra_update_targets)
+          SchemaArtifacts::RuntimeMetadata::ObjectType.new(
+            update_targets: extra_update_targets,
+            index_definition_names: [],
+            graphql_fields_by_name: graphql_fields_by_name.transform_values(&:runtime_metadata_graphql_field),
+            elasticgraph_category: nil,
+            source_type: nil,
+            graphql_only_return_type: false
+          )
+        end
+
+        def derived_graphql_types
+          []
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/interface_type.rb

@@ -0,0 +1,72 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "delegate"
+require "elastic_graph/schema_definition/mixins/has_indices"
+require "elastic_graph/schema_definition/mixins/has_subtypes"
+require "elastic_graph/schema_definition/mixins/implements_interfaces"
+require "elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation"
+require "elastic_graph/schema_definition/schema_elements/type_with_subfields"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # {include:API#interface_type}
+      #
+      # @example Define an interface
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.interface_type "Athlete" do |t|
+      #       # in the block, `t` is an InterfaceType
+      #     end
+      #   end
+      class InterfaceType < DelegateClass(TypeWithSubfields)
+        # As of the October 2021 GraphQL spec, interfaces can now implement other interfaces:
+        # http://spec.graphql.org/October2021/#sec-Interfaces.Interfaces-Implementing-Interfaces
+        # Originated from: graphql/graphql-spec#373
+        include Mixins::ImplementsInterfaces
+        include Mixins::SupportsFilteringAndAggregation
+        include Mixins::HasIndices
+        include Mixins::HasSubtypes
+        include Mixins::HasReadableToSAndInspect.new { |t| t.name }
+
+        # @private
+        def initialize(schema_def_state, name)
+          field_factory = schema_def_state.factory.method(:new_field)
+          schema_def_state.factory.new_type_with_subfields(:interface, name, wrapping_type: self, field_factory: field_factory) do |type|
+            __skip__ = super(type) do
+              yield self
+            end
+          end
+        end
+
+        # This contains more than just the proper interface fields; it also contains the fields from the
+        # subtypes, which winds up being used to generate an input filter and aggregation type.
+        #
+        # For just the interface fields, use `interface_fields_by_name`.
+        #
+        # @private
+        def graphql_fields_by_name
+          merged_fields_from_subtypes_by_name = super # delegates to the `HasSubtypes` definition.
+          # The interface field definitions should take precedence over the merged fields from the subtypes.
+          merged_fields_from_subtypes_by_name.merge(interface_fields_by_name)
+        end
+
+        # @private
+        def interface_fields_by_name
+          __getobj__.graphql_fields_by_name
+        end
+
+        private
+
+        def resolve_subtypes
+          schema_def_state.implementations_by_interface_ref[type_ref]
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/list_counts_state.rb

@@ -0,0 +1,40 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/constants"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # @private
+      class ListCountsState < ::Data.define(
+        # the path from the root to the current list counts field
+        :path_to_list_counts,
+        # the path within the list counts field
+        :path_from_list_counts
+      )
+        # @dynamic path_to_list_counts, path_from_list_counts, with
+
+        def self.new_list_counts_field(at:)
+          new(path_to_list_counts: at, path_from_list_counts: "")
+        end
+
+        INITIAL = new_list_counts_field(at: LIST_COUNTS_FIELD)
+
+        def [](subpath)
+          with(path_from_list_counts: "#{path_from_list_counts}#{subpath}.")
+        end
+
+        def path_to_count_subfield(subpath)
+          count_subfield = (path_from_list_counts + subpath).gsub(".", LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR)
+          "#{path_to_list_counts}.#{count_subfield}"
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/object_type.rb

@@ -0,0 +1,53 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "delegate"
+require "elastic_graph/error"
+require "elastic_graph/schema_definition/mixins/has_indices"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/mixins/implements_interfaces"
+require "elastic_graph/schema_definition/schema_elements/type_with_subfields"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # {include:API#object_type}
+      #
+      # @example Define an object type
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.object_type "Money" do |t|
+      #       # in the block, `t` is an ObjectType
+      #     end
+      #   end
+      class ObjectType < DelegateClass(TypeWithSubfields)
+        # DelegateClass(TypeWithSubfields) provides the following methods:
+        # @dynamic name, type_ref, to_sdl, derived_graphql_types, to_indexing_field_type, current_sources, index_field_runtime_metadata_tuples, graphql_only?, relay_pagination_type
+        include Mixins::SupportsFilteringAndAggregation
+
+        # `include HasIndices` provides the following methods:
+        # @dynamic runtime_metadata, derived_indexed_types, indices, indexed?, abstract?
+        include Mixins::HasIndices
+
+        # `include ImplementsInterfaces` provides the following methods:
+        # @dynamic verify_graphql_correctness!
+        include Mixins::ImplementsInterfaces
+        include Mixins::HasReadableToSAndInspect.new { |t| t.name }
+
+        # @private
+        def initialize(schema_def_state, name)
+          field_factory = schema_def_state.factory.method(:new_field)
+          schema_def_state.factory.new_type_with_subfields(:type, name, wrapping_type: self, field_factory: field_factory) do |type|
+            __skip__ = super(type) do
+              yield self
+            end
+          end
+        end
+      end
+    end
+  end
+end