elasticgraph-schema_definition 0.18.0.0

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

@@ -0,0 +1,157 @@
+# 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/indexing/index"
+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_indices"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/mixins/has_subtypes"
+require "elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation"
+require "elastic_graph/schema_definition/mixins/verifies_graphql_name"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # {include:API#union_type}
+      #
+      # @example Define a union type
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.object_type "Card" do |t|
+      #       # ...
+      #     end
+      #
+      #     schema.object_type "BankAccount" do |t|
+      #       # ...
+      #     end
+      #
+      #     schema.object_type "BitcoinWallet" do |t|
+      #       # ...
+      #     end
+      #
+      #     schema.union_type "FundingSource" do |t|
+      #       t.subtype "Card"
+      #       t.subtypes "BankAccount", "BitcoinWallet"
+      #     end
+      #   end
+      #
+      # @!attribute [r] schema_def_state
+      #   @return [State] state of the schema
+      # @!attribute [rw] type_ref
+      #   @private
+      # @!attribute [rw] subtype_refs
+      #   @private
+      class UnionType < Struct.new(:schema_def_state, :type_ref, :subtype_refs)
+        prepend Mixins::VerifiesGraphQLName
+        include Mixins::CanBeGraphQLOnly
+        include Mixins::HasDocumentation
+        include Mixins::HasDirectives
+        include Mixins::SupportsFilteringAndAggregation
+        include Mixins::HasIndices
+        include Mixins::HasSubtypes
+        include Mixins::HasDerivedGraphQLTypeCustomizations
+        include Mixins::HasReadableToSAndInspect.new { |t| t.name }
+
+        # @private
+        def initialize(schema_def_state, name)
+          super(schema_def_state, schema_def_state.type_ref(name).to_final_form, Set.new) do
+            yield self
+          end
+        end
+
+        # @return [String] the name of the union type
+        def name
+          type_ref.name
+        end
+
+        # Defines a subtype of this union type.
+        #
+        # @param name [String] the name of an object type which is a member of this union type
+        # @return [void]
+        #
+        # @example
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Card" do |t|
+        #       # ...
+        #     end
+        #
+        #     schema.union_type "FundingSource" do |t|
+        #       t.subtype "Card"
+        #     end
+        #   end
+        def subtype(name)
+          type_ref = schema_def_state.type_ref(name.to_s).to_final_form
+
+          if subtype_refs.include?(type_ref)
+            raise SchemaError, "Duplicate subtype on UnionType #{self.name}: #{name}"
+          end
+
+          subtype_refs << type_ref
+        end
+
+        # Defines multiple subtypes of this union type.
+        #
+        # @param names [Array<String>] names of object types which are members of this union type
+        # @return [void]
+        #
+        # @example Define a union type
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "BankAccount" do |t|
+        #       # ...
+        #     end
+        #
+        #     schema.object_type "BitcoinWallet" do |t|
+        #       # ...
+        #     end
+        #
+        #     schema.union_type "FundingSource" do |t|
+        #       t.subtypes "BankAccount", "BitcoinWallet"
+        #     end
+        #   end
+        def subtypes(*names)
+          names.flatten.each { |n| subtype(n) }
+        end
+
+        # @return [String] the formatted GraphQL SDL of the union type
+        def to_sdl
+          if subtype_refs.empty?
+            raise SchemaError, "UnionType type #{name} has no subtypes, but must have at least one."
+          end
+
+          "#{formatted_documentation}union #{name} #{directives_sdl(suffix_with: " ")}= #{subtype_refs.map(&:name).to_a.join(" | ")}"
+        end
+
+        # @private
+        def verify_graphql_correctness!
+          # Nothing to verify. `verify_graphql_correctness!` will be called on each subtype automatically.
+        end
+
+        # Various things check `mapping_options` on indexed types (usually object types, but can also happen on union types).
+        # We need to implement `mapping_options` here to satisfy those method calls, but we will never use custom mapping on
+        # a union type so we hardcode it to return nil.
+        #
+        # @private
+        def mapping_options
+          {}
+        end
+
+        private
+
+        def resolve_subtypes
+          subtype_refs.map do |ref|
+            ref.as_object_type || raise(
+              SchemaError, "The subtype `#{ref}` of the UnionType `#{name}` is not a defined object type."
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/scripting/file_system_repository.rb

@@ -0,0 +1,77 @@
+# 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/error"
+require "elastic_graph/schema_definition/scripting/script"
+require "elastic_graph/support/memoizable_data"
+require "pathname"
+
+module ElasticGraph
+  module SchemaDefinition
+    # @private
+    module Scripting
+      # A simple abstraction that supports loading static scripts off of disk. The given directory
+      # is expected to have a sub-directory per script context, with individual scripts under the
+      # context sub-directories. The language is inferred from the script file extensions.
+      #
+      # @private
+      class FileSystemRepository < Support::MemoizableData.define(:dir)
+        # Based on https://www.elastic.co/guide/en/elasticsearch/reference/8.5/modules-scripting.html
+        SUPPORTED_LANGUAGES_BY_EXTENSION = {
+          ".painless" => "painless",
+          ".expression" => "expression",
+          ".mustache" => "mustache",
+          ".java" => "java"
+        }
+
+        # The `Script` objects available in this file system repository.
+        def scripts
+          @scripts ||= ::Pathname.new(dir).children.sort.flat_map do |context_dir|
+            unless context_dir.directory?
+              raise InvalidScriptDirectoryError, "`#{dir}` has a file (#{context_dir}) that is not a context directory as expected."
+            end
+
+            context_dir.children.sort.map do |script_file|
+              unless script_file.file?
+                raise InvalidScriptDirectoryError, "`#{dir}` has extra directory nesting (#{script_file}) that is unexpected."
+              end
+
+              language = SUPPORTED_LANGUAGES_BY_EXTENSION[script_file.extname] || raise(
+                InvalidScriptDirectoryError, "`#{dir}` has a file (`#{script_file}`) that has an unrecognized file extension: #{script_file.extname}."
+              )
+
+              Script.new(
+                name: script_file.basename.sub_ext("").to_s,
+                source: script_file.read.strip,
+                language: language,
+                context: context_dir.basename.to_s
+              )
+            end
+          end.tap { |all_scripts| verify_no_duplicates!(all_scripts) }
+        end
+
+        # Map of script ids keyed by the `scoped_name` to allow easy lookup of the ids.
+        def script_ids_by_scoped_name
+          @script_ids_by_scoped_name ||= scripts.to_h { |s| [s.scoped_name, s.id] }
+        end
+
+        private
+
+        def verify_no_duplicates!(scripts)
+          duplicate_scoped_names = scripts.group_by(&:scoped_name).select do |scoped_name, scripts_with_scoped_name|
+            scripts_with_scoped_name.size > 1
+          end.keys
+
+          if duplicate_scoped_names.any?
+            raise InvalidScriptDirectoryError, "`#{dir}` has multiple scripts with the same scoped name, which is not allowed: #{duplicate_scoped_names.join(", ")}."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/scripting/script.rb

@@ -0,0 +1,48 @@
+# 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 "digest/md5"
+require "elastic_graph/support/memoizable_data"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Scripting
+      # @private
+      class Script < Support::MemoizableData.define(:name, :source, :language, :context)
+        # The id we use when storing the script in the datastore. The id is based partially on a hash of
+        # the source code to make script safely evolveable: when the source code of a script changes, its
+        # id changes, and the old and new versions continue to be accessible in the datastore, allowing
+        # old and new versions of the deployed ElasticGraph application to be running at the same time
+        # (as happens during a zero-downtime rolled-out deploy). Scripts are invoked by their id, so we
+        # can trust that when the code tries to use a specific version of a script, it'll definitely use
+        # that version.
+        def id
+          @id ||= "#{context}_#{name}_#{::Digest::MD5.hexdigest(source)}"
+        end
+
+        # The `name` scoped with the `context`. Due to how we structure static scripts on
+        # the file system (nested under a directory that names the `context`), a given `name`
+        # is only guaranteed to be unique within the scope of a given `context`. The `scoped_name`
+        # is how we will refer to a script from elsewhere in the code when we want to use it.
+        def scoped_name
+          @scoped_name ||= "#{context}/#{name}"
+        end
+
+        def to_artifact_payload
+          {
+            "context" => context,
+            "script" => {
+              "lang" => language,
+              "source" => source
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/scripting/scripts/field/as_day_of_week.painless

@@ -0,0 +1,24 @@
+// Check if required params are missing
+if (params.offset_ms == null) {
+  throw new IllegalArgumentException("Missing required parameter: offset_ms");
+}
+if (params.time_zone == null) {
+  throw new IllegalArgumentException("Missing required parameter: time_zone");
+}
+
+// Set variables used in the loop
+ZoneId zoneId = ZoneId.of(params.time_zone);
+List results = new ArrayList();
+
+for (ZonedDateTime timestamp : doc[params.field]) {
+  // Convert the timestamp to the specified time zone
+  ZonedDateTime zonedTimestamp = timestamp.withZoneSameInstant(zoneId);
+
+  // Adjust the timestamp based on the offset_ms parameter
+  ZonedDateTime adjustedTimestamp = zonedTimestamp.plus(params.offset_ms, ChronoUnit.MILLIS);
+
+  // Format and add the result to the list
+  results.add(adjustedTimestamp.getDayOfWeek().name());
+}
+
+return results;

data/lib/elastic_graph/schema_definition/scripting/scripts/field/as_time_of_day.painless

@@ -0,0 +1,41 @@
+// Check if required params are missing
+if (params.offset_ms == null) {
+  throw new IllegalArgumentException("Missing required parameter: offset_ms");
+}
+if (params.time_zone == null) {
+  throw new IllegalArgumentException("Missing required parameter: time_zone");
+}
+if (params.interval == null) {
+  throw new IllegalArgumentException("Missing required parameter: interval");
+}
+
+// Set variables used in the loop
+ZoneId zoneId = ZoneId.of(params.time_zone);
+ChronoUnit intervalUnit;
+if (params.interval == "hour") {
+  intervalUnit = ChronoUnit.HOURS;
+} else if (params.interval == "minute") {
+  intervalUnit = ChronoUnit.MINUTES;
+} else if (params.interval == "second") {
+  intervalUnit = ChronoUnit.SECONDS;
+} else {
+  throw new IllegalArgumentException("Invalid interval value: " + params.interval);
+}
+DateTimeFormatter formatter = DateTimeFormatter.ISO_LOCAL_TIME;
+List results = new ArrayList();
+
+for (ZonedDateTime timestamp : doc[params.field]) {
+  // Convert the timestamp to the specified time zone
+  ZonedDateTime zonedTimestamp = timestamp.withZoneSameInstant(zoneId);
+
+  // Adjust the timestamp based on the offset_ms parameter
+  ZonedDateTime adjustedTimestamp = zonedTimestamp.plus(params.offset_ms, ChronoUnit.MILLIS);
+
+  // Truncate the timestamp to the specified interval
+  adjustedTimestamp = adjustedTimestamp.truncatedTo(intervalUnit);
+
+  // Format and add the result to the list
+  results.add(adjustedTimestamp.format(formatter));
+}
+
+return results;

data/lib/elastic_graph/schema_definition/scripting/scripts/filter/by_time_of_day.painless

@@ -0,0 +1,22 @@
+ZoneId zoneId = ZoneId.of(params.time_zone);
+
+for (ZonedDateTime timestamp : doc[params.field]) {
+  long docValue = timestamp
+    .withZoneSameInstant(zoneId)
+    .toLocalTime()
+    .toNanoOfDay();
+
+  // Perform comparisons based on whichever params are set.
+  // ElasticGraph takes care of passing us param values as nano-of-day so that we
+  // can directly and efficiently compare against `docValue`.
+  if ((params.gte == null || docValue >= params.gte) &&
+      (params.gt == null || docValue > params.gt) &&
+      (params.lte == null || docValue <= params.lte) &&
+      (params.lt == null || docValue < params.lt) &&
+      (params.equal_to_any_of == null || params.equal_to_any_of.contains(docValue))) {
+    return true;
+  }
+}
+
+// No timestamp values matched the params, so return `false`.
+return false;

data/lib/elastic_graph/schema_definition/scripting/scripts/update/index_data.painless

@@ -0,0 +1,93 @@
+Map source = ctx._source;
+String sourceId = params.sourceId;
+String relationship = params.relationship;
+
+// Numbers in JSON appear to be parsed as doubles, but we want the version stored as a long, so we need to cast it here.
+long eventVersion = (long) params.version;
+
+if (source.__sources == null) {
+  source.__sources = [];
+}
+
+if (source.__versions == null) {
+  source.__versions = [:];
+}
+
+if (source.__versions[relationship] == null) {
+  source.__versions[relationship] = [:];
+}
+
+Map relationshipVersionsMap = source.__versions.get(relationship);
+List previousSourceIdsForRelationship = relationshipVersionsMap.keySet().stream().filter(id -> id != sourceId).collect(Collectors.toList());
+
+if (previousSourceIdsForRelationship.size() > 0) {
+  String previousIdDescription = previousSourceIdsForRelationship.size() == 1 ? previousSourceIdsForRelationship.get(0) : previousSourceIdsForRelationship.toString();
+  throw new IllegalArgumentException(
+    "Cannot update document " + params.id + " " +
+    "with data from related " + relationship + " " + sourceId + " " +
+    "because the related " + relationship + " has apparently changed (was: " + previousSourceIdsForRelationship + "), " +
+    "but mutations of relationships used with `sourced_from` are not supported because " +
+    "allowing it could break ElasticGraph's out-of-order processing guarantees."
+ );
+}
+
+// While the version in `__versions` is going to be used for the doc version in the future, for now
+// we need to continue getting it from `__sourceVersions`. Both our old version and this versions of this
+// script keep the value in `__sourceVersions` up-to-date, whereas the old script only writes it to
+// `__sourceVersions`. Until we have completely migrated off of the old script for all ElasticGraph
+// clusters, we need to keep using it.
+//
+// Later, after the old script is no longer used by any clusters, we'll stop using `__sourceVersions`.
+// TODO: switch to `__versions` when we no longer need to maintain compatibility with the old version of the script.
+Number _versionForSourceType = source.get("__sourceVersions")?.get(params.sourceType)?.get(sourceId);
+Number _versionForRelationship = relationshipVersionsMap.get(sourceId);
+
+// Our JSON schema requires event versions to be non-negative, so we can safely use Long.MIN_VALUE as a stand-in when the value is null.
+long versionForSourceType = _versionForSourceType == null ? Long.MIN_VALUE : _versionForSourceType.longValue();
+long versionForRelationship = _versionForRelationship == null ? Long.MIN_VALUE : _versionForRelationship.longValue();
+
+// Pick the larger of the two versions as our doc version. Note that `Math.max` didn't work for me here for
+// reasons I don't understand, but a simple ternary works fine.
+//
+// In theory, we could just use `versionForSourceType` as the `docVersion` (and not even check `__versions` at all)
+// since both the old version and this version maintain the doc version in `__sourceVersions`. However, that would
+// prevent this version of the script from being forward-compatible with the planned next version of this script.
+// In the next version, we plan to stop writing to `__sourceVersions`, and as we can't deploy that change atomically,
+// this version of the script will continue to run after that has begun to be used. So this version of the script
+// must consider which version is greater here, and not simply trust either version value.
+long docVersion = versionForSourceType > versionForRelationship ? versionForSourceType : versionForRelationship;
+
+if (docVersion >= eventVersion) {
+  throw new IllegalArgumentException("ElasticGraph update was a no-op: [" +
+    params.id + "]: version conflict, current version [" +
+    docVersion + "] is higher or equal to the one provided [" +
+    eventVersion + "]");
+} else {
+  source.putAll(params.data);
+  Map __counts = params.__counts;
+
+  if (__counts != null) {
+    if (source.__counts == null) {
+      source.__counts = [:];
+    }
+
+    source.__counts.putAll(__counts);
+  }
+
+  source.id = params.id;
+  source.__versions[relationship][sourceId] = eventVersion;
+
+  // Record the relationship in `__sources` if it's not already there. We maintain it as an append-only set using a sorted list.
+  // This ensures deterministic ordering of its elements regardless of event ingestion order, and lets us check membership in O(log N) time.
+  //
+  // As per https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Collections.html#binarySearch(java.util.List,java.lang.Object):
+  //
+  // > Returns the index of the search key, if it is contained in the list; otherwise, (-(insertion point) - 1).
+  // > The insertion point is defined as the point at which the key would be inserted into the list: the index
+  // > of the first element greater than the key, or list.size() if all elements in the list are less than the
+  // > specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.
+  int sourceBinarySearchResult = Collections.binarySearch(source.__sources, relationship);
+  if (sourceBinarySearchResult < 0) {
+    source.__sources.add(-sourceBinarySearchResult - 1, relationship);
+  }
+}

data/lib/elastic_graph/schema_definition/state.rb

@@ -0,0 +1,212 @@
+# 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/schema_definition/factory"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/schema_elements/enum_value_namer"
+require "elastic_graph/schema_definition/schema_elements/type_namer"
+require "elastic_graph/schema_definition/schema_elements/sub_aggregation_path"
+
+module ElasticGraph
+  module SchemaDefinition
+    # Encapsulates all state that needs to be managed while a schema is defined.
+    # This is separated from `API` to make it easy to expose some state management
+    # helper methods to our internal code without needing to expose it as part of
+    # the public API.
+    #
+    # @private
+    class State < Struct.new(
+      :api,
+      :schema_elements,
+      :index_document_sizes,
+      :types_by_name,
+      :object_types_by_name,
+      :scalar_types_by_name,
+      :enum_types_by_name,
+      :implementations_by_interface_ref,
+      :sdl_parts,
+      :paginated_collection_element_types,
+      :user_defined_fields,
+      :renamed_types_by_old_name,
+      :deleted_types_by_old_name,
+      :renamed_fields_by_type_name_and_old_field_name,
+      :deleted_fields_by_type_name_and_old_field_name,
+      :json_schema_version,
+      :json_schema_version_setter_location,
+      :graphql_extension_modules,
+      :initially_registered_built_in_types,
+      :built_in_types_customization_blocks,
+      :user_definition_complete,
+      :sub_aggregation_paths_by_type,
+      :type_refs_by_name,
+      :output,
+      :type_namer,
+      :enum_value_namer
+    )
+      include Mixins::HasReadableToSAndInspect.new
+
+      def self.with(
+        api:,
+        schema_elements:,
+        index_document_sizes:,
+        derived_type_name_formats:,
+        type_name_overrides:,
+        enum_value_overrides_by_type:,
+        output: $stdout
+      )
+        # @type var types_by_name: SchemaElements::typesByNameHash
+        types_by_name = {}
+
+        new(
+          api: api,
+          schema_elements: schema_elements,
+          index_document_sizes: index_document_sizes,
+          types_by_name: types_by_name,
+          object_types_by_name: {},
+          scalar_types_by_name: {},
+          enum_types_by_name: {},
+          implementations_by_interface_ref: ::Hash.new { |h, k| h[k] = ::Set.new },
+          sdl_parts: [],
+          paginated_collection_element_types: ::Set.new,
+          user_defined_fields: ::Set.new,
+          renamed_types_by_old_name: {},
+          deleted_types_by_old_name: {},
+          renamed_fields_by_type_name_and_old_field_name: ::Hash.new { |h, k| h[k] = {} },
+          deleted_fields_by_type_name_and_old_field_name: ::Hash.new { |h, k| h[k] = {} },
+          json_schema_version_setter_location: nil,
+          json_schema_version: nil,
+          graphql_extension_modules: [],
+          initially_registered_built_in_types: ::Set.new,
+          built_in_types_customization_blocks: [],
+          user_definition_complete: false,
+          sub_aggregation_paths_by_type: {},
+          type_refs_by_name: {},
+          type_namer: SchemaElements::TypeNamer.new(
+            format_overrides: derived_type_name_formats,
+            name_overrides: type_name_overrides
+          ),
+          enum_value_namer: SchemaElements::EnumValueNamer.new(enum_value_overrides_by_type),
+          output: output
+        )
+      end
+
+      # @dynamic index_document_sizes?
+      alias_method :index_document_sizes?, :index_document_sizes
+
+      def type_ref(name)
+        # Type references are immutable and can be safely cached. Here we cache them because we've observed
+        # it having a noticeable impact on our test suite runtime.
+        type_refs_by_name[name] ||= factory.new_type_reference(name)
+      end
+
+      def register_object_interface_or_union_type(type)
+        register_type(type, object_types_by_name)
+      end
+
+      def register_enum_type(type)
+        register_type(type, enum_types_by_name)
+      end
+
+      def register_scalar_type(type)
+        register_type(type, scalar_types_by_name)
+      end
+
+      def register_input_type(type)
+        register_type(type)
+      end
+
+      def register_renamed_type(type_name, from:, defined_at:, defined_via:)
+        renamed_types_by_old_name[from] = factory.new_deprecated_element(
+          type_name,
+          defined_at: defined_at,
+          defined_via: defined_via
+        )
+      end
+
+      def register_deleted_type(type_name, defined_at:, defined_via:)
+        deleted_types_by_old_name[type_name] = factory.new_deprecated_element(
+          type_name,
+          defined_at: defined_at,
+          defined_via: defined_via
+        )
+      end
+
+      def register_renamed_field(type_name, from:, to:, defined_at:, defined_via:)
+        renamed_fields_by_type_name_and_old_field_name[type_name][from] = factory.new_deprecated_element(
+          to,
+          defined_at: defined_at,
+          defined_via: defined_via
+        )
+      end
+
+      def register_deleted_field(type_name, field_name, defined_at:, defined_via:)
+        deleted_fields_by_type_name_and_old_field_name[type_name][field_name] = factory.new_deprecated_element(
+          field_name,
+          defined_at: defined_at,
+          defined_via: defined_via
+        )
+      end
+
+      # Registers the given `field` as a user-defined field, unless the user definitions are complete.
+      def register_user_defined_field(field)
+        user_defined_fields << field
+      end
+
+      def user_defined_field_references_by_type_name
+        @user_defined_field_references_by_type_name ||= begin
+          unless user_definition_complete
+            raise SchemaError, "Cannot access `user_defined_field_references_by_type_name` until the schema definition is complete."
+          end
+
+          @user_defined_field_references_by_type_name ||= user_defined_fields
+            .group_by { |f| f.type.fully_unwrapped.name }
+        end
+      end
+
+      def factory
+        @factory ||= Factory.new(self)
+      end
+
+      def enums_for_indexed_types
+        @enums_for_indexed_types ||= factory.new_enums_for_indexed_types
+      end
+
+      def sub_aggregation_paths_for(type)
+        sub_aggregation_paths_by_type.fetch(type) do
+          SchemaElements::SubAggregationPath.paths_for(type, schema_def_state: self).uniq.tap do |paths|
+            # Cache our results if the user has finished their schema definition. Otherwise, it's not safe to cache.
+            # :nocov: -- we never execute this with `user_definition_complete == false`
+            sub_aggregation_paths_by_type[type] = paths if user_definition_complete
+            # :nocov:
+          end
+        end
+      end
+
+      private
+
+      RESERVED_TYPE_NAMES = [EVENT_ENVELOPE_JSON_SCHEMA_NAME].to_set
+
+      def register_type(type, additional_type_index = nil)
+        name = (_ = type).name
+
+        if RESERVED_TYPE_NAMES.include?(name)
+          raise SchemaError, "`#{name}` cannot be used as a schema type because it is a reserved name."
+        end
+
+        if types_by_name.key?(name)
+          raise SchemaError, "Duplicate definition for type #{name} detected. Each type can only be defined once."
+        end
+
+        additional_type_index[name] = type if additional_type_index
+        types_by_name[name] = type
+      end
+    end
+  end
+end