deco_lite 0.1.0

data/deco_lite.gemspec

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'deco_lite/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'deco_lite'
+  spec.version       = DecoLite::VERSION
+  spec.authors       = ['Gene M. Angelo, Jr.']
+  spec.email         = ['public.gma@gmail.com']
+
+  spec.summary       = 'Dynamically creates an active model from a Hash.'
+  spec.description   = 'Dynamically creates an active model from a Hash.'
+  spec.homepage      = 'https://github.com/gangelo/deco_lite'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against ' \
+  #     'public gem pushes.'
+  # end
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '~> 3.0.1'
+
+  spec.add_runtime_dependency 'activemodel', '~> 7.0', '>= 7.0.3.1'
+  spec.add_runtime_dependency 'activesupport', '~> 7.0', '>= 7.0.3.1'
+  spec.add_runtime_dependency 'immutable_struct_ex', '~> 0.2.0'
+  # spec.add_development_dependency 'benchmark-ips', '~> 2.3'
+  spec.add_development_dependency 'bundler', '~> 2.2', '>= 2.2.17'
+  # spec.add_development_dependency 'factory_bot', '~> 6.2'
+  spec.add_development_dependency 'pry-byebug', '~> 3.9'
+  # #spec.add_development_dependency 'rake', '~> 0'
+  # #spec.add_development_dependency 'redcarpet', '~> 3.5', '>= 3.5.1'
+  spec.add_development_dependency 'reek', '~> 6.0', '>= 6.0.4'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  # This verson of rubocop is returning errors.
+  # spec.add_development_dependency 'rubocop', '~> 1.14'
+  spec.add_development_dependency 'rubocop', '~> 1.9.1'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.11', '>= 1.11.3'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.3'
+  spec.add_development_dependency 'simplecov', '~> 0.21.2'
+
+  # spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency 'rake', '~> 10.0'
+  # spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/deco_lite/field_assignable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'field_creatable'
+require_relative 'field_retrievable'
+
+module DecoLite
+  # Defines methods to assign model field values dynamically.
+  module FieldAssignable
+    include FieldCreatable
+    include FieldRetrievable
+
+    def set_field_values(hash:, field_info:, options:)
+      field_info.each do |name, info|
+        value = get_field_value(hash: hash, field_info: info)
+        set_field_value(field_name: name, value: value, options: options)
+      end
+    end
+
+    def set_field_value(field_name:, value:, options:)
+      # Create our fields before we send.
+      create_field_accessor field_name: field_name, options: options
+      send("#{field_name}=", value)
+    end
+  end
+end

data/lib/deco_lite/field_conflictable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'fields_optionable'
+
+module DecoLite
+  # Defines methods to to manage fields that conflict with
+  # existing model attributes.
+  module FieldConflictable
+    include FieldsOptionable
+
+    def validate_field_conflicts!(field_name:, options:)
+      return unless options.strict? && field_conflict?(field_name: field_name)
+
+      raise "Field '#{field_name}' conflicts with existing attribute; " \
+        'this will raise an error when running in strict mode: ' \
+        "options: { #{OPTION_FIELDS}: :#{OPTION_FIELDS_STRICT} }."
+    end
+
+    def field_conflict?(field_name:)
+      respond_to? field_name
+    end
+  end
+end

data/lib/deco_lite/field_creatable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'field_conflictable'
+
+module DecoLite
+  # Takes an array of symbols and creates attr_accessors.
+  module FieldCreatable
+    include FieldConflictable
+
+    def create_field_accessors(field_names:, options:)
+      return if field_names.blank?
+
+      field_names.each do |field_name|
+        create_field_accessor(field_name: field_name, options: options)
+      end
+    end
+
+    def create_field_accessor(field_name:, options:)
+      validate_field_conflicts!(field_name: field_name, options: options)
+
+      self.class.attr_accessor(field_name) if field_name.present?
+    end
+  end
+end

data/lib/deco_lite/field_informable.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Creates and returns a hash given the parameters that are used to
+  # dynamically create fields and assign values to a model.
+  module FieldInformable
+    # This method simply navigates the payload hash received and creates qualified
+    # hash key names that can be used to verify/map to our field names in this model.
+    # This can be used to qualify nested hash fields and saves us some headaches
+    # if there are nested field names with the same name:
+    #
+    # given:
+    #
+    # hash = {
+    #   first_name: 'first_name',
+    #   ...
+    #   address: {
+    #     street: '',
+    #     ...
+    #   }
+    # }
+    #
+    # get_field_info(hash: hash) #=>
+    #
+    # {
+    #   :first_name=>{:field_name=>:first_name, :dig=>[]},
+    #   ...
+    #   :address_street=>{:field_name=>:street, :dig=>[:address]},
+    #   ...
+    # }
+    #
+    # The generated, qualified field names expected to map to our model, because we named
+    # them as such.
+    #
+    # :field_name is the actual, unqualified field name found in the payload hash sent.
+    # :dig is the hash key by which :field_name can be found in the payload hash if need be -
+    #   retained across recursive calls.
+    def get_field_info(hash:, namespace: nil, dig: [], field_info: {})
+      hash.each do |key, value|
+        if value.is_a? Hash
+          get_field_info hash: value,
+                         namespace: namespace,
+                         dig: dig << key,
+                         field_info: field_info
+          dig.pop
+        else
+          set_field_info!(field_info: field_info,
+                          key: key,
+                          namespace: namespace,
+                          dig: dig)
+        end
+      end
+
+      field_info
+    end
+
+    def set_field_info!(field_info:, key:, namespace:, dig:)
+      field_key = [namespace, *dig, key].compact.join('_').to_sym
+      field_info[field_key] = {
+        field_name: key,
+        dig: dig.dup
+      }
+    end
+
+    def merge_field_info!(field_info:)
+      @field_info.merge!(field_info)
+    end
+
+    def field_names
+      field_info&.keys || []
+    end
+
+    attr_reader :field_info
+
+    private
+
+    attr_writer :field_info
+
+    module_function :get_field_info, :set_field_info!, :merge_field_info!
+  end
+end

data/lib/deco_lite/field_requireable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Provides methods to manage fields that must be defined from
+  # the dynamically loaded data.
+  module FieldRequireable
+    # Returns field names that will be used to validate the presence of
+    # dynamically created fields from loaded objects.
+    #
+    # You must override this method if you want to return field names that
+    # are required to be present. You may simply return a static array, but
+    # if you want to dynamically manipulate this field, return a variable.
+    def required_fields
+      # @required_fields ||= []
+      []
+    end
+
+    # Validator for field names. This validator simply checks to make
+    # sure that the field was created, which can only occur if:
+    # A) The field was defined on the model explicitly (e.g. attr_accessor :field).
+    # B) The field was created as a result of loading data dynamically.
+    def validate_required_fields
+      required_fields.each do |field_name|
+        next if required_field_exist? field_name: field_name
+
+        errors.add(field_name, 'field is missing', type: :missing_required_field)
+      end
+    end
+
+    # :reek:ManualDispatch - method added dynamically; this is the best way to check.
+    def required_field_exist?(field_name:)
+      respond_to?(field_name) && respond_to?("#{field_name}=".to_sym)
+    end
+  end
+end

data/lib/deco_lite/field_retrievable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Defines methods to retrieve model field values dynamically.
+  module FieldRetrievable
+    module_function
+
+    # Returns the value of the field using fully quaified field names.
+    def get_field_value(hash:, field_info:)
+      hash.dig(*[field_info[:dig], field_info[:field_name]].flatten.compact)
+    end
+  end
+end

data/lib/deco_lite/fields_optionable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Defines the fields option hash key and acceptable hash key values.
+  module FieldsOptionable
+    # The option hash key for this option.
+    OPTION_FIELDS = :fields
+    # The valid option values for this option key.
+    OPTION_FIELDS_MERGE = :merge
+    OPTION_FIELDS_STRICT = :strict
+    # The default value for this option.
+    OPTION_FIELDS_DEFAULT = OPTION_FIELDS_MERGE
+    # The valid option key values for this option.
+    OPTION_FIELDS_VALUES = [OPTION_FIELDS_MERGE, OPTION_FIELDS_STRICT].freeze
+  end
+end

data/lib/deco_lite/hash_loadable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'field_assignable'
+require_relative 'field_informable'
+
+module DecoLite
+  # Provides methods to load and return information about a given hash.
+  module HashLoadable
+    include FieldAssignable
+    include FieldInformable
+
+    private
+
+    def load_hash(hash:, options:)
+      raise ArgumentError, "Argument hash is not a Hash (#{hash.class})" unless hash.is_a? Hash
+
+      return if hash.blank?
+
+      field_info = get_field_info(hash: hash, namespace: options.namespace)
+      set_field_values(hash: hash, field_info: field_info, options: options)
+      merge_field_info! field_info: field_info
+    end
+  end
+end

data/lib/deco_lite/model.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require_relative 'field_requireable'
+require_relative 'hash_loadable'
+require_relative 'model_nameable'
+require_relative 'optionable'
+
+module DecoLite
+  # This class defines the base class for classes that create
+  # dynamic models that can be used as decorators.
+  class Model
+    include ActiveModel::Model
+    include FieldRequireable
+    include HashLoadable
+    include ModelNameable
+    include Optionable
+
+    validate :validate_required_fields
+
+    def initialize(options: {})
+      @field_info = {}
+      # Accept whatever options are sent, but make sure
+      # we have defaults set up. #options_with_defaults
+      # will merge options into OptionsDefaultable::DEFAULT_OPTIONS
+      # so we have defaults for any options not passed in through
+      # options.
+      self.options = Options.with_defaults options
+    end
+
+    def load(hash:, options: {})
+      # Merge options into the default options passed through the
+      # constructor; these will override any options passed in when
+      # this object was created, allowing us to retain any defaut
+      # options while loading, but also provide option customization
+      # of options when needed.
+      options = Options.with_defaults(options, defaults: self.options)
+      load_hash(hash: hash, options: options)
+
+      self
+    end
+  end
+end

data/lib/deco_lite/model_nameable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Provides class methods to return an appropriate model name.
+  module ModelNameable
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    # Class methods to extend.
+    module ClassMethods
+      def model_name
+        ActiveModel::Name.new(self, nil, to_s.gsub('::', ''))
+      end
+    end
+  end
+end

data/lib/deco_lite/namespace_optionable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Defines the namespace option hash key
+  module NamespaceOptionable
+    # The option hash key for this option.
+    OPTION_NAMESPACE = :namespace
+    # The default value for this option - no namespace.
+    OPTION_NAMESPACE_DEFAULT = nil
+  end
+end

data/lib/deco_lite/optionable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'immutable_struct_ex'
+require_relative 'options'
+require_relative 'options_validatable'
+
+module DecoLite
+  # Defines methods and fields to manage options.
+  module Optionable
+    include OptionsValidatable
+
+    def options
+      @options || Options.default
+    end
+
+    private
+
+    def options=(value)
+      options_hash = value.to_h
+
+      validate_options! options: options_hash
+
+      @options = Options.new(**options_hash)
+    end
+  end
+end

data/lib/deco_lite/options.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'immutable_struct_ex'
+require_relative 'options_defaultable'
+require_relative 'options_validatable'
+
+module DecoLite
+  # Defines methods to create options.
+  module Options
+    extend DecoLite::OptionsDefaultable
+    extend DecoLite::OptionsValidatable
+
+    class << self
+      def new(**options)
+        immutable_struct_ex = ImmutableStructEx.new(**options) do
+          def merge?
+            fields == OPTION_FIELDS_MERGE
+          end
+
+          def strict?
+            fields == OPTION_FIELDS_STRICT
+          end
+
+          def namespace?
+            namespace || false
+          end
+        end
+        validate_options! options: immutable_struct_ex.to_h
+        immutable_struct_ex
+      end
+
+      def with_defaults(options, defaults: DEFAULT_OPTIONS)
+        new(**defaults.to_h.merge(options.to_h))
+      end
+
+      def default
+        with_defaults({})
+      end
+    end
+  end
+end

data/lib/deco_lite/options_defaultable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'fields_optionable'
+require_relative 'namespace_optionable'
+
+module DecoLite
+  # Defines default options and their optionn values.
+  module OptionsDefaultable
+    include DecoLite::FieldsOptionable
+    include DecoLite::NamespaceOptionable
+
+    DEFAULT_OPTIONS = {
+      OPTION_FIELDS => OPTION_FIELDS_DEFAULT,
+      OPTION_NAMESPACE => OPTION_NAMESPACE_DEFAULT
+    }.freeze
+  end
+end

data/lib/deco_lite/options_validatable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'fields_optionable'
+require_relative 'namespace_optionable'
+
+module DecoLite
+  # Methods to validate options.
+  module OptionsValidatable
+    include DecoLite::FieldsOptionable
+    include DecoLite::NamespaceOptionable
+
+    OPTIONS = [OPTION_FIELDS, OPTION_NAMESPACE].freeze
+
+    def validate_options!(options:)
+      raise ArgumentError, 'options is not a Hash' unless options.is_a? Hash
+
+      validate_options_present! options: options
+
+      validate_option_keys! options: options
+      validate_option_fields! fields: options[:fields]
+      validate_option_namespace! namespace: options[:namespace]
+    end
+
+    def validate_options_present!(options:)
+      raise ArgumentError, 'options is blank?' if options.blank?
+    end
+
+    def validate_option_keys!(options:)
+      invalid_options = options.except(*OPTIONS)&.keys
+      raise ArgumentError, "One or more option keys were unrecognized: #{invalid_options}" unless invalid_options.blank?
+    end
+
+    def validate_option_fields!(fields:)
+      return if OPTION_FIELDS_VALUES.include?(fields)
+
+      raise ArgumentError,
+        "option :fields value or type is invalid. #{OPTION_FIELDS_VALUES} (Symbol) " \
+          "was expected, but '#{fields}' (#{fields.class}) was received."
+    end
+
+    def validate_option_namespace!(namespace:)
+      # :namespace is optional.
+      return if namespace.blank? || namespace.is_a?(Symbol)
+
+      raise ArgumentError, 'option :namespace value or type is invalid. A Symbol was expected, ' \
+        "but '#{namespace}' (#{namespace.class}) was received."
+    end
+  end
+end

data/lib/deco_lite/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Defines the version of this gem.
+module DecoLite
+  VERSION = '0.1.0'
+end

data/lib/deco_lite.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir[File.join('.', 'lib/deco_lite/**/*.rb')].each do |f|
+  require f
+end