deco_lite 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74286df21784817e45f4d615081bfeac44d90f13d8200bc8f066107e8d0f773f
-  data.tar.gz: 57dcc52147494eb3caf59159cbb21bc23bb6788d0b6315ebc1ddd8cf1868c779
+  metadata.gz: 40f7b315deefbdf848f9d2743d27e672d3916da793f0bd32a705c7d34acac1f9
+  data.tar.gz: b283948784b3fd9b1a4eaef20b7f0ca26a7de9b2971042c04a01021be6195d10
 SHA512:
-  metadata.gz: b79af6a65df899227821e4a02bf17587f1f423042a4280a54525c8469c1c3344f3dd2c3b16bd0de477c711d27ed04527295ca37e811c1c829037379509971ac6
-  data.tar.gz: 7d1b5dea80d0af672713d18675166207e2d62ab51aff84045411d02344529a32de513df76d394e3769dfb14a69d0742f18e850398dc9b4cc6bac10eb5c72ecec
+  metadata.gz: 37a1083dfa95d51ab710fff1bab946edcc5b9fa825e37bf7f29c7a0174198d913469c8ac17f82b795949425f7e068236c73ca2ed9df50aba45bdfa3ef7cf1d18
+  data.tar.gz: f3fbb8ab71dad6720dae8dc25179977757d55f7b802c2016ffc673fcdd423b3f86d04a406bd9a4bade6233efb5120cad1d7c2d7176045f44ec78da911311419a

data/.reek.yml

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

data/.rubocop.yml

@@ -116,7 +116,7 @@ Layout/LineLength:
 # Avoid methods longer than 15 lines of code.
 Metrics/MethodLength:
   Max: 20
-  IgnoredMethods:
+  AllowedMethods:
     - swagger_path
     - operation
 

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+### 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>)`.
+  * `DecoLite::Model#new now creates attr_accessors (fields) for any attribute that has an ActiveModel validator associated with it. This prevents errors raised when #validate is called before data is #load!ed.
+  * `DecoLite::Model#new` now creates attr_accessors (fields) for any field returned from `DecoLite::Model#reqired_fields` IF the required_fields: :auto option is set.
+  * bin/console now starts a pry-byebug session.
+
 ### 0.2.5
 * Changes
   * Remove init of `@field_names = []` in `Model#initialize` as unnecessary - FieldNamesPersistable takes care of this.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    deco_lite (0.2.5)
+    deco_lite (0.3.0)
       activemodel (~> 7.0, >= 7.0.3.1)
       activesupport (~> 7.0, >= 7.0.3.1)
       immutable_struct_ex (~> 0.2.0)

data/README.md

@@ -15,17 +15,17 @@
 
 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.
 
-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 (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 `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.
 
 `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:
 
 ```ruby
 # NOTE: keys :name and :age are not unique across this Hash.
-{
+family = {
   name: 'John Doe',
   age: 35,
   wife: {
@@ -34,37 +34,66 @@ A `DecoLite::Model` will allow you to consume a Ruby Hash that you supply via th
   }
 }
 ```
-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 when loaded (`DecoLite::Model#load!`), and assign the values:
 
 ```ruby
-name=, name #=> 'John Doe'
-age=, age #=> 35
-wife_name=, wife_name #=> 'Mary Doe'
-wife_age=, wife_age #=> 30
+model = DecoLite::Model.new.load!(hash: family)
+
+model.name #=> 'John Doe'
+model.respond_to? :name= #=> true
+
+model.age #=> 35
+model.respond_to? :age= #=> true
+
+model.wife_name #=> 'Mary Doe'
+model.respond_to? :wife_name= #=> true
+
+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, it would 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!.
 ```
 
-However, passing a `namespace: :grandpa` option to the `DecoLite::Model#load` method, would produce the following `attr_accessors`, ensuring uniquess:
+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
-# Unique now that the namespace "grandpa" has been applied.
-grandpa_name=, grandpa_name #=> 'Henry Doe'
-grandpa_age=, grandpa_age #=> 85
+model.load!(hash: grandpa, options: { namespace: :grandpa })
+
+# Unique now that the namespace: :grandpa has been applied:
+model.grandpa_name #=> 'Henry Doe'
+model.respond_to? :grandpa_name= #=> true
+
+model.grandpa_age #=> 85
+model.respond_to? :grandpa_age= #=> true
+
+# All the other attributes on the model remain the same, and unique:
+model.name #=> 'John Doe'
+model.respond_to? :name= #=> true
+
+model.age #=> 35
+model.respond_to? :age= #=> true
+
+model.wife_name #=> 'Mary Doe'
+model.respond_to? :wife_name= #=> true
+
+model.wife_age #=> 30
+model.respond_to? :wife_age= #=> true
 ```
-## Use Cases
+## Use cases
 
 ### General
-_Deco_ would _most likely_ thrive where the structure of the Hashe(s) consumed by the `DecoLite::Model#load` method is known. This is because of the way _Deco_ mangles loaded Hash key names to create unique `attr_accessor` names (see the Introduction section) although, I'm sure there are some metaprogramming geniuses out there that might prove me wrong. Assuming this is the case, _Deco_ would be ideal to handle Model attributes, Webservice JSON results (converted to Ruby Hash), JSON Web Token (JWT) payload, etc..
+_Deco_ would _most likely_ thrive where the structure of the Hashe(s) consumed by the `DecoLite::Model#load!` method is known. This is because of the way _Deco_ mangles loaded Hash key names to create unique `attr_accessor` names (see the Introduction section); although, I'm sure there are some metaprogramming geniuses out there that might prove me wrong. Assuming this is the case, _Deco_ would be ideal to handle Model attributes, Webservice JSON results (converted to Ruby Hash), JSON Web Token (JWT) payload, etc..
 
 ### Rails
-Because `DecoLite::Model` includes `ActiveModel::Model`, it could also be ideal for use as a model in Rails applications, where a _decorator pattern_ can be used, and methods provided for use in Rails views; for example:
+Because `DecoLite::Model` includes `ActiveModel::Model`, it could also be ideal for use as a model in Rails applications, where a _decorator pattern_ might be used, and decorator methods provided for use in Rails views; for example:
 
 ```ruby
 class ViewModel < DecoLite::Model
@@ -81,7 +110,7 @@ end
 
 view_model = ViewModel.new
 
-view_model.load(hash: { first: 'John', last: 'Doe' })
+view_model.load!(hash: { first: 'John', last: 'Doe' })
 
 view_model.valid?
 #=> true
@@ -96,23 +125,7 @@ view_model.salutation
 
 Get creative. Please pop me an email and let me know how _you're_ using _Deco_.
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'deco_lite'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install deco_lite
-
-## Examples and Usage
+## Examples and usage
 
 ```ruby
 require 'deco_lite'
@@ -154,8 +167,8 @@ end
 
 couple = Couple.new
 
-couple.load(hash: husband, options: { namespace: :husband })
-couple.load(hash: wife, options: { namespace: :wife })
+couple.load!(hash: husband, options: { namespace: :husband })
+couple.load!(hash: wife, options: { namespace: :wife })
 
 # Will produce the following:
 model.live_together?        #=> true
@@ -169,17 +182,35 @@ model.wife_name             #=> Amy Doe
 model.wife_info_age         #=> 20
 model.wife_info_address     #=> 1 street, boonton, nj 07005
 ```
+## More examples and usage
+
+### I want to...
+
+#### 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:
+
+```ruby
+class Model < DecoLite::Model
+  validates :first, :last, :address, presence: true
+end
+
+model = Model.new(hash: { first: 'John', last: 'Doe' })
+
+# No :address; a NoMethodError error for :address will be raised.
+model.validate
+#=> undefined method 'address' for #<Model:0x00007f95931568c0 ... @field_names=[:first, :last], @first="John", @last="Doe", ...> (NoMethodError)
+
+model.load!(hash: { address: '123 park road, anytown, nj 01234' })
+model.validate
+#=> true
+```
 
-### Manually Defining Attributes
+#### Manually define attributes (fields) on my model
 
-Manually defining attributes on your subclass is possible; however, you
-must add your attr_reader name to the `DecoLite::Model@field_names` array, or an error will be reaised _if_ there are any conflicting field names being loaded
-using `DecoLite::Model#load!`, regardless of setting the `{ fields: :merge }`
-option. This is because DecoLite assumes any existing attributes not added to
-the model via `load!`to be native to the object created, and therefore will not
-allow you to create attr_accessors for existing attributes, as this can potentially be dangerous.
+Manually defining attributes on your subclass is possible, although there doesn't seem a valid reason to do so, since you can just use `DecoLite::Model#load!` to wire all this up for you automatically. However, if there _were_ a need to do this, you must add your `attr_reader` to the `DecoLite::Model@field_names` array, or an error will be raised _provided_ there are any conflicting field names being loaded using `DecoLite::Model#load!`. Note that the aforementioned error will be raised regardless of whether or not you set `options: { fields: :merge }`. This is because DecoLite considers any existing model attributes _not_ added to the model via `load!`to be native to the model object, and therefore will not allow you to create attr_accessors for existing model attributes because this can potentially be dangerous.
 
-To avoid errors when manually defining attributes on the model that could potentially be in conflict with fields loaded using `DecoLite::Model#load!`, do the following:
+To avoid errors when manually defining model attributes that could potentially conflict with fields loaded using `DecoLite::Model#load!`, do the following:
 
 ```ruby
 class JustBecauseYouCanDoesntMeanYouShould < DecoLite::Model
@@ -193,6 +224,35 @@ class JustBecauseYouCanDoesntMeanYouShould < DecoLite::Model
 end
 ```
 
+However, the above is unnecessary as this can be easily accomplished using `DecoLite::Model#load!`:
+```ruby
+model = Class.new(DecoLite::Model).new.load!(hash:{ existing_field: :existing_field_value })
+
+model.field_names
+#=> [:existing_field]
+
+model.existing_field
+#=> :existing_field_value
+
+model.respond_to? :existing_field=
+#=> true
+```
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'deco_lite'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install deco_lite
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/console

@@ -10,6 +10,5 @@ require 'deco_lite'
 # (If you use this, don't forget to add pry to your Gemfile!)
 # require "pry"
 # Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
+require 'pry-byebug'
+Pry.start

data/lib/deco_lite/field_conflictable.rb

@@ -19,7 +19,8 @@ module DecoLite
             ":#{field_name} and/or :#{field_name}=; " \
             'this will raise an error when loading using strict mode ' \
             "(i.e. options: { #{OPTION_FIELDS}: :#{OPTION_FIELDS_STRICT} }) " \
-            'or if the method(s) are native to the object (e.g :to_s, :==, etc.).'
+            'or if the method(s) are native to the object (e.g :to_s, :==, etc.). ' \
+            "Current options are: options: #{options.to_h}."
     end
 
     # This method returns true

data/lib/deco_lite/fields_auto_attr_accessable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DecoLite
+  # Defines fields that may have attr_accessors automatically created for them
+  # on the model.
+  module FieldsAutoloadable
+    private
+
+    def auto_attr_accessors?
+      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.
+    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
+
+    def auto_attr_accessors_assign
+      @auto_attr_accessors.flatten.uniq.each_with_object({}) do |field_name, auto_attr_accessors_hash|
+        auto_attr_accessors_hash[field_name] = nil
+      end
+    end
+  end
+end

data/lib/deco_lite/hash_loadable.rb

@@ -16,8 +16,8 @@ module DecoLite
       return {} if hash.blank?
 
       load_service_options = merge_with_load_service_options deco_lite_options: deco_lite_options
-      load_service.execute(hash: hash, options: load_service_options).tap do |h|
-        h.each_pair do |field_name, value|
+      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
           set_field_value(field_name: field_name, value: value, options: deco_lite_options)

data/lib/deco_lite/hashable.rb

@@ -4,7 +4,7 @@ module DecoLite
   # Provides methods to convert the object to a Hash.
   module Hashable
     def to_h
-      field_names.each.each_with_object({}) do |field_name, hash|
+      field_names.each_with_object({}) do |field_name, hash|
         hash[field_name] = public_send field_name
       end
     end

data/lib/deco_lite/model.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require 'active_model'
-require_relative 'field_creatable'
-require_relative 'field_requireable'
+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'
 require_relative 'model_nameable'
@@ -14,9 +15,10 @@ module DecoLite
   # dynamic models that can be used as decorators.
   class Model
     include ActiveModel::Model
-    include FieldCreatable
+    include FieldAssignable
     include FieldNamesPersistable
     include FieldRequireable
+    include FieldsAutoloadable
     include HashLoadable
     include Hashable
     include ModelNameable
@@ -24,13 +26,18 @@ module DecoLite
 
     validate :validate_required_fields
 
-    def initialize(options: {})
+    def initialize(hash: {}, options: {})
       # 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
+
+      hash ||= {}
+
+      auto_fields = auto_attr_accessors.merge(hash)
+      load!(hash: auto_fields, options: options) if hash.present? || auto_attr_accessors?
     end
 
     def load!(hash:, options: {})

data/lib/deco_lite/options.rb

@@ -24,6 +24,10 @@ 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,16 +2,19 @@
 
 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_NAMESPACE => OPTION_NAMESPACE_DEFAULT,
+      OPTION_REQUIRED_FIELDS => OPTION_REQUIRED_FIELDS_DEFAULT
     }.freeze
   end
 end

data/lib/deco_lite/options_validatable.rb

@@ -2,14 +2,16 @@
 
 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].freeze
+    OPTIONS = [OPTION_FIELDS, OPTION_NAMESPACE, OPTION_REQUIRED_FIELDS].freeze
 
     def validate_options!(options:)
       raise ArgumentError, 'options is not a Hash' unless options.is_a? Hash
@@ -17,8 +19,9 @@ module DecoLite
       validate_options_present! options: options
 
       validate_option_keys! options: options
-      validate_option_fields! fields: options[:fields]
-      validate_option_namespace! namespace: options[:namespace]
+      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:)
@@ -45,5 +48,14 @@ 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/required_fields_optionable.rb

@@ -0,0 +1,15 @@
+# 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

data/lib/deco_lite/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deco_lite
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-22 00:00:00.000000000 Z
+date: 2022-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -266,6 +266,7 @@ files:
 - 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
 - lib/deco_lite/fields_optionable.rb
 - lib/deco_lite/hash_loadable.rb
 - lib/deco_lite/hashable.rb
@@ -276,6 +277,7 @@ 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: