pack_api 1.0.0

data/lib/pack_api/models/mapping/attribute_map.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+###
+# Map (convert) the names of attributes presented on one side of an API to those required on the other side.
+# Handles 3 scenarios:
+#
+#   1. create/update API endpoints
+#       IN: attribute Hash with names conforming to the ValueObject type attributes*
+#       OUT: attribute Hash with names conforming to the ActiveRecord model type
+#
+#       * generally true; except when it's not. For example, if the ValueObject type has an attribute
+#         named "user", and the ActiveRecord model has an attribute named "user", typically this is set during
+#         create/update calls by passing in the "user_id" attribute.
+#
+#  2. converting an ActiveRecord model as a ValueObject
+#      IN: ActiveRecord model instance
+#      OUT: attribute Hash with names conforming to the ValueObject type attributes
+#
+#  3. converting an ActiveModel::Errors instance to an attribute Hash
+#     IN: ActiveModel::Errors instance
+#     OUT: attribute Hash with names conforming to the ValueObject type attributes*
+#
+#     * generally true; except when it's not. For example, if the ValueObject type has an attribute
+#       named "user", and the ActiveRecord model has an attribute named "user", typically this is set during
+#       create/update calls by passing in the "user_id" attribute. Therefore, the error hash will have to
+#       associate the error with the "user_id" attribute (not the "user" attribute).
+module PackAPI::Mapping
+  class AttributeMap
+    FROZEN_EMPTY_HASH = {}.freeze
+
+    attr_reader :config, :options
+
+    class << self
+      def map(source_attr, to: nil, from_api_attribute: nil, from_model_attribute: nil, readonly: nil, transform_nested_attributes_with: nil)
+        @mappings ||= {}
+        @from_api_attributes ||= {}
+        @from_model_attributes ||= {}
+        @transform_nested_attributes_with ||= {}
+        @mappings[source_attr] = to || source_attr
+        @from_model_attributes[source_attr] = from_model_attribute if from_model_attribute.present?
+        @from_api_attributes[source_attr] = from_api_attribute if from_api_attribute.present?
+        @transform_nested_attributes_with[source_attr] = transform_nested_attributes_with if transform_nested_attributes_with.present?
+        if readonly
+          @from_api_attributes[source_attr] = ->(*) { raise PackAPI::InternalError, "Unable to modify read-only attribute '#{source_attr}'" }
+        end
+      end
+
+      def api_type(api_type = nil)
+        return @api_type unless api_type
+
+        @api_type = api_type
+      end
+
+      def model_type(model_type = nil)
+        return @model_type unless model_type
+
+        @model_type = model_type
+      end
+
+      def config
+        {
+          mappings: @mappings,
+          from_api_attributes: @from_api_attributes,
+          from_model_attributes: @from_model_attributes,
+          transform_nested_attributes_with: @transform_nested_attributes_with,
+          api_type: @api_type,
+          model_type: @model_type
+        }
+      end
+    end
+
+    def self.model_attribute_keys(hash)
+      options = { contains_model_attributes: false,
+                  transformer_type_for_source: AttributeHashTransformer.name }
+      new(hash.symbolize_keys, options).attributes
+    end
+
+    def self.api_attribute_keys(hash)
+      options = { contains_model_attributes: true,
+                  transformer_type_for_source: AttributeHashTransformer.name }
+      new(hash.symbolize_keys, options).attributes
+    end
+
+    DEFAULT_OPTIONS = { optional_attributes: nil }.freeze
+    private_constant :DEFAULT_OPTIONS
+
+    def initialize(data_source = nil, options = nil)
+      @options = DEFAULT_OPTIONS
+      @config = self.class.config
+
+      self.options = options
+      self.data_source = data_source
+    end
+
+    def from_model_attributes
+      @from_model_attributes ||= config[:from_model_attributes].transform_values do |proc_or_method_name|
+        ValueTransformationChain.new([ValueTransformation.new(self.class, proc_or_method_name, options)])
+      end
+    end
+
+    def from_api_attributes
+      return @from_api_attributes if defined?(@from_api_attributes)
+
+      @from_api_attributes = config[:from_api_attributes].transform_values do |proc_or_method_name|
+        ValueTransformationChain.new([ValueTransformation.new(self.class, proc_or_method_name, options)])
+      end
+
+      config[:transform_nested_attributes_with].each do |source_attr, attribute_map_class|
+        @from_api_attributes[source_attr] ||= ValueTransformationChain.new([])
+        @from_api_attributes[source_attr].transformations << ValueTransformation.new(
+          self.class, :convert_nested_attribute, { attribute_map_class: attribute_map_class }
+        )
+      end
+
+      @from_api_attributes
+    end
+
+    def data_source=(data_source)
+      transformer_type = transformer_type_for_source(data_source)
+      unless @transformer.is_a?(transformer_type)
+        @transformer = transformer_type.new(config_for_adapter_type(transformer_type))
+      end
+      @transformer.data_source = data_source
+      @transformer.options = @options
+    end
+
+    def data_source
+      @transformer&.data_source
+    end
+
+    def options=(new_options)
+      return if new_options == @provided_options
+
+      @provided_options = new_options
+      @options = @provided_options ?
+                   DEFAULT_OPTIONS.merge(@provided_options) :
+                   DEFAULT_OPTIONS
+      from_model_attributes.each_value { |transformation| transformation.kwargs = options }
+      @transformer&.options = options
+    end
+
+    def register_transformation_from_model_attribute(source_attr, proc_or_method_name)
+      from_model_attributes[source_attr] ||= ValueTransformationChain.new([])
+      transformation = ValueTransformation.new(self.class, proc_or_method_name, options)
+      from_model_attributes[source_attr].transformations << transformation
+    end
+
+    def attributes
+      @transformer.execute
+    end
+
+    def api_type
+      self.class.api_type
+    end
+
+    def model_type
+      self.class.model_type
+    end
+
+    private
+
+    def convert_nested_attribute(parent_attribute_value, attribute_map_class:)
+      attribute_map = attribute_map_class.new
+      if parent_attribute_value.is_a?(Array)
+        parent_attribute_value.map do |nested_attributes|
+          attribute_map.data_source = nested_attributes
+          attribute_map.attributes
+        end
+      else
+        attribute_map.data_source = parent_attribute_value
+        attribute_map.attributes
+      end
+    end
+
+    def transformer_type_for_source(source)
+      if options.key?(:transformer_type_for_source)
+        options[:transformer_type_for_source].constantize
+      elsif source.nil?
+        NullTransformer
+      elsif source.is_a?(Hash)
+        APIToModelAttributesTransformer
+      elsif source.is_a?(ActiveModel::Errors)
+        ErrorHashToAPIAttributesTransformer
+      elsif source.is_a?(ActiveModel::AttributeAssignment)
+        ModelToAPIAttributesTransformer
+      else
+        raise "Unknown source #{source}"
+      end
+    end
+
+    def config_for_adapter_type(adapter_type)
+      if [ErrorHashToAPIAttributesTransformer, ModelToAPIAttributesTransformer].include?(adapter_type)
+        transform_value = method(:transform_value_for_api)
+        config.merge(transform_value:)
+      elsif adapter_type == APIToModelAttributesTransformer
+        transform_value = method(:transform_value_for_model)
+        config.merge(transform_value:)
+      else
+        config
+      end
+    end
+
+    def transform_value_for_api(api_attribute, model_value)
+      from_model_attributes.key?(api_attribute) ?
+        from_model_attributes[api_attribute].call(self, model_value) :
+        model_value
+    end
+
+    def transform_value_for_model(api_attribute, api_value)
+      from_api_attributes.key?(api_attribute) ?
+        from_api_attributes[api_attribute].call(self, api_value) :
+        api_value
+    end
+
+    class ValueTransformation
+      attr_reader :proc, :instance_method
+
+      def initialize(klass, proc_or_method_name, kwargs = nil)
+        if proc_or_method_name.is_a?(Proc)
+          @proc = proc_or_method_name
+        else
+          @instance_method = klass.instance_method(proc_or_method_name)
+        end
+        self.kwargs = kwargs
+      end
+
+      def call(attribute_map, attribute_value)
+        proc ?
+          attribute_map.instance_exec(attribute_value, **@kwargs, &proc) :
+          attribute_map.send(instance_method.name, attribute_value, **@kwargs)
+      end
+
+      def kwargs=(new_kwargs)
+        @kwargs = supported_kwargs(new_kwargs)
+      end
+
+      private
+
+      def supported_kwargs(kwargs)
+        return FROZEN_EMPTY_HASH if kwargs.blank?
+
+        kwargs.select { |kwarg| parameters.any? { |parameter| parameter.last == kwarg } }
+      end
+
+      def parameters
+        @parameters ||= (proc || instance_method).parameters
+      end
+    end
+
+    class ValueTransformationChain
+      attr_reader :transformations
+      def initialize(transformations)
+        @transformations = transformations
+      end
+
+      def kwargs=(new_kwargs)
+        transformations.each { it.kwargs = new_kwargs }
+      end
+
+      def call(attribute_map, attribute_value)
+        transformations.reduce(attribute_value) do |prev_result, next_transformation|
+          next_transformation.call(attribute_map, prev_result)
+        end
+      end
+    end
+
+  end
+end

data/lib/pack_api/models/mapping/attribute_map_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  class AttributeMapRegistry
+
+    class << self
+      attr_reader :attribute_maps
+
+      def register_attribute_map(attribute_map_class)
+        @attribute_maps ||= {}
+        @attribute_maps[attribute_map_class.model_type] = attribute_map_class
+      end
+    end
+
+    def attribute_map_class(model_class)
+      raise "No attribute map defined for #{model_class}" unless self.class.attribute_maps.key?(model_class)
+
+      self.class.attribute_maps[model_class]
+    end
+  end
+end

data/lib/pack_api/models/mapping/error_hash_to_api_attributes_transformer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  ###
+  # Specialized attribute transformer converting the attribute names in an ActiveRecord Error object to those
+  # that should be present in the Error Hash in the API Result object.
+  class ErrorHashToAPIAttributesTransformer < AbstractTransformer
+    NESTED_ATTRIBUTE_ERROR_KEY = /\A(?<parent>[\w_]+)\[(?<index>\d+)\]\.(?<child>[\w_]+)\z/
+
+    def initialize(config)
+      super
+      @transform_nested_attributes_with = config[:transform_nested_attributes_with]
+    end
+
+    def execute
+      api_attributes = api_attribute_names.flat_map do |api_attribute|
+        model_attribute = model_attribute(api_attribute)
+        next unless error_present_for?(model_attribute)
+
+        error_keys_for(model_attribute).map do |error_key|
+          converted_error_key = nested_attribute_error_key?(error_key) ?
+            convert_nested_attribute_error_key(error_key, api_attribute) :
+            normalize_association_reference(api_attribute, model_attribute)
+          [converted_error_key, data_source[error_key]]
+        end
+      end
+      api_attributes.compact.to_h
+    end
+
+    private
+
+    def convert_nested_attribute_error_key(error_key, parent_api_attribute)
+      NESTED_ATTRIBUTE_ERROR_KEY.match(error_key) do |match_data|
+        child_attribute_map_class = @transform_nested_attributes_with[parent_api_attribute]
+        child_model_attribute = match_data[:child].to_sym
+        child_api_attribute = child_model_attribute
+        if child_attribute_map_class
+          mapping = child_attribute_map_class.config[:mappings].find { |_k, v| v == child_model_attribute }
+          child_api_attribute = mapping.first if mapping
+        end
+        "#{parent_api_attribute}[#{match_data[:index]}].#{child_api_attribute}"
+      end
+    end
+
+    def nested_attribute_error_key?(error_key)
+      NESTED_ATTRIBUTE_ERROR_KEY.match?(error_key.to_s)
+    end
+
+    def error_keys_for(model_attribute)
+      data_source.include?(model_attribute) ?
+        [model_attribute] :
+        nested_attributes_with_errors(model_attribute)
+    end
+
+    def error_present_for?(model_attribute)
+      data_source.include?(model_attribute) || nested_attributes_with_errors(model_attribute).any?
+    end
+
+    def nested_attributes_with_errors(parent_attribute)
+      data_source.attribute_names.select { |attribute| attribute.to_s.start_with?("#{parent_attribute}[") }
+    end
+
+    def resource_association?(model_attribute)
+      resource_associations.include?(model_attribute)
+    end
+
+    def collection_association?(model_attribute)
+      collection_associations.include?(model_attribute)
+    end
+
+    def resource_associations
+      @resource_associations ||= model_type.reflect_on_all_associations
+                                           .reject(&:collection?)
+                                           .map(&:name)
+    end
+
+    def collection_associations
+      @collection_associations ||= model_type.reflect_on_all_associations
+                                             .select(&:collection?)
+                                             .map(&:name)
+    end
+
+    def normalize_association_reference(api_attribute, model_attribute)
+      if resource_association?(model_attribute)
+        normalize_resource_association_reference(api_attribute)
+      elsif collection_association?(model_attribute)
+        normalize_collection_association_reference(api_attribute)
+      else
+        api_attribute
+      end
+    end
+
+    def normalize_collection_association_reference(api_attribute)
+      :"#{api_attribute.to_s.singularize}_ids"
+    end
+
+    def normalize_resource_association_reference(api_attribute)
+      :"#{api_attribute.to_s.singularize}_id"
+    end
+  end
+end

data/lib/pack_api/models/mapping/filter_map.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  FROZEN_EMPTY_ARRAY = [].freeze
+  FROZEN_EMPTY_HASH = {}.freeze
+
+  ##
+  # This class is responsible for transforming API filter names into model filters. It also produces filter definitions
+  # in API terms for those filters that are supported by the model.
+  class FilterMap
+    attr_reader :filter_factory, :attribute_map_class
+
+    def initialize(filter_factory:, attribute_map_class: nil)
+      @filter_factory = filter_factory
+      @attribute_map_class = attribute_map_class
+    end
+
+    def from_api_filters(api_filters)
+      validate(api_filters)
+      transform_api_attribute_filters(api_filters).merge(transform_api_custom_filters(api_filters))
+    end
+
+    def filter_definitions(filter_names: nil, **)
+      supported_filters.filter_map do |filter_name, filter_class|
+        next if filter_names&.exclude?(filter_name)
+
+        api_attribute_filter_name_map.key?(filter_name) ?
+          attribute_filter_definition(filter_name, filter_class) :
+          other_filter_definition(filter_name, filter_class, **)
+      end
+    end
+
+    private
+
+    def attribute_filter_definition(filter_name, filter_class)
+      api_filter_name = api_attribute_filter_name_map[filter_name]
+      filter_class.definition.merge(name: api_filter_name)
+    end
+
+    def other_filter_definition(_filter_name, filter_class, **)
+      filter_class.definition(**)
+    end
+
+    def api_attribute_filter_names
+      @api_attribute_filter_names ||= attribute_map_class.nil? ?
+                                        FROZEN_EMPTY_ARRAY :
+                                        attribute_map_class.api_type.filterable_attributes.keys
+    end
+
+    ###
+    # Map from a backend filter name to an API filter name for default attribute filters.
+    def api_attribute_filter_name_map
+      return @api_attribute_filter_name_map if defined?(@api_attribute_filter_name_map)
+      return FROZEN_EMPTY_HASH if attribute_map_class.nil?
+
+      names = {}
+      api_attribute_filter_names.each { |name| names[name] = name }
+      @api_attribute_filter_name_map = attribute_map_class.model_attribute_keys(names)
+    end
+
+    def validate(filters)
+      invalid_filter_names = filters.keys.reject { |filter_name| valid?(filter_name) }
+      raise PackAPI::InternalError, validation_error_message(invalid_filter_names) if invalid_filter_names.any?
+    end
+
+    def valid?(filter_name)
+      api_filter_names.include?(filter_name)
+    end
+
+    def api_filter_names
+      @api_filter_names ||= supported_filters.keys.map do |filter_name|
+        api_attribute_filter_name_map.fetch(filter_name, filter_name)
+      end
+    end
+
+    def validation_error_message(unsupported_filter_names)
+      filter_names_string = unsupported_filter_names.map { |filter_name| "'#{filter_name}'" }.join(', ')
+      api_type_name = attribute_map_class.api_type.name
+      "unsupported #{'filter'.pluralize(unsupported_filter_names.size)} #{filter_names_string} for #{api_type_name}."
+    end
+
+    def transform_api_attribute_filters(api_filters)
+      return api_filters if attribute_map_class.nil?
+
+      api_attribute_filters = api_filters.select { |filter_name, _| api_attribute_filter_names.include?(filter_name) }
+      attribute_map_class.model_attribute_keys(api_attribute_filters)
+    end
+
+    def transform_api_custom_filters(api_filters)
+      api_filters.except(*api_attribute_filter_names)
+    end
+
+    def supported_filters
+      @supported_filters ||= filter_factory.filter_classes
+    end
+  end
+end

data/lib/pack_api/models/mapping/model_to_api_attributes_transformer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  ###
+  # Specialized attribute transformer converting an ActiveRecord model attributes to the attribute names needed
+  # to create a ValueObject in the public API.
+  class ModelToAPIAttributesTransformer < AbstractTransformer
+
+    def options=(options)
+      super
+      @optional_attributes_to_include = nil
+      @model_attributes_of_interest = nil
+    end
+
+    def execute
+      api_attribute_names.each_with_object({}) do |api_attribute, result|
+        model_attribute = model_attribute(api_attribute)
+        next unless include_model_attribute?(model_attribute)
+
+        value = unless optional_api_attribute?(api_attribute) && !include_api_attribute?(api_attribute)
+                  api_value(api_attribute, model_value(model_attribute))
+                end
+        result[api_attribute] = value
+      end
+    end
+
+    protected
+
+    def model_attributes_of_interest
+      @model_attributes_of_interest ||= options[:model_attributes_of_interest]
+    end
+
+    def optional_attributes_to_include
+      @optional_attributes_to_include ||= options[:optional_attributes]
+    end
+
+    def optional_api_attribute?(api_attribute_name)
+      api_type_optional_attributes.include?(api_attribute_name)
+    end
+
+    def include_api_attribute?(api_attribute_name)
+      return false if optional_attributes_to_include.nil?
+      return false if optional_attributes_to_include.respond_to?(:exclude?) &&
+                      optional_attributes_to_include.exclude?(api_attribute_name)
+
+      true
+    end
+
+    def include_model_attribute?(model_attribute)
+      return true if model_attributes_of_interest.blank?
+
+      model_attributes_of_interest.include?(model_attribute)
+    end
+
+    def api_type_optional_attributes
+      @api_type_optional_attributes ||= api_type.optional_attributes || []
+    end
+
+    def model_value(model_attribute)
+      data_source.public_send(model_attribute)
+    end
+
+    def api_value(api_attribute, model_value)
+      transform_value(api_attribute, model_value)
+    end
+  end
+end

data/lib/pack_api/models/mapping/normalized_api_attribute.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  class NormalizedAPIAttribute
+    PLURAL_IDS = '_ids'
+    SINGULAR_ID = '_id'
+
+    attr_reader :api_attribute_names
+
+    def initialize(api_attribute_names)
+      @api_attribute_names = api_attribute_names
+    end
+
+    def normalize(attribute_name)
+      if id_for_resource_association?(attribute_name)
+        normalize_resource_association_reference(attribute_name)
+      elsif id_for_collection_association?(attribute_name)
+        normalize_collection_association_reference(attribute_name)
+      else
+        attribute_name
+      end
+    end
+
+    def normalize_collection_association_reference(attribute_name)
+      :"#{attribute_name.to_s.delete_suffix(PLURAL_IDS)}s"
+    end
+
+    def id_for_collection_association?(attribute_name)
+      api_attribute_names.exclude?(attribute_name) && attribute_name.to_s.end_with?(PLURAL_IDS) # && api_attribute_names.include?(it_without_id_suffix)
+    end
+
+    def normalize_resource_association_reference(attribute_name)
+      attribute_name.to_s.delete_suffix(SINGULAR_ID).to_sym
+    end
+
+    def id_for_resource_association?(attribute_name)
+      api_attribute_names.exclude?(attribute_name) && attribute_name.to_s.end_with?(SINGULAR_ID) # && api_attribute_names.include?(it_without_id_suffix)
+    end
+  end
+end

data/lib/pack_api/models/mapping/null_transformer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  class NullTransformer < AbstractTransformer
+    def execute
+      nil
+    end
+  end
+end

data/lib/pack_api/models/mapping/value_object_factory.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  class ValueObjectFactory
+
+    class << self
+      attr_reader :attribute_map_registry, :value_object_attributes
+
+      def set_attribute_map_registry(registry)
+        @attribute_map_registry = registry
+        @value_object_attributes ||= {}
+      end
+
+      def model_attributes_containing_value_objects(*attributes, model_class:)
+        @value_object_attributes ||= {}
+        @value_object_attributes[model_class] = attributes
+      end
+    end
+
+    def create_object(model:, optional_attributes: nil)
+      return nil if model.blank?
+
+      options = attribute_map_options_cache.compute_if_absent(optional_attributes) { { optional_attributes: } }
+      attribute_map = attribute_map(model.class, model, options)
+      attribute_map.api_type.new(attribute_map.attributes)
+
+    rescue Dry::Struct::Error => e
+      model_id = model.respond_to?(:id) ? "(id #{model.id})" : ''
+      raise PackAPI::InternalError, "Unable to convert #{model.class.name} #{model_id} to value object (#{e.message})"
+    end
+
+    def create_collection(models:, optional_attributes: nil)
+      return [] if models.blank?
+
+      models.filter_map { |model| create_object(model:, optional_attributes:) }
+    end
+
+    def create_errors(model:)
+      attribute_map(model.class, model.errors).attributes
+    end
+
+    protected
+
+    def attribute_map(klass, data_source, options = nil)
+      attribute_map_cache.compute_if_absent(klass) { create_attribute_map(klass) }.tap do |map|
+        map.data_source = data_source
+        map.options = options
+      end
+    end
+
+    def convert(value, optional_attributes: nil)
+      value_is_collection?(value) ?
+        create_collection(models: value.to_a, optional_attributes:) :
+        create_object(model: value, optional_attributes:)
+    end
+
+    def value_is_collection?(value)
+      value.is_a?(ActiveRecord::Associations::CollectionProxy) || value.is_a?(Array)
+    end
+
+    def create_attribute_map(model_class)
+      attribute_map_class = self.class.attribute_map_registry.new.attribute_map_class(model_class)
+      convert_proc = method(:convert).to_proc
+      attribute_map_class.new.tap do |attribute_map|
+        self.class.value_object_attributes.fetch(model_class, []).each do |attribute|
+          attribute_map.register_transformation_from_model_attribute(attribute, convert_proc)
+        end
+      end
+    end
+
+    def attribute_map_cache
+      object_cache.compute_if_absent(:attribute_maps) { Concurrent::Map.new }
+    end
+
+    def object_cache
+      @object_cache ||= Concurrent::Map.new
+    end
+
+    def attribute_map_options_cache
+      object_cache.compute_if_absent(:attribute_map_options) { Concurrent::Map.new }
+    end
+  end
+end