deco_lite 0.3.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77c440561731ca11332b76f0ee373e4568d4e84c11930d530d1dde9d5c097eb9
-  data.tar.gz: f771f70f192ae1c2b2d7a935933f7157cde64c6f44e9dc60d50e66d58e8abb05
+  metadata.gz: 00c4b0e5c7169ef19c7f3f43ddc01a13b542f542f6f42d8b84e14e648ea1dea1
+  data.tar.gz: a092f920b44a0c0274e0b39e7a4674f8ebc00ae81893a135dcfde274acf3ccd0
 SHA512:
-  metadata.gz: 6aa192d5c0d1c68860a4e41c31c3997307e90560d293ba6d2e1f5d30a82f537358988cfba766f34415c8321041f3844c2ac88d176a818647f13474f86171c3f6
-  data.tar.gz: e7910463ad7ede8f002af8bc0f46c220bcb715dce09d1690c10b3a3af7db66577acd372a607698470b2fd168a8295d3b24c1fd705601064f02e2f54e0f5ef350
+  metadata.gz: 817c072e966c9ce994c10cc7113f1c6dbbf8653e9ca84af330903fc7f82187f3df4e995516871085a77f9de7c89eac2d0ba2f1a1a67dfbf5f8821406d7652c4e
+  data.tar.gz: 8878462c837f7e6e312ce0d9f6184ee3cab4c4cc564dd2d8aa49d1ac8954129e3d5ae9f0dde89ef9b3faffa4dd817d2e81065397163182c67414ee5266fae118

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+### 1.0.0
+* Breaking changes
+  * Removed `FieldRequireable` and moved this code to the `Model` class because determination of required fields loaded is now determined in the `Model` class, rather than checking the existance of model attributes.
+  * Removed `RequiredFieldsOptionable` since determination of whether or not required fields were loaded no longer depends on the existance of model attributes, this option was removed. `Model#required_fields` model attributes can now be created unconditionally, and still determine whether or not reqired fields were loaded or not.
+  * Since `FieldRequireable` has been removed, along with `#required_fields`, the `Model#required_fields` can now be overridden or manipulated to designate required fields. Required fields will cause validtion to fail if those fields are not loaded into the model like before.
+  * The reason for the aforementioned changes is that the whole paradigm to validate "required fields" (i.e. fields required when loading a Hash) based on model attributes introduced complexity/awkwardness in using the `DecoLite::Model` class, as well as complexity in the `DecoLite` codebase. These changes makes things simpler and cleaner.
+  * Remove deprecated `DecoLite::Model#load`. Use `DecoLite::Model#load!` instead.
+* Changes
+  * Update README.md file accordingly.
+
 ### 0.3.2
 * Changes
   * Refactor FieldAssignable to remove call to FieldCreatable#create_field_accessor as this breaks single responsibility rule; which, in this case, makes sense to remove. FieldCreatable#create_field_accessor can be called wherever creation of a attr_accessor is needed.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    deco_lite (0.3.3)
+    deco_lite (1.0.0)
       activemodel (~> 7.0, >= 7.0.3.1)
       activesupport (~> 7.0, >= 7.0.3.1)
       immutable_struct_ex (~> 0.2.0)
@@ -107,4 +107,4 @@ DEPENDENCIES
   simplecov (~> 0.21.2)
 
 BUNDLED WITH
-   2.2.17
+   2.3.22

data/README.md

@@ -13,11 +13,7 @@
 
 ## Introduction
 
-DecoLite is in development. I wouldn't expect breaking changes before v1.0.0; however, I can't completely rule this out. Currently, DecoLite only supports Hashes whose keys are `Symbols`, contain no embedded spaces, and conform to Ruby `attr_accessor` naming conventions. However, I might try work out a reasonable solution for all this in future releases if the need is there.
-
-TBD: Documentation regarding `DecoLite::Model` options, `DecoLite::Model#load!` options: how these work, and how they play together (e.g. options `fields: :merge` and `fields: :strict` for example; in the meantime, see the specs).
-
-_Deco_ is a little gem that allows you to use the provided `DecoLite::Model` class (`include ActiveModel::Model`) to create Decorator classes which can be instantiated and used. Inherit from `DecoLite::Model` to create your own unique classes with custom functionality. A `DecoLite::Model` includes `ActiveModel::Model`, so validation can be applied using [ActiveModel validation helpers](https://api.rubyonrails.org/v6.1.3/classes/ActiveModel/Validations/HelperMethods.html) you are familiar with; or, you can roll your own - just like any other ActiveModel.
+_Deco_ is a little gem that allows you to use the provided `DecoLite::Model` class (`include ActiveModel::Model`) to dynamically create Decorator class objects. Inherit from `DecoLite::Model` to create your own unique classes with custom functionality. A `DecoLite::Model` includes `ActiveModel::Model`, so validation can be applied using [ActiveModel validation helpers](https://api.rubyonrails.org/v6.1.3/classes/ActiveModel/Validations/HelperMethods.html) you are familiar with; or, you can roll your own - just like any other ActiveModel.
 
 A `DecoLite::Model` will allow you to consume a Ruby Hash that you supply via the initializer (`DecoLite::Model#new`) or via the `DecoLite::Model#load!` method. Your supplied Ruby Hashes are used to create `attr_accessor` attributes (_"fields"_) on the model. Each attribute created, is then assigned its value from the Hash loaded. Any number of hashes can be consumed using the `DecoLite::Model#load!` method.
 
@@ -221,13 +217,11 @@ model.validate
 
 #### Validate whether or not certain fields were loaded
 
-To be clear, this example does not validate the _data_ associated with the fields loaded; rather, this example validates whether or not the _fields themselves_ (`attr_accessors`) were created on your model as a result of loading data into your model. If you only want to validate the _data_ loaded into your model, simply add `ActiveModel` validation, just like you would any other `ActiveModel` model, see the [Add validators to my model](#add-validators-to-my-model) section.
+To be clear, this example does not validate the _data_ associated with the fields loaded; rather, this example validates whether or not the _fields themselves_ were loaded into your model, and as a result, `attr_accessors` created. If you only want to validate the _data_ loaded into your model, simply add `ActiveModel` validation, just like you would any other `ActiveModel` model, see the [Add validators to my model](#add-validators-to-my-model) section.
 
-If you want to validate whether or not particular _fields_ were added to your model as attributes (`attr_accessor`), as a result of `#load!`ing data into your model, you need to do a few things:
+If you want to validate whether or not particular _fields_ were added to your model as attributes (`attr_accessor`), as a result of `#load!`ing data into your model, you need to add the required field names to the `DecoLite::Model#required_fields` attribute, or use inheritance:
   - Create a `DecoLite::Model` subclass.
-  - Override the `DecoLite::Model#required_fields` method to return the field names you want to validate.
-  - Use the `required_fields: nil` option when instantiating your model object.
-  - DO NOT add `ActiveModel` validators that _explicitly_ reference any field returned from `DecoLite::Model#required_fields`; this will cause `attr_accessors` to be created for these fields; consequently, `DecoLite::FieldRequireable#validate_required_fields` will *never* return any errors because these fields will exist as attributes on your model. In other words, do not add (for example) `validates :first, :last, :address, presence: true` to your model if you need to validate whether or not the data you load into your model includs fields `:first`, `:last` and `:address`.
+  - Override the `DecoLite::Model#required_fields` method and return an Array of field names represented by `Symbols` you want to validate.
 
 For example:
 
@@ -238,15 +232,11 @@ class Model < DecoLite::Model
 
   def required_fields
     # We want to ensure these fields were included as Hash keys during loading.
-    %i(first last address)
+    %i[first last address]
   end
 end
-```
 
-Option `required_fields: :auto` is the default which will automatically create `attr_accessors` for any field returned from the `DecoLite::Model#required_fields` method; therefore, we need to set the `:required_fields` option to `nil` (i.e. `required_fields: nil`). This will prohibit `DecoLite::Model` from automatically creating `attr_accessors` for `:first`, `:last` and `:address`, and achieve the results we want:
-
-```ruby
-model = Model.new(options: { required_fields: nil })
+model = Model.new
 
 model.validate
 #=> false
@@ -279,34 +269,19 @@ model.errors.full_messages
 
 If you simply want to validate the _data_ loaded into your model, simply add `ActiveModel` validation, just like you would any other `ActiveModel` model, see the [Add validators to my model](#add-validators-to-my-model) section.
 
-If you want to validate whether or not particular fields were loaded _and_ field data associated with these same fields, you'll have to use custom validation (e.g. override `DecoLite::FieldRequireable#validate_required_fields` and manually add your own validation and errors). This is because `DecoLite::Model#new` will automatically create `attr_accessors` for any attribute (field) that has an _explicit_ `ActiveModel` validation associated with it, and return false positives when you validate your model. In addition to this, you will need to do several other things outlined in the [Validate whether or not certain fields were loaded](#validate-whether-or-not-certain-fields-were-loaded) section.
+If you want to validate whether or not particular fields were loaded _and_ field data associated with these same fields, you simply need to add the required fields and any other validation(s).
 
 For example:
 
 ```ruby
 class Model < DecoLite::Model
-  def required_fields
-    %i(first last address age)
-  end
+  validates :first, :last, :address, :age, presence: true
 
-  def validate_required_fields
-    super
-
-    first = self.try(:first)
-    errors.add(:first, "can't be blank") if first.nil?
-
-    last = self.try(:last)
-    errors.add(:last, "can't be blank") if last.nil?
-
-    address = self.try(:address)
-    errors.add(:address, "can't be blank") if address.nil?
-
-    age = self.try(:age)
-    errors.add(:age, "can't be blank") if age.nil?
-    errors.add(:age, 'is not a number') unless /\d+/ =~ age
+  def required_fields
+    %i[first last address age]
   end
 end
-model = Model.new(options: { required_fields: nil })
+model = Model.new
 
 model.validate
 #=> false
@@ -336,7 +311,7 @@ class JustBecauseYouCanDoesntMeanYouShould < DecoLite::Model
   def initialize(options: {})
     super
 
-    @field_names = %i(existing_field)
+    @field_names = %i[existing_field]
   end
 end
 ```

data/lib/deco_lite/field_conflictable.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'field_name_namespaceable'
-require_relative 'field_requireable'
 require_relative 'fields_optionable'
 
 module DecoLite
@@ -10,7 +9,6 @@ module DecoLite
   module FieldConflictable
     include FieldNameNamespaceable
     include FieldsOptionable
-    include FieldRequireable
 
     def validate_field_conflicts!(field_name:, options:)
       return unless field_conflict?(field_name: field_name, options: options)

data/lib/deco_lite/fields_auto_attr_accessable.rb

@@ -10,14 +10,12 @@ module DecoLite
       auto_attr_accessors.present?
     end
 
-    # This method returns a Hash of fields that are implicitly defined either
-    # through ActiveModel validators or by returning them from the
-    # #required_fields Array.
+    # This method returns a Hash of fields that are implicitly defined
+    # through ActiveModel validators.
     def auto_attr_accessors
       return @auto_attr_accessors.dup if defined?(@auto_attr_accessors)
 
       @auto_attr_accessors = self.class.validators.map(&:attributes)
-      @auto_attr_accessors.concat(required_fields) if options.required_fields_auto?
       @auto_attr_accessors = auto_attr_accessors_assign
     end
 

data/lib/deco_lite/hash_loadable.rb

@@ -21,7 +21,10 @@ module DecoLite
       load_service.execute(hash: hash, options: load_service_options).tap do |service_hash|
         service_hash.each_pair do |field_name, value|
           create_field_accessor field_name: field_name, options: deco_lite_options
-          field_names << field_name unless field_names.include? field_name
+          unless field_names.include? field_name
+            yield field_name if block_given?
+            field_names << field_name
+          end
           set_field_value(field_name: field_name, value: value, options: deco_lite_options)
         end
       end

data/lib/deco_lite/model.rb

@@ -3,7 +3,6 @@
 require 'active_model'
 require_relative 'field_assignable'
 require_relative 'field_names_persistable'
-require_relative 'field_requireable'
 require_relative 'fields_auto_attr_accessable'
 require_relative 'hash_loadable'
 require_relative 'hashable'
@@ -17,14 +16,13 @@ module DecoLite
     include ActiveModel::Model
     include FieldAssignable
     include FieldNamesPersistable
-    include FieldRequireable
     include FieldsAutoloadable
     include HashLoadable
     include Hashable
     include ModelNameable
     include Optionable
 
-    validate :validate_required_fields
+    MISSING_REQUIRED_FIELD_ERROR_TYPE = :missing_required_field
 
     def initialize(hash: {}, options: {})
       # Accept whatever options are sent, but make sure
@@ -36,27 +34,60 @@ module DecoLite
 
       hash ||= {}
 
-      auto_fields = auto_attr_accessors.merge(hash)
-      load!(hash: auto_fields, options: options) if hash.present? || auto_attr_accessors?
+      load_hash!(hash: hash, options: options) if hash.present?
+
+      load_hash!(hash: auto_attr_accessors, options: options, add_loaded_fields: false) if auto_attr_accessors?
+    end
+
+    validate :validate_required_fields
+
+    # Returns field names that will be used to validate whether or not
+    # these fields were loaded from hashes upon construction (#new) or
+    # via #load!.
+    #
+    # You must override this method if you want to return field names that
+    # are required to be present.
+    def required_fields
+      @required_fields ||= %i[]
     end
 
     def load!(hash:, options: {})
+      load_hash! hash: hash, options: options
+    end
+
+    private
+
+    attr_writer :required_fields
+
+    def loaded_fields
+      @loaded_fields ||= []
+    end
+
+    def load_hash!(hash:, options: {}, add_loaded_fields: true)
       # 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, deco_lite_options: options)
+      load_hash(hash: hash, deco_lite_options: options) do |loaded_field|
+        loaded_fields << loaded_field if add_loaded_fields
+      end
 
       self
     end
 
-    def load(hash:, options: {})
-      puts 'WARNING: DecoLite::Model#load will be deprecated in a future release; ' \
-           'use DecoLite::Model#load! instead!'
+    # 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 loaded_fields.include? field_name
 
-      load!(hash: hash, options: options)
+        errors.add(field_name, 'field is missing',
+          type: self.class::MISSING_REQUIRED_FIELD_ERROR_TYPE)
+      end
     end
   end
 end

data/lib/deco_lite/options.rb

@@ -24,10 +24,6 @@ module DecoLite
           def namespace?
             namespace.present? || false
           end
-
-          def required_fields_auto?
-            required_fields == OPTION_REQUIRED_FIELDS_AUTO
-          end
         end
         validate_options! options: immutable_struct_ex.to_h
         immutable_struct_ex

data/lib/deco_lite/options_defaultable.rb

@@ -2,19 +2,16 @@
 
 require_relative 'fields_optionable'
 require_relative 'namespace_optionable'
-require_relative 'required_fields_optionable'
 
 module DecoLite
   # Defines default options and their optionn values.
   module OptionsDefaultable
     include DecoLite::FieldsOptionable
     include DecoLite::NamespaceOptionable
-    include DecoLite::RequiredFieldsOptionable
 
     DEFAULT_OPTIONS = {
       OPTION_FIELDS => OPTION_FIELDS_DEFAULT,
-      OPTION_NAMESPACE => OPTION_NAMESPACE_DEFAULT,
-      OPTION_REQUIRED_FIELDS => OPTION_REQUIRED_FIELDS_DEFAULT
+      OPTION_NAMESPACE => OPTION_NAMESPACE_DEFAULT
     }.freeze
   end
 end

data/lib/deco_lite/options_validatable.rb

@@ -2,16 +2,14 @@
 
 require_relative 'fields_optionable'
 require_relative 'namespace_optionable'
-require_relative 'required_fields_optionable'
 
 module DecoLite
   # Methods to validate options.
   module OptionsValidatable
     include DecoLite::FieldsOptionable
     include DecoLite::NamespaceOptionable
-    include DecoLite::RequiredFieldsOptionable
 
-    OPTIONS = [OPTION_FIELDS, OPTION_NAMESPACE, OPTION_REQUIRED_FIELDS].freeze
+    OPTIONS = [OPTION_FIELDS, OPTION_NAMESPACE].freeze
 
     def validate_options!(options:)
       raise ArgumentError, 'options is not a Hash' unless options.is_a? Hash
@@ -21,7 +19,6 @@ module DecoLite
       validate_option_keys! options: options
       validate_option_fields! fields: options[OPTION_FIELDS]
       validate_option_namespace! namespace: options[OPTION_NAMESPACE]
-      validate_option_required_fields! required_fields: options[OPTION_REQUIRED_FIELDS]
     end
 
     def validate_options_present!(options:)
@@ -48,14 +45,5 @@ module DecoLite
       raise ArgumentError, 'option :namespace value or type is invalid. A Symbol was expected, ' \
                            "but '#{namespace}' (#{namespace.class}) was received."
     end
-
-    def validate_option_required_fields!(required_fields:)
-      # :required_fields is optional.
-      return if required_fields.blank? || OPTION_REQUIRED_FIELDS_VALUES.include?(required_fields)
-
-      raise ArgumentError,
-        "option :fields_required value or type is invalid. #{OPTION_REQUIRED_FIELDS_VALUES} (Symbol) " \
-        "was expected, but '#{required_fields}' (#{required_fields.class}) was received."
-    end
   end
 end

data/lib/deco_lite/version.rb

@@ -2,5 +2,5 @@
 
 # Defines the version of this gem.
 module DecoLite
-  VERSION = '0.3.3'
+  VERSION = '1.0.0'
 end

data/lib/deco_lite.rb

@@ -5,7 +5,6 @@ require_relative 'deco_lite/field_conflictable'
 require_relative 'deco_lite/field_creatable'
 require_relative 'deco_lite/field_name_namespaceable'
 require_relative 'deco_lite/field_names_persistable'
-require_relative 'deco_lite/field_requireable'
 require_relative 'deco_lite/field_retrievable'
 require_relative 'deco_lite/fields_optionable'
 require_relative 'deco_lite/hash_loadable'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deco_lite
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-30 00:00:00.000000000 Z
+date: 2022-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -263,7 +263,6 @@ files:
 - lib/deco_lite/field_creatable.rb
 - lib/deco_lite/field_name_namespaceable.rb
 - lib/deco_lite/field_names_persistable.rb
-- lib/deco_lite/field_requireable.rb
 - lib/deco_lite/field_retrievable.rb
 - lib/deco_lite/field_validatable.rb
 - lib/deco_lite/fields_auto_attr_accessable.rb
@@ -277,7 +276,6 @@ files:
 - lib/deco_lite/options.rb
 - lib/deco_lite/options_defaultable.rb
 - lib/deco_lite/options_validatable.rb
-- lib/deco_lite/required_fields_optionable.rb
 - lib/deco_lite/version.rb
 homepage: https://github.com/gangelo/deco_lite
 licenses:
@@ -298,7 +296,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.3.22
 signing_key:
 specification_version: 4
 summary: Dynamically creates an active model from a Hash.

data/lib/deco_lite/field_requireable.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module DecoLite
-  # Provides methods to manage fields that must be defined from
-  # the dynamically loaded data.
-  module FieldRequireable
-    MISSING_REQUIRED_FIELD_ERROR_TYPE = :missing_required_field
-
-    # 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_ERROR_TYPE)
-      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/required_fields_optionable.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module DecoLite
-  # Defines the fields option hash key and acceptable hash key values.
-  module RequiredFieldsOptionable
-    # The option hash key for this option.
-    OPTION_REQUIRED_FIELDS = :required_fields
-    # The valid option values for this option key.
-    OPTION_REQUIRED_FIELDS_AUTO = :auto
-    # The default value for this option.
-    OPTION_REQUIRED_FIELDS_DEFAULT = OPTION_REQUIRED_FIELDS_AUTO
-    # The valid option key values for this option.
-    OPTION_REQUIRED_FIELDS_VALUES = [OPTION_REQUIRED_FIELDS_AUTO].freeze
-  end
-end