Skip to content
  • Neil Carvalho's avatar
    ccb23939
    Clarify `composed_of` allows a Hash for `mapping` · ccb23939
    Neil Carvalho authored
    [`composed_of`](https://api.rubyonrails.org/classes/ActiveRecord/Aggregations/ClassMethods.html#method-i-composed_of)
    is a feature that is not widely used and its API is somewhat confusing,
    especially for beginners. It was even deprecated for a while, but 10
    years after its deprecation, it's still here.
    
    The Rails documentation includes these examples including mapping:
    ```ruby
    composed_of :temperature, mapping: %w(reading celsius)
    composed_of :balance, class_name: "Money", mapping: %w(balance amount)
    composed_of :address, mapping: [ %w(address_street street),
    %w(address_city city) ]
    ```
    
    Hashes are accepted kind-of accidentally for the `mapping` option. Using
    a hash, instead of an array or array of arrays makes the documentation
    more beginner-friendly.
    
    ```ruby
    composed_of :temperature, mapping: { reading: :celsius }
    composed_of :balance, class_name: "Money", mapping: { balance: :amount }
    composed_of :address, mapping: { address_street: :street, address_city:
    :city }
    ```
    
    Before Ruby 1.9, looping through a hash didn't have deterministic order,
    and the mapping order is important, as that's the same order Rails uses
    when initializing the value object. Since Ruby 1.9, this isn't an issue
    anymore, so we can change the documentation to use hashes instead.
    
    This commit changes the documentation for `composed_of`, clarifying that
    any key-value format (both a `Hash` and an `Array`) are accepted for the
    `mapping` option. It also adds tests to ensure hashes are also accepted.
    ccb23939
    Clarify `composed_of` allows a Hash for `mapping`
    Neil Carvalho authored
    [`composed_of`](https://api.rubyonrails.org/classes/ActiveRecord/Aggregations/ClassMethods.html#method-i-composed_of)
    is a feature that is not widely used and its API is somewhat confusing,
    especially for beginners. It was even deprecated for a while, but 10
    years after its deprecation, it's still here.
    
    The Rails documentation includes these examples including mapping:
    ```ruby
    composed_of :temperature, mapping: %w(reading celsius)
    composed_of :balance, class_name: "Money", mapping: %w(balance amount)
    composed_of :address, mapping: [ %w(address_street street),
    %w(address_city city) ]
    ```
    
    Hashes are accepted kind-of accidentally for the `mapping` option. Using
    a hash, instead of an array or array of arrays makes the documentation
    more beginner-friendly.
    
    ```ruby
    composed_of :temperature, mapping: { reading: :celsius }
    composed_of :balance, class_name: "Money", mapping: { balance: :amount }
    composed_of :address, mapping: { address_street: :street, address_city:
    :city }
    ```
    
    Before Ruby 1.9, looping through a hash didn't have deterministic order,
    and the mapping order is important, as that's the same order Rails uses
    when initializing the value object. Since Ruby 1.9, this isn't an issue
    anymore, so we can change the documentation to use hashes instead.
    
    This commit changes the documentation for `composed_of`, clarifying that
    any key-value format (both a `Hash` and an `Array`) are accepted for the
    `mapping` option. It also adds tests to ensure hashes are also accepted.
Loading