pragma-decorator 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1d247ca8e236d5a993b70a518c5f64fc82e9ed80
-  data.tar.gz: 145c3dbf948aa6bbc8e2d63b2e49126778d417b7
+  metadata.gz: 4cc969bd13e27d434cc079786db43b29ae6b6154
+  data.tar.gz: cfefba30c1aab7b6d53db48031df9e991159537e
 SHA512:
-  metadata.gz: 55cb0eacc764ba44011b43c0bb9e1203202dc43d7b395379bf016295ba0a268e0c1dcacfe268dd8238d452cd6dbc5d210bec792fb7a1d6dad3d89c9a7ac32ab7
-  data.tar.gz: 105d6b13dbcfa5e31943739840e73c39a0aca84da28a4d248cc97d760f160458fc313d354e7d236b98c44a59017bd3af2428a0868e164d90de1f7f703dc31199
+  metadata.gz: 26574df0b3a1807c18fe1c156feadf6ea37947fcb044f1587d4de0319782af2164cb5a7c591a99bb954d187b0ec6c6e5c499150eba89be2ab04c8b36c00a6763
+  data.tar.gz: d502113406896fd913100c0ededa0242ead3fc8fa1d1cdd7545d2bff0ed15fe9d8a227beac6f3177f22189354223c9bada76a62f02f188b4119b3549bab0c51d

data/.rubocop.yml

@@ -15,6 +15,7 @@ AllCops:
    - 'config/**/*'
    - '**/Rakefile'
    - '**/Gemfile'
+   - 'pragma-decorator.gemspec'
 
 RSpec/DescribeClass:
   Exclude:
@@ -24,26 +25,26 @@ Style/BlockDelimiters:
   Exclude:
     - 'spec/**/*'
 
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
-Style/ClosingParenthesisIndentation:
+Layout/ClosingParenthesisIndentation:
   Enabled: false
 
 Metrics/LineLength:
   Max: 100
   AllowURI: true
 
-Style/FirstParameterIndentation:
+Layout/FirstParameterIndentation:
   Enabled: false
 
-Style/MultilineMethodCallIndentation:
+Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
-Style/IndentArray:
+Layout/IndentArray:
   EnforcedStyle: consistent
 
-Style/IndentHash:
+Layout/IndentHash:
   EnforcedStyle: consistent
 
 Style/SignalException:
@@ -68,7 +69,7 @@ RSpec/NamedSubject:
 RSpec/ExampleLength:
   Enabled: false
 
-Style/MultilineMethodCallBraceLayout:
+Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
 Metrics/MethodLength:
@@ -86,12 +87,8 @@ Metrics/CyclomaticComplexity:
 Metrics/BlockLength:
   Enabled: false
 
-Metrics/ClassLength:
-  Enabled: false
-
 Style/GuardClause:
   Enabled: false
 
-Naming/FileName:
-  Exclude:
-    - 'pragma-decorator.gemspec'
+Capybara/FeatureMethods:
+  Enabled: false

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in pragma-decorator.gemspec
 gemspec
+
+gem 'pry'

data/README.md

@@ -7,8 +7,8 @@
 
 Decorators are a way to easily convert your API resources to JSON with minimum hassle.
 
-They are built on top of [ROAR](https://github.com/apotonick/roar) but provide some useful helpers
-for rendering collections, including pagination metadata and expanding associations.
+They are built on top of [ROAR](https://github.com/apotonick/roar). We provide some useful helpers
+for rendering collections, expanding associations and much more.
 
 ## Installation
 
@@ -32,7 +32,286 @@ $ gem install pragma-decorator
 
 ## Usage
 
-All documentation is in the [doc](https://github.com/pragmarb/pragma-decorator/tree/master/doc) folder.
+Creating a decorator is as simple as inheriting from `Pragma::Decorator::Base`:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Instance < Pragma::Decorator::Base
+          property :id
+          property :email
+          property :full_name
+        end
+      end
+    end
+  end
+end
+```
+
+Just instantiate the decorator by passing it an object to decorate, then call `#to_hash` or
+`#to_json`:
+
+```ruby
+decorator = API::V1::User::Decorator::Instance.new(user)
+decorator.to_json
+```
+
+This will produce the following JSON:
+
+```json
+{
+  "id": 1,
+  "email": "jdoe@example.com",
+  "full_name": "John Doe"
+}
+```
+
+Since Pragma::Decorator is built on top of [ROAR](https://github.com/apotonick/roar) (which, in
+turn, is built on top of [Representable](https://github.com/apotonick/representable)), you should
+consult their documentation for the basic usage of decorators; the rest of this section only covers
+the features provided specifically by Pragma::Decorator.
+
+### Object Types
+
+It is recommended that decorators expose the type of the decorated object. You can achieve this
+with the `Type` mixin:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Instance < Pragma::Decorator::Base
+          feature Pragma::Decorator::Type
+        end
+      end
+    end
+  end
+end
+```
+
+This would result in the following representation:
+
+```json
+{
+  "type": "user",
+  "...": "...""
+}
+```
+
+You can also set a custom type name (just make sure to use it consistently!):
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Instance < Pragma::Decorator::Base
+          def type
+            :custom_type
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Note: `array` is already overridden with the more language-agnostic `list`.
+
+### Timestamps
+
+[UNIX time](https://en.wikipedia.org/wiki/Unix_time) is your safest bet when rendering/parsing
+timestamps in your API, as it doesn't require a timezone indicator (the timezone is always UTC).
+
+You can use the `Timestamp` mixin for converting `Time` instances to UNIX times:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Instance < Pragma::Decorator::Base
+          feature Pragma::Decorator::Timestamp
+
+          timestamp :created_at
+        end
+      end
+    end
+  end
+end
+```
+
+This will render a user like this:
+
+```json
+{
+  "type": "user",
+  "created_at": 1480287994
+}
+```
+
+The `#timestamp` method supports all the options supported by `#property` (except for `:as`).
+
+### Associations
+
+`Pragma::Decorator::Association` allows you to define associations in your decorator (currently,
+only `belongs_to`/`has_one` associations are supported):
+
+```ruby
+module API
+  module V1
+    module Invoice
+      module Decorator
+        class Instance < Pragma::Decorator::Base
+          feature Pragma::Decorator::Association
+
+          belongs_to :customer, decorator: API::V1::Customer::Decorator
+        end
+      end
+    end
+  end
+end
+```
+
+Rendering an invoice will now create the following representation:
+
+```json
+{
+  "customer": 19
+}
+```
+
+You can pass `expand[]=customer` as a request parameter and have the `customer` property expanded 
+into a full object!
+
+```json
+{
+  "customer": {
+    "id": 19,
+    "...": "..."
+  }
+}
+```
+
+This also works for nested associations. For instance, if the customer decorator had a `company`
+association, you could pass `expand[]=customer&expand[]=customer.company` to get the company 
+expanded too.
+
+Note that you will have to pass the associations to expand as a user option when rendering:
+
+```ruby
+decorator = API::V1::Invoice::Decorator::Instance.new(invoice)
+decorator.to_json(user_options: {
+  expand: ['customer', 'customer.company', 'customer.company.contact']
+})
+```
+
+Needless to say, this is done automatically for you when you use all components together through
+the [pragma](https://github.com/pragmarb/pragma) gem! :)
+
+### Collection
+
+`Pragma::Decorator::Collection` wraps collections in a `data` property so that you can include
+metadata about them:
+
+```ruby
+module API
+  module V1
+    module Invoice
+      module Decorator
+        class Collection < Pragma::Decorator::Base
+          feature Pragma::Decorator::Collection
+          decorate_with Instance # specify the instance decorator
+          
+          property :total_cents, exec_context: :decorator
+          
+          def total_cents
+            represented.sum(:total_cents)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+You can now do this:
+
+```ruby
+API::V1::Invoice::Decorator::Collection.new(Invoice.all).to_json
+```
+
+Which will produce the following JSON:
+
+```json
+{
+  "data": [{
+    "id": 1,
+    "total_cents": 1500,
+  }, {
+    "id": 2,
+    "total_cents": 3000,
+  }],
+  "total_cents": 4500
+}
+```
+
+This is very useful, for instance, when you have a paginated collection, but want to include data
+about the entire collection (not just the current page) in the response.
+
+### Pagination
+
+Speaking of pagination, you can use `Pragma::Decorator::Pagination` in combination with 
+`Collection` to include pagination data in your response:
+
+```ruby
+module API
+  module V1
+    module Invoice
+      module Decorator
+        class Collection < Pragma::Decorator::Base
+          feature Pragma::Decorator::Collection
+          feature Pragma::Decorator::Pagination
+          
+          decorate_with Instance
+        end
+      end
+    end
+  end
+end
+```
+
+Now, you can run this code:
+
+```ruby
+API::V1::Invoice::Decorator::Collection.new(Invoice.all).to_json
+```
+
+Which will produce the following JSON:
+
+```json
+{
+  "data": [{
+    "id": 1,
+    "...": "...",
+  }, {
+    "id": 2,
+    "...": "...",
+  }],
+  "total_entries": 2,
+  "per_page": 30,
+  "total_pages": 1,
+  "previous_page": null,
+  "current_page": 1,
+  "next_page": null
+}
+```
+
+It works with both [will_paginate](https://github.com/mislav/will_paginate) and 
+[Kaminari](https://github.com/kaminari/kaminari)!
 
 ## Contributing
 

data/lib/pragma/decorator.rb

@@ -7,10 +7,11 @@ require 'pragma/decorator/base'
 require 'pragma/decorator/association'
 require 'pragma/decorator/association/reflection'
 require 'pragma/decorator/association/binding'
-require 'pragma/decorator/association/unexpandable_error'
-require 'pragma/decorator/association/inconsistent_type_error'
+require 'pragma/decorator/association/errors'
 require 'pragma/decorator/timestamp'
 require 'pragma/decorator/type'
+require 'pragma/decorator/collection'
+require 'pragma/decorator/pagination'
 
 module Pragma
   # Represent your API resources in JSON with minimum hassle.

data/lib/pragma/decorator/association.rb

@@ -2,88 +2,84 @@
 
 module Pragma
   module Decorator
-    # Adds association expansion to decorators.
-    #
-    # @author Alessandro Desantis
     module Association
       def self.included(klass)
         klass.extend ClassMethods
+        klass.include InstanceMethods
+      end
 
-        klass.class_eval do
-          @associations = {}
-
-          def self.associations
-            @associations
-          end
+      module ClassMethods # rubocop:disable Style/Documentation
+        def associations
+          @associations ||= {}
         end
-      end
 
-      # Inizializes the decorator and bindings for all the associations.
-      #
-      # @see Association::Binding
-      def initialize(*)
-        super
+        def belongs_to(property_name, options = {})
+          define_association :belongs_to, property_name, options
+        end
 
-        @association_bindings = {}
-        self.class.associations.each_pair do |property, reflection|
-          @association_bindings[property] = Binding.new(reflection: reflection, decorator: self)
+        def has_one(property_name, options = {}) # rubocop:disable Naming/PredicateName
+          define_association :has_one, property_name, options
         end
-      end
 
-      module ClassMethods # rubocop:disable Style/Documentation
-        # Defines a +belongs_to+ association.
-        #
-        # See {Association::Reflection#initialize} for the list of available options.
-        #
-        # @param property [Symbol] the property containing the associated object
-        # @param options [Hash] the options of the association
-        def belongs_to(property, options = {})
-          define_association :belongs_to, property, options
+        private
+
+        def define_association(type, property_name, options = {})
+          create_association_definition(type, property_name, options)
+          create_association_property(type, property_name, options)
         end
 
-        # Defines a +has_one+ association.
-        #
-        # See {Association::Reflection#initialize} for the list of available options.
-        #
-        # @param property [Symbol] the property containing the associated object
-        # @param options [Hash] the options of the association
-        def has_one(property, options = {}) # rubocop:disable Style/PredicateName
-          define_association :has_one, property, options
+        def create_association_definition(type, property_name, options)
+          associations[property_name.to_sym] = Reflection.new(type, property_name, options)
         end
 
-        private
+        def create_association_property(_type, property_name, options)
+          property_options = options.dup.tap { |po| po.delete(:decorator) }.merge(
+            exec_context: :decorator,
+            as: property_name,
+            getter: (lambda do |decorator:, user_options:, **_args|
+              Binding.new(
+                reflection: decorator.class.associations[property_name],
+                decorator: decorator
+              ).render(user_options[:expand])
+            end)
+          )
 
-        def define_association(type, property, options = {})
-          create_association_definition(type, property, options)
-          create_association_getter(property)
-          create_association_property(property)
+          property("_#{property_name}_association", property_options)
         end
+      end
 
-        def create_association_definition(type, property, options)
-          @associations[property.to_sym] = Reflection.new(type, property, options)
+      module InstanceMethods
+        def validate_expansion(expand)
+          check_parent_associations_are_expanded(expand)
+          check_expanded_associations_exist(expand)
         end
 
-        def create_association_getter(property)
-          code = <<~RUBY
-            def _#{property}_association
-              @association_bindings[:#{property}].render(user_options[:expand])
-            end
-          RUBY
+        private
+
+        def check_parent_associations_are_expanded(expand)
+          expand = normalize_expand(expand)
+
+          expand.each do |property|
+            next unless property.include?('.')
 
-          class_eval code, __FILE__, __LINE__
+            parent_path = property.split('.')[0..-2].join('.')
+            next if expand.include?(parent_path)
+
+            fail Association::UnexpandedAssociationParent.new(property, parent_path)
+          end
         end
 
-        def create_association_property(property_name)
-          options = {
-            exec_context: :decorator,
-            as: property_name
-          }.tap do |opts|
-            if @associations[property_name].options.key?(:render_nil)
-              opts[:render_nil] = @associations[property_name].options[:render_nil]
-            end
+        def check_expanded_associations_exist(expand)
+          expand = normalize_expand(expand)
+
+          expand.each do |property|
+            next if self.class.associations.key?(property.to_sym) || property.include?('.')
+            fail Association::AssociationNotFound, property
           end
+        end
 
-          property("_#{property_name}_association", options)
+        def normalize_expand(expand)
+          [expand].flatten.map(&:to_s).reject(&:blank?)
         end
       end
     end

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

@@ -21,8 +21,6 @@ module Pragma
         def initialize(reflection:, decorator:)
           @reflection = reflection
           @decorator = decorator
-
-          check_type_consistency
         end
 
         # Returns the associated object.
@@ -31,52 +29,18 @@ module Pragma
         def associated_object
           case reflection.options[:exec_context]
           when :decorated
-            model.public_send(reflection.property)
+            decorator.decorated.send(reflection.property)
           when :decorator
-            decorator.public_send(reflection.property)
+            decorator.send(reflection.property)
           end
         end
 
-        # Returns whether the association belongs to the model.
-        #
-        # @return [Boolean]
-        def model_context?
-          reflection.options[:exec_context].to_sym == :decorated
-        end
-
-        # Returns whether the association belongs to the decorator.
-        #
-        # @return [Boolean]
-        def decorator_context?
-          reflection.options[:exec_context].to_sym == :decorator
-        end
-
         # Returns the unexpanded value for the associated object (i.e. its +id+ property).
         #
         # @return [String]
         def unexpanded_value
-          if decorator_context? || model_reflection.nil? || !reflection.options[:optimize]
-            return associated_object&.public_send(associated_object.class.primary_key)
-          end
-
-          case reflection.type
-          when :belongs_to
-            model.public_send(model_reflection.foreign_key)
-          when :has_one
-            if model.association(reflection.property).loaded?
-              return associated_object&.public_send(associated_object.class.primary_key)
-            end
-
-            pk = model.public_send(model_reflection.active_record_primary_key)
-
-            model_reflection
-              .klass
-              .where(model_reflection.foreign_key => pk)
-              .pluck(model_reflection.klass.primary_key)
-              .first
-          else
-            associated_object&.public_send(associated_object.class.primary_key)
-          end
+          return unless associated_object
+          associated_object.id
         end
 
         # Returns the expanded value for the associated object.
@@ -92,11 +56,7 @@ module Pragma
         # @param expand [Array<String>] the associations to expand
         #
         # @return [Hash]
-        #
-        # @raise [UnexpandableError] if the association is not expandable
         def expanded_value(expand)
-          fail UnexpandableError, reflection unless reflection.expandable?
-
           return unless associated_object
 
           options = {
@@ -153,36 +113,6 @@ module Pragma
             reflection.options[:decorator]
           end
         end
-
-        def model
-          decorator.decorated
-        end
-
-        def model_reflection
-          # rubocop:disable Metrics/LineLength
-          @model_reflection ||= if Object.const_defined?('ActiveRecord') && model.is_a?(ActiveRecord::Base)
-            model.class.reflect_on_association(reflection.property)
-          end
-          # rubocop:enable Metrics/LineLength
-        end
-
-        def model_association_type
-          return unless model_reflection
-
-          if Object.const_defined?('ActiveRecord') && model.is_a?(ActiveRecord::Base)
-            model_reflection.macro
-          end
-        end
-
-        def check_type_consistency
-          return if !model_association_type || model_association_type == reflection.type
-
-          fail InconsistentTypeError.new(
-            decorator: decorator,
-            reflection: reflection,
-            model_type: model_association_type
-          )
-        end
       end
     end
   end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Association
+      class ExpansionError < StandardError
+      end
+
+      class AssociationNotFound < ExpansionError
+        attr_reader :property
+
+        def initialize(property)
+          @property = property
+          super "The '#{property}' association is not defined."
+        end
+      end
+
+      class UnexpandedAssociationParent < ExpansionError
+        attr_reader :child, :parent
+
+        def initialize(child, parent)
+          @child = child
+          @parent = parent
+
+          super "The '#{child}' association is expanded, but its parent '#{parent}' is not."
+        end
+      end
+    end
+  end
+end

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

@@ -23,7 +23,6 @@ module Pragma
         # @param property [Symbol] the property holding the associated object
         # @param options [Hash] additional options
         #
-        # @option options [Boolean] :expandable (`false`) whether the association is expandable
         # @option options [Class|Proc] :decorator the decorator to use for the associated object
         #   or a callable that will return the decorator class (or +nil+ to skip decoration)
         # @option options [Boolean] :render_nil (`true`) whether to render a +nil+ association
@@ -38,33 +37,31 @@ module Pragma
           validate_options
         end
 
-        # Returns whether the association is expandable.
-        #
-        # @return [Boolean]
-        def expandable?
-          options[:expandable]
-        end
-
         private
 
         def normalize_options
           @options = {
-            expandable: false,
-            render_nil: false,
-            exec_context: :decorated,
-            optimize: true,
+            render_nil: true,
+            exec_context: :decorated
           }.merge(options).tap do |opts|
             opts[:exec_context] = opts[:exec_context].to_sym
           end
         end
 
         def validate_options
-          return if %i[decorator decorated].include?(options[:exec_context])
+          unless %i[decorator decorated].include?(options[:exec_context])
+            fail(
+              ArgumentError,
+              "'#{options[:exec_context]}' is not a valid value for :exec_context."
+            )
+          end
 
-          fail(
-            ArgumentError,
-            "'#{options[:exec_context]}' is not a valid value for :exec_context."
-          )
+          unless options[:decorator]
+            fail(
+              ArgumentError,
+              'The :decorator option is required.'
+            )
+          end
         end
       end
     end

data/lib/pragma/decorator/base.rb

@@ -13,36 +13,7 @@ module Pragma
     class Base < Roar::Decorator
       feature Roar::JSON
 
-      # Overrides Representable's default +#to_hash+ to save the last options the method was run
-      # with.
-      #
-      # This allows accessing the options from property getters and is required by {Association}.
-      #
-      # @param options [Hash]
-      #
-      # @return [Hash]
-      def to_hash(options = {}, *args)
-        @last_options = options
-        super(options, *args)
-      end
-
-      protected
-
-      # Returns the options +#to_hash+ was last run with.
-      #
-      # @return [Hash]
-      def options
-        @last_options
-      end
-
-      # Returns the user options +#to_hash+ was last run with.
-      #
-      # @return [Hash]
-      #
-      # @see #options
-      def user_options
-        @last_options[:user_options] || {}
-      end
+      defaults render_nil: true
     end
   end
 end

data/lib/pragma/decorator/collection.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Collection
+      def self.included(klass)
+        klass.include InstanceMethods
+        klass.extend ClassMethods
+
+        klass.class_eval do
+          collection :represented, as: :data, exec_context: :decorator
+        end
+      end
+
+      module InstanceMethods
+        def type
+          'collection'
+        end
+      end
+
+      module ClassMethods
+        def decorate_with(decorator)
+          collection :represented, as: :data, exec_context: :decorator, decorator: decorator
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/pagination.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Decorator
+    module Pagination
+      module InstanceMethods
+        def current_page
+          represented.current_page.to_i
+        end
+
+        def next_page
+          represented.next_page
+        end
+
+        def per_page
+          per_page_method = if represented.respond_to?(:per_page)
+            :per_page
+          else
+            :limit_value
+          end
+
+          represented.public_send(per_page_method)
+        end
+
+        def previous_page
+          previous_page_method = if represented.respond_to?(:previous_page)
+            :previous_page
+          else
+            :prev_page
+          end
+
+          represented.public_send(previous_page_method)
+        end
+
+        def total_entries
+          total_entries_method = if represented.respond_to?(:total_entries)
+            :total_entries
+          else
+            :total_count
+          end
+
+          represented.public_send(total_entries_method)
+        end
+      end
+
+      def self.included(klass)
+        klass.include InstanceMethods
+
+        klass.class_eval do
+          property :total_entries, exec_context: :decorator
+          property :per_page, exec_context: :decorator
+          property :total_pages
+          property :previous_page, exec_context: :decorator
+          property :current_page, exec_context: :decorator
+          property :next_page, exec_context: :decorator
+        end
+      end
+    end
+  end
+end

data/lib/pragma/decorator/timestamp.rb

@@ -24,7 +24,7 @@ module Pragma
 
         def create_timestamp_getter(name, options = {})
           define_method "_#{name}_timestamp" do
-            if options[:exec_context] && options[:exec_context].to_sym == :decorator
+            if options[:exec_context]&.to_sym == :decorator
               send(name)
             else
               decorated.send(name)

data/lib/pragma/decorator/version.rb

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

data/pragma-decorator.gemspec

@@ -1,4 +1,3 @@
-
 # frozen_string_literal: true
 
 lib = File.expand_path('../lib', __FILE__)
@@ -22,13 +21,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'multi_json', '~> 1.12'
   spec.add_dependency 'roar', '~> 1.0'
+  spec.add_dependency 'multi_json', '~> 1.12'
 
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'coveralls'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'coveralls'
 end

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: pragma-decorator
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-17 00:00:00.000000000 Z
+date: 2017-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: multi_json
+  name: roar
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: roar
+  name: multi_json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: coveralls
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop-rspec
+  name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -139,17 +139,14 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- doc/01-basic-usage.md
-- doc/02-object-types.md
-- doc/03-associations.md
-- doc/04-timestamps.md
 - lib/pragma/decorator.rb
 - lib/pragma/decorator/association.rb
 - lib/pragma/decorator/association/binding.rb
-- lib/pragma/decorator/association/inconsistent_type_error.rb
+- lib/pragma/decorator/association/errors.rb
 - lib/pragma/decorator/association/reflection.rb
-- lib/pragma/decorator/association/unexpandable_error.rb
 - lib/pragma/decorator/base.rb
+- lib/pragma/decorator/collection.rb
+- lib/pragma/decorator/pagination.rb
 - lib/pragma/decorator/timestamp.rb
 - lib/pragma/decorator/type.rb
 - lib/pragma/decorator/version.rb

data/doc/01-basic-usage.md

@@ -1,42 +0,0 @@
-# Basic usage
-
-Creating a decorator is as simple as inheriting from `Pragma::Decorator::Base`:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          property :id
-          property :email
-          property :full_name
-        end
-      end
-    end
-  end
-end
-```
-
-Just instantiate the decorator by passing it an object to decorate, then call `#to_hash` or
-`#to_json`:
-
-```ruby
-decorator = API::V1::User::Decorator::Resource.new(user)
-decorator.to_json
-```
-
-This will produce the following JSON:
-
-```json
-{
-  "id": 1,
-  "email": "jdoe@example.com",
-  "full_name": "John Doe"
-}
-```
-
-Since Pragma::Decorator is built on top of [ROAR](https://github.com/apotonick/roar) (which, in
-turn, is built on top of [Representable](https://github.com/apotonick/representable)), you should
-consult their documentation for the basic usage of decorators; the rest of this section only covers
-the features provided specifically by Pragma::Decorator.

data/doc/02-object-types.md

@@ -1,47 +0,0 @@
-# Object types
-
-It is recommended that decorators expose the type of the decorated object. You can achieve this
-with the `Type` mixin:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Type
-        end
-      end
-    end
-  end
-end
-```
-
-This would result in the following representation:
-
-```json
-{
-  "type": "user",
-  "...": "...""
-}
-```
-
-You can also set a custom type name (just make sure to use it consistently!):
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          def type
-            :custom_type
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Note: `array` is already overridden with the more language-agnostic `list`.

data/doc/03-associations.md

@@ -1,91 +0,0 @@
-# Associations
-
-`Pragma::Decorator::Association` allows you to define associations in your decorator (currently,
-only `belongs_to`/`has_one` associations are supported):
-
-```ruby
-module API
-  module V1
-    module Invoice
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Association
-
-          belongs_to :customer
-        end
-      end
-    end
-  end
-end
-```
-
-Rendering an invoice will now create the following representation:
-
-```json
-{
-  "customer": 19
-}
-```
-
-Not impressed? Just wait.
-
-## Expanding associations
-
-We also support association expansion through an interface similar to the one provided by the
-[Stripe API](https://stripe.com/docs/api/curl#expanding_objects). You can define which associations
-are expandable in the decorator:
-
-```ruby
-module API
-  module V1
-    module Invoice
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Association
-
-          belongs_to :customer, expandable: true
-        end
-      end
-    end
-  end
-end
-```
-
-You can now pass `expand[]=customer` as a request parameter and have the `customer` property
-expanded into a full object!
-
-```json
-{
-  "customer": {
-    "id": 19,
-    "...": "..."
-  }
-}
-```
-
-## Nested associations
-
-This also works for nested associations. For instance, if the customer has a `company` association
-marked as expandable, you can pass `expand[]=customer&expand[]=customer.company` to get that
-association expanded too.
-
-In order for association expansion to work, you will have to pass the associations to expand to the
-representer as a user option:
-
-```ruby
-decorator = API::V1::Invoice::Decorator::Resource.new(invoice)
-decorator.to_json(user_options: {
-  expand: ['customer', 'customer.company', 'customer.company.contact']
-})
-```
-
-## Accepted options
-
-Here's a list of options accepted when defining an association:
-
-Name | Type | Default | Meaning
----- | ---- | ------- | -------
-`expandable` | Boolean | `false` | Whether this association is expandable by consumers. Attempting to expand a non-expandable association will raise a `UnexpandableError`.
-`decorator` | Class|Proc | - | If provided, decorates the expanded object with this decorator. Otherwise, simply calls `#to_hash` on the object to get a representable hash. If the option is callable, will call it and pass the associated object - a decorator class should be returned, or `nil` to skip decoration.
-`render_nil` | Boolean | `false` | Whether the property should be rendered at all when it is `nil`.
-`exec_context` | Symbol | `:decorated` | Whether to call the getter on the decorator (`:decorator`) or the decorated object (`:decorated`).

data/doc/04-timestamps.md

@@ -1,33 +0,0 @@
-# Timestamps
-
-[UNIX time](https://en.wikipedia.org/wiki/Unix_time) is your safest bet when rendering/parsing
-timestamps in your API, as it doesn't require a timezone indicator (the timezone is always UTC).
-
-You can use the `Timestamp` mixin for converting `Time` instances to UNIX times:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Timestamp
-
-          timestamp :created_at
-        end
-      end
-    end
-  end
-end
-```
-
-This will render a user like this:
-
-```json
-{
-  "type": "user",
-  "created_at": 1480287994
-}
-```
-
-The `#timestamp` method supports all the options supported by `#property` (except for `:as`).

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

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Pragma
-  module Decorator
-    module Association
-      # 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/unexpandable_error.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Pragma
-  module Decorator
-    module Association
-      # This error is raised when expansion of an unexpandable association is attempted.
-      #
-      # @author Alessandro Desantis
-      class UnexpandableError < StandardError
-        # Initializes the error.
-        #
-        # @param reflection [Reflection] the unexpandable association
-        def initialize(reflection)
-          super "Association '#{reflection.property}' cannot be expanded."
-        end
-      end
-    end
-  end
-end