deco_lite 0.3.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f7b315deefbdf848f9d2743d27e672d3916da793f0bd32a705c7d34acac1f9
-  data.tar.gz: b283948784b3fd9b1a4eaef20b7f0ca26a7de9b2971042c04a01021be6195d10
+  metadata.gz: 77c440561731ca11332b76f0ee373e4568d4e84c11930d530d1dde9d5c097eb9
+  data.tar.gz: f771f70f192ae1c2b2d7a935933f7157cde64c6f44e9dc60d50e66d58e8abb05
 SHA512:
-  metadata.gz: 37a1083dfa95d51ab710fff1bab946edcc5b9fa825e37bf7f29c7a0174198d913469c8ac17f82b795949425f7e068236c73ca2ed9df50aba45bdfa3ef7cf1d18
-  data.tar.gz: f3fbb8ab71dad6720dae8dc25179977757d55f7b802c2016ffc673fcdd423b3f86d04a406bd9a4bade6233efb5120cad1d7c2d7176045f44ec78da911311419a
+  metadata.gz: 6aa192d5c0d1c68860a4e41c31c3997307e90560d293ba6d2e1f5d30a82f537358988cfba766f34415c8321041f3844c2ac88d176a818647f13474f86171c3f6
+  data.tar.gz: e7910463ad7ede8f002af8bc0f46c220bcb715dce09d1690c10b3a3af7db66577acd372a607698470b2fd168a8295d3b24c1fd705601064f02e2f54e0f5ef350

data/.gitignore

@@ -16,5 +16,5 @@
 /.vscode/
 *.code-workspace
 
-scratch.rb
+scratch*.rb
 readme.txt

data/.reek.yml

@@ -1,7 +1,7 @@
 exclude_paths:
   - vendor
   - spec
-  - scratch.rb
+  - scratch*.rb
 detectors:
   # TooManyInstanceVariables:
   #  exclude:

data/.rubocop.yml

@@ -13,7 +13,7 @@ AllCops:
     - '*.gemspec'
     - 'spec/**/*'
     - 'vendor/**/*'
-    - 'scratch.rb'
+    - 'scratch*.rb'
 
 # Align the elements of a hash literal if they span more than one line.
 Layout/HashAlignment:

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+### 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.
+  * Refactor specs in keeping with above changes.
+  * README.md changes.
+* Bugs
+  * Fix bug where loading fields with the options: { fields: :strict } option raises an error for field that already exists.
+
+### 0.3.1
+* Changes
+  * Added `DecoLite::FieldRequireable::MISSING_REQUIRED_FIELD_ERROR_TYPE` for required field type errors.
+  * Update README.md with more examples.
+
 ### 0.3.0
 * Changes
   * `DecoLite::Model#new` how accepts a :hash named parameter that will load the Hash as if calling `DecoLite::Model.new.load!(hash: <hash>)`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    deco_lite (0.3.0)
+    deco_lite (0.3.3)
       activemodel (~> 7.0, >= 7.0.3.1)
       activesupport (~> 7.0, >= 7.0.3.1)
       immutable_struct_ex (~> 0.2.0)
@@ -25,7 +25,7 @@ GEM
     docile (1.4.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    immutable_struct_ex (0.2.2)
+    immutable_struct_ex (0.2.3)
     json (2.6.2)
     kwalify (0.7.2)
     mad_flatter (1.0.1.pre.beta)
@@ -63,7 +63,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
     rspec-support (3.11.0)
-    rubocop (1.35.0)
+    rubocop (1.35.1)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.1.2.1)

data/README.md

@@ -13,13 +13,13 @@
 
 ## 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'll certainly work out a solution for all this in future releases.
+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 (in the meantime, see the specs).
+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.
 
-A `DecoLite::Model` will allow you to consume a Ruby Hash that you supply 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.
+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.
 
 `attr_accessor` names created are _mangled_ to include namespacing. This creates unique attribute names for nested Hashes that may include non-unique keys. For example:
 
@@ -34,10 +34,11 @@ family = {
   }
 }
 ```
-Given the above example, DecoLite will produce the following `attr_accessors` on the `DecoLite::Model` object when loaded (`DecoLite::Model#load!`), and assign the values:
+Given the above example, DecoLite will produce the following `attr_accessors` on the `DecoLite::Model` object and assign the values:
 
 ```ruby
-model = DecoLite::Model.new.load!(hash: family)
+# Or DecoLite::Model.new.load!(hash: family)
+model = DecoLite::Model.new(hash: family)
 
 model.name #=> 'John Doe'
 model.respond_to? :name= #=> true
@@ -52,17 +53,21 @@ model.wife_age #=> 30
 model.respond_to? :wife_age= #=> true
 ```
 
-`DecoLite::Model#load!` can be called _multiple times_, on the same model, with different Hashes. This could potentially cause `attr_accessor` name clashes. In order to ensure unique `attr_accessor` names, a _"namespace"_ may be _explicitly_ provided to ensure uniqueness. For example, continuing from the previous example; if we were to call `DecoLite::Model#load!` a _second time_ with the following Hash, it would produce `attr_accessor` name clashes:
+`DecoLite::Model#load!` can be called _multiple times_, on the same model, with different Hashes. This could potentially cause `attr_accessor` name clashes. In order to ensure unique `attr_accessor` names, a _"namespace"_ may be _explicitly_ provided to ensure uniqueness.
+
+For example, **continuing from the previous example;** if we were to call `DecoLite::Model#load!` a _second time_ with the following Hash, this would potentially produce `attr_accessor` name clashes:
 
 ```ruby
 grandpa = {
   name: 'Henry Doe',
   age: 85,
 }
-# The :name and :age Hash keys above will produce :name/:name= and :age/:age= attr_accessors and clash because these were already added to the model when "John Doe" was loaded with the first call to DecoLite::Model#load!.
+# The :name and :age Hash keys above will produce :name/:name= and :age/:age= attr_accessors
+# and clash because these were already added to the model when "John Doe" was loaded with
+# the first call to DecoLite::Model.new(hash: family).
 ```
 
-However, passing a `namespace:` option (for example `namespace: :grandpa`) to the `DecoLite::Model#load!` method, would produce the following `attr_accessors`, ensuring their uniqueness:
+However, passing a `:namespace` option (for example `namespace: :grandpa`) to the `DecoLite::Model#load!` method, would produce the following `attr_accessors`, ensuring their uniqueness:
 
 ```ruby
 model.load!(hash: grandpa, options: { namespace: :grandpa })
@@ -87,6 +92,11 @@ model.respond_to? :wife_name= #=> true
 model.wife_age #=> 30
 model.respond_to? :wife_age= #=> true
 ```
+
+### For more examples and usage
+
+For more examples and usage, see the [Examples and usage](#examples-and-usage) and [Mode examples and usage](#more-examples-and-usage) sections; there is also an "I want to..." section with examples you might encounter when using `DecoLite`.
+
 ## Use cases
 
 ### General
@@ -108,9 +118,7 @@ class ViewModel < DecoLite::Model
   end
 end
 
-view_model = ViewModel.new
-
-view_model.load!(hash: { first: 'John', last: 'Doe' })
+view_model = ViewModel.new(hash: { first: 'John', last: 'Doe' })
 
 view_model.valid?
 #=> true
@@ -188,22 +196,131 @@ model.wife_info_address     #=> 1 street, boonton, nj 07005
 
 #### Add validators to my model
 
-Simply add your `ActiveModel` validators just like you would any other `ActiveModel::Model` validator. However, be aware that (currently), any attribute (field) being validated that does not exist on the model, will raise a `NoMethodError` error:
+Simply add your `ActiveModel` validators just like you would any other `ActiveModel::Model` validator. However, be aware that (currently), any attribute (field) having an _explicit validation_ associated with it, will automatically cause an `attr_accessor` to be created for that field; this is to avoid `NoMethodErrors` when calling a validation method on the model (e.g. `#valid?`, `#validate`, etc.) *before* the data is loaded to create the associated `attr_accessors`:
 
 ```ruby
 class Model < DecoLite::Model
   validates :first, :last, :address, presence: true
+  validates :age, numericality: true
 end
 
-model = Model.new(hash: { first: 'John', last: 'Doe' })
+# No :address
+model = Model.new(hash: { first: 'John', last: 'Doe', age: 25 })
+model.respond_to? :address
+#=> true
+
+model.valid?
+#=> false
+model.errors.full_messages
+#=> ["Address can't be blank"]
 
-# No :address; a NoMethodError error for :address will be raised.
+model.load!(hash: { address: '123 park road, anytown, nj 01234' })
 model.validate
-#=> undefined method 'address' for #<Model:0x00007f95931568c0 ... @field_names=[:first, :last], @first="John", @last="Doe", ...> (NoMethodError)
+#=> true
+```
 
-model.load!(hash: { address: '123 park road, anytown, nj 01234' })
+#### 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.
+
+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:
+  - 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`.
+
+For example:
+
+```ruby
+class Model < DecoLite::Model
+  # :age field is optional and it's value is optional.
+  validates :age, numericality: { only_integer: true }, allow_blank: true
+
+  def required_fields
+    # We want to ensure these fields were included as Hash keys during loading.
+    %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.validate
+#=> false
+model.errors.full_messages
+#=> ["First field is missing", "Last field is missing", "Address field is missing"]
+
+# If we load data that includes :first, :last, and :address Hash keys even with
+# nil data, our ":<field> field is missing" errors go away; in this scenario,
+# we're validating the presence of the FIELDS, not the data associated with
+# these fields!
+model.load!(hash: { first: nil, last: nil, address: nil })
 model.validate
 #=> true
+model.errors.full_messages
+#=> []
+
+user = {
+  first: 'John',
+  last: 'Doe',
+  address: '123 anystreet, anytown, nj 01234',
+  age: 'x'
+}
+model.load!(hash: user)
+model.validate
+#=> false
+model.errors.full_messages
+#=> ["Age is not a number"]
+```
+#### Validate whether or not certain fields were loaded _and_ validate the data associated with these same fields
+
+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.
+
+For example:
+
+```ruby
+class Model < DecoLite::Model
+  def required_fields
+    %i(first last address age)
+  end
+
+  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
+  end
+end
+model = Model.new(options: { required_fields: nil })
+
+model.validate
+#=> false
+
+model.errors.full_messages
+#=> ["First field is missing",
+ "Last field is missing",
+ "Address field is missing",
+ "Age field is missing",
+ "First can't be blank",
+ "Last can't be blank",
+ "Address can't be blank",
+ "Age can't be blank",
+ "Age is not a number"]
 ```
 
 #### Manually define attributes (fields) on my model
@@ -224,19 +341,21 @@ class JustBecauseYouCanDoesntMeanYouShould < DecoLite::Model
 end
 ```
 
-However, the above is unnecessary as this can be easily accomplished using `DecoLite::Model#load!`:
+However, the above is unnecessary as this can be easily accomplished by passing a `Hash` to the initializer or by using `DecoLite::Model#load!`:
+
 ```ruby
-model = Class.new(DecoLite::Model).new.load!(hash:{ existing_field: :existing_field_value })
+model = Class.new(DecoLite::Model).new(hash:{ existing_field: :value })
 
 model.field_names
 #=> [:existing_field]
 
 model.existing_field
-#=> :existing_field_value
+#=> :value
 
 model.respond_to? :existing_field=
 #=> true
 ```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/deco_lite/field_assignable.rb

@@ -1,12 +1,10 @@
 # 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:)
@@ -16,10 +14,10 @@ module DecoLite
       end
     end
 
+    # rubocop:disable Lint/UnusedMethodArgument
     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
+    # rubocop:enable Lint/UnusedMethodArgument
   end
 end

data/lib/deco_lite/field_conflictable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'field_name_namespaceable'
+require_relative 'field_requireable'
 require_relative 'fields_optionable'
 
 module DecoLite
@@ -9,6 +10,7 @@ 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/field_requireable.rb

@@ -4,6 +4,8 @@ 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.
     #
@@ -23,7 +25,7 @@ module DecoLite
       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)
+        errors.add(field_name, 'field is missing', type: MISSING_REQUIRED_FIELD_ERROR_TYPE)
       end
     end
 

data/lib/deco_lite/hash_loadable.rb

@@ -2,11 +2,13 @@
 
 require 'mad_flatter'
 require_relative 'field_assignable'
+require_relative 'field_creatable'
 
 module DecoLite
   # Provides methods to load and return information about a given hash.
   module HashLoadable
     include FieldAssignable
+    include FieldCreatable
 
     private
 

data/lib/deco_lite/hashable.rb

@@ -5,7 +5,11 @@ module DecoLite
   module Hashable
     def to_h
       field_names.each_with_object({}) do |field_name, hash|
-        hash[field_name] = public_send field_name
+        field_value = public_send(field_name)
+
+        field_name, field_value = yield [field_name, field_value] if block_given?
+
+        hash[field_name] = field_value
       end
     end
   end

data/lib/deco_lite/model.rb

@@ -47,7 +47,6 @@ module DecoLite
       # 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)
 
       self

data/lib/deco_lite/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deco_lite
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.3
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-26 00:00:00.000000000 Z
+date: 2022-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel