right 0.7.2

data/lib/right/filter_parameter_definition.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+module Right
+  # Filtering parameter definition
+  #
+  class FilterParameterDefinition
+    # If the property name doesn't match the name in the query string, use the :as option
+    # @return [String]
+    attr_reader :as
+
+    # @return [String]
+    attr_reader :name
+
+    # Association on which this parameter is defined.
+    # @return [String, nil]
+    attr_reader :on
+
+    # White-listed predicates
+    # @return [<String>]
+    attr_reader :predicates
+
+    # @param [String] name of the field
+    # @param [Hash] options
+    # @option options [Symbol, {Symbol => String}, {Symbol => <String>}] :on (nil) filter on given relation
+    # @option options [<String>] :predicates (ALL_PREDICATES) white-listed predicates
+    # @option options [Proc] :coerce coercion for the value
+    # @option options [Hash{Symbol => any}] :validates for the value
+    #   @example
+    #     validates: presence: true, length: { is: 6 }
+    #
+    def initialize(name, options = {})
+      options.assert_valid_keys(:as, :on, :predicates, :coerce, :validates)
+      @as = options.fetch(:as, name).to_s
+      @name = name.to_s
+      @on = options[:on]
+      @predicates = Array(options.fetch(:predicates, FilterPredicates.all)).map(&:to_s)
+      @coerce = options.fetch(:coerce, ->(v) { v })
+      @validations = options.fetch(:validates, {})
+    end
+
+    # If two parameters have the same name, they are equal.
+    delegate :hash, to: :name
+
+    def eql?(other)
+      other.is_a?(self.class) && other.name == name
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        other.name == name &&
+        other.as == as &&
+        other.on == on &&
+        other.predicates == predicates
+    end
+
+    # @param [any] value
+    # @return [any] coerced value according the definition
+    #
+    def coerce(value)
+      @coerce.call(value)
+    end
+
+    def validator
+      FilterValueValidator.build(self)
+    end
+
+    def defined?
+      true
+    end
+
+    def undefined?
+      !self.defined?
+    end
+
+    # Proc with defined validations
+    # @return [Proc]
+    # @api private
+    attr_reader :validations
+  end
+end

data/lib/right/filter_parameters.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+module Right
+  #
+  class FilterParameters
+    include Comparable
+    include Enumerable
+    extend Forwardable
+
+    FilterError = Class.new(KeyError)
+
+    def_delegators :parameters, :detect, :each
+
+    # @param [<Right::FilterParameter>]
+    def initialize(parameters = nil)
+      @parameters = Set.new(parameters)
+    end
+
+    # Dup internal set.
+    def initialize_dup(orig)
+      super
+      @parameters = orig.parameters.dup
+    end
+
+    # Clone internal set.
+    def initialize_clone(orig)
+      super
+      @parameters = orig.parameters.clone
+    end
+
+    # Find filter by name
+    # @param name [String]
+    # @return [Right::FilterParameter, nil]
+    #
+    def [](name)
+      parameters.detect { |filter| filter.name == name }
+    end
+
+    # Find filter by name or raise error
+    # @param name [String]
+    # @yieldparam name [String]
+    #   block value will be returned if no `FilterParameter` found with specified name
+    # @return [Right::FilterParameter]
+    # @raise FilterError
+    #
+    def fetch(name)
+      if (filter = self[name])
+        filter
+      elsif block_given?
+        yield(name)
+      else
+        fail FilterError, "filter not found: #{name.inspect}"
+      end
+    end
+
+    # param value [Right::FilterParameter]
+    def add(value)
+      self.class.new(parameters.add(value))
+    end
+
+    alias << add
+
+    def map(&block)
+      self.class.new(parameters.map(&block))
+    end
+
+    # param other [Right::FilterParameters]
+    def -(other)
+      self.class.new(parameters - other.parameters)
+    end
+
+    # param other [Right::FilterParameters]
+    def +(other)
+      self.class.new(parameters.merge(other.parameters))
+    end
+
+    # Delete filter by name
+    # @param name [String]
+    # @return [Right::FilterParameter, nil]
+    def delete(name)
+      filter_parameter = self[name]
+      parameters.delete(filter_parameter) if filter_parameter
+      filter_parameter
+    end
+
+    def <=>(other)
+      parameters <=> other.parameters
+    end
+
+    protected
+
+    attr_reader :parameters
+  end
+end

data/lib/right/filter_parameters_extractor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+module Right
+  # User provided filters syntax:
+  #   * `{ 'name_eq' => 'Martin' }` - name is equal to Martin
+  #   * `{ 'name_in' => 'Martin,Bob' }` - name is either Martin or Bob
+  #
+  # This middleware parses filters hash and builds Parameter array
+  # @see Right::FilterParameter
+  #
+  # If user passes not defined filter, it yields to `UndefinedParameter`, so you may
+  # validate it.
+  #
+  class FilterParametersExtractor
+    # @param app [#call]
+    # @param parameters_definition [Set<Right::FilterParameterDefinition>]
+    def initialize(app, parameters_definition)
+      @app = app
+      @parameters_definition = parameters_definition
+    end
+
+    # @param env [<{:filter => Hash}, []>]
+    #   * first element is a scope to be filtered
+    #   * second is a hash with user provided filters
+    # @return [<{:filter => <Right::FilterParameter>, []}]
+    #
+    def call(env)
+      params, errors = env
+
+      provided_parameters = Hash(params[:filter]).each_with_object(FilterParameters.new) do |(name, value), parameters|
+        type_casted_value = type_cast_value(name, value)
+        parameters << extract_parameter(name, type_casted_value)
+      end
+
+      not_provided_parameters = parameters_definition - provided_parameters.map(&:definition)
+
+      undefined_parameters = not_provided_parameters.map do |definition|
+        FilterParameter.new(nil, nil, definition)
+      end
+
+      # Keep even undefined parameters to validate required ones
+      filters = provided_parameters + undefined_parameters
+
+      app.call([params.merge(filter: filters), errors])
+    end
+
+    private
+
+    attr_reader :parameters_definition, :app
+
+    def name_and_predicate(name_with_predicate)
+      predicate = FilterPredicates.all.detect { |p| name_with_predicate.end_with?("_#{p}") }
+      [
+        name_with_predicate.chomp("_#{predicate}"),
+        predicate,
+      ]
+    end
+
+    # @param [String] name
+    # @param [String, Array<String>] value
+    #
+    def extract_parameter(name, value)
+      name, predicate = name_and_predicate(name)
+      definition = parameters_definition.detect { |d| d.as == name } || FilterUndefinedParameter.new(name)
+      FilterParameter.new(value, predicate, definition)
+    end
+
+    def type_cast_value(name, value)
+      if name.end_with?(*FilterPredicates.array)
+        value.split(',')
+      else
+        value
+      end
+    end
+  end
+end

data/lib/right/filter_parameters_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module Right
+  # Validates filters and raises error if one of them is invalid
+  #
+  class FilterParametersValidator
+    # @param app [#call]
+    def initialize(app)
+      @app = app
+    end
+
+    # @param env [<{:filter => <Right::FilterParameter>, Array>}]
+    # @return [<{:filter => <Right::FilterParameter>, Array>}]
+    #
+    def call(env)
+      params, errors = env
+
+      invalid_filters = Array(params[:filter]).select(&:invalid?)
+      messages = invalid_filters.flat_map(&:errors)
+
+      app.call([params, errors.concat(messages)])
+    end
+
+    private
+
+    attr_reader :app
+  end
+end

data/lib/right/filter_predicates.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+module Right
+  # Contains contains with all supported predicates
+  # You can register your own predicates. Predicates should perform on array or on singular value:
+  #
+  #   Right::FilterPredicates.register('includes', on: :array)
+  #   Right::FilterPredicates.register('is_upper_case', on: :value)
+  #
+  module FilterPredicates
+    NOT_EQ = 'not_eq'
+    EQ = 'eq'
+    DOES_NOT_MATCH = 'does_not_match'
+    MATCHES = 'matches'
+    GT = 'gt'
+    LT = 'lt'
+    GTEQ = 'gteq'
+    LTEQ = 'lteq'
+    NOT_CONT = 'not_cont'
+    CONT = 'cont'
+    NOT_START = 'not_start'
+    START = 'start'
+    DOES_NOT_END = 'not_end'
+    ENDS = 'end'
+    NOT_TRUE = 'not_true'
+    TRUE = 'true'
+    NOT_FALSE = 'not_false'
+    FALSE = 'false'
+    BLANK = 'blank'
+    PRESENT = 'present'
+    NOT_NULL = 'not_null'
+    NULL = 'null'
+    NOT_IN = 'not_in'
+    IN = 'in'
+    NOT_CONT_ANY = 'not_cont_any'
+    CONT_ANY = 'cont_any'
+
+    @predicates_on_value = Set.new([
+      NOT_EQ, EQ,
+      DOES_NOT_MATCH, MATCHES,
+      GT, LT,
+      GTEQ, LTEQ,
+      NOT_CONT, CONT,
+      NOT_START, START,
+      DOES_NOT_END, ENDS,
+      NOT_TRUE, TRUE,
+      NOT_FALSE, FALSE,
+      BLANK, PRESENT,
+      NOT_NULL, NULL
+    ])
+    @predicates_on_array = Set.new([
+      NOT_IN, IN,
+      NOT_CONT_ANY, CONT_ANY
+    ])
+
+    # Registers predicate on singular value or on array
+    # @param predicate [String, Symbol]
+    # @param on [:array, :value]
+    # @return [Right::FilterPredicates]
+    #
+    def register(predicate, on:)
+      case on
+      when :value
+        @predicates_on_value.add(predicate.to_s)
+      when :array
+        @predicates_on_array.add(predicate.to_s)
+      else
+        fail ArgumentError, 'on must be :array, or :value'
+      end
+      self
+    end
+    module_function :register
+
+    # Returns predicates for array
+    # @return [Set<String>]
+    #
+    def array
+      @predicates_on_array.dup
+    end
+    module_function :array
+
+    # Returns predicates for values
+    # @return [Set<String>]
+    #
+    def value
+      @predicates_on_value.dup
+    end
+    module_function :value
+
+    # Returns all predicates
+    # @return [Set<String>]
+    #
+    def all
+      @predicates_on_value + @predicates_on_array
+    end
+    module_function :all
+  end
+end

data/lib/right/filter_undefined_parameter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module Right
+  # Null object for ParameterDefinition
+  #
+  class FilterUndefinedParameter < FilterParameterDefinition
+    def required?
+      false
+    end
+
+    def defined?
+      false
+    end
+  end
+end

data/lib/right/filter_value_validator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Right
+  # Build singleton validation class for specified attribute name
+  # @example you need a nice validator for a first_name
+  #   validator_klass = ValueValidator.build('first_name', presence: true, length: { minimum: 3 })
+  #   validator = validator_klass.new('Bo')
+  #   validator.valid? #=> false
+  #   validator.errors.full_messages #=> ['First name is too short (minimum is 3 characters)']
+  #
+  module FilterValueValidator
+    module_function
+
+    # Validates if Parameter is undefined or not
+    class DefinedValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, _value)
+        record.errors.add(attribute, :undefined_filter) if record.undefined?
+      end
+    end
+
+    def build(definition)
+      Struct.new(definition.as.to_sym) do
+        include ActiveModel::Validations
+
+        validates(definition.as, definition.validations) if definition.validations.present?
+        validates(definition.as, 'right/filter_value_validator/defined': true)
+
+        define_method(:undefined?) { definition.undefined? }
+
+        define_singleton_method :model_name do
+          ActiveModel::Name.new(Right, nil, 'Right')
+        end
+      end
+    end
+  end
+end

data/lib/right/pagination_middleware.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+module Right
+  # Pagination middleware
+  #
+  class PaginationMiddleware
+    # @param app [#call, Proc]
+    # @param max_per_page [Integer]
+    # @param per_page [Integer]
+    #
+    def initialize(app, max_per_page: false, per_page: 50, paginator_class: Paginator)
+      @app = app
+      @max_per_page = max_per_page
+      @per_page = per_page
+      @paginator_class = paginator_class
+    end
+
+    # @param [Array(ActiveRecord::Relation, Hash)] env
+    # First argument is a ActiveRecord relation which must be paginated
+    # Second argument is a request parameters provided by user
+    #
+    def call(env)
+      scope, params = env
+
+      paginated_scope = @paginator_class.new(pagination_options(params)).paginate(scope)
+      app.call([paginated_scope, params])
+    end
+
+    private
+
+    attr_reader :app
+
+    # @param [Hash] params
+    # @option params [Hash] (nil) :limit
+    # @option params [Hash] (nil) :offset
+    #
+    def pagination_options(params)
+      options = default_pagination_options.merge(Hash(params[:page]))
+      max_per_page = @max_per_page
+
+      if max_per_page && options[:limit] > max_per_page
+        options.merge(limit: max_per_page)
+      else
+        options
+      end
+    end
+
+    def default_pagination_options
+      {
+        limit: @per_page,
+        offset: 0,
+      }.with_indifferent_access
+    end
+  end
+end