elasticgraph-schema_definition 0.18.0.0

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

@@ -0,0 +1,21 @@
+# 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
+      DeprecatedElement = ::Data.define(:schema_def_state, :name, :defined_at, :defined_via) do
+        # @implements DeprecatedElement
+        def description
+          "`#{defined_via}` at #{defined_at.path}:#{defined_at.lineno}"
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/directive.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/schema_definition/mixins/verifies_graphql_name"
+require "elastic_graph/support/graphql_formatter"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Represents a [GraphQL directive](https://spec.graphql.org/October2021/#sec-Language.Directives).
+      #
+      # @!attribute [r] name
+      #   @return [String] name of the directive
+      # @!attribute [r] arguments
+      #   @return [Hash<Symbol, Object>] directive arguments
+      # @!parse class Directive < ::Data; end
+      class Directive < ::Data.define(:name, :arguments)
+        prepend Mixins::VerifiesGraphQLName
+
+        # @return [String] GraphQL SDL form of the directive
+        def to_sdl
+          %(@#{name}#{Support::GraphQLFormatter.format_args(**arguments)})
+        end
+
+        # Duplicates this directive on another GraphQL schema element.
+        #
+        # @param element [Argument, EnumType, EnumValue, Field, ScalarType, TypeWithSubfields, UnionType] schema element
+        # @return [void]
+        def duplicate_on(element)
+          element.directive name, arguments
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,189 @@
+# 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/schema_artifacts/runtime_metadata/enum"
+require "elastic_graph/schema_definition/indexing/field_type/enum"
+require "elastic_graph/schema_definition/mixins/can_be_graphql_only"
+require "elastic_graph/schema_definition/mixins/has_derived_graphql_type_customizations"
+require "elastic_graph/schema_definition/mixins/has_directives"
+require "elastic_graph/schema_definition/mixins/has_documentation"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/mixins/verifies_graphql_name"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # {include:API#enum_type}
+      #
+      # @example Define an enum type
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.enum_type "Currency" do |t|
+      #       # in the block, `t` is an EnumType
+      #       t.value "USD"
+      #     end
+      #   end
+      #
+      # @!attribute [r] schema_def_state
+      #   @return [State] state of the schema
+      # @!attribute [rw] type_ref
+      #   @private
+      # @!attribute [rw] for_output
+      #   @return [Boolean] `true` if this enum is used for both input and output; `false` if it is for input only
+      # @!attribute [r] values_by_name
+      #   @return [Hash<String, EnumValue>] map of enum values, keyed by name
+      class EnumType < Struct.new(:schema_def_state, :type_ref, :for_output, :values_by_name)
+        # @dynamic type_ref, graphql_only?
+        prepend Mixins::VerifiesGraphQLName
+        include Mixins::CanBeGraphQLOnly
+        include Mixins::HasDocumentation
+        include Mixins::HasDirectives
+        include Mixins::HasDerivedGraphQLTypeCustomizations
+        include Mixins::HasReadableToSAndInspect.new { |e| e.name }
+
+        # @private
+        def initialize(schema_def_state, name)
+          # @type var values_by_name: ::Hash[::String, EnumValue]
+          values_by_name = {}
+          super(schema_def_state, schema_def_state.type_ref(name).to_final_form, true, values_by_name)
+
+          # :nocov: -- currently all invocations have a block
+          yield self if block_given?
+          # :nocov:
+        end
+
+        # @return [String] name of the enum type
+        def name
+          type_ref.name
+        end
+
+        # @return [TypeReference] reference to `AggregatedValues` type to use for this enum.
+        def aggregated_values_type
+          schema_def_state.type_ref("NonNumeric").as_aggregated_values
+        end
+
+        # Defines an enum value for the current enum type.
+        #
+        # @param value_name [String] name of the enum value
+        # @yield [EnumValue] enum value so it can be further customized
+        # @return [void]
+        #
+        # @example Define an enum type with multiple enum values
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.enum_type "Currency" do |t|
+        #       t.value "USD" do |v|
+        #         v.documentation "US Dollars."
+        #       end
+        #
+        #       t.value "JPY" do |v|
+        #         v.documentation "Japanese Yen."
+        #       end
+        #     end
+        #   end
+        def value(value_name, &block)
+          alternate_original_name = value_name
+          value_name = schema_def_state.enum_value_namer.name_for(name, value_name.to_s)
+
+          if values_by_name.key?(value_name)
+            raise SchemaError, "Duplicate value on Enum::Type #{name}: #{value_name}"
+          end
+
+          if value_name.length > DEFAULT_MAX_KEYWORD_LENGTH
+            raise SchemaError, "Enum value `#{name}.#{value_name}` is too long: it is #{value_name.length} characters but cannot exceed #{DEFAULT_MAX_KEYWORD_LENGTH} characters."
+          end
+
+          values_by_name[value_name] = schema_def_state.factory.new_enum_value(value_name, alternate_original_name, &block)
+        end
+
+        # Defines multiple enum values. In contrast to {#value}, the enum values cannot be customized
+        # further via a block.
+        #
+        # @param value_names [Array<String>] names of the enum values
+        # @return [void]
+        #
+        # @example Define an enum type with multiple enum values
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.enum_type "Currency" do |t|
+        #       t.values "USD", "JPY", "CAD", "GBP"
+        #     end
+        #   end
+        def values(*value_names)
+          value_names.flatten.each { |name| value(name) }
+        end
+
+        # @return [SchemaArtifacts::RuntimeMetadata::Enum::Type] runtime metadata for this enum type
+        def runtime_metadata
+          runtime_metadata_values_by_name = values_by_name
+            .transform_values(&:runtime_metadata)
+            .compact
+
+          SchemaArtifacts::RuntimeMetadata::Enum::Type.new(values_by_name: runtime_metadata_values_by_name)
+        end
+
+        # @return [String] GraphQL SDL form of the enum type
+        def to_sdl
+          if values_by_name.empty?
+            raise SchemaError, "Enum type #{name} has no values, but enums must have at least one value."
+          end
+
+          <<~EOS
+            #{formatted_documentation}enum #{name} #{directives_sdl(suffix_with: " ")}{
+              #{values_by_name.values.map(&:to_sdl).flat_map { |s| s.split("\n") }.join("\n  ")}
+            }
+          EOS
+        end
+
+        # @private
+        def derived_graphql_types
+          # Derived GraphQL types must be generated for an output enum. For an enum type that is only
+          # used as an input, we do not need derived types.
+          return [] unless for_output
+
+          derived_scalar_types = schema_def_state.factory.new_scalar_type(name) do |t|
+            t.mapping type: "keyword"
+            t.json_schema type: "string"
+            t.graphql_only graphql_only?
+          end.derived_graphql_types
+
+          if (input_enum = as_input).equal?(self)
+            derived_scalar_types
+          else
+            [input_enum] + derived_scalar_types
+          end
+        end
+
+        # @return [Indexing::FieldType::Enum] indexing representation of this enum type
+        def to_indexing_field_type
+          Indexing::FieldType::Enum.new(values_by_name.keys)
+        end
+
+        # @return [false] enum types are never directly indexed
+        def indexed?
+          false
+        end
+
+        # @return [EnumType] converts the enum type to its input form for when different naming is used for input vs output enums.
+        def as_input
+          input_name = type_ref
+            .as_input_enum # To apply the configured format for input enums.
+            .to_final_form # To handle a type name override of the input enum.
+            .name
+
+          return self if input_name == name
+
+          schema_def_state.factory.new_enum_type(input_name) do |t|
+            t.for_output = false # flag that it's not used as an output enum, and therefore `derived_graphql_types` will be empty on it.
+            t.graphql_only true # input enums are always GraphQL-only.
+            t.documentation doc_comment
+            directives.each { |dir| dir.duplicate_on(t) }
+            values_by_name.each { |_, val| val.duplicate_on(t) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# 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/schema_definition/mixins/has_directives"
+require "elastic_graph/schema_definition/mixins/has_documentation"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/mixins/verifies_graphql_name"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Represents a value of a [GraphQL enum type](https://spec.graphql.org/October2021/#sec-Enums).
+      #
+      # @!attribute [r] schema_def_state
+      #   @return [State] state of the schema
+      # @!attribute [r] name
+      #   @return [String] name of the value
+      # @!attribute [r] runtime_metadata
+      #   @return [SchemaElements::RuntimeMetadata::Enum::Value] runtime metadata
+      class EnumValue < Struct.new(:schema_def_state, :name, :runtime_metadata)
+        prepend Mixins::VerifiesGraphQLName
+        include Mixins::HasDocumentation
+        include Mixins::HasDirectives
+        include Mixins::HasReadableToSAndInspect.new { |v| v.name }
+
+        # @private
+        def initialize(schema_def_state, name, original_name)
+          runtime_metadata = SchemaArtifacts::RuntimeMetadata::Enum::Value.new(
+            sort_field: nil,
+            datastore_value: nil,
+            datastore_abbreviation: nil,
+            alternate_original_name: (original_name if original_name != name)
+          )
+
+          super(schema_def_state, name, runtime_metadata)
+          yield self
+        end
+
+        # @return [String] GraphQL SDL form of the enum value
+        def to_sdl
+          "#{formatted_documentation}#{name}#{directives_sdl(prefix_with: " ")}"
+        end
+
+        # Duplicates this enum value on another {EnumType}.
+        #
+        # @param other_enum_type [EnumType] enum type to duplicate this value onto
+        # @return [void]
+        def duplicate_on(other_enum_type)
+          other_enum_type.value name do |v|
+            v.documentation doc_comment
+            directives.each { |dir| dir.duplicate_on(v) }
+            v.update_runtime_metadata(**runtime_metadata.to_h)
+          end
+        end
+
+        # Updates the runtime metadata.
+        #
+        # @param [Hash<Symbol, Object>] updates to apply to the runtime metadata
+        # @return [void]
+        def update_runtime_metadata(**updates)
+          self.runtime_metadata = runtime_metadata.with(**updates)
+        end
+
+        private :runtime_metadata=
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# 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"
+require "elastic_graph/error"
+require "elastic_graph/support/hash_util"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Abstraction for generating names for GraphQL enum values. This allows users to customize the
+      # naming of our built-in enum values.
+      #
+      # @private
+      class EnumValueNamer < ::Struct.new(:overrides_by_type_name)
+        def initialize(overrides_by_type_name = {})
+          overrides_by_type_name = Support::HashUtil
+            .stringify_keys(overrides_by_type_name) # : ::Hash[::String, ::Hash[::String, ::String]]
+
+          @used_value_names_by_type_name = ::Hash.new { |h, k| h[k] = [] }
+          validate_overrides(overrides_by_type_name)
+          super(overrides_by_type_name: overrides_by_type_name)
+        end
+
+        # Returns the name that should be used for the given `type_name` and `value_name`.
+        def name_for(type_name, value_name)
+          @used_value_names_by_type_name[type_name] << value_name
+          overrides_by_type_name.dig(type_name, value_name) || value_name
+        end
+
+        # Returns the overrides that did not wind up being used. Unused overrides usually happen
+        # because of a typo, and can be safely removed.
+        def unused_overrides
+          overrides_by_type_name.filter_map do |type_name, overrides|
+            if @used_value_names_by_type_name.key?(type_name)
+              unused_overrides = overrides.except(*@used_value_names_by_type_name.fetch(type_name))
+              [type_name, unused_overrides] unless unused_overrides.empty?
+            else
+              [type_name, overrides]
+            end
+          end.to_h
+        end
+
+        # Full set of enum type and value names that were used. Can be used to provide suggestions
+        # for when there are `unused_overrides`.
+        def used_value_names_by_type_name
+          @used_value_names_by_type_name.dup
+        end
+
+        private
+
+        def validate_overrides(overrides_by_type_name)
+          duplicate_problems = overrides_by_type_name.flat_map do |type_name, overrides|
+            overrides
+              .group_by { |k, v| v }
+              .transform_values { |kv_pairs| kv_pairs.map(&:first) }
+              .select { |_, v| v.size > 1 }
+              .map do |override, source_names|
+                "Multiple `#{type_name}` enum value overrides (#{source_names.sort.join(", ")}) map to the same name (#{override}), which is not supported."
+              end
+          end
+
+          invalid_name_problems = overrides_by_type_name.flat_map do |type_name, overrides|
+            overrides.filter_map do |source_name, override|
+              unless GRAPHQL_NAME_PATTERN.match(override)
+                "`#{override}` (the override for `#{type_name}.#{source_name}`) is not a valid GraphQL type name. " +
+                  GRAPHQL_NAME_VALIDITY_DESCRIPTION
+              end
+            end
+          end
+
+          notify_problems(duplicate_problems + invalid_name_problems)
+        end
+
+        def notify_problems(problems)
+          return if problems.empty?
+
+          raise ConfigError, "Provided `enum_value_overrides_by_type_name` have #{problems.size} problem(s):\n\n" \
+            "#{problems.map.with_index(1) { |problem, i| "#{i}. #{problem}" }.join("\n\n")}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# 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/schema_artifacts/runtime_metadata/enum"
+require "elastic_graph/schema_artifacts/runtime_metadata/sort_field"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Responsible for generating enum types based on specific indexed types.
+      #
+      # @private
+      class EnumsForIndexedTypes
+        def initialize(schema_def_state)
+          @schema_def_state = schema_def_state
+        end
+
+        # Generates a `SortOrder` enum type for the given indexed type.
+        def sort_order_enum_for(indexed_type)
+          return nil unless indexed_type.indexed?
+
+          build_enum(indexed_type, :sort_order, :sortable?, "sorted") do |enum_type, field_path|
+            value_name_parts = field_path.map(&:name)
+            index_field = field_path.map(&:name_in_index).join(".")
+
+            {asc: "ascending", desc: "descending"}.each do |dir, dir_description|
+              enum_type.value((value_name_parts + [dir.to_s.upcase]).join("_")) do |v|
+                v.update_runtime_metadata sort_field: SchemaArtifacts::RuntimeMetadata::SortField.new(index_field, dir)
+                v.documentation "Sorts #{dir_description} by the `#{graphql_field_path_description(field_path)}` field."
+
+                wrapped_enum_value = @schema_def_state.factory.new_sort_order_enum_value(v, field_path)
+
+                field_path.each do |field|
+                  field.sort_order_enum_value_customizations.each { |block| block.call(wrapped_enum_value) }
+                end
+              end
+            end
+          end
+        end
+
+        private
+
+        def build_enum(indexed_type, category, field_predicate, past_tense_verb, &block)
+          derived_type_ref = indexed_type.type_ref.as_static_derived_type(category)
+
+          enum = @schema_def_state.factory.new_enum_type(derived_type_ref.name) do |enum_type|
+            enum_type.documentation "Enumerates the ways `#{indexed_type.name}`s can be #{past_tense_verb}."
+            define_enum_values_for_type(enum_type, indexed_type, field_predicate, &block)
+          end.as_input
+
+          enum unless enum.values_by_name.empty?
+        end
+
+        def define_enum_values_for_type(enum_type, object_type, field_predicate, parents: [], &block)
+          object_type
+            .graphql_fields_by_name.values
+            .select(&field_predicate)
+            .each { |f| define_enum_values_for_field(enum_type, f, field_predicate, parents: parents, &block) }
+        end
+
+        def define_enum_values_for_field(enum_type, field, field_predicate, parents:, &block)
+          path = parents + [field]
+
+          if (object_type = field.type.fully_unwrapped.as_object_type)
+            define_enum_values_for_type(enum_type, object_type, field_predicate, parents: path, &block)
+          else
+            block.call(enum_type, path)
+          end
+        end
+
+        def graphql_field_path_description(field_path)
+          field_path.map(&:name).join(".")
+        end
+      end
+    end
+  end
+end