pragma-decorator 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4cc969bd13e27d434cc079786db43b29ae6b6154
-  data.tar.gz: cfefba30c1aab7b6d53db48031df9e991159537e
+  metadata.gz: 3112d0727880b4dc23ca921b073f064e2f06067f
+  data.tar.gz: fea5ef98f76c7a32c28e461502039f1f1c9a2d32
 SHA512:
-  metadata.gz: 26574df0b3a1807c18fe1c156feadf6ea37947fcb044f1587d4de0319782af2164cb5a7c591a99bb954d187b0ec6c6e5c499150eba89be2ab04c8b36c00a6763
-  data.tar.gz: d502113406896fd913100c0ededa0242ead3fc8fa1d1cdd7545d2bff0ed15fe9d8a227beac6f3177f22189354223c9bada76a62f02f188b4119b3549bab0c51d
+  metadata.gz: ac722386db2bfe735422685fbf81fdecbcf4c79a8c03677df38b84a681b2c435232260dc60f11843504dfca7d772439f42ec3f8c4a8dbbdd76d66c30853fb93b
+  data.tar.gz: 444d356b1fbc1277c77a2caa86ee2d4378636f285c574451a4b7a0843f53bd9fe46898b2d599f10d18ea77f830bb60ae8b3e0413104143c72f0b6f3123b21d59

data/.rubocop.yml

@@ -92,3 +92,13 @@ Style/GuardClause:
 
 Capybara/FeatureMethods:
   Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'pragma-decorator.gemspec'

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.1.0]
+
+### Added
+
+- Added support for `:as` in `timestamp` properties
+- `user_options` are now forwarded to expanded associations
+- Made associations ORM-independent with the Adapter API
+- Implemented the Type Overrides API
+- Implemented the Pagination Adapter API
+
+### Changed
+
+- Changed the `#type` of collections from `collection` to `list`
+- Replaced `feature` with `include` in tests and examples
+
+### Fixed
+
+- Fixed `type` property not returning `list` for instances of `ActiveRecord::Relation`
+- Fixed bugs with the optimization of associations with custom scopes
+ 
+## [2.0.0]
+
+First Pragma 2 release.
+
+[Unreleased]: https://github.com/pragmarb/pragma-decorator/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/pragmarb/pragma-decorator/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/pragmarb/pragma-decorator/compare/v1.2.0...v2.0.0

data/README.md

@@ -1,9 +1,9 @@
 # Pragma::Decorator
 
-[![Build Status](https://img.shields.io/travis/pragmarb/pragma-decorator.svg?maxAge=3600&style=flat-square)](https://travis-ci.org/pragmarb/pragma-decorator)
-[![Dependency Status](https://img.shields.io/gemnasium/pragmarb/pragma-decorator.svg?maxAge=3600&style=flat-square)](https://gemnasium.com/github.com/pragmarb/pragma-decorator)
-[![Code Climate](https://img.shields.io/codeclimate/github/pragmarb/pragma-decorator.svg?maxAge=3600&style=flat-square)](https://codeclimate.com/github/pragmarb/pragma-decorator)
-[![Coveralls](https://img.shields.io/coveralls/pragmarb/pragma-decorator.svg?maxAge=3600&style=flat-square)](https://coveralls.io/github/pragmarb/pragma-decorator)
+[![Build Status](https://travis-ci.org/pragmarb/pragma-decorator.svg?branch=master)](https://travis-ci.org/pragmarb/pragma-decorator)
+[![Dependency Status](https://gemnasium.com/badges/github.com/pragmarb/pragma-decorator.svg)](https://gemnasium.com/github.com/pragmarb/pragma-decorator)
+[![Coverage Status](https://coveralls.io/repos/github/pragmarb/pragma-decorator/badge.svg?branch=master)](https://coveralls.io/github/pragmarb/pragma-decorator?branch=master)
+[![Maintainability](https://api.codeclimate.com/v1/badges/e51e8d7489eb72ab97ba/maintainability)](https://codeclimate.com/github/pragmarb/pragma-decorator/maintainability)
 
 Decorators are a way to easily convert your API resources to JSON with minimum hassle.
 
@@ -84,7 +84,7 @@ module API
     module User
       module Decorator
         class Instance < Pragma::Decorator::Base
-          feature Pragma::Decorator::Type
+          include Pragma::Decorator::Type
         end
       end
     end
@@ -134,7 +134,7 @@ module API
     module User
       module Decorator
         class Instance < Pragma::Decorator::Base
-          feature Pragma::Decorator::Timestamp
+          include Pragma::Decorator::Timestamp
 
           timestamp :created_at
         end
@@ -153,7 +153,7 @@ This will render a user like this:
 }
 ```
 
-The `#timestamp` method supports all the options supported by `#property` (except for `:as`).
+The `#timestamp` method supports all the options supported by `#property`.
 
 ### Associations
 
@@ -166,7 +166,7 @@ module API
     module Invoice
       module Decorator
         class Instance < Pragma::Decorator::Base
-          feature Pragma::Decorator::Association
+          include Pragma::Decorator::Association
 
           belongs_to :customer, decorator: API::V1::Customer::Decorator
         end
@@ -212,6 +212,8 @@ decorator.to_json(user_options: {
 Needless to say, this is done automatically for you when you use all components together through
 the [pragma](https://github.com/pragmarb/pragma) gem! :)
 
+Associations support all the options supported by `#property`.
+
 ### Collection
 
 `Pragma::Decorator::Collection` wraps collections in a `data` property so that you can include
@@ -223,7 +225,7 @@ module API
     module Invoice
       module Decorator
         class Collection < Pragma::Decorator::Base
-          feature Pragma::Decorator::Collection
+          include Pragma::Decorator::Collection
           decorate_with Instance # specify the instance decorator
           
           property :total_cents, exec_context: :decorator
@@ -273,8 +275,8 @@ module API
     module Invoice
       module Decorator
         class Collection < Pragma::Decorator::Base
-          feature Pragma::Decorator::Collection
-          feature Pragma::Decorator::Pagination
+          include Pragma::Decorator::Collection
+          include Pragma::Decorator::Pagination
           
           decorate_with Instance
         end

data/lib/pragma/decorator/association/adapter/active_record.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Association
+      module Adapter
+        # The ActiveRecord association adapter is used in AR environments and tries to minimize the
+        # number of SQL queries that are made to retrieve the associated object's data.
+        #
+        # @api private
+        class ActiveRecord < Base
+          class << self
+            # Returns whether the adapter supports the given model.
+            #
+            # @param model [Object] the model to check
+            #
+            # @return [Boolean] whether the object is an instance of +ActiveRecord::Base+
+            def supports?(model)
+              Object.const_defined?('ActiveRecord::Base') && model.is_a?(ActiveRecord::Base)
+            end
+          end
+
+          # Initializes the adapter.
+          #
+          # @param bond [Bond] the bond to use in the adapter
+          #
+          # @raise [InconsistentTypeError] when the association's real type is different from the
+          #   one defined on the decorator ()e.g. decorator defines the association as +belongs_to+,
+          #   but ActiveRecord reports its type is +has_one+)
+          def initialize(bond)
+            super
+            check_type_consistency
+          end
+
+          # Returns the primary key of the associated object.
+          #
+          # If the +exec_context+ of the association is +decorator+, this will simply return early
+          # with the value returned by +#id+ on the associated object.
+          #
+          # If the association is a +belongs_to+, there are three possible scenarios:
+          #
+          #   * the association does not have a custom scope: this will compute the PK by calling
+          #     the foreign key on the parent model;
+          #   * the association has a custom scope and it has not been loaded: this will compute
+          #     the PK by +pluck+ing the PK column of the associated object;
+          #   * the association has a custom scope and it has been loaded: this will compute
+          #     the PK by retrieving the PK attribute from the loaded object.
+          #
+          # If the association is a +has_one+, there are two possible scenarios:
+          #
+          #   * the association has already been loaded: this will compute the PK by retrieving the
+          #     PK attribute from the loaded object;
+          #   * the association has not been loaded: this will compute the PK by +pluck+ing the PK
+          #     column of the associated object;
+          #
+          # Custom scopes are always respected in both +belongs_to+ and +has_one+.
+          #
+          # +nil+ values are handled gracefully in all cases.
+          #
+          # @return [String|Integer|NilClass] the PK of the associated object
+          #
+          # @todo Allow to specify a different PK attribute when +exec_context+ is +decorator+
+          def primary_key
+            return associated_object&.id if reflection.options[:exec_context] == :decorator
+
+            case reflection.type
+            when :belongs_to
+              compute_belongs_to_fk
+            when :has_one
+              compute_has_one_fk
+            else
+              fail "Cannot compute primary key for #{reflection.type} association"
+            end
+          end
+
+          # Returns the expanded associated object.
+          #
+          # This will simply return the associated object itself, delegating caching to AR.
+          #
+          # @return [Object] the associated object
+          #
+          # @todo Ensure the required attributes are present on the associated object
+          def full_object
+            associated_object
+          end
+
+          private
+
+          def compute_belongs_to_fk
+            if model.association(reflection.property).loaded?
+              return associated_object&.public_send(association_reflection.association_primary_key)
+            end
+
+            if association_reflection.scope.nil?
+              return model.public_send(association_reflection.foreign_key)
+            end
+
+            pluck_association_fk do |scope|
+              fk = model.public_send(association_reflection.foreign_key)
+              scope.where(association_reflection.association_primary_key => fk)
+            end
+          end
+
+          def compute_has_one_fk
+            if model.association(reflection.property).loaded?
+              return associated_object&.public_send(associated_object.association_primary_key)
+            end
+
+            pluck_association_fk do |scope|
+              pk = model.public_send(association_reflection.active_record_primary_key)
+              scope.where(association_reflection.foreign_key => pk)
+            end
+          end
+
+          def pluck_association_fk
+            scope = association_reflection.klass.all
+
+            if association_reflection.scope
+              scope = association_reflection.instance_eval(&association_reflection.scope)
+            end
+
+            yield(scope).pluck(association_reflection.association_primary_key).first
+          end
+
+          def association_reflection
+            @association_reflection ||= model.class.reflect_on_association(reflection.property)
+          end
+
+          def check_type_consistency
+            return if association_reflection.macro.to_sym == reflection.type.to_sym
+
+            fail InconsistentTypeError.new(
+              decorator: decorator,
+              reflection: reflection,
+              model_type: association_reflection.macro
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/association/adapter/base.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Association
+      module Adapter
+        # The base association adapter, defining the interface for the implementations.
+        #
+        # @abstract Subclass and override {.supports?}, {#primary_key} and {#full_object} to
+        #   create a new adapter
+        #
+        # @api private
+        class Base
+          class << self
+            # Returns whether the adapter supports the given model.
+            #
+            # @param _model [Object] a model
+            #
+            # @return [Boolean] whether the adpater supports the model
+            #
+            # @abstract
+            def supports?(_model)
+              fail NotImplementedError
+            end
+          end
+
+          # @!attribute [r] bond
+          #   @return [Bond] the bond this adapter has been instantiated with
+          attr_reader :bond
+
+          # Initializes the adapter.
+          #
+          # @param bond [Bond] the bond to use
+          def initialize(bond)
+            @bond = bond
+          end
+
+          # Returns the primary key of the association represented by the provided bond.
+          #
+          # @return [String|Integer] the PK
+          #
+          # @abstract
+          def primary_key
+            fail NotImplementedError
+          end
+
+          # Returns the full object of the association represented by the provided bond.
+          #
+          # @return [Object] the full object
+          #
+          # @abstract
+          def full_object
+            fail NotImplementedError
+          end
+
+          protected
+
+          # This is a convenience method returning the reflection defined on the bond.
+          #
+          # @return [Reflection] the bond's reflection
+          #
+          # @see Bond#reflection
+          def reflection
+            bond.reflection
+          end
+
+          # This is a convenience method returning the reflection defined on the bond.
+          #
+          # @return [Object] the bond's associated object
+          #
+          # @see Bond#associated_object
+          def associated_object
+            bond.associated_object
+          end
+
+          # This is a convenience method returning the model defined on the bond.
+          #
+          # @return [Reflection] the bond's model
+          #
+          # @see Bond#model
+          def model
+            bond.model
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/association/adapter/poro.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Association
+      module Adapter
+        # This is the fallback adapter that is used when no other adpater is compatible with a
+        # model. It simply calls +#id+ on the associated object to get the PK and returns the
+        # associated object itself when expanding.
+        #
+        # @api private
+        class Poro < Base
+          class << self
+            # Returns whether the adapter supports the model.
+            #
+            # Since this is the default adapter, this always returns +true+.
+            #
+            # @param _model [Object] the model to check
+            #
+            # @return [Boolean] always +true+
+            def supports?(_model)
+              true
+            end
+          end
+
+          # Returns the PK of the associated object.
+          #
+          # This adapter simply calls +#id+ on the associated object or returns +nil+ if there is
+          # no associated object.
+          #
+          # @return [Integer|String|NilClass] the PK of the associated object
+          def primary_key
+            associated_object&.id
+          end
+
+          # Returns the expanded associated object.
+          #
+          # This adapter simply returns the associated object itself.
+          #
+          # @return [Object] the associated object
+          def full_object
+            associated_object
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/association/adapter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Association
+      # Adapters make associations ORM-independent by providing support for multiple underlying
+      # libraries like ActiveRecord and simple POROs.
+      #
+      # @api private
+      module Adapter
+        # The list of supported adapters, in order of priority.
+        SUPPORTED_ADAPTERS = [ActiveRecord, Poro].freeze
+
+        # Loads the adapter for the given association bond.
+        #
+        # This will try {SUPPORTED_ADAPTERS} in order until it finds an adapter that supports the
+        # bond's model. When the adapter is found, it will return a new instance of it.
+        #
+        # @param bond [Bond] the bond to load the adapter for
+        #
+        # @return [Adapter::Base]
+        #
+        # @see Adapter::Base.supports?
+        def self.load_for(bond)
+          SUPPORTED_ADAPTERS.find do |adapter|
+            adapter.supports?(bond.model)
+          end.new(bond)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/association/{binding.rb → bond.rb}

@@ -5,8 +5,8 @@ module Pragma
     module Association
       # Links an association definition to a specific decorator instance, allowing to render it.
       #
-      # @author Alessandro Desantis
-      class Binding
+      # @api private
+      class Bond
         # @!attribute [r] reflection
         #   @return [Reflection] the association reflection
         #
@@ -14,7 +14,7 @@ module Pragma
         #   @return [Pragma::Decorator::Base] the decorator instance
         attr_reader :reflection, :decorator
 
-        # Initializes the binding.
+        # Initializes the bond.
         #
         # @param reflection [Reflection] the association reflection
         # @param decorator [Pragma::Decorator::Base] the decorator instance
@@ -29,9 +29,9 @@ module Pragma
         def associated_object
           case reflection.options[:exec_context]
           when :decorated
-            decorator.decorated.send(reflection.property)
+            model.public_send(reflection.property)
           when :decorator
-            decorator.send(reflection.property)
+            decorator.public_send(reflection.property)
           end
         end
 
@@ -39,8 +39,7 @@ module Pragma
         #
         # @return [String]
         def unexpanded_value
-          return unless associated_object
-          associated_object.id
+          adapter.primary_key
         end
 
         # Returns the expanded value for the associated object.
@@ -53,48 +52,58 @@ module Pragma
         # In any case, passes all nested associations as the +expand+ user option of the method
         # called.
         #
-        # @param expand [Array<String>] the associations to expand
+        # @param user_options [Array]
         #
         # @return [Hash]
-        def expanded_value(expand)
-          return unless associated_object
+        def expanded_value(user_options)
+          full_object = adapter.full_object
+          return unless full_object
 
           options = {
-            user_options: {
-              expand: flatten_expand(expand)
-            }
+            user_options: user_options.merge(
+              expand: flatten_expand(user_options[:expand])
+            )
           }
 
           decorator_klass = compute_decorator
 
           if decorator_klass
-            decorator_klass.new(associated_object).to_hash(options)
+            decorator_klass.new(full_object).to_hash(options)
           else
-            associated_object.as_json(options)
+            full_object.as_json(options)
           end
         end
 
         # Renders the unexpanded or expanded associations, depending on the +expand+ user option
         # passed to the decorator.
         #
-        # @param expand [Array<String>] the associations to expand
+        # @param user_options [Array]
         #
         # @return [Hash|Pragma::Decorator::Base]
-        def render(expand)
-          return unless associated_object
-
-          expand ||= []
-
-          if expand.any? { |value| value.to_s == reflection.property.to_s }
-            expanded_value(expand)
+        def render(user_options)
+          if user_options[:expand]&.any? { |value| value.to_s == reflection.property.to_s }
+            expanded_value(user_options)
           else
             unexpanded_value
           end
         end
 
+        # Returns the model associated to this bond.
+        #
+        # @return [Object]
+        def model
+          decorator.decorated
+        end
+
         private
 
+        def adapter
+          @adapter ||= Adapter.load_for(self)
+        end
+
         def flatten_expand(expand)
+          expand ||= []
+
           expected_beginning = "#{reflection.property}."
 
           expand.reject { |value| value.to_s == reflection.property.to_s }.map do |value|

data/lib/pragma/decorator/association/errors.rb

@@ -3,21 +3,38 @@
 module Pragma
   module Decorator
     module Association
+      # This is a generic class for all errors during association expansion.
       class ExpansionError < StandardError
       end
 
+      # This is raised when a non-existing association is expanded.
       class AssociationNotFound < ExpansionError
+        # @!attribute [r] property
+        #   @return [String|Sybmol] the property the user tried to expand
         attr_reader :property
 
+        # Initializes the rror.
+        #
+        # @param property [String|Symbol] the property the user tried to expand
         def initialize(property)
           @property = property
           super "The '#{property}' association is not defined."
         end
       end
 
+      # This is raised when the user expanded a nested association without expanding its parent.
       class UnexpandedAssociationParent < ExpansionError
+        # @!attribute [r] child
+        #   @return [String|Symbol] the name of the child association
+        #
+        # @!attribute [r] parent
+        #   @return [String|Symbol] the name of the parent association
         attr_reader :child, :parent
 
+        # Initializes the error.
+        #
+        # @param child [String|Symbol] the name of the child association
+        # @param parent [String|Symbol] the name of the parent association
         def initialize(child, parent)
           @child = child
           @parent = parent
@@ -25,6 +42,26 @@ module Pragma
           super "The '#{child}' association is expanded, but its parent '#{parent}' is not."
         end
       end
+
+      # This error is raised when an association's type is different from its type as reported by
+      # the model's reflection.
+      #
+      # @author Alessandro Desantis
+      class InconsistentTypeError < StandardError
+        # Initializes the error.
+        #
+        # @param decorator [Base] the decorator where the association is defined
+        # @param reflection [Reflection] the reflection of the inconsistent association
+        # @param model_type [Symbol|String] the real type of the association
+        def initialize(decorator:, reflection:, model_type:)
+          message = <<~MSG.tr("\n", ' ')
+            #{decorator.class}: Association #{reflection.property} is defined as #{model_type} on
+            the model, but as #{reflection.type} in the decorator.
+          MSG
+
+          super message
+        end
+      end
     end
   end
 end

data/lib/pragma/decorator/association/reflection.rb

@@ -5,7 +5,7 @@ module Pragma
     module Association
       # Holds the information about an association.
       #
-      # @author Alessandro Desantis
+      # @api private
       class Reflection
         # @!attribute [r] type
         #   @return [Symbol] the type of the association