rubanok 0.1.1 → 0.4.0

data/lib/rubanok.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require "rubanok/version"
-require "rubanok/plane"
+require "rubanok/processor"
 
 require "rubanok/railtie" if defined?(Rails)
 
+# @type const ENV: Hash[String, String]
 if defined?(RSpec) && (ENV["RACK_ENV"] == "test" || ENV["RAILS_ENV"] == "test")
   require "rubanok/rspec"
 end
@@ -13,15 +14,15 @@ end
 #
 # Example:
 #
-#   class CourseSessionPlane < Rubanok::Plane
+#   class CourseSessionProcessor < Rubanok::Processor
 #     map :q do |q:|
-#      raw.searh(q)
+#       raw.searh(q)
 #     end
 #   end
 #
 #   class CourseSessionController < ApplicationController
 #     def index
-#       @sessions = planish(CourseSession.all)
+#       @sessions = rubanok_process(CourseSession.all)
 #     end
 #   end
 module Rubanok
@@ -30,7 +31,10 @@ module Rubanok
     # When the value is empty and ignored the corresponding matcher/mapper
     # is not activated (true by default)
     attr_accessor :ignore_empty_values
+    # Define wheter to fail when `match` rule cannot find matching value
+    attr_accessor :fail_when_no_matches
   end
 
   self.ignore_empty_values = true
+  self.fail_when_no_matches = false
 end

data/lib/rubanok/dsl/mapping.rb

@@ -2,7 +2,7 @@
 
 module Rubanok
   module DSL
-    # Adds `.map` method to Plane to define key-matching rules:
+    # Adds `.map` method to Processor to define key-matching rules:
     #
     #   map :q do |q:|
     #    # this rule is activated iff "q" (or :q) param is present
@@ -20,12 +20,29 @@ module Rubanok
         end
       end
 
-      def map(*fields, **options, &block)
-        rule = Rule.new(fields, options)
+      module ClassMethods
+        def map(*fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil, &block)
+          filter = filter_with
 
-        define_method(rule.to_method_name, &block)
+          if filter.is_a?(Symbol)
+            respond_to?(filter) || raise(
+              ArgumentError,
+              "Unknown class method #{filter} for #{self}. " \
+              "Make sure that a filter method is defined before the call to .map."
+            )
+            filter = method(filter)
+          end
 
-        rules << rule
+          rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always, ignore_empty_values: ignore_empty_values, filter_with: filter)
+
+          define_method(rule.to_method_name, &block)
+
+          add_rule rule
+        end
+      end
+
+      def self.included(base)
+        base.extend ClassMethods
       end
     end
   end

data/lib/rubanok/dsl/matching.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module Rubanok
+  class UnexpectedInputError < StandardError; end
+
   module DSL
-    # Adds `.match` method to Plane class to define key-value-matching rules:
+    # Adds `.match` method to Processor class to define key-value-matching rules:
     #
     #   match :sort, :sort_by do |sort:, sort_by:|
     #     # this rule is activated iff both "sort" and "sort_by" params are present
@@ -20,8 +22,8 @@ module Rubanok
         class Clause < Rubanok::Rule
           attr_reader :values, :id, :block
 
-          def initialize(id, fields, values = [], **options, &block)
-            super(fields, options)
+          def initialize(id, fields, values, activate_on: fields, activate_always: false, &block)
+            super(fields, activate_on: activate_on, activate_always: activate_always)
             @id = id
             @block = block
             @values = Hash[fields.take(values.size).zip(values)].freeze
@@ -37,7 +39,7 @@ module Rubanok
 
         attr_reader :clauses
 
-        def initialize(*)
+        def initialize(fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil)
           super
           @clauses = []
         end
@@ -53,7 +55,7 @@ module Rubanok
         end
 
         def default(&block)
-          clauses << Clause.new("#{to_method_name}_default", fields, activate_always: true, &block)
+          clauses << Clause.new("#{to_method_name}_default", fields, [], activate_always: true, &block)
         end
 
         private
@@ -64,23 +66,45 @@ module Rubanok
         end
       end
 
-      def match(*fields, **options, &block)
-        rule = Rule.new(fields, options)
+      module ClassMethods
+        def match(*fields, activate_on: fields, activate_always: false, fail_when_no_matches: nil, &block)
+          rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always)
 
-        rule.instance_eval(&block)
+          rule.instance_eval(&block)
 
-        define_method(rule.to_method_name) do |params|
-          clause = rule.matching_clause(params)
-          next raw unless clause
+          define_method(rule.to_method_name) do |params = {}|
+            params ||= {} if params.nil?
 
-          apply_rule! clause.to_method_name, clause.project(params)
-        end
+            clause = rule.matching_clause(params)
+
+            if clause
+              apply_rule! clause, params
+            else
+              default_match_handler(rule, params, fail_when_no_matches)
+            end
+          end
+
+          rule.clauses.each do |clause|
+            define_method(clause.to_method_name, &clause.block)
+          end
 
-        rule.clauses.each do |clause|
-          define_method(clause.to_method_name, &clause.block)
+          add_rule rule
         end
+      end
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      def default_match_handler(rule, params, fail_when_no_matches)
+        fail_when_no_matches = Rubanok.fail_when_no_matches if fail_when_no_matches.nil?
+        return raw unless fail_when_no_matches
 
-        rules << rule
+        raise ::Rubanok::UnexpectedInputError, <<~MSG
+          Unexpected input: #{params.slice(*rule.fields)}.
+          Available values are:
+            #{rule.clauses.map(&:values).join("\n  ")}
+        MSG
       end
     end
   end

data/lib/rubanok/processor.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "set"
+
+require "rubanok/rule"
+
+require "rubanok/dsl/mapping"
+require "rubanok/dsl/matching"
+
+module Rubanok
+  # Base class for processors (_planes_)
+  #
+  # Define transformation rules via `map` and `match` methods
+  # and apply them by calling the processor:
+  #
+  #   class MyTransformer < Rubanok::Processor
+  #     map :type do
+  #       raw.where(type: type)
+  #     end
+  #   end
+  #
+  #   MyTransformer.call(MyModel.all, {type: "public"})
+  #
+  # NOTE: the second argument (`params`) MUST be a Hash. Keys could be either Symbols
+  # or Strings (we automatically transform strings to symbols while matching rules).
+  #
+  # All transformation methods are called within the context of the instance of
+  # a processor class.
+  #
+  # You can access the input data via `raw` method.
+  class Processor
+    include DSL::Matching
+    include DSL::Mapping
+
+    UNDEFINED = Object.new
+
+    class << self
+      def call(input, params = UNDEFINED)
+        input, params = nil, input if params == UNDEFINED
+
+        raise ArgumentError, "Params could not be nil" if params.nil?
+
+        # @type var params: untyped
+        new(input).call(params)
+      end
+
+      def add_rule(rule)
+        fields_set.merge rule.fields
+        rules << rule
+      end
+
+      def rules
+        return @rules if instance_variable_defined?(:@rules)
+
+        @rules =
+          if superclass <= Processor
+            superclass.rules.dup
+          else
+            []
+          end
+      end
+
+      def fields_set
+        return @fields_set if instance_variable_defined?(:@fields_set)
+
+        @fields_set =
+          if superclass <= Processor
+            superclass.fields_set.dup
+          else
+            Set.new
+          end
+      end
+
+      # Generates a `params` projection including only the keys used
+      # by the rules
+      def project(params)
+        params = params.transform_keys(&:to_sym)
+        params.slice(*fields_set.to_a)
+      end
+
+      # DSL to define the #prepare method
+      def prepare(&block)
+        define_method(:prepare, &block)
+      end
+    end
+
+    def initialize(input)
+      @input = input
+      @prepared = false
+    end
+
+    def call(params)
+      params = params.transform_keys(&:to_sym)
+
+      rules.each do |rule|
+        next unless rule.applicable?(params)
+
+        prepare! unless prepared?
+        apply_rule! rule, params
+      end
+
+      input
+    end
+
+    private
+
+    attr_accessor :input, :prepared
+
+    alias raw input
+    alias prepared? prepared
+
+    def apply_rule!(rule, params)
+      method_name, data = rule.to_method_name, rule.project(params)
+
+      return unless data
+
+      self.input =
+        if data.empty?
+          send(method_name)
+        else
+          send(method_name, **data)
+        end
+    end
+
+    def prepare
+      # no-op
+    end
+
+    def prepare!
+      @prepared = true
+
+      prepared_input = prepare
+      return unless prepared_input
+
+      self.input = prepared_input
+    end
+
+    def rules
+      self.class.rules
+    end
+  end
+
+  Plane = Processor
+end

data/lib/rubanok/rails/controller.rb

@@ -4,33 +4,78 @@ require "active_support/concern"
 
 module Rubanok
   # Controller concern.
-  # Adds `planish` method.
+  # Adds `rubanok_process` method.
   module Controller
     extend ActiveSupport::Concern
 
-    # Planish passed data (e.g. ActiveRecord relation) using
-    # the corrsponding Plane class.
+    included do
+      if respond_to?(:helper_method)
+        helper_method :rubanok_scope
+        helper_method :planish_scope
+      end
+    end
+
+    # This method process passed data (e.g. ActiveRecord relation) using
+    # the corresponding Processor class.
     #
-    # Plane is inferred from controller name, e.g.
-    # "PostsController -> PostPlane".
+    # Processor is inferred from controller name, e.g.
+    # "PostsController -> PostProcessor".
     #
-    # You can specify the Plane class explicitly via `with` option.
+    # You can specify the Processor class explicitly via `with` option.
     #
-    # By default, `params` object is passed as paraters, but you
+    # By default, `params` object is passed as parameters, but you
     # can specify the params via `params` option.
-    def planish(data, plane_params = nil, with: implicit_plane_class)
+    def rubanok_process(data, params = nil, with: nil)
+      with_inferred_rubanok_params(with, params) do |rubanok_class, rubanok_params|
+        rubanok_class.call(data, rubanok_params)
+      end
+    end
+
+    # This method filters the passed params and returns the Hash (!)
+    # of the params recongnized by the processor.
+    #
+    # Processor is inferred from controller name, e.g.
+    # "PostsController -> PostProcessor".
+    #
+    # You can specify the Processor class explicitly via `with` option.
+    #
+    # By default, `params` object is passed as parameters, but you
+    # can specify the params via `params` option.
+    def rubanok_scope(params = nil, with: nil)
+      with_inferred_rubanok_params(with, params) do |rubanok_class, rubanok_params|
+        rubanok_class.project(rubanok_params)
+      end
+    end
+
+    # Tries to infer the rubanok processor class from controller path
+    def implicit_rubanok_class
+      "#{controller_path.classify.pluralize}Processor".safe_constantize
+    end
+
+    def with_inferred_rubanok_params(with, params)
+      with ||= implicit_rubanok_class
+
       if with.nil?
-        raise ArgumentError, "Failed to find a plane class for #{self.class.name}. " \
-                             "Please, specify the plane class explicitly via `with` option"
+        raise ArgumentError, "Failed to find a processor class for #{self.class.name}. " \
+                             "Please, specify the processor class explicitly via `with` option"
       end
 
-      plane_params ||= params
+      params ||= self.params
+
+      params = params.to_unsafe_h if params.is_a?(ActionController::Parameters)
+
+      yield with, params
+    end
+
+    # Backward compatibility
+    def planish(*args, with: implicit_plane_class)
+      rubanok_process(*args, with: with)
+    end
 
-      plane_params = plane_params.to_unsafe_h if plane_params.is_a?(ActionController::Parameters)
-      with.call(data, plane_params)
+    def planish_scope(*args, with: implicit_plane_class)
+      rubanok_scope(*args, with: with)
     end
 
-    # Tries to infer the plane class from controller path
     def implicit_plane_class
       "#{controller_path.classify.pluralize}Plane".safe_constantize
     end

data/lib/rubanok/railtie.rb

@@ -8,6 +8,12 @@ module Rubanok # :nodoc:
 
         ActionController::Base.include Rubanok::Controller
       end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        require "rubanok/rails/controller"
+
+        ActionController::API.include Rubanok::Controller
+      end
     end
   end
 end

data/lib/rubanok/rspec.rb

@@ -3,20 +3,26 @@
 require "rspec/mocks"
 
 module Rubanok
-  class HavePlanished < RSpec::Matchers::BuiltIn::BaseMatcher
+  class HaveProcessed < RSpec::Matchers::BuiltIn::BaseMatcher
     include RSpec::Mocks::ExampleMethods
 
-    attr_reader :data_class, :plane, :matcher
+    attr_reader :data_class, :processor, :matcher
 
     def initialize(data_class = nil)
       if data_class
         @data_class = data_class.is_a?(Module) ? data_class : data_class.class
       end
       @matcher = have_received(:call)
+      @name = "have_rubanok_processed"
     end
 
-    def with(plane)
-      @plane = plane
+    def as(alias_name)
+      @name = alias_name
+      self
+    end
+
+    def with(processor)
+      @processor = processor
       self
     end
 
@@ -25,32 +31,40 @@ module Rubanok
     end
 
     def matches?(proc)
-      raise ArgumentError, "have_planished only supports block expectations" unless Proc === proc
+      raise ArgumentError, "#{name} only supports block expectations" unless Proc === proc
 
-      raise ArgumentError, "Plane class is required. Please, specify it using `.with` modifier" if plane.nil?
+      raise ArgumentError, "Processor class is required. Please, specify it using `.with` modifier" if processor.nil?
 
-      allow(plane).to receive(:call).and_call_original
+      allow(processor).to receive(:call).and_call_original
       proc.call
 
       matcher.with(an_instance_of(data_class), anything) if data_class
 
-      matcher.matches?(plane)
+      matcher.matches?(processor)
     end
 
     def failure_message
-      "expected to use #{plane.name}#{data_class ? " for #{data_class.name}" : ""}, but didn't"
+      "expected to use #{processor.name}#{data_class ? " for #{data_class.name}" : ""}, but didn't"
     end
 
     def failure_message_when_negated
-      "expected not to use #{plane.name}#{data_class ? " for #{data_class.name} " : ""}, but have used"
+      "expected not to use #{processor.name}#{data_class ? " for #{data_class.name} " : ""}, but have used"
     end
+
+    private
+
+    attr_reader :name
   end
 end
 
 RSpec.configure do |config|
   config.include(Module.new do
+    def have_rubanok_processed(*args)
+      Rubanok::HaveProcessed.new(*args)
+    end
+
     def have_planished(*args)
-      Rubanok::HavePlanished.new(*args)
+      Rubanok::HaveProcessed.new(*args).as("have_planished")
     end
   end)
 end