hashie 4.1.0 → 5.2.0

data/lib/hashie/extensions/dash/indifferent_access.rb

@@ -1,12 +1,33 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Dash
+      # Allows string and symbol access to declared Dash properties.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Dash) do
+      #     include Hashie::Extensions::Dash::IndifferentAccess
+      #     property :name
+      #   end
+      #   klass.new(name: 'Ada')['name'] # => 'Ada'
       module IndifferentAccess
+        # @example Include indifferent access in a Dash subclass
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name
+        #   end
+        #   klass.property?('name') # => true
         def self.included(base)
           base.extend ClassMethods
           base.send :include, Hashie::Extensions::IndifferentAccess
         end
 
+        # @example Add Dash-specific class methods when needed
+        #   klass = Class.new(Hashie::Dash) { property :name }
+        #   Hashie::Extensions::Dash::IndifferentAccess.maybe_extend(klass)
+        #   klass.property?('name') # => true
+        #   klass.singleton_class.included_modules.include?(Hashie::Extensions::Dash::IndifferentAccess::ClassMethods) # => true
         def self.maybe_extend(base)
           return unless requires_class_methods?(base)
 
@@ -19,25 +40,91 @@ module Hashie
         end
         private_class_method :requires_class_methods?
 
+        # @example Include defaults under string keys in the returned hash
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name, default: 'Ada'
+        #     property :age
+        #   end
+        #   klass.new(age: 37).to_h # => {'name' => 'Ada', 'age' => 37}
+        def to_h
+          defaults = self.class.properties.to_h do |prop|
+            [Hashie::Extensions::IndifferentAccess.convert_key(prop), self.class.defaults[prop]]
+          end
+
+          defaults.merge(self)
+        end
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name, default: 'Ada'
+        #   end
+        #   klass.new.to_hash # => {'name' => 'Ada'}
+        alias to_hash to_h
+
+        # Class-level property and translation lookup with indifferent keys.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name
+        #   end
+        #   klass.property?('name') # => true
         module ClassMethods
           # Check to see if the specified property has already been
           # defined.
+          #
+          # @example
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :name
+          #   end
+          #   klass.property?('name') # => true
+          #   klass.property?(:missing) # => false
           def property?(name)
-            name = translations[name.to_sym] if translation_for?(name)
-            name = name.to_s
-            !!properties.find { |property| property.to_s == name }
+            targets = if translation_for?(name)
+                        Array(translations.find { |key, _| key.to_s == name.to_s }.last)
+                      else
+                        [name]
+                      end
+            targets.all? do |target|
+              properties.any? { |property| property.to_s == target.to_s }
+            end
           end
 
+          # @example Look up a translation with a string or symbol
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translation_exists?('fullName') # => true
+          #   klass.translation_exists?(:missing) # => false
           def translation_exists?(name)
             name = name.to_s
             !!translations.keys.find { |key| key.to_s == name }
           end
 
+          # @example Apply a transformer declared with a symbol key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformed_property('age', '37') # => 37
           def transformed_property(property_name, value)
             transform = transforms[property_name] || transforms[property_name.to_sym]
             transform.call(value)
           end
 
+          # @example Find a transformer regardless of key type
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformation_exists?('age') # => true
+          #   klass.transformation_exists?(:missing) # => false
           def transformation_exists?(name)
             name = name.to_s
             !!transforms.keys.find { |key| key.to_s == name }

data/lib/hashie/extensions/dash/lazy.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    module Dash
+      # Loads declared properties on demand from an initializer block.
+      # Include after other Dash extensions. Hash enumeration only sees loaded
+      # entries; to_h loads every declared property.
+      #
+      # @example Load and memoize a property
+      #   klass = Class.new(Hashie::Dash) do
+      #     include Hashie::Extensions::Dash::Lazy
+      #     property :name
+      #   end
+      #   calls = []
+      #   dash = klass.new { |key| calls << key; 'Ada' }
+      #   calls # => []
+      #   dash.name # => 'Ada'
+      #   dash.name # => 'Ada'
+      #   calls # => [:name]
+      module Lazy
+        # @example Hash initialization without a loader retains normal behavior
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name, required: true
+        #   end
+        #   klass.new(name: 'Ada').name # => 'Ada'
+        def initialize(attributes = {}, &loader)
+          @lazy_loader = loader
+          @lazy_loading = []
+          super(attributes, &nil)
+        end
+
+        # @example Read a property without loading its neighbors
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name
+        #     property :age
+        #   end
+        #   dash = klass.new { |key| { name: 'Ada', age: 37 }[key] }
+        #   dash[:name] # => 'Ada'
+        #   dash.keys # => [:name]
+        def [](property, &block)
+          return super unless @lazy_loader
+
+          assert_property_exists!(property)
+          canonical_property = lazy_property(property)
+          load_property(canonical_property) unless key?(property)
+          value = super
+          assert_property_required!(canonical_property, value)
+          value
+        end
+
+        # @example Fetch a declared value through its loader
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name
+        #   end
+        #   klass.new { |_key| 'Ada' }.fetch(:name) # => 'Ada'
+        def fetch(property, *args, &block)
+          self[property] if @lazy_loader && self.class.property?(property)
+          super
+        end
+
+        # @example Load the first property before digging into its value
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :user
+        #   end
+        #   klass.new { |_key| { name: 'Ada' } }.dig(:user, :name) # => 'Ada'
+        def dig(property, *path)
+          self[property] if @lazy_loader && self.class.property?(property)
+          super
+        end
+
+        # @example Convert all declared properties to a plain hash
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name
+        #   end
+        #   klass.new { |_key| 'Ada' }.to_h # => { name: 'Ada' }
+        def to_h
+          self.class.properties.each { |property| self[property] } if @lazy_loader
+          super
+        end
+
+        # @example Convert all declared properties for hash coercion
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name
+        #   end
+        #   klass.new { |_key| 'Ada' }.to_hash # => { name: 'Ada' }
+        alias to_hash to_h
+
+        # @example Freezing resolves pending values before preventing mutation
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Lazy
+        #     property :name
+        #   end
+        #   klass.new { |_key| 'Ada' }.freeze.name # => 'Ada'
+        def freeze
+          to_h if @lazy_loader && !frozen?
+          super
+        end
+
+        private
+
+        def initialize_attributes(attributes)
+          return super unless @lazy_loader
+
+          @lazy_attributes = attributes || {}
+        end
+
+        def assert_required_attributes_set!
+          super unless @lazy_loader
+        end
+
+        def initialize_copy(other)
+          super
+          @lazy_loading = []
+        end
+
+        def lazy_property(property)
+          return property if self.class.properties.include?(property)
+
+          self.class.properties.find { |key| key.to_s == property.to_s } || property
+        end
+
+        def lazy_attribute_key(property)
+          return property if @lazy_attributes.key?(property)
+          return unless respond_to?(:convert_key)
+
+          converted = convert_key(property)
+          converted if @lazy_attributes.key?(converted)
+        end
+
+        def load_property(property)
+          raise ArgumentError, "circular lazy loading for property `#{property}`" if @lazy_loading.include?(property)
+
+          @lazy_loading << property
+          begin
+            source = if self.class.respond_to?(:inverse_translations)
+                       self.class.inverse_translations.fetch(property, property)
+                     else
+                       property
+                     end
+            attribute = lazy_attribute_key(property)
+            if attribute
+              source = property
+              value = @lazy_attributes[attribute]
+            else
+              attribute = lazy_attribute_key(source)
+              value = attribute ? @lazy_attributes[attribute] : @lazy_loader.call(source)
+            end
+            if value.nil?
+              value = self.class.defaults[property].dup
+              value = value.arity == 1 ? value.call(self) : value.call if value.is_a?(Proc)
+            elsif source != property
+              translator = self.class.translations_hash[source][property]
+              value = translator.call(value) if translator.respond_to?(:call)
+            end
+            self[property] = value
+          ensure
+            @lazy_loading.pop
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/dash/predefined_values.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    module Dash
+      # Extends a Dash with the ability to accept only predefined values on a property.
+      #
+      # @example
+      #
+      #   class PersonHash < Hashie::Dash
+      #     include Hashie::Extensions::Dash::PredefinedValues
+      #
+      #     property :gender, values: [:male, :female, :prefer_not_to_say]
+      #     property :age, values: (0..150) # a Range
+      #   end
+      #
+      #   expect { PersonHash.new(gender: :male, age: -1) }
+      #     .to raise_error(ArgumentError, /value `-1` is not allowed for `age`/)
+      #   PersonHash.new(gender: :male, age: 42).age # => 42
+      module PredefinedValues
+        # @example Install predefined-value declarations
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PredefinedValues
+        #   end
+        #   klass.values_for_properties # => {}
+        def self.included(base)
+          base.instance_variable_set(:@values_for_properties, {})
+          base.extend(ClassMethods)
+          base.include(InstanceMethods)
+        end
+
+        # Declares and inherits permitted values for properties.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PredefinedValues
+        #     property :status, values: [:open, :closed]
+        #   end
+        #   klass.values_for_properties # => {status: [:open, :closed]}
+        module ClassMethods
+          # @example Read the constraints for declared properties
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PredefinedValues
+          #     property :age, values: (0..150)
+          #   end
+          #   klass.values_for_properties # => {age: (0..150)}
+          attr_reader :values_for_properties
+
+          # @example Inherit constraints without sharing the constraint map
+          #   parent = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PredefinedValues
+          #     property :status, values: [:open, :closed]
+          #   end
+          #   child = Class.new(parent) { property :age, values: (0..150) }
+          #   child.values_for_properties.keys # => [:status, :age]
+          #   parent.values_for_properties.keys # => [:status]
+          def inherited(klass)
+            super
+            klass.instance_variable_set(:@values_for_properties, values_for_properties.dup)
+          end
+
+          # @example Accept an array or range of values
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PredefinedValues
+          #     property :status, values: [:open, :closed]
+          #     property :age, values: (0..150)
+          #   end
+          #   klass.new(status: :open, age: 42).age # => 42
+          #   expect { klass.new(status: :unknown) }.to raise_error(ArgumentError, /status/)
+          def property(property_name, options = {})
+            super
+
+            return unless (predefined_values = options[:values])
+
+            assert_predefined_values!(predefined_values)
+            set_predefined_values(property_name, predefined_values)
+          end
+
+          private
+
+          def assert_predefined_values!(predefined_values)
+            return if supported_type?(predefined_values)
+
+            raise ArgumentError, %(`values` accepts an `Array` or a `Range`)
+          end
+
+          def supported_type?(predefined_values)
+            [::Array, ::Range].any? { |klass| predefined_values.is_a?(klass) }
+          end
+
+          def set_predefined_values(property_name, predefined_values)
+            @values_for_properties[property_name] = predefined_values
+          end
+        end
+
+        # Validates property constraints when constructing a Dash.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PredefinedValues
+        #     property :status, values: [:open, :closed]
+        #   end
+        #   klass.new(status: :open).status # => :open
+        module InstanceMethods
+          # @example Reject values outside the declared set
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PredefinedValues
+          #     property :status, values: [:open, :closed]
+          #   end
+          #   expect { klass.new(status: :unknown) }.to raise_error(ArgumentError, /status/)
+          #   klass.new.status # => nil
+          def initialize(*)
+            super
+
+            assert_property_values!
+          end
+
+          private
+
+          def assert_property_values!
+            self.class.values_for_properties.each_key do |property|
+              value = send(property)
+
+              allowed_values = values_for_properties(property)
+              fail_property_value_error!(property, value, allowed_values) if value && !allowed_values.include?(value)
+            end
+          end
+
+          def fail_property_value_error!(property, value, allowed_values)
+            expected_values = if allowed_values.is_a?(::Range)
+                                "a value in `#{allowed_values}`"
+                              else
+                                "one of `#{allowed_values.inspect}`"
+                              end
+
+            raise ArgumentError,
+                  "value `#{value.inspect}` is not allowed for `#{property}`; " \
+                  "expected #{expected_values}"
+          end
+
+          def values_for_properties(property)
+            self.class.values_for_properties[property]
+          end
+        end
+      end
+    end
+  end
+end