hashie 5.1.0 → 5.2.0

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

@@ -1,9 +1,11 @@
+# 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
+      # @example
       #
       #   class PersonHash < Hashie::Dash
       #     include Hashie::Extensions::Dash::PredefinedValues
@@ -12,23 +14,59 @@ module Hashie
       #     property :age, values: (0..150) # a Range
       #   end
       #
-      #   person = PersonHash.new(gender: :male, age: -1)
-      #   # => ArgumentError: The value '-1' is not accepted for property 'age'
+      #   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
 
@@ -43,7 +81,7 @@ module Hashie
           def assert_predefined_values!(predefined_values)
             return if supported_type?(predefined_values)
 
-            raise ArgumentError, %(`values` accepts an Array or a Range.)
+            raise ArgumentError, %(`values` accepts an `Array` or a `Range`)
           end
 
           def supported_type?(predefined_values)
@@ -55,7 +93,22 @@ module Hashie
           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
 
@@ -68,14 +121,21 @@ module Hashie
             self.class.values_for_properties.each_key do |property|
               value = send(property)
 
-              if value && !values_for_properties(property).include?(value)
-                fail_property_value_error!(property)
-              end
+              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)
-            raise ArgumentError, "Invalid value for property '#{property}'"
+          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)

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Dash
@@ -7,12 +9,12 @@ module Hashie
       # application -- such as a Java API -- where the keys are named
       # differently from Ruby conventions.
       #
-      # == Example from inconsistent APIs
+      # @example Translate inconsistent API keys
       #
       #   class PersonHash < Hashie::Dash
       #     include Hashie::Extensions::Dash::PropertyTranslation
       #
-      #     property :first_name, from :firstName
+      #     property :first_name, from: :firstName
       #     property :last_name, from: :lastName
       #     property :first_name, from: :f_name
       #     property :last_name, from: :l_name
@@ -25,7 +27,8 @@ module Hashie
       # You can also use a lambda to translate the value. This is particularly
       # useful when you want to ensure the type of data you're wrapping.
       #
-      # == Example using translation lambdas
+      # @example Transform input values
+      #   require 'time'
       #
       #   class DataModelHash < Hashie::Dash
       #     include Hashie::Extensions::Dash::PropertyTranslation
@@ -35,28 +38,66 @@ module Hashie
       #   end
       #
       #   model = DataModelHash.new(id: '123', created: '2014-04-25 22:35:28')
-      #   model.id.class          #=> Integer (Fixnum if you are using Ruby 2.3 or lower)
+      #   model.id.class          #=> Integer
       #   model.created_at.class  #=> Time
       module PropertyTranslation
+        # @example Install translation declarations on a Dash
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.new(fullName: 'Ada').name # => 'Ada'
         def self.included(base)
           base.instance_variable_set(:@transforms, {})
           base.instance_variable_set(:@translations_hash, ::Hash.new { |hash, key| hash[key] = {} })
           base.extend(ClassMethods)
           base.send(:include, InstanceMethods)
+          base.extend Hashie::Extensions::DeepMerge
         end
 
+        # Defines input translations and value transformations.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.translations # => {fullName: :name}
         module ClassMethods
+          # @example Inspect value transformers
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transforms[:age].call('37') # => 37
+          #   klass.translations_hash # => {}
           attr_reader :transforms, :translations_hash
 
           # Ensures that any inheriting classes maintain their translations.
           #
-          # * <tt>:default</tt> - The class inheriting the translations.
+          # * `:default` - The class inheriting the translations.
+          #
+          # @example Copy translation settings to subclasses
+          #   parent = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   child = Class.new(parent) { property :age, from: :years }
+          #   child.new(fullName: 'Ada', years: 37).age # => 37
+          #   parent.translations # => {fullName: :name}
           def inherited(klass)
             super
             klass.instance_variable_set(:@transforms, transforms.dup)
-            klass.instance_variable_set(:@translations_hash, translations_hash.dup)
+            klass.instance_variable_set(:@translations_hash, _deep_dup(translations_hash))
           end
 
+          # @example List translated input keys alongside untranslated properties
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #     property :age
+          #   end
+          #   klass.permitted_input_keys # => [:fullName, :age]
           def permitted_input_keys
             @permitted_input_keys ||=
               properties
@@ -65,12 +106,19 @@ module Hashie
 
           # Defines a property on the Trash. Options are as follows:
           #
-          # * <tt>:default</tt> - Specify a default value for this property, to be
+          # * `:default` - Specify a default value for this property, to be
           # returned before a value is set on the property in a new Dash.
-          # * <tt>:from</tt> - Specify the original key name that will be write only.
-          # * <tt>:with</tt> - Specify a lambda to be used to convert value.
-          # * <tt>:transform_with</tt> - Specify a lambda to be used to convert value
+          # * `:from` - Specify the original key name that will be write only.
+          # * `:with` - Specify a lambda to be used to convert value.
+          # * `:transform_with` - Specify a lambda to be used to convert value
           # without using the :from option. It transform the property itself.
+          #
+          # @example Declare a translated and converted property
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, from: :years, with: ->(value) { value.to_i }
+          #   end
+          #   klass.new(years: '37').age # => 37
           def property(property_name, options = {})
             super
 
@@ -79,7 +127,7 @@ module Hashie
             transformer = options[:transform_with]
 
             if from
-              fail_self_transformation_error!(property_name) if property_name == from
+              fail_self_transformation_error!(property_name) if property_name.to_s == from.to_s
               define_translation(from, property_name, converter || transformer)
               define_writer_for_source_property(from)
             elsif valid_transformer?(transformer)
@@ -87,18 +135,44 @@ module Hashie
             end
           end
 
+          # @example Apply a declared transformer directly
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformed_property(:age, '37') # => 37
           def transformed_property(property_name, value)
             transforms[property_name].call(value)
           end
 
+          # @example Check for a property transformer
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformation_exists?(:age) # => true
+          #   klass.transformation_exists?(:name) # => false
           def transformation_exists?(name)
             transforms.key? name
           end
 
+          # @example Check for a translated source key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translation_exists?(:fullName) # => true
+          #   klass.translation_exists?(:name) # => false
           def translation_exists?(name)
             translations_hash.key? name
           end
 
+          # @example Map source keys to destination properties
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translations # => {fullName: :name}
           def translations
             @translations ||= {}.tap do |translations|
               translations_hash.each do |(property_name, property_translations)|
@@ -112,6 +186,12 @@ module Hashie
             end
           end
 
+          # @example Map destination properties back to source keys
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.inverse_translations # => {name: :fullName}
           def inverse_translations
             @inverse_translations ||= {}.tap do |translations|
               translations_hash.each do |(property_name, property_translations)|
@@ -138,7 +218,7 @@ module Hashie
 
           def fail_self_transformation_error!(property_name)
             raise ArgumentError,
-                  "Property name (#{property_name}) and :from option must not be the same"
+                  "property name `#{property_name}` and :from option must not be the same"
           end
 
           def valid_transformer?(transformer)
@@ -146,39 +226,77 @@ module Hashie
           end
         end
 
+        # Applies translations and transformations during assignment.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.new(fullName: 'Ada').name # => 'Ada'
         module InstanceMethods
           # Sets a value on the Dash in a Hash-like way.
           #
           # Note: Only works on pre-existing properties.
+          #
+          # @example Assign through a translated source key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   dash = klass.new
+          #   dash[:fullName] = 'Ada'
+          #   dash.name # => 'Ada'
           def []=(property, value)
             if self.class.translation_exists? property
               send("#{property}=", value)
 
               if self.class.transformation_exists? property
-                super property, self.class.transformed_property(property, value)
+                super(property, self.class.transformed_property(property, value))
               elsif self.class.properties.include?(property)
-                super(property, value)
+                super
               end
             elsif self.class.transformation_exists? property
-              super property, self.class.transformed_property(property, value)
+              super(property, self.class.transformed_property(property, value))
             elsif property_exists? property
               super
             end
           end
 
           # Deletes any keys that have a translation
+          #
+          # @example Initialize translated input without modifying the source
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   attributes = {fullName: 'Ada'}
+          #   dash = klass.new
+          #   dash.initialize_attributes(attributes)
+          #   dash.name # => 'Ada'
+          #   attributes # => {fullName: 'Ada'}
           def initialize_attributes(attributes)
             return unless attributes
+
             attributes_copy = attributes.dup.delete_if do |k, v|
               if self.class.translations_hash.include?(k)
                 self[k] = v
                 true
               end
             end
-            super attributes_copy
+            super(attributes_copy)
           end
 
           # Raises an NoMethodError if the property doesn't exist
+          #
+          # @example Check for an existing property
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name
+          #   end
+          #   dash = klass.new
+          #   dash.property_exists?(:name) # => true
+          #   expect { dash.property_exists?(:missing) }.to raise_error(NoMethodError)
           def property_exists?(property)
             fail_no_property_error!(property) unless self.class.property?(property)
             true

data/lib/hashie/extensions/deep_fetch.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
-    # Searches a deeply nested datastructure for a key path, and returns the associated value.
+    # Searches a deeply nested data structure for a key path, and returns the associated value.
     #
     #  options = { user: { location: { address: '123 Street' } } }
     #  options.deep_fetch :user, :location, :address #=> '123 Street'
@@ -11,19 +13,29 @@ module Hashie
     #
     # This is particularly useful for fetching values from deeply nested api responses
     #   or params hashes.
+    #
+    # @example Traverse hashes and arrays
+    #   hash = { users: [{ name: 'Ada' }] }.extend(Hashie::Extensions::DeepFetch)
+    #   hash.deep_fetch(:users, 0, :name) # => 'Ada'
     module DeepFetch
+      # @example Report an undefined path
+      #   error = Hashie::Extensions::DeepFetch::UndefinedPathError.new('missing address')
+      #   error.message # => 'missing address'
       class UndefinedPathError < StandardError; end
 
+      # @example Use a fallback for a missing path
+      #   hash = { user: {} }.extend(Hashie::Extensions::DeepFetch)
+      #   hash.deep_fetch(:user, :name) { |key| "missing #{key}" } # => 'missing name'
+      #   hash.deep_fetch(:user) # => {}
       def deep_fetch(*args, &block)
         args.reduce(self) do |obj, arg|
-          begin
-            arg = Integer(arg) if obj.is_a? Array
-            obj.fetch(arg)
-          rescue ArgumentError, IndexError, NoMethodError => e
-            break yield(arg) if block
-            raise UndefinedPathError,
-                  "Could not fetch path (#{args.join(' > ')}) at #{arg}", e.backtrace
-          end
+          arg = Integer(arg) if obj.is_a? Array
+          obj.fetch(arg)
+        rescue ArgumentError, IndexError, NoMethodError => e
+          break yield(arg) if block
+
+          raise UndefinedPathError,
+                "could not fetch path (`#{args.join(' > ')}`) at `#{arg}`", e.backtrace
         end
       end
     end

data/lib/hashie/extensions/deep_find.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/deep_locate'
 module Hashie
   module Extensions
+    # @example Find values in nested collections
+    #   hash = { users: [{ name: 'Ada' }] }.extend(Hashie::Extensions::DeepFind)
+    #   hash.deep_find(:name) # => 'Ada'
     module DeepFind
       # Performs a depth-first search on deeply nested data structures for
       # a key and returns the first occurrence of the key.
@@ -16,10 +21,17 @@ module Hashie
       #  my_hash = MyHash.new
       #  my_hash[:user] = {location: {address: '123 Street'}}
       #  my_hash.deep_find(:address) # => '123 Street'
+      #
+      # @example Return the first value
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_find(:name) # => 'Ada'
       def deep_find(key)
         _deep_find(key)
       end
 
+      # @example Detect the first nested value
+      #   hash = { user: { name: 'Ada' } }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_detect(:name) # => 'Ada'
       alias deep_detect deep_find
 
       # Performs a depth-first search on deeply nested data structures for
@@ -44,11 +56,19 @@ module Hashie
       #    {location: {address: '234 Street'}}
       #  ]
       #  my_hash.deep_find_all(:address) # => ['123 Street', '234 Street']
+      #
+      # @example Collect all values, or nil if absent
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_find_all(:name) # => ['Ada', 'Grace']
+      #   hash.deep_find_all(:email) # => nil
       def deep_find_all(key)
         matches = _deep_find_all(key)
         matches.empty? ? nil : matches
       end
 
+      # @example Select every nested value
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_select(:name) # => ['Ada', 'Grace']
       alias deep_select deep_find_all
 
       private