fend 0.1.0

data/lib/fend/plugins/collective_params.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # `collective_params` plugin allows you to specify multiple params at once,
+    # instead of defining each one separately.
+    #
+    # Example:
+    #
+    #     plugin :collective_params
+    #     plugin :validation_helpers # just to make the example more concise
+    #
+    #     validate do |i|
+    #       i.params(:name, :email, :address) do |name, email, address|
+    #         name.validate_presence
+    #
+    #         email.validate_format(EMAIL_REGEX)
+    #
+    #         address.params(:city, :street, :zip) do |city, street, zip|
+    #           # ...
+    #         end
+    #       end
+    #     end
+    #
+    # Since all params are then available in the same scope, you can add custom
+    # validations more easily:
+    #
+    #     validate do |i|
+    #       i.params(:started_at, :ended_at) do |started_at, ended_at|
+    #         started_at.validate_presence
+    #         started_at.validate_type(Time)
+    #
+    #         ended_at.validate_presence
+    #         ended_at.validate_type(Time)
+    #
+    #         if started_at.valid? && ended_at.valid? && started_at > ended_at
+    #           started_at.add_error("must happen before ended_at")
+    #         end
+    #       end
+    #     end
+    module CollectiveParams
+      module ParamMethods
+        def params(*names, &block)
+          return if flat? && invalid?
+
+          params = names.each_with_object({}) do |name, result|
+            param = _build_param(self[name])
+            result[name] = param
+          end
+
+          yield(*params.values)
+
+          params.each { |name, param| _nest_errors(name, param.errors) if param.invalid? }
+        end
+      end
+    end
+
+    register_plugin(:collective_params, CollectiveParams)
+  end
+end

data/lib/fend/plugins/data_processing.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # By default, Fend provides methods for input and output processing.
+    #
+    #     class UserValidation < Fend
+    #       #...
+    #
+    #       def process_input(input)
+    #         # symbolize input data keys
+    #         symbolized_input = input.each_with_object({}) do |(key, value), result|
+    #           new_key = key.is_a?(String) ? key.to_sym : key
+    #           result[new_key] = value
+    #         end
+    #
+    #         # do some additional processing
+    #       end
+    #
+    #       def process_output(output)
+    #         # filter output data
+    #         whitelist = [:username, :email, :address]
+    #         filtered_output = output.each_with_object({}) do |(key, value), result|
+    #           result[key] = value if whitelist.include?(key)
+    #         end
+    #
+    #         # do some additional processing
+    #       end
+    #     end
+    #
+    # `data_processing` plugin allows you to define processing steps in more
+    #  declarative manner:
+    #
+    #     plugin :data_processing
+    #
+    #     process(:input) do |input|
+    #       # symbolize keys
+    #     end
+    #
+    #     process(:output) do |output|
+    #       # filter
+    #     end
+    #
+    # You can define as much processing steps as you need and they will be
+    # executed in order in which they are defined.
+    #
+    # ## Built-in processings
+    #
+    # You can activate built-in processings when loading the plugin:
+    #
+    #     # this will:
+    #     #   symbolize and freeze input data
+    #     #   stringify output data
+    #     plugin :data_processing, input: [:symbolize, :freeze],
+    #                              output: [:stringify]
+    #
+    # :symbolize
+    # : Symbolizes keys.
+    #
+    # :stringify
+    # : Stringifies keys
+    #
+    # :dup
+    # : Duplicates data
+    #
+    # :freeze
+    # : Freezes data
+    #
+    # All of the above support deeply nested data.
+    #
+    # Built-in processings are executed **before** any
+    # user-defined ones.
+    #
+    # ## Data mutation
+    #
+    # Fend will never mutate the raw input data you provide:
+    #
+    #     raw_input = { username: "john", email: "john@example.com" }
+    #     UserValidation.call(raw_input)
+    #
+    # However, nothing can stop you from performing destructive operations
+    # (`merge!`, `delete`, etc...) in custom processing steps. If you intend to
+    # mutate input/output data, make sure to use `:dup` processing, in order to
+    # ensure immutability.
+    module DataProcessing
+      BUILT_IN_PROCESSINGS = {
+        symbolize:   ->(data) { Process.symbolize_keys(data) },
+        stringify:   ->(data) { Process.stringify_keys(data) },
+        dup:         ->(data) { Process.duplicate(data) },
+        freeze:      ->(data) { Process.frost(data) }
+      }.freeze
+
+      def self.configure(validation, options = {})
+        validation.opts[:data_processing] = {}
+        validation.opts[:data_processing][:input] ||= []
+        validation.opts[:data_processing][:output] ||= []
+
+        return if options.empty?
+
+        options.each do |data_ref, processings|
+          processings.each_with_object(validation.opts[:data_processing][data_ref]) do |name, result|
+            raise Error, "Built-in processing not found: ':#{name}'" unless BUILT_IN_PROCESSINGS.key?(name)
+
+            result << BUILT_IN_PROCESSINGS[name]
+          end
+        end
+      end
+
+      module ClassMethods
+        def process(data_key, &block)
+          opts[:data_processing][data_key] ||= []
+          opts[:data_processing][data_key] << block
+        end
+      end
+
+      module InstanceMethods
+        def process_input(data)
+          super
+          process_data(:input, data)
+        end
+
+        def process_output(data)
+          super
+          process_data(:output, data)
+        end
+
+        private
+
+        def process_data(key, data)
+          result = data
+
+          self.class.opts[:data_processing][key].each do |process_block|
+            result = instance_exec(result, &process_block)
+          end
+
+          result
+        end
+      end
+
+      class Process
+        HASH_OR_ARRAY = ->(a) { a.is_a?(Hash) || a.is_a?(Array) }.freeze
+        NESTED_ARRAY  = ->(a) { a.is_a?(Array) && a.any? { |member| HASH_OR_ARRAY[member] } }.freeze
+        NESTED_HASH   = ->(a) { a.is_a?(Hash)  && a.any? { |_, value| HASH_OR_ARRAY[value] } }.freeze
+
+        def self.symbolize_keys(data)
+          return data unless HASH_OR_ARRAY[data]
+
+          transformation = ->(key) { key.is_a?(String) ? key.to_sym : key }
+
+          deep_transform_keys(data, transformation)
+        end
+
+        def self.stringify_keys(data)
+          return data unless HASH_OR_ARRAY[data]
+
+          transformation = ->(key) { key.is_a?(Symbol) ? key.to_s : key }
+
+          deep_transform_keys(data, transformation)
+        end
+
+        def self.duplicate(data, opts = {})
+          return data unless HASH_OR_ARRAY[data]
+
+          case data
+          when NESTED_HASH
+            data.each_with_object({}) { |(key, value), result| result[key] = duplicate(value) }
+          when NESTED_ARRAY
+            data.map(&method(:duplicate))
+          when HASH_OR_ARRAY
+            data.dup
+          else
+            data
+          end
+        end
+
+        def self.frost(data)
+          return data unless HASH_OR_ARRAY[data]
+
+          case data
+          when NESTED_HASH
+            data.each_with_object({}) { |(key, value), result| result[key] = frost(value) }.freeze
+          when NESTED_ARRAY
+            data.map(&method(:frost)).freeze
+          when HASH_OR_ARRAY
+            data.dup.freeze
+          else
+            data
+          end
+        end
+
+        private
+
+        def self.deep_transform_keys(data, key_proc)
+          case data
+          when Hash
+            data.each_with_object({}) do |(key, value), result|
+              _key = key_proc[key]
+
+              result[_key] = deep_transform_keys(value, key_proc)
+            end
+          when NESTED_ARRAY
+            data.map { |member| deep_transform_keys(member, key_proc) }
+          else
+            data
+          end
+        end
+      end
+    end
+
+    register_plugin(:data_processing, DataProcessing)
+  end
+end

data/lib/fend/plugins/dependencies.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # `dependencies` plugin enables you to register validation dependencies and
+    # later resolve them so they would be available in validation block
+    #
+    #     plugin :dependencies
+    #
+    # ## Registering dependencies
+    #
+    # There are two types of dependencies:
+    #
+    # 1. **Inheritable dependencies** - available in current validation class
+    #                                   and in subclasses
+    # 2. **Local dependencies** - available only in current validation class
+    #
+    # ### Inheritable dependencies
+    #
+    # Inheritable dependencies can be registered when plugin is loaded:
+    #
+    #     plugin :dependencies, user_class: User
+    #
+    # **Global dependencies** can be registered by loading the plugin directly in
+    # `Fend` class:
+    #
+    #     require "address_checker"
+    #
+    #     Fend.plugin :dependencies, address_checker: AddressChecker.new
+    #
+    # Now, all `Fend` subclasses will be able to resolve `address_checker`
+    #
+    # ### Local dependencies
+    #
+    # Local dependencies can be registered in `deps` registry, on instance level.
+    # Recommended place to do this is the initializer.
+    #
+    #     class UserValidation < Fend
+    #       plugin :dependencies
+    #
+    #       def initialize(model)
+    #         # you can pass a dependency on initialization
+    #         deps[:model] = model
+    #
+    #         # or
+    #
+    #         # hardcode it yourself
+    #         deps[:address_checker] = AddressChecker.new
+    #       end
+    #     end
+    #
+    #     user_validation = UserValidation.new(User)
+    #
+    # ## Resolving dependencies
+    #
+    # To resolve dependencies, `:inject` option needs to be provided to the
+    # `validate` method, with a list of keys representing dependency names:
+    #
+    #     class UserValidation < Fend
+    #       plugin :dependencies, user_model: User
+    #
+    #       validate(inject: [:user_model, :address_checker]) do |i, user_model, address_checker|
+    #         user_model #=> User
+    #         address_checker #=> #<AddressChecker ...>
+    #       end
+    #
+    #       def initialize(address_checker)
+    #         deps[:address_checker] = address_checker
+    #       end
+    #     end
+    #
+    # ## Overriding inheritable dependencies
+    #
+    # To override inheritable dependency, just load the plugin again in a
+    # subclass, or define local dependency with the same name.
+    #
+    #     plugin :dependencies, user_model: SpecialUser
+    #
+    #     # or
+    #
+    #     def initialize
+    #       deps[:user_model] = SpecialUser
+    #     end
+    #
+    # ## Example usage
+    #
+    # Here's an example of email uniqueness validation:
+    #
+    #     validate(inject: [:user_model]) do |i, user_model|
+    #       i.param(:email) do |email|
+    #         email.add_error("must be unique") if user_model.exists?(email: email.value)
+    #       end
+    #     end
+    module Dependencies
+      def self.configure(validation, opts = {})
+        validation.opts[:dependencies] = (validation.opts[:dependencies] || {}).merge(opts)
+      end
+
+      module ClassMethods
+        attr_reader :specified_dependencies
+
+        def validate(opts = {}, &block)
+          if opts.key?(:inject)
+            raise ArgumentError, ":inject option value must be an array" unless opts[:inject].is_a?(Array)
+
+            @specified_dependencies = opts[:inject] unless opts[:inject].nil?
+          end
+
+          super(&block)
+        end
+      end
+
+      module InstanceMethods
+        def deps
+          @_deps ||= self.class.opts[:dependencies].dup
+        end
+
+        def validate(&block)
+          super if self.class.specified_dependencies.nil?
+
+          dependencies = deps.values_at(*self.class.specified_dependencies)
+
+          yield(@_input_param, *dependencies) if block_given?
+        end
+      end
+    end
+
+    register_plugin(:dependencies, Dependencies)
+  end
+end

data/lib/fend/plugins/external_validation.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # `external_validation` plugin allows you to delegate param validations to
+    # external classes/objects.
+    #
+    #     plugin :external_validation
+    #
+    # External validation must respond to `call` method that takes param value
+    # as an argument and returns error messages either as an array or hash
+    # (nested data).
+    #
+    #     class CustomEmailValidator
+    #       def initialize
+    #         @errors = []
+    #       end
+    #
+    #       def call(email_value)
+    #         @errors << "must be string" unless email_value.is_a?(String)
+    #         @errors << "must be unique" unless unique?(email_value)
+    #
+    #         @errors
+    #       end
+    #
+    #       def unique?(value)
+    #         UniquenessCheck.call(value)
+    #       end
+    #     end
+    #
+    #     class AddressValidation < Fend
+    #       plugin :validation_options
+    #       plugin :collective_params
+    #
+    #       validate do |i|
+    #         i.params(:city, :street) do |city, street|
+    #           city.validate(type: String)
+    #           street.validate(type: String)
+    #         end
+    #       end
+    #     end
+    #
+    #     class UserValidation < Fend
+    #       plugin :external_validation
+    #       plugin :collective_params
+    #
+    #       validate do |i|
+    #         i.params(:email, :address) do |email, address|
+    #           email.validate_with(CustomEmailValidation.new)
+    #
+    #           address.validate_with(AddressValidation)
+    #         end
+    #       end
+    #     end
+    #
+    # `validation_options` plugin supports `external_validation`:
+    #
+    #     email.validate(with: CustomEmailValidation.new)
+    #
+    # You are free to combine internal and external validations any way you
+    # like. Using one doesn't mean you can't use the other.
+
+    module ExternalValidation
+      module ParamMethods
+        def validate_with(validation)
+          result   = validation.call(value)
+          messages = result.class.ancestors.include?(Fend::Result) ? result.messages : result
+
+          return if messages.is_a?(Hash) && flat? && invalid?
+
+          @errors = if @errors.is_a?(Hash) && messages.is_a?(Hash)
+                      _deep_merge_messages(@errors, messages)
+                    elsif @errors.is_a?(Array) && messages.is_a?(Array)
+                      @errors + messages
+                    else
+                      messages
+                    end
+        end
+
+        private
+
+        def _deep_merge_messages(hash, other_hash)
+          hash.merge(other_hash) do |_, old_val, new_val|
+            if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+              deep_merge(old_val, new_val)
+            elsif old_val.is_a?(Array) && new_val.is_a?(Array)
+              old_val + new_val
+            else
+              new_val
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:external_validation, ExternalValidation)
+  end
+end