fend 0.1.0

data/lib/fend/plugins/full_messages.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # `full_messages` plugin adds `#full_messages` method to `Result` which
+    # returns error messages with prependend param name
+    #
+    #      class UserValidation < Fend
+    #        plugin :full_messages
+    #
+    #        # ...
+    #      end
+    #      result = UserValidation.call(email: "invalid", profile: "invalid", address: { })
+    #
+    #      result.full_messages
+    #      #=> { email: ["email is in invalid format"], profile: ["profile must be hash"], address: { city: ["city must be string"] } }
+    #
+    # ## Array members
+    #
+    # When validating array elements, messages are returned with prependend
+    # index, since array members don't have a name.
+    #
+    #      { tags: { 0 => ["0 must be string"] } }
+    #
+    # In order to make full messages nicer for array elements,
+    # pass `:array_memeber_names` option when loading the plugin:
+    #
+    #      plugin :full_messages, array_member_names: { tags: :tag }
+    #
+    #      # which will produce
+    #      { tags: { 0 => ["tag must be string"] } }
+    #
+    # `:array_member_names` options is inheritable, so it's possible to define
+    # it globaly by loading the plugin directly through `Fend` class.
+    #
+    #     Fend.plugin :full_messages, array_member_names: { octopi: :octopus }
+    #
+    module FullMessages
+      def self.configure(validation, opts = {})
+        validation.opts[:full_messages_array_member_names] = (validation.opts[:full_messages_array_member_names] || {}).merge(opts[:array_member_names] || {})
+      end
+
+      module ResultMethods
+        def full_messages
+          @_full_messages ||= generate_full_messages(@errors)
+        end
+
+        private
+
+        def generate_full_messages(errors, array_param_name = nil)
+          errors.each_with_object({}) do |(param, messages), result|
+            result[param] = if messages.is_a?(Hash)
+                              param_is_array = messages.first[0].is_a?(Integer)
+
+                              generate_full_messages(messages, param_is_array ? param : nil)
+                            else
+                              param_name = fend_class.opts[:full_messages_array_member_names].fetch(array_param_name, param)
+                              messages.map { |message| "#{param_name} #{message}"}
+                            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:full_messages, FullMessages)
+  end
+end

data/lib/fend/plugins/validation_helpers.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # `validation_helpers` plugin provides additional `Param` methods for common
+    # validation cases.
+    #
+    #     plugin :validation_helpers
+    #
+    #     validate do |i|
+    #       i.param(:username) do |username|
+    #         username.validate_presence
+    #         username.validate_max_length(20)
+    #         username.validate_type(String)
+    #       end
+    #     end
+    #
+    # You can find list of all available helpers in ParamMethods.
+    #
+    # ## Overriding default messages
+    #
+    # You can override default messages by specifying `:default_messages`
+    # options when loading the plugin
+    #
+    #     plugin :validation_helpers, default_messages: {
+    #       exact_length: ->(length) { I18n.t("errors.exact_length", length: length) },
+    #       presence: "cannot be blank",
+    #       type: ->(type) { "is not of valid type. Must be #{type.to_s.downcase}" }
+    #     }
+    #
+    # Custom messages can be defined by passing `:message` option to validation
+    # helper method:
+    #
+    #     username.validate_max_length(20, message: "must be shorter than 20 chars")
+
+    module ValidationHelpers
+      # depends on ValueHelpers plugin, which provides methods that are used in
+      # certain validation helpers
+      def self.load_dependencies(validation, *args, &block)
+        validation.plugin(:value_helpers)
+      end
+
+      def self.configure(validation, opts = {})
+        validation.opts[:validation_default_messages] = (validation.opts[:validation_default_messages] || {}).merge(opts[:default_messages] || {})
+      end
+
+      DEFAULT_MESSAGES = {
+        absence:                  -> { "must be absent" },
+        acceptance:               -> { "must be accepted" },
+        equality:                 ->(value) { "must be equal to '#{value}'" },
+        exact_length:             ->(length) { "length must be equal to #{length}" },
+        exclusion:                ->(list) { "cannot be one of: #{list.join(', ')}" },
+        format:                   -> { "is in invalid format" },
+        greater_than:             ->(value) { "must be greater than #{value}" },
+        greater_than_or_equal_to: ->(value) { "must be greater than or equal to #{value}" },
+        inclusion:                ->(list) { "must be one of: #{list.join(', ')}" },
+        length_range:             ->(range) { "length must be between #{range.min} and #{range.max}" },
+        less_than:                ->(value) { "must be less than #{value}" },
+        less_than_or_equal_to:    ->(value) { "must be less than or equal to #{value}" },
+        max_length:               ->(value) { "length cannot be greater than #{value}" },
+        min_length:               ->(value) { "length cannot be less than #{value}" },
+        presence:                 -> { "must be present" },
+        type:                     ->(type) { "must be #{type.to_s.downcase}" }
+      }.freeze
+
+      ACCEPTABLE       = [1, "1", true, "true", "TRUE", :yes, "YES", "yes"].freeze
+      UNSUPPORTED_TYPE = "__unsupported_type__".freeze
+
+      module ParamClassMethods
+        def default_messages
+          @default_messages ||= DEFAULT_MESSAGES.merge(fend_class.opts[:validation_default_messages])
+        end
+      end
+
+      module ParamMethods
+        # Validates that param value is blank. To see what values are considered
+        # as blank, check ValueHelpers::ParamMethods#blank?.
+        #
+        #     id.validate_absence
+        def validate_absence(opts = {})
+          add_error(:absence, opts[:message]) if present?
+        end
+
+        # Validates acceptance. Potential use case would be checking if Terms of
+        # Service has been accepted.
+        #
+        # By default, validation will pass if value is one of:
+        # `[1, "1", :true, true, "true", "TRUE", :yes, "YES", "yes"]`
+        #
+        # You can pass the `:as` option with custom list of acceptable values:
+        #
+        #     tos.validate_acceptance(as: ["Agreed", "OK"])
+        def validate_acceptance(opts = {})
+          as = Array(opts.fetch(:as, ACCEPTABLE))
+
+          add_error(:acceptance, opts[:message]) unless as.include?(value)
+        end
+
+        # Validates that param value is equal to the specified value.
+        #
+        #     color.validate_equality("black")
+        def validate_equality(rhs, opts = {})
+          add_error(:equality, opts[:message], rhs) unless value.eql?(rhs)
+        end
+
+        # Validates that param value length is equal to the specified value.
+        # Works with any object that responds to `#length` method.
+        #
+        #     code.validate_exact_length(10)
+        def validate_exact_length(exact_length, opts = {})
+          value_length = value.respond_to?(:length) ? value.length : UNSUPPORTED_TYPE
+
+          return if !value_length.eql?(UNSUPPORTED_TYPE) && value_length.eql?(exact_length)
+
+          add_error(:exact_length, opts[:message], exact_length)
+        end
+
+        # Validates that param value is not one of the specified values.
+        #
+        #     account_type.validate_exclusion(["admin", "editor"])
+        def validate_exclusion(exclude_from, opts = {})
+          add_error(:exclusion, opts[:message], exclude_from) if exclude_from.include?(value)
+        end
+
+        # Validates that param value is a match for specified regex.
+        #
+        #     name.validate_format(/\A[a-z]\z/i)
+        def validate_format(format, opts = {})
+          add_error(:format, opts[:message]) if format.match(value.to_s).nil?
+        end
+
+        # Validates that param value is greater than specified value
+        #
+        #     age.validate_greater_than(18)
+        def validate_greater_than(rhs, opts = {})
+          add_error(:greater_than, opts[:message], rhs) unless value.is_a?(Numeric) && value > rhs
+        end
+
+        # Validates that param value is greater than or equal to specified value
+        #
+        #     age.validate_greater_than_or_equal_to(18)
+        #
+        # Aliased as `validate_gteq`
+        #
+        #     age.validate_gteq(10)
+        def validate_greater_than_or_equal_to(rhs, opts = {})
+          add_error(:greater_than_or_equal_to, opts[:message], rhs) unless value.is_a?(Numeric) && value >= rhs
+        end
+        alias_method :validate_gteq, :validate_greater_than_or_equal_to
+
+        # Validates that param value is one of the specified values.
+        #
+        #     account_type.validate_inclusion(["admin", "editor"])
+        def validate_inclusion(include_in, opts = {})
+          add_error(:inclusion, opts[:message], include_in) unless include_in.include?(value)
+        end
+
+        # Validates that param value length is within specified range
+        #
+        #     code.validate_length_range(10..15)
+        def validate_length_range(range, opts = {})
+          value_length = value.respond_to?(:length) ? value.length : UNSUPPORTED_TYPE
+
+          return if !value_length.eql?(UNSUPPORTED_TYPE) && range.include?(value_length)
+
+          add_error(:length_range, opts[:message], range)
+        end
+
+        # Validates that param value is less than specified value
+        #
+        #     funds.validate_less_than(100)
+        def validate_less_than(rhs, opts = {})
+          add_error(:less_than, opts[:message], rhs) unless value.is_a?(Numeric) && value < rhs
+        end
+
+        # Validates that param value is less than or equal to specified value
+        #
+        #     funds.validate_less_than_or_equal_to(100)
+        #
+        # Aliased as `validate_lteq`
+        #
+        #     funds.validate_lteq(100)
+        def validate_less_than_or_equal_to(rhs, opts = {})
+          add_error(:less_than_or_equal_to, opts[:message], rhs) unless value.is_a?(Numeric) && value <= rhs
+        end
+        alias_method :validate_lteq, :validate_less_than_or_equal_to
+
+        # Validates that param value length is not greater than specified value
+        #
+        #     password.validate_max_length(15)
+        def validate_max_length(length, opts = {})
+          value_length = value.respond_to?(:length) ? value.length : UNSUPPORTED_TYPE
+
+          return if !value_length.eql?(UNSUPPORTED_TYPE) && value_length <= length
+
+          add_error(:max_length, opts[:message], length)
+        end
+
+        # Validates that param value length is not less than specified value
+        #
+        #     password.validate_min_length(5)
+        def validate_min_length(length, opts = {})
+          value_length = value.respond_to?(:length) ? value.length : UNSUPPORTED_TYPE
+
+          return if !value_length.eql?(UNSUPPORTED_TYPE) && value_length >= length
+
+          add_error(:min_length, opts[:message], length)
+        end
+
+        # Validates that param value is present. To see what values are
+        # considered as present, check ValueHelpers::ParamMethods#present?
+        #
+        #     name.validate_presence
+        def validate_presence(opts = {})
+          add_error(:presence, opts[:message]) if blank?
+        end
+
+        # Uses ValueHelpers::ParamMethods#type_of? method to validate that
+        # param value is of specified type.
+        #
+        #     tags.validate_type(Array)
+        def validate_type(type, opts = {})
+          add_error(:type, opts[:message], type) unless type_of?(type)
+        end
+
+        # :nodoc:
+        def add_error(*args)
+          if args.size == 1 && args.first.is_a?(String)
+            super(*args)
+          else
+            @errors << error_message(*args)
+          end
+        end
+
+        private
+
+        def error_message(type, message, *args)
+          message ||= self.class.default_messages.fetch(type)
+          message.is_a?(String) ? message : message.call(*args)
+        end
+      end
+    end
+
+    register_plugin(:validation_helpers, ValidationHelpers)
+  end
+end

data/lib/fend/plugins/validation_options.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+class Fend
+  module Plugins
+    # Instead of calling ValidationHelpers::ParamMethods separately,
+    # you can use `validation_options` plugin in order to specify all
+    # validations as options and pass them to `Param#validate` method.
+    #
+    #     plugin :validation_options
+    #
+    #     validate do |i|
+    #       i.param(:email) do |email|
+    #         email.validate(presence: true, type: String, format: EMAIL_REGEX)
+    #       end
+    #     end
+    #
+    # ## Custom error messages
+    #
+    # Custom error messages can be defined with `:message` option:
+    #
+    #     email.validate(presence: { message: "cannot be blank"})
+    #
+    # ## Mandatory arguments
+    #
+    # For ValidationHelpers::ParamMethods that expect mandatory arguments, there
+    # are predefined option keys that you can use. To see them all check
+    # MANDATORY_ARG_KEYS constant.
+    #
+    #     email.validate type: { of: String, message: "is not a string" }, format: { with: EMAIL_REGEX }
+    #     account_type.validate inclusion: { in: %w(admin, moderator) }
+    #
+    # You can also use the DEFAULT_ARG_KEY (`:value`) if you find it hard to
+    # remember the specific ones.
+    #
+    #     email.validate type: { value: String }, format: { value: EMAIL_REGEX }
+    #
+    # `validation_options` supports ExternalValidation plugin:
+    #
+    #     plugin :external_validation
+    #
+    #     # ...
+    #
+    #     email.validate(with: CustomEmailValidator)
+    module ValidationOptions
+      NO_ARG_METHODS = [:absence, :presence, :acceptance].freeze
+      ARRAY_ARG_METHODS = [:exclusion, :inclusion, :length_range].freeze
+
+      DEFAULT_ARG_KEY = :value
+
+      # List of keys to use when specifying mandatory validation arguments
+      MANDATORY_ARG_KEYS = {
+        equality:                 :value,
+        exact_length:             :of,
+        exclusion:                :from,
+        format:                   :with,
+        greater_than:             :value,
+        greater_than_or_equal_to: :value,
+        gteq:                     :value,
+        inclusion:                :in,
+        length_range:             :within,
+        less_than:                :value,
+        less_than_or_equal_to:    :value,
+        lteq:                     :value,
+        max_length:               :of,
+        min_length:               :of,
+        type:                     :of
+      }.freeze
+
+      # Depends on ValidationHelpers plugin
+      def self.load_dependencies(validation, *args, &block)
+        validation.plugin(:validation_helpers)
+      end
+
+      module ParamMethods
+        def validate(opts = {})
+          return if opts.empty?
+
+          opts.each do |validator_name, args|
+            method_name = "validate_#{validator_name}"
+
+            raise Error, "undefined validation method '#{validator_name}'" unless respond_to?(method_name)
+
+            if NO_ARG_METHODS.include?(validator_name)
+              if !!args == args
+                next unless args
+
+                validation_method_args = []
+              else
+                validation_method_args = [args]
+              end
+            elsif args.is_a?(Hash)
+              next if args[:allow_nil] == true && value.nil?
+              next if args[:allow_blank] == true && blank?
+
+              mandatory_arg_key = MANDATORY_ARG_KEYS[validator_name]
+
+              unless args.key?(mandatory_arg_key) || args.key?(DEFAULT_ARG_KEY)
+                raise Error, "missing mandatory argument for '#{validator_name}' validator"
+              end
+
+              mandatory_arg = args.delete(mandatory_arg_key) || args.delete(DEFAULT_ARG_KEY)
+
+              validation_method_args = [mandatory_arg, args]
+            else
+              validation_method_args = ARRAY_ARG_METHODS.include?(validator_name) ? [args] : args
+            end
+
+            public_send(method_name, *validation_method_args)
+          end
+        end
+      end
+    end
+
+    register_plugin(:validation_options, ValidationOptions)
+  end
+end

data/lib/fend/plugins/value_helpers.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class Fend
+  module Plugins
+    # `value_helpers` plugin provides helper methods you can use to
+    # check/fetch param values.
+    #
+    #     plugin :value_helpers
+    #
+    #     validate do |i|
+    #       i.param(:username) do |username|
+    #         username.present? #=> true
+    #         username.blank? #=> false
+    #         username.empty_string? #=> false
+    #       end
+    #     end
+    #
+    # For a complete list of available methods, see ParamMethods.
+    module ValueHelpers
+      module ParamMethods
+        # Returns `true` when:
+        #
+        # * `value.empty?`
+        # * `value.nil?`
+        # * `value == false`
+        # * `value.empty_string?`
+        def blank?
+          case value
+          when Array, Hash
+            value.empty?
+          when NilClass, FalseClass
+            true
+          when Integer, Float, Numeric, Time, TrueClass, Symbol
+            false
+          when String
+            empty_string?
+          else
+            value.respond_to?(:empty?) ? !!value.empty? : !value
+          end
+        end
+
+        # Enables easier fetching of nested data values.
+        # Works with hashes and arrays.
+        #
+        #     validate do |i|
+        #       # { user: { address: { city: "Amsterdam" } } }
+        #       i.dig(:user, :address, :city) #=> "Amsterdam"
+        #       i.dig(:user, :profile, :username) #=> nil
+        #
+        #       # { tags: [ { id: 2, name: "JS" }, { id: 3, name: "Ruby" }] }
+        #       i.dig(:tags, 1, :name) #=> "Ruby"
+        #       i.dig(:tags, 5, :id) #=> nil
+        #
+        #       i.param(:accounts) do |accounts|
+        #         accounts.dig(0, :transactions, 3) #=> "$100.00"
+        #       end
+        #     end
+        def dig(*path)
+          result = value
+
+          path.each do |point|
+            break if result.is_a?(Array) && !point.is_a?(Integer)
+
+            result = result.is_a?(Enumerable) ? result[point] : nil
+
+            break if result.nil?
+          end
+
+          result
+        end
+
+        # Returns `true` when value is an empty string (_space_, _tab_, _newline_,
+        # _carriage_return_, etc...)
+        #
+        #     # email.value #=> ""
+        #     # email.value #=> "   "
+        #     # email.value #=> "\n"
+        #     # email.value #=> "\r"
+        #     # email.value #=> "\t"
+        #     # email.value #=> "\n\r\t"
+        #
+        #     email.empty_string? #=> true
+        def empty_string?
+          return false unless value.is_a?(String) || value.is_a?(Symbol)
+
+          regex = /\A[[:space:]]*\z/
+
+          !regex.match(value).nil?
+        end
+
+        # Returns `true` if value is present/not blank
+        def present?
+          !blank?
+        end
+
+        # Returns `true` if value is of specified type. Accepts constants, their
+        # string representations and symbols:
+        #
+        #     email.type_of?(String)
+        #
+        #     # or
+        #
+        #     email.type_of?("string")
+        #
+        #     # or
+        #
+        #     email.type_of?(:string)
+        #
+        # Additional examples:
+        #
+        #     # these are all checking the same thing
+        #     user.type_of?(AdminUser)
+        #     user.type_of?(:admin_user)
+        #     user.type_of?("admin_user")
+        #
+        # Provides a convenient way for checking if value is boolean, decimal or
+        # nil:
+        #
+        #     # true if value is TrueClass or FalseClass
+        #     confirmed.type_of?(:boolean)
+        #
+        #     # true if value is Float or BigDecimal
+        #     amount.type_of?(:decimal)
+        #
+        #     # true if value is nil/NilClass
+        #     email.type_of?(:nil)
+        def type_of?(type_ref)
+          return value.is_a?(type_ref) unless type_ref.is_a?(String) || type_ref.is_a?(Symbol)
+
+          case type_ref.to_s
+          when "boolean" then !!value == value
+          when "decimal" then value.is_a?(Float) || value.is_a?(BigDecimal)
+          when "nil" then value.is_a?(NilClass)
+          else
+            camelized_type_ref = type_ref.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:\A|_)(.)/) { $1.upcase }
+            type_class = Object.const_get(camelized_type_ref)
+
+            value.is_a?(type_class)
+          end
+        end
+      end
+    end
+
+    register_plugin(:value_helpers, ValueHelpers)
+  end
+end