pragma-decorator 2.0.0 → 2.1.0

data/lib/pragma/decorator/association.rb

@@ -2,21 +2,58 @@
 
 module Pragma
   module Decorator
+    # Associations provide a way to define related records on your decorators.
+    #
+    # Once you define an association, it can be expanded by API clients through the +expand+ query
+    # parameter to load the full record.
+    #
+    # @example Defining and expanding an association
+    #   class ArticleDecorator < Pragma::Decorator::Base
+    #     belongs_to :author, decorator: API::V1::User::Decorator
+    #   end
+    #
+    #   # This will return a hash whose `author` key is the ID of the article's author.
+    #   ArticleDecorator.new(article).to_hash
+    #
+    #   # This will return a hash whose `author` key is a hash representing the decorated
+    #   # article's author.
+    #   ArticleDecorator.new(article).to_hash(user_options: { expand: ['author'] })
     module Association
       def self.included(klass)
         klass.extend ClassMethods
         klass.include InstanceMethods
       end
 
-      module ClassMethods # rubocop:disable Style/Documentation
+      module ClassMethods # :nodoc:
+        # Returns the associations defined on this decorator.
+        #
+        # @return [Hash{Symbol => Reflection}] the associations
         def associations
           @associations ||= {}
         end
 
+        # Defines a +belongs_to+ association on this decorator.
+        #
+        # This will first create an association definition and then define a new property with the
+        # name of the association.
+        #
+        # This method supports all the usual options accepted by +#property+.
+        #
+        # @param property_name [Symbol] name of the association
+        # @param options [Hash] the association's options
         def belongs_to(property_name, options = {})
           define_association :belongs_to, property_name, options
         end
 
+        # Defines a +has_one+ association on this decorator.
+        #
+        # This will first create an association definition and then define a new property with the
+        # name of the association.
+        #
+        # This method supports all the usual options accepted by +#property+.
+        #
+        # @param property_name [Symbol] name of the association
+        # @param options [Hash] the association's options
         def has_one(property_name, options = {}) # rubocop:disable Naming/PredicateName
           define_association :has_one, property_name, options
         end
@@ -35,12 +72,12 @@ module Pragma
         def create_association_property(_type, property_name, options)
           property_options = options.dup.tap { |po| po.delete(:decorator) }.merge(
             exec_context: :decorator,
-            as: property_name,
+            as: options[:as] || property_name,
             getter: (lambda do |decorator:, user_options:, **_args|
-              Binding.new(
+              Bond.new(
                 reflection: decorator.class.associations[property_name],
                 decorator: decorator
-              ).render(user_options[:expand])
+              ).render(user_options)
             end)
           )
 
@@ -48,7 +85,7 @@ module Pragma
         end
       end
 
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
         def validate_expansion(expand)
           check_parent_associations_are_expanded(expand)
           check_expanded_associations_exist(expand)

data/lib/pragma/decorator/base.rb

@@ -7,9 +7,7 @@ module Pragma
   module Decorator
     # This is the base decorator that all your resource-specific decorators should extend from.
     #
-    # It is already configured to render your resources in JSON.
-    #
-    # @author Alessandro Desantis
+    # It is already configured to render your resources as JSON.
     class Base < Roar::Decorator
       feature Roar::JSON
 

data/lib/pragma/decorator/collection.rb

@@ -2,6 +2,33 @@
 
 module Pragma
   module Decorator
+    # This module is used to represent collections of objects.
+    #
+    # It will wrap the collection in a +data+ property so that you can include meta-data about the
+    # collection at the root level.
+    #
+    # @example Using Collection to include a total count
+    #   class ArticlesDecorator < Pragma::Decorator::Base
+    #     include Pragma::Decorator::Collection
+    #
+    #     decorate_with ArticleDecorator
+    #
+    #     property :total_count, exec_context: :decorator
+    #
+    #     def total_count
+    #       represented.count
+    #     end
+    #   end
+    #
+    #   # {
+    #   #   "data": [
+    #   #     { "...": "..." },
+    #   #     { "...": "..." },
+    #   #     { "...": "..." }
+    #   #   ],
+    #   #   "total_count": 150
+    #   # }
+    #   ArticlesDecorator.new(Article.all).to_hash
     module Collection
       def self.included(klass)
         klass.include InstanceMethods
@@ -12,13 +39,21 @@ module Pragma
         end
       end
 
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
+        # Overrides the type of the resource to be +list+, for compatibility with {Type}.
+        #
+        # @see Type
         def type
-          'collection'
+          'list'
         end
       end
 
-      module ClassMethods
+      module ClassMethods # :nodoc:
+        # Defines the decorator to use for each resource in the collection.
+        #
+        # @param decorator [Class] a decorator class
+        #
+        # @todo Accept a callable/block or document how to decorate polymorphic collections
         def decorate_with(decorator)
           collection :represented, as: :data, exec_context: :decorator, decorator: decorator
         end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Pagination
+      module Adapter
+        # This is the base pagination adapter.
+        #
+        # @abstract Subclass and override the abstract methods to implement an adapter
+        #
+        # @api private
+        class Base
+          # @!attribute [r] collection
+          #   @return [Object] the collection this adapter is working with
+          attr_reader :collection
+
+          class << self
+            # Returns whether this adapter supports the given collection.
+            #
+            # @return [Boolean] whether the adapter supports the given collection
+            #
+            # @see Adapter.load_for
+            def supports?(_collection)
+              fail NotImplementedError
+            end
+          end
+
+          # Initializes the adapter.
+          #
+          # @param collection [Object] the collection to work with
+          def initialize(collection)
+            @collection = collection
+          end
+
+          # Returns the total number of entries in the collection.
+          #
+          # @return [Integer] the total number of entries in the collection
+          def total_entries
+            fail NotImplementedError
+          end
+
+          # Returns the number of entries per page in the collection.
+          #
+          # @return [Integer] the number of entries per page in the collection
+          def per_page
+            fail NotImplementedError
+          end
+
+          # Returns the total number of pages in the collection.
+          #
+          # @return [Integer] the total number of pages in the collection
+          def total_pages
+            fail NotImplementedError
+          end
+
+          # Returns the number of the previous page, if any.
+          #
+          # @return [Integer|NilClass] the number of the previous page, if any
+          def previous_page
+            fail NotImplementedError
+          end
+
+          # Returns the number of the current page.
+          #
+          # @return [Integer] the number of the current page
+          def current_page
+            fail NotImplementedError
+          end
+
+          # Returns the number of the next page, if any.
+          #
+          # @return [Integer|NilClass] the number of the next page, if any
+          def next_page
+            fail NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/pagination/adapter/kaminari.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Pagination
+      module Adapter
+        # This adapter provides support for retireving pagination information from collections
+        # paginated with {https://github.com/kaminari/kaminari Kaminari}.
+        #
+        # @api private
+        class Kaminari < Base
+          class << self
+            # Returns whether this adapter supports the given collection.
+            #
+            # Esnures that the +Kaminari+ constant is defined and that the collection responds to
+            # +#prev_page+.
+            #
+            # @return [Boolean] whether the adapter supports the given collection
+            #
+            # @see Adapter.load_for
+            def supports?(collection)
+              Object.const_defined?('Kaminari') && collection.respond_to?(:prev_page)
+            end
+          end
+
+          # Returns the total number of entries in the collection.
+          #
+          # @return [Integer] the total number of entries in the collection
+          def total_entries
+            collection.total_count
+          end
+
+          # Returns the number of entries per page in the collection.
+          #
+          # @return [Integer] the number of entries per page in the collection
+          def per_page
+            collection.limit_value
+          end
+
+          # Returns the total number of pages in the collection.
+          #
+          # @return [Integer] the total number of pages in the collection
+          def total_pages
+            collection.total_pages
+          end
+
+          # Returns the number of the previous page, if any.
+          #
+          # @return [Integer|NilClass] the number of the previous page, if any
+          def previous_page
+            collection.prev_page
+          end
+
+          # Returns the number of the current page.
+          #
+          # @return [Integer] the number of the current page
+          def current_page
+            collection.current_page
+          end
+
+          # Returns the number of the next page, if any.
+          #
+          # @return [Integer|NilClass] the number of the next page, if any
+          def next_page
+            collection.next_page
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/pagination/adapter/will_paginate.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Pagination
+      module Adapter
+        # This adapter provides support for retireving pagination information from collections
+        # paginated with {https://github.com/mislav/will_paginate will_paginate}.
+        #
+        # @api private
+        class WillPaginate < Base
+          class << self
+            # Returns whether this adapter supports the given collection.
+            #
+            # Esnures that the +WillPaginate+ constant is defined and that the collection responds
+            # to +#previous_page+.
+            #
+            # @return [Boolean] whether the adapter supports the given collection
+            #
+            # @see Adapter.load_for
+            def supports?(collection)
+              Object.const_defined?('WillPaginate') && collection.respond_to?(:previous_page)
+            end
+          end
+
+          # Returns the total number of entries in the collection.
+          #
+          # @return [Integer] the total number of entries in the collection
+          def total_entries
+            collection.total_entries
+          end
+
+          # Returns the number of entries per page in the collection.
+          #
+          # @return [Integer] the number of entries per page in the collection
+          def per_page
+            collection.per_page
+          end
+
+          # Returns the total number of pages in the collection.
+          #
+          # @return [Integer] the total number of pages in the collection
+          def total_pages
+            collection.total_pages
+          end
+
+          # Returns the number of the previous page, if any.
+          #
+          # @return [Integer|NilClass] the number of the previous page, if any
+          def previous_page
+            collection.previous_page
+          end
+
+          # Returns the number of the current page.
+          #
+          # @return [Integer] the number of the current page
+          def current_page
+            collection.current_page
+          end
+
+          # Returns the number of the next page, if any.
+          #
+          # @return [Integer|NilClass] the number of the next page, if any
+          def next_page
+            collection.next_page
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Pagination
+      # Adapters make pagination library-independent by providing support for multiple underlying
+      # libraries like Kaminari and will_paginate.
+      #
+      # @api private
+      module Adapter
+        # The list of supported adapters, in order of priority.
+        SUPPORTED_ADAPTERS = [Kaminari, WillPaginate].freeze
+
+        # Loads the adapter for the given collection.
+        #
+        # This will try {SUPPORTED_ADAPTERS} in order until it finds an adapter that supports the
+        # collection. When the adapter is found, it will return a new instance of it.
+        #
+        # @param collection [Object] the collection to load the adapter for
+        #
+        # @return [Adapter::Base]
+        #
+        # @see Adapter::Base.supports?
+        #
+        # @raise [AdapterError] if no adapter supports the collection
+        def self.load_for(collection)
+          adapter_klass = SUPPORTED_ADAPTERS.find do |klass|
+            klass.supports?(collection)
+          end
+
+          fail NoAdapterError unless adapter_klass
+
+          adapter_klass.new(collection)
+        end
+
+        # This error is raised when no adapter can be found for a collection.
+        class NoAdapterError < StandardError
+          # Initializes the adapter.
+          def initialize
+            message = <<~MESSAGE.tr("\n", ' ')
+              No adapter found for the collection. The available adapters are:
+              #{SUPPORTED_ADAPTERS.map { |a| a.to_s.split('::').last }.join(', ')}.
+            MESSAGE
+
+            super message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/pagination.rb

@@ -2,44 +2,93 @@
 
 module Pragma
   module Decorator
+    # Pagination provides support for including pagination metadata in your collection.
+    #
+    # It is particularly useful when used in conjunction with {Collection}.
+    #
+    # It supports both {https://github.com/kaminari/kaminari Kaminari} and
+    # {https://github.com/mislav/will_paginate will_paginate}.
+    #
+    # @example Including pagination metadata
+    #   class ArticlesDecorator < Pragma::Decorator::Base
+    #     include Pragma::Decorator::Collection
+    #     include Pragma::Decorator::Pagination
+    #   end
+    #
+    #   # {
+    #   #   "data": [
+    #   #     { "...": "..." },
+    #   #     { "...": "..." },
+    #   #     { "...": "..." }
+    #   #   ],
+    #   #   "total_entries": 150,
+    #   #   "per_page": 30,
+    #   #   "total_pages": 5,
+    #   #   "previous_page": 2,
+    #   #   "current_page": 3,
+    #   #   "next_page": 4
+    #   # }
+    #   ArticlesDecorator.new(Article.all).to_hash
     module Pagination
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
+        # Returns the current page of the collection.
+        #
+        # @return [Integer] current page number
+        #
+        # @see Adapter::Base#current_page
         def current_page
-          represented.current_page.to_i
+          adapter.current_page
         end
 
+        # Returns the next page of the collection.
+        #
+        # @return [Integer|NilClass] next page number, if any
+        #
+        # @see Adapter::Base#next_page
         def next_page
-          represented.next_page
+          adapter.next_page
         end
 
+        # Returns the number of items per page in the collection.
+        #
+        # @return [Integer] items per page
+        #
+        # @see Adapter::Base#per_page
         def per_page
-          per_page_method = if represented.respond_to?(:per_page)
-            :per_page
-          else
-            :limit_value
-          end
-
-          represented.public_send(per_page_method)
+          adapter.per_page
         end
 
+        # Returns the previous page of the collection.
+        #
+        # @return [Integer|NilClass] previous page number, if any
+        #
+        # @see Adapter::Base#previous_page
         def previous_page
-          previous_page_method = if represented.respond_to?(:previous_page)
-            :previous_page
-          else
-            :prev_page
-          end
-
-          represented.public_send(previous_page_method)
+          adapter.previous_page
         end
 
+        # Returns the total number of items in the collection.
+        #
+        # @return [Integer] number of items
+        #
+        # @see Adapter::Base#total_entries
         def total_entries
-          total_entries_method = if represented.respond_to?(:total_entries)
-            :total_entries
-          else
-            :total_count
-          end
+          adapter.total_entries
+        end
+
+        # Returns the total number of pages in the collection.
+        #
+        # @return [Integer] number of pages
+        #
+        # @see Adapter::Base#total_pages
+        def total_pages
+          adapter.total_pages
+        end
+
+        private
 
-          represented.public_send(total_entries_method)
+        def adapter
+          @adapter ||= Pagination::Adapter.load_for(represented)
         end
       end
 
@@ -49,7 +98,7 @@ module Pragma
         klass.class_eval do
           property :total_entries, exec_context: :decorator
           property :per_page, exec_context: :decorator
-          property :total_pages
+          property :total_pages, exec_context: :decorator
           property :previous_page, exec_context: :decorator
           property :current_page, exec_context: :decorator
           property :next_page, exec_context: :decorator

data/lib/pragma/decorator/timestamp.rb

@@ -4,13 +4,21 @@ module Pragma
   module Decorator
     # Supports rendering timestamps as UNIX times.
     #
-    # @author Alessandro Desantis
+    # @example Rendering a timestamp as UNIX time
+    #   class ArticleDecorator < Pragma::Decorator::Base
+    #     timestamp :created_at
+    #   end
+    #
+    #   # {
+    #   #   "created_at": 1515250106
+    #   # }
+    #   ArticleDecorator.new(article).to_hash
     module Timestamp
       def self.included(klass)
         klass.extend ClassMethods
       end
 
-      module ClassMethods # rubocop:disable Style/Documentation
+      module ClassMethods # :nodoc:
         # Defines a timestamp property which will be rendered as UNIX time.
         #
         # @param name [Symbol] the name of the property
@@ -34,7 +42,7 @@ module Pragma
 
         def create_timestamp_property(name, options = {})
           property "_#{name}_timestamp", options.merge(
-            as: name,
+            as: options[:as] || name,
             exec_context: :decorator
           )
         end

data/lib/pragma/decorator/type.rb

@@ -4,28 +4,59 @@ module Pragma
   module Decorator
     # Adds a +type+ property containing the machine-readable type of the represented object.
     #
-    # @author Alessandro Desantis
+    # This is useful for the client to understand what kind of resource it's dealing with
+    # and trigger related logic.
+    #
+    # @example Including the resource's type
+    #   class ArticleDecorator < Pragma::Decorator::Base
+    #     include Pragma::Decorator::Type
+    #   end
+    #
+    #   # {
+    #   #   "type": "article"
+    #   # }
+    #   ArticleDecorator.new(article).to_hash
     module Type
-      TYPE_OVERRIDES = {
-        array: 'list'
-      }.freeze
+      class << self
+        def included(klass)
+          klass.class_eval do
+            property :type, exec_context: :decorator, render_nil: false
+          end
+        end
 
-      def self.included(klass)
-        klass.class_eval do
-          property :type, exec_context: :decorator, render_nil: false
+        # Returns the type overrides.
+        #
+        # By default, +Array+ and +ActiveRecord::Relation+ are renamed to +list+.
+        #
+        # @return [Hash{String => String}] a hash of class-override pairs
+        def overrides
+          @overrides ||= {
+            'Array' => 'list',
+            'ActiveRecord::Relation' => 'list'
+          }
         end
       end
 
-      # Returns the type of the decorated object (i.e. its underscored class name).
+      # Returns the type to expose to API clients.
+      #
+      # If an override is present for the decorated class, returns the override, otherwise returns
+      # the underscored class.
+      #
+      # @return [String] type to expose
       #
-      # @return [String]
+      # @see .overrides
       def type
-        type = decorated.class.name
+        Pragma::Decorator::Type.overrides[decorated.class.name] ||
+          underscore_klass(decorated.class.name)
+      end
+
+      private
+
+      def underscore_klass(klass)
+        klass
           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
           .downcase
-
-        TYPE_OVERRIDES[type.to_sym] || type
       end
     end
   end

data/lib/pragma/decorator/version.rb

@@ -2,6 +2,6 @@
 
 module Pragma
   module Decorator
-    VERSION = '2.0.0'
+    VERSION = '2.1.0'
   end
 end