praxis 2.0.pre.5 → 2.0.pre.6

data/lib/praxis/extensions/pagination/active_record_pagination_handler.rb

@@ -0,0 +1,42 @@
+require_relative 'pagination_handler'
+
+module Praxis
+  module Extensions
+    module Pagination
+      class ActiveRecordPaginationHandler < PaginationHandler
+
+        def self.where_lt(query, attr, value)
+          # TODO: common for AR/Sequel? Seems we could use Arel and more-specific Sequel things
+          query.where(query.table[attr].lt(value))
+        end
+        
+        def self.where_gt(query, attr, value)
+          query.where(query.table[attr].gt(value))
+        end
+
+        def self.order(query, order)
+          return query unless order
+          query = query.reorder('')
+          
+          order.each do |spec_hash|
+            direction, name = spec_hash.first
+            query = query.order(name => direction)
+          end
+          query
+        end
+        
+        def self.count(query)
+          query.count(:all)
+        end
+
+        def self.offset(query, offset)
+          query.offset(offset)
+        end
+
+        def self.limit(query, limit)
+          query.limit(limit)
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/pagination/header_generator.rb

@@ -0,0 +1,70 @@
+module Praxis
+  module Extensions
+    module Pagination
+      class HeaderGenerator        
+        def self.build_cursor_headers(paginator:, last_value:, total_count: nil)
+          [:next, :prev, :first, :last].each_with_object({}) do |rel_name, info|
+            case rel_name
+            when :next
+              # If we don't know the total, we'll try to go to the next page
+              # but assume we're done if there isn't a last value...
+              if last_value
+                info[:next] = { by: paginator.by, from: last_value, items: paginator.items }
+                info[:next][:total_count] = true if total_count.present?
+              end
+            when :prev
+            # Not possible to go back
+            when :first
+              info[:first] = { by: paginator.by, items: paginator.items }
+              info[:first][:total_count] = true if total_count.present?
+            when :last
+              # Not possible to scroll to last
+            end
+          end
+        end
+
+        # This is only for plain paging
+        def self.build_paging_headers(paginator:, total_count: nil)
+          last_page = total_count.nil? ? nil : (total_count / (paginator.items * 1.0)).ceil
+          [:next, :prev, :first, :last].each_with_object({}) do |rel_name, info|
+            num = case rel_name
+                  when :first
+                    1
+                  when :prev
+                    next if paginator.page < 2
+                    paginator.page - 1
+                  when :next
+                    # don't include this link if we know the total and we see there are no more pages
+                    next if last_page.present? && (paginator.page >= last_page)
+                    # if we don't know the total, we'll specify to the next page even if it ends up being blank
+                    paginator.page + 1
+                  when :last
+                    next if last_page.blank?
+                    last_page
+                  end
+            info[rel_name] = {
+              page:         num,
+              items:        paginator.items,
+              total_count:  total_count.present?
+            }
+          end
+        end
+
+        def self.generate_headers(links:, current_url:, current_query_params:, total_count:)
+          mapped = links.map do |(rel, info)|
+            # Make sure to encode it our way (with comma-separated args, as it is our own syntax, and not a query string one)
+            pagination_param = info.map { |(k, v)| "#{k}=#{v}" }.join(",")
+            new_url = current_url + "?" + current_query_params.dup.merge(pagination:  pagination_param).to_query
+
+            LinkHeader::Link.new(new_url, [["rel", rel.to_s]])
+          end
+          link_header = LinkHeader.new(mapped)
+
+          headers = { "Link" => link_header.to_s }
+          headers["Total-Count"] = total_count if total_count
+          headers
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/pagination/ordering_params.rb

@@ -0,0 +1,234 @@
+require 'forwardable'
+
+module Praxis
+  module Extensions
+    module Pagination
+      class OrderingParams
+        include Attributor::Type
+        include Attributor::Dumpable
+        extend Forwardable
+
+        def_delegators :items, :empty?
+
+        # DSL for restricting how to order.
+        # It allows the concrete list of the fields one can use (through 'by_fields')
+        # It also allows to enforce that list for all positions of the ordering definition (through 'enforce_for :all|:first')
+        #  By default, only the first ordering position will be subject to that enforcement (i.e., 'enforce_for :first' is the default)
+        # Example
+        #
+        # attribute :order, Praxis::Types::OrderingParams.for(MediaTypes::Bar) do
+        #   by_fields :id, :name
+        #   enforce_for :all
+        # end
+        class DSLCompiler < Attributor::DSLCompiler
+          def by_fields(*fields)
+            requested = fields.map(&:to_sym)
+            non_matching = requested - target.media_type.attributes.keys
+            unless non_matching.empty?
+              raise "Error, you've requested to order by fields that do not exist in the mediatype!\n" \
+              "The following #{non_matching.size} field/s do not exist in media type #{target.media_type.name} :\n" +
+                    non_matching.join(',').to_s
+            end
+            target.fields_allowed = requested
+          end
+
+          def enforce_for(which)
+            case which.to_sym
+            when :all
+              target.enforce_all = true
+            when :first
+              # nothing, that's the default
+            else
+              raise "Error: unknown parameter for the 'enforce_for' : #{which}. Only :all or :first are allowed"
+            end
+          end
+        end
+
+        # Configurable DEFAULTS
+        @enforce_all_fields = false
+
+        def self.enforce_all_fields(newval = nil)
+          newval ? @enforce_all_fields = newval : @enforce_all_fields
+        end
+
+        # Ordering type that allows you to specify the ordering characteristing of a requested listing
+        # Ordering is based on given mediatype, which allows for ensuring validation of type names etc.
+
+        # Syntax (similar to json-api)
+        # * One can specify ordering based on several fields (to resolve tie breakers) by separating them with commas
+        # * Requesting a descending order can be done by adding a `-` before the field name. Prepending a `+` enforces
+        #   ascending order (which is the default if no sign is specified)
+        # Example:
+        # `name,last_name,-birth_date`
+
+        # Abstract class, which needs to be used by subclassing it through the .for method, to link it to a particular
+        # MediaType, so that the field name checking and value coercion can be performed
+        class << self
+          attr_reader :media_type
+          attr_accessor :fields_allowed
+          attr_accessor :enforce_all # True when we need to enforce the allowed fields at all ordering positions
+
+          def for(media_type, **_opts)
+            unless media_type < Praxis::MediaType
+              raise ArgumentError, "Invalid type: #{media_type.name} for Ordering. " \
+                "Must be a subclass of MediaType"
+            end
+
+            ::Class.new(self) do
+              @media_type = media_type
+              if media_type
+                # By default all fields in the mediatype are allowed (but defining a DSL block will override it to more specific ones)
+                @fields_allowed = media_type.attributes.keys
+              end
+              # Default is to only enforce the allowed fields in the first ordering position (the one typicall uses an index if there)
+              @enforce_all = OrderingParams.enforce_all_fields
+            end
+          end
+        end
+
+        attr_reader :items
+
+        def self.native_type
+          self
+        end
+
+        def self.name
+          'Praxis::Types::OrderingParams'
+        end
+
+        def self.display_name
+          'Ordering'
+        end
+
+        def self.family
+          'string'
+        end
+
+        def self.constructable?
+          true
+        end
+
+        def self.construct(pagination_definition, **options)
+          return self if pagination_definition.nil?
+
+          DSLCompiler.new(self, options).parse(*pagination_definition)
+          self
+        end
+
+        def self.example(_context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          fields = if media_type
+                    chosen_set = if enforce_all
+                                    fields_allowed.sample(2)
+                                  else
+                                    starting_set = fields_allowed.sample(1)
+                                    simple_attrs = media_type.attributes.select do |_k, attr|
+                                      attr.type == Attributor::String || attr.type < Attributor::Numeric || attr.type < Attributor::Temporal
+                                    end.keys
+                                    starting_set + simple_attrs.select { |attr| attr != starting_set.first }.sample(1)
+                                  end
+                    chosen_set.each_with_object([]) do |chosen, arr|
+                      sign = rand(10) < 5 ? "-" : ""
+                      arr << "#{sign}#{chosen}"
+                    end.join(',')
+                  else
+                    "name,last_name,-birth_date"
+                  end
+          load(fields)
+        end
+
+        def self.validate(value, context = Attributor::DEFAULT_ROOT_CONTEXT, _attribute = nil)
+          instance = load(value, context)
+          instance.validate(context)
+        end
+
+        def self.load(order, _context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          return order if order.is_a?(native_type)
+
+          parsed_order = {}
+          unless order.nil?
+            parsed_order = order.split(',').each_with_object([]) do |order_string, arr|
+              item = if order_string[0] == '-'
+                      { desc: order_string[1..-1].to_s }
+                    elsif order_string[0] == '+'
+                      { asc: order_string[1..-1].to_s }
+                    else
+                      { asc: order_string.to_s }
+                    end
+              arr.push item
+            end
+          end
+
+          new(parsed_order)
+        end
+
+        def self.dump(value, **_opts)
+          load(value).dump
+        end
+
+        def self.describe(_root = false, example: nil)
+          hash = super
+
+          if fields_allowed
+            hash[:fields_allowed] = fields_allowed
+            hash[:enforced_for] = enforce_all ? :all : :first
+          end
+
+          hash
+        end
+
+        def initialize(parsed)
+          @items = parsed
+        end
+
+        def validate(_context = Attributor::DEFAULT_ROOT_CONTEXT)
+          return [] if items.blank?
+
+          errors = []
+          if self.class.fields_allowed
+            # Validate against the enforced components (either all, or just the first one)
+            enforceable_items = self.class.enforce_all ? items : [items.first]
+
+            enforceable_items.each do |spec|
+              _dir, field = spec.first
+              field = field.to_sym
+              next unless !self.class.fields_allowed.include?(field)
+              errors << if self.class.media_type.attributes.key?(field)
+                          "Ordering by field \'#{field}\' is disallowed. Ordering is only allowed using the following fields: " +
+                          self.class.fields_allowed.map { |f| "\'#{f}\'" }.join(', ').to_s
+                        else
+                          "Ordering by field \'#{field}\' is not possible as this field does not exist in " \
+                          "media type #{self.class.media_type.name}"
+                        end
+            end
+          end
+
+          errors
+        end
+
+        def dump
+          items.each_with_object([]) do |spec, arr|
+            dir, field = spec.first
+            arr << if dir == :desc
+                    "-#{field}"
+                  else
+                    field
+                  end
+          end.join(',')
+        end
+
+        def each
+          items.each do |item|
+            yield item
+          end
+        end
+      end
+    end
+  end
+end
+
+# Alias it to a much shorter and sweeter name in the Types namespace.
+module Praxis
+  module Types
+    OrderingParams = Praxis::Extensions::Pagination::OrderingParams
+  end
+end

data/lib/praxis/extensions/pagination/pagination_handler.rb

@@ -0,0 +1,68 @@
+module Praxis
+  module Extensions
+    module Pagination
+      class PaginationHandler
+        class PaginationException < Exception; end
+
+        def self.paginate(query, pagination)
+          return query unless pagination.paginator
+
+          paginator = pagination.paginator
+
+          q = if paginator.page
+            offset(query, (paginator.page - 1) * paginator.items)            
+          else
+            # If there is an order clause that complies with the "by" field sorting, we can use it directly
+            # i.e., We can be smart about allowing the main sort field matching the pagination one (in case you want to sub-order in a custom way)
+            oclause = if pagination.order.nil? || pagination.order.empty? # No ordering specified => use ascending based on the "by" field
+                        direction = :asc
+                        order(query, [{ asc: paginator.by }])
+                      else
+                        first_ordering = pagination.order.items.first
+                        direction = first_ordering.keys.first
+                        unless first_ordering[direction].to_sym == pagination.paginator.by.to_sym
+                          string_clause = pagination.order.items.map { |h|
+                            dir, name = h.first
+                            "#{name} #{dir}"
+                          }.join(',')
+                          raise PaginationException,
+                                "Ordering clause [#{string_clause}] is incompatible with pagination by field '#{pagination.paginator.by}'. " \
+                                "When paginating by a field value, one cannot specify the 'order' clause " \
+                                "unless the clause's primary field matches the pagination field."
+                        end
+                        order(query, pagination.order)
+                      end
+
+            if paginator.from
+              if direction == :desc
+                where_lt(oclause, paginator.by, paginator.from)
+              else
+                where_gt(oclause, paginator.by, paginator.from)
+              end
+            else
+              oclause
+            end
+
+          end
+          limit(q, paginator.items)
+        end
+
+        def self.where_lt(query, attr, value)
+          raise "implement in derived class"
+        end
+        
+        def self.where_gt(query, attr, value)
+          raise "implement in derived class"
+        end
+
+        def self.offset(query, offset)
+          raise "implement in derived class"
+        end
+
+        def self.limit(query, limit)
+          raise "implement in derived class"
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/pagination/pagination_params.rb

@@ -0,0 +1,374 @@
+module Praxis
+  module Extensions
+    module Pagination
+      class PaginationParams
+        include Attributor::Type
+        include Attributor::Dumpable
+
+        # Pagination type that allows you to define a parameter type in an endpoint, including a DSL to restrict or configure
+        # the pagination options of every single definition, and which will take care of parsing, coercing and validating the
+        # pagination syntax below. It also takes care of generating the Link
+        # and total count headers.
+        # Pagination supports both cursor and page-based:
+        # 1 - Page-based pagination (i.e., offset-limit based paging assuming an explicit or implicit ordering underneath)
+        #   * it is done by using the 'page=<integer>' parameter, indicating which page number to output (based on a given page size)
+        #   * setting the page size on a per-request basis can be achieved by setting the 'items=<integer>` parameter
+        #   * example: `page=5,items=50`  (should return items 200-250 from the collection)
+        # 2- Cursor-based pagination (paginating based on a field value)
+        #   * it is done by using 'by=email', indicating the field name to use, and possibly using 'from=joe@example.com' to indicate
+        #     after which values of the field to start listing (no 'from' values assume starting from the beginning).
+        #   * the default page size can be overriden on a per-request basis as well with the 'items=<integer>` parameter
+        #   #  example `by=email,from=joe@example.com,items=100`
+        #
+        # In either situation, one can also request to receive the total count of elements existing in the collection (pre-paging)
+        # by using 'total_count=true'.
+        #
+        # Every pagination request will also receive a Link header (RFC 5988) properly populated with followable links.
+        # When the 'total_count=true' parameter is used, a 'Total-Count' header will also be returned containing the total number
+        # of existing results pre-pagination. Note that calculating the total count incurs in an extra DB query so it does have
+        # performance implications
+
+        ######################################################
+        # DSL for definition pagination parameters in a defined filter.
+        # Available options are:
+        #
+        # One can limit which fields the pagination (by cursor) can be allowed. Typically only indexed fields should
+        # be allowed for performance reasons:
+        #  * by_fields <Array of field names>  (if not provided, all fields are allowed)
+        # One can limit the total maximum of items of the requested page size from the client can ask for:
+        #  * max_items <integer> (there is a static upper limit to thie value set by the MAX_ITEMS constant)
+        # One can set the default amount of items to return when not specified by the client
+        #  * page_size <integer> (less or equal than max_items, if the max is set)
+        # One can expicitly disallow either paging or cursor based pagination (by default both are allowed)
+        # * disallow :paging | :cursor
+        # One can set the default pagination mode when no :page, :by/:from parameters are passed in.
+        # * default  <mode>: <value>  where mode can be :page or :by (and the value is an integer or a field name respectively)
+        #
+        # Here's a full example:
+        # attribute :pagination, Types::PaginationParams.for(MediaTypes::Book) do
+        #   by_fields :id, :name
+        #   max_items 500
+        #   page_size 50
+        #   disallow :paging
+        #   default by: :id
+        # end
+        class DSLCompiler < Attributor::DSLCompiler
+          def by_fields(*fields)
+            requested = fields.map(&:to_sym)
+            non_matching = requested - target.media_type.attributes.keys
+            unless non_matching.empty?
+              raise "Error, you've requested to paginate by fields that do not exist in the mediatype!\n" \
+              "The following #{non_matching.size} field/s do not exist in media type #{target.media_type.name} :\n" +
+                    non_matching.join(',').to_s
+            end
+            target.fields_allowed = requested
+          end
+
+          def max_items(max)
+            target.defaults[:max_items] = Integer(max)
+          end
+
+          def page_size(size)
+            target.defaults[:page_size] = Integer(size)
+          end
+
+          def disallow(pagination_type)
+            default_mode, default_value = target.defaults[:default_mode].first
+            case pagination_type
+            when :paging
+              if default_mode == :page
+                raise "Cannot disallow page-based pagination if you define a default pagination of:  page: #{default_value}"
+              end
+              target.defaults[:disallow_paging] = true
+            when :cursor
+              if default_mode == :by
+                raise "Cannot disallow cursor-based pagination if you define a default pagination of:   by: #{default_value}"
+              end
+              target.defaults[:disallow_cursor] = true
+            end
+          end
+
+          def default(spec)
+            unless spec.is_a?(Hash) && spec.keys.size == 1 && [:by, :page].include?(spec.keys.first)
+              raise "'default' syntax for pagination takes exactly one key specification. Either by: <:fieldname> or page: <num>" \
+                    "#{spec} is invalid"
+            end
+            mode, value = spec.first
+            def_mode = case mode
+                       when :by
+                         if target.fields_allowed && !target.fields_allowed&.include?(value)
+                           raise "Error setting default pagination. Field #{value} is not amongst the allowed fields."
+                         end
+                         if target.defaults[:disallow_cursor]
+                           raise "Cannot define a default pagination that is cursor based, if cursor-based pagination is disallowed."
+                         end
+                         { by: value }
+                       when :page
+                         unless value.is_a?(Integer)
+                           raise "Error setting default pagination. Initial page should be a integer (but got #{value})"
+                         end
+                         if target.defaults[:disallow_paging]
+                           raise "Cannot define a default pagination that is page-based, if page-based pagination is disallowed."
+                         end
+                         { page: value }
+                       end
+            target.defaults[:default_mode] = def_mode
+          end
+        end
+
+        # Configurable DEFAULTS
+        @max_items = nil # Unlimited by default (since it's not possible to set it to nil for now from the app)
+        @default_page_size = 100
+        @paging_default_mode = { page: 1 }
+        @disallow_paging_by_default = false
+        @disallow_cursor_by_default = false
+
+        def self.max_items(newval = nil)
+          newval ? @max_items = newval : @max_items
+        end
+
+        def self.default_page_size(newval = nil)
+          newval ? @default_page_size = newval : @default_page_size
+        end
+
+        def self.disallow_paging_by_default(newval = nil)
+          newval ? @disallow_paging_by_default = newval : @disallow_paging_by_default
+        end
+
+        def self.disallow_cursor_by_default(newval = nil)
+          newval ? @disallow_cursor_by_default = newval : @disallow_cursor_by_default
+        end
+
+        def self.paging_default_mode(newval = nil)
+          if newval
+            unless newval.respond_to?(:keys) && newval.keys.size == 1 && [:by, :page].include?(newval.keys.first)
+              raise "Error setting paging_default_mode, value must be a hash with :by or :page keys"
+            end
+            @paging_default_mode = newval
+          end
+          @paging_default_mode
+        end
+
+        # Abstract class, which needs to be used by subclassing it through the .for method, to link it to a particular
+        # MediaType, so that the field name checking and value coercion can be performed
+        class << self
+          attr_reader :media_type
+          attr_reader :defaults
+          attr_accessor :fields_allowed
+
+          def for(media_type, **_opts)
+            unless media_type < Praxis::MediaType
+              raise ArgumentError, "Invalid type: #{media_type.name} for Paginator. " \
+                "Must be a subclass of MediaType"
+            end
+
+            ::Class.new(self) do
+              @media_type = media_type
+              @defaults = {
+                page_size: PaginationParams.default_page_size,
+                max_items: PaginationParams.max_items,
+                disallow_paging: PaginationParams.disallow_paging_by_default,
+                disallow_cursor: PaginationParams.disallow_cursor_by_default,
+                default_mode: PaginationParams.paging_default_mode
+              }
+            end
+          end
+        end
+
+        def self.native_type
+          self
+        end
+
+        def self.name
+          'Extensions::Pagination::PaginationParams'
+        end
+
+        def self.display_name
+          'Paginator'
+        end
+
+        def self.family
+          'string'
+        end
+
+        def self.constructable?
+          true
+        end
+
+        def self.construct(pagination_definition, **options)
+          return self if pagination_definition.nil?
+
+          DSLCompiler.new(self, options).parse(*pagination_definition)
+          self
+        end
+
+        attr_reader :by
+        attr_reader :from
+        attr_reader :items
+        attr_reader :page
+        attr_reader :total_count
+
+        def self.example(_context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          fields = if media_type
+                     mt_example = media_type.example
+                     simple_attrs = media_type.attributes.select do |_k, attr|
+                       attr.type == Attributor::String || attr.type == Attributor::Integer
+                     end
+
+                     selectable = mt_example.object.keys & simple_attrs.keys
+                     by = selectable.sample(1).first
+                     from = media_type.attributes[by].example(parent: mt_example)
+                     # Make sure to encode the value of the from, as it can contain commas and such
+                     from = CGI.escape(from) if from.is_a? String
+                     "by=#{by},from=#{from},items=#{defaults[:page_size]}"
+                   else
+                     "by=id,from=20,items=100"
+                   end
+          load(fields)
+        end
+
+        def self.validate(value, context = Attributor::DEFAULT_ROOT_CONTEXT, _attribute = nil)
+          instance = load(value, context)
+          instance.validate(context)
+        end
+
+        CLAUSE_REGEX = /(?<type>[^=]+)=(?<value>.+)$/
+        def self.load(paginator, _context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          return paginator if paginator.is_a?(native_type) || paginator.nil?
+          parsed = {}
+          unless paginator.nil?
+            parsed = paginator.split(',').each_with_object({}) do |paginator_string, hash|
+              match = CLAUSE_REGEX.match(paginator_string)
+              case match[:type].to_sym
+              when :page
+                hash[:page] = Integer(match[:value])
+              when :by
+                hash[:by] = match[:value]
+              when :from
+                hash[:from] = match[:value]
+              when :total_count
+                hash[:total_count] = (match[:value] != 'false') # unless explicitly set to false, we'll take it as true...
+              when :items
+                hash[:items] = Integer(match[:value])
+              else
+                raise "Error loading pagination parameters: unknown parameter with name '#{match[:type]}' found"
+              end
+            end
+          end
+
+          parsed[:items] = defaults[:page_size] unless parsed.key?(:items)
+          parsed[:from] = coerce_field(parsed[:by], parsed[:from]) if parsed.key?(:from)
+
+          # If no by/from or page specified, we're gonna apply the defaults
+          unless parsed.key?(:by) || parsed.key?(:from) || parsed.key?(:page)
+            mode, value = defaults[:default_mode].first
+            case mode
+            when :by
+              parsed[:by] = value
+            when :page
+              parsed[:page] = value
+            end
+          end
+
+          new(parsed)
+        end
+
+        def self.dump(value, **_opts)
+          load(value).dump
+        end
+
+        def self.describe(_root = false, example: nil)
+          hash = super
+
+          hash[:fields_allowed] = fields_allowed if fields_allowed
+          if defaults
+            hash[:max_items]    = defaults[:max_items]
+            hash[:page_size]    = defaults[:page_size]
+            hash[:default_mode] = defaults[:default_mode]
+
+            disallowed = []
+            disallowed << :paging if defaults[:disallow_paging] == true
+            disallowed << :cursor if defaults[:disallow_cursor] == true
+            hash[:disallowed] = disallowed unless disallowed.empty?
+          end
+
+          hash
+        end
+
+        # Silently ignore if the fiels does not exist...let's let the validation check it instead
+        def self.coerce_field(name, value)
+          if media_type&.attributes
+            attrs = media_type&.attributes || {}
+            attribute = attrs[name.to_sym]
+            attribute.type.load(value) if attribute
+          else
+            value
+          end
+        end
+
+        # Instance methods
+        def initialize(parsed)
+          @by = parsed[:by]
+          @from = parsed[:from]
+          @items = parsed[:items]
+          @page = parsed[:page]
+          @total_count = parsed[:total_count]
+        end
+
+        def validate(_context = Attributor::DEFAULT_ROOT_CONTEXT) # rubocop:disable Metrics/PerceivedComplexity
+          errors = []
+
+          if page
+            if self.class.defaults[:disallow_paging]
+              errors << "Page-based pagination is disallowed (i.e., using 'page=' parameter)"
+            end
+          elsif self.class.defaults[:disallow_cursor]
+            errors << "Cursor-based pagination is disallowed (i.e., using 'by=' or 'from=' parameter)"
+          end
+
+          if page && page <= 0
+            errors << "Page parameter cannot be zero or negative! (got: #{parsed.page})"
+          end
+
+          if items && (items <= 0 || ( self.class.defaults[:max_items] && items > self.class.defaults[:max_items]) )
+            errors << "Value of 'items' is invalid (got: #{items}). It must be positive, and smaller than the maximum amount of items per request (set to #{self.class.defaults[:max_items]})"
+          end
+
+          if page && (by || from)
+            errors << "Cannot specify the field to use and its start value to paginate from when using a fix pager (i.e., `by` and/or `from` params are not compabible with `page`)"
+          end
+
+          if by && self.class.fields_allowed && !self.class.fields_allowed.include?(by.to_sym)
+            errors << if self.class.media_type.attributes.key?(by.to_sym)
+                        "Paginating by field \'#{by}\' is disallowed"
+                      else
+                        "Paginating by field \'#{by}\' is not possible as this field does not exist in "\
+                        "media type #{self.class.media_type.name}"
+                      end
+          end
+          errors
+        end
+
+        # Dump back string parseable form
+        def dump
+          str = if @page
+                  "page=#{@page}"
+                else
+                  s = "by=#{@by}"
+                  s += ",from=#{@from}" if @from
+                end
+          str += ",items=#{items}" if @items
+          str += ",total_count=true" if @total_count
+          str
+        end
+      end
+    end
+  end
+end
+
+# Alias it to a much shorter and sweeter name in the Types namespace.
+module Praxis
+  module Types
+    PaginationParams = Praxis::Extensions::Pagination::PaginationParams
+  end
+end