might 0.3.0

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:rspec)
+
+task default: :rspec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'might'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  activemodel:
+    errors:
+      messages:
+        undefined_filter: is not allowed filter name
+        undefined_sort_order: is not allowed sort order
+        invalid_page_type: is expected to be a HashMap with :limit and :offset keys

data/lib/might.rb

@@ -0,0 +1,4 @@
+# Top level namespace for mighty fetchers
+module Might
+  require 'might/version'
+end

data/lib/might/fetcher.rb

@@ -0,0 +1,252 @@
+require 'might/sort_parameters_extractor'
+require 'might/sort_parameters_validator'
+require 'might/filter_parameters_extractor'
+require 'might/filter_parameters_validator'
+require 'might/pagination_parameters_validator'
+
+require 'might/filter_middleware'
+require 'might/sort_middleware'
+require 'might/pagination_middleware'
+
+require 'might/result'
+require 'uber/inheritable_attr'
+require 'middleware'
+
+#
+module Might
+  # Configure your own fetcher
+  #
+  #     PagesFetcher < Might::Fetcher
+  #       self.resource_class = Page
+  #     end
+  #
+  # You can configure filterable attributes for model
+  #
+  #     filter :id, validates: { presence: true }
+  #     filter :name
+  #     filter :start_at, validates: { presence: true }
+  #
+  # If your property name doesn't match the name in the query string, use the :as option:
+  #
+  #     filter :kind, as: :type
+  #
+  # So the Movie#kind property would be exposed to API as :type
+  #
+  # You may specify allowed sorting order:
+  #
+  #     sort :id
+  #     sort :name
+  #
+  # If your property name doesn't match the name in the query string, use the :as option:
+  #
+  #     sort :position, as: :relevance
+  #
+  # So client should pass +?sort=relevance+ in order to sort by position
+  #
+  # It's also possible to reverse meaning of the order direction. For example it's not
+  # make sense to order by position from lower value to higher.
+  # The meaning default for that sorting is reversed order by default, so more relevant elenents
+  # would be the first.
+  #
+  #     sort :position, as: :relevance, reverse_direction: true
+  #
+  class Fetcher
+    extend Uber::InheritableAttr
+
+    inheritable_attr :resource_class
+    inheritable_attr :filter_parameters_definition
+    inheritable_attr :sort_parameters_definition
+    inheritable_attr :middleware_changes
+
+    self.filter_parameters_definition = Set.new
+    self.sort_parameters_definition = Set.new
+    self.middleware_changes = []
+
+    # @return [Hash]
+    attr_reader :params
+
+    # @param params [Hash]
+    def initialize(params)
+      @params = params
+    end
+
+    # @return [ActiveRecord::Result] filtered and sorted collection
+    # @yieldparam collection [Result] if a block given
+    #
+    # @example
+    #   PagesFetcher.new(params).call #=> Result
+    #
+    # @example block syntax
+    #   PagesFetcher.new(params) do |result|
+    #     if result.success?
+    #       result.get
+    #     else
+    #       result.errors
+    #     end
+    #   end
+    #
+    def call
+      processed_params, errors = process_params(params)
+      result = if errors.any?
+                 Failure.new(errors)
+               else
+                 processed_collection, = middleware.call([collection, processed_params])
+                 Success.new(processed_collection)
+               end
+
+      if block_given?
+        yield result
+      else
+        result
+      end
+    end
+
+    private
+
+    # @return [ActiveRecord::Relation]
+    def collection
+      self.class.resource_class.all
+    end
+
+    # Library middleware stack
+    # @return [Middleware::Builder]
+    def default_middleware
+      Middleware::Builder.new do |b|
+        b.use FilterMiddleware
+        b.use SortMiddleware
+        b.use PaginationMiddleware
+      end
+    end
+
+    # User modified middleware stack
+    # @return [Middleware::Builder]
+    def middleware
+      default_middleware.tap do |builder|
+        self.class.middleware_changes.each do |change|
+          builder.instance_eval(&change)
+        end
+      end
+    end
+
+    # @return [Hash, Array] tuple of parameters and processing errors
+    #   this errors may be shown to front-end developer
+    def process_params(params)
+      Middleware::Builder.new do |b|
+        b.use FilterParametersExtractor, self.class.filter_parameters_definition
+        b.use FilterParametersValidator
+        b.use SortParametersExtractor, self.class.sort_parameters_definition
+        b.use SortParametersValidator
+        b.use PaginationParametersValidator
+      end.call([params, []])
+    end
+
+    class << self
+      # Alter middleware chain with the given block
+      # @param [Proc] change
+      # @return [Might]
+      #
+      # @example
+      #   class ChannelsFetcher
+      #     middleware do
+      #       use CustomMiddleware
+      #     end
+      #   end
+      #
+      def middleware(&change)
+        fail ArgumentError unless block_given?
+        middleware_changes << change
+        self
+      end
+
+      # Register collection sorting by its name
+      # @param name [Symbol] of the field
+      # @return [void]
+      # @see +RansackableSort+ for details
+      #
+      def sort(name, options = {})
+        definition = SortParameterDefinition.new(name, options)
+        sort_parameters_definition.add(definition)
+      end
+
+      # Register collection filter by its name
+      # @see +Might::Filter+ for details
+      #
+      # @overload filter(filter_name, options)
+      #   @param [Symbol] filter_name
+      #   @param [Hash] options
+      #   @return [void]
+      # @example
+      #   filter :genre_name, on: :resource
+      #
+      # @overload filter(filter_name: predicates, **options)
+      #   @param [Symbol] filter_name
+      #   @param [<Symbol>] predicates
+      #   @param [Hash] other options options
+      #   @return [void]
+      # @example
+      #   filter genre_name: [:eq, :in], on: :resource
+      #
+      def filter(*args)
+        options = args.extract_options!
+        if args.empty?
+          filter_name = options.keys.first
+          predicates = options.values.first
+          options = options.except(filter_name).merge(predicates: predicates)
+        else
+          filter_name = args.first
+        end
+
+        definition = FilterParameterDefinition.new(filter_name, options)
+        filter_parameters_definition.add(definition)
+      end
+
+      # @param params [Hash] user provided input
+      # @yieldparam collection [ActiveRecord::Relation]
+      def run(params, &block)
+        new(params).call(&block)
+      end
+
+      # Add middleware to the end of middleware chane
+      #
+      #   class MovieFetcher
+      #     after do |scope, params|
+      #       # do something with scope and params
+      #       [scope.map(&:resource), params]
+      #     end
+      #   end
+      #
+      def after(&block)
+        alter_middleware(:use, &block)
+      end
+
+      # Add middleware to the beginning of middleware chane
+      #
+      #   class MovieFetcher
+      #     before do |scope, params|
+      #       # do something with scope and params
+      #       [scope.map(&:resource), params]
+      #     end
+      #   end
+      #
+      def before(middleware_or_index = 0, &block)
+        alter_middleware(:insert_before, middleware_or_index, &block)
+      end
+
+      private
+
+      def alter_middleware(method_name, *args, &block)
+        fail ArgumentError unless block_given?
+        middleware_changes.push lambda { |builder|
+          builder.send method_name, *args, lambda { |env|
+            scope, params = env
+            block.call(scope, params).tap do |r|
+              if !r.is_a?(Array) || r.size != 2
+                fail 'After block must return tuple of scope and params'
+              end
+            end
+          }
+        }
+      end
+    end
+  end
+end

data/lib/might/fetcher_error.rb

@@ -0,0 +1,4 @@
+module Might
+  class FetcherError < StandardError
+  end
+end

data/lib/might/filter_middleware.rb

@@ -0,0 +1,28 @@
+require_relative 'ransackable_filter'
+require_relative 'ransackable_filter_parameters_adapter'
+require 'middleware'
+#
+module Might
+  # Filter scope using ransack gem
+  #
+  class FilterMiddleware
+    # @param app [#call, Proc]
+    #
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      scope, = ::Middleware::Builder.new do |b|
+        b.use RansackableFilterParametersAdapter
+        b.use RansackableFilter
+      end.call(env)
+
+      app.call([scope, env[1]])
+    end
+
+    private
+
+    attr_reader :app
+  end
+end

data/lib/might/filter_parameter.rb

@@ -0,0 +1,68 @@
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/blank'
+
+module Might
+  # User provided filtering on particular parameter
+  #
+  class FilterParameter
+    # @return [String, nil]
+    #
+    attr_reader :predicate
+
+    # @return [ParameterDefinition, nil]
+    #
+    attr_reader :definition
+
+    def initialize(value, predicate, definition)
+      @value = value
+      @predicate = predicate.to_s
+      @definition = definition
+    end
+
+    delegate :name, to: :definition
+    delegate :on, to: :definition
+
+    # Check if this parameter provided by user.
+    # If the parameter defined by not given by user this returns false.
+    # @return [Boolean]
+    def provided?
+      value.present? && predicate.present?
+    end
+
+    def ==(other)
+      is_a?(other.class) &&
+        value == other.value &&
+        predicate == other.predicate &&
+        definition == other.definition
+    end
+
+    # @return [String, Array<String>]
+    # TODO: memoize
+    def value
+      if @value.is_a?(Array)
+        @value.map { |v| definition.coerce(v) }
+      else
+        definition.coerce(@value)
+      end
+    end
+
+    def valid?
+      validators.all?(&:valid?)
+    end
+
+    def invalid?
+      validators.any?(&:invalid?)
+    end
+
+    def errors
+      validators.map(&:errors).flat_map(&:full_messages).compact.uniq
+    end
+
+    private
+
+    def validators
+      values_for_validation = @value.is_a?(Array) ? @value : [@value]
+      @validators ||= values_for_validation.map { |v| definition.validator.new(v) }
+    end
+  end
+end

data/lib/might/filter_parameter_definition.rb

@@ -0,0 +1,82 @@
+require 'active_support/core_ext/module/delegation'
+require_relative 'filter_predicates'
+require_relative 'filter_value_validator'
+
+module Might
+  # 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