dry-validation 0.13.3 → 1.7.0

data/lib/dry/validation/evaluator.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/core/deprecations"
+
+require "dry/validation/constants"
+require "dry/validation/failures"
+
+module Dry
+  module Validation
+    # Evaluator is the execution context for rules
+    #
+    # Evaluators expose an API for setting failure messages and forward
+    # method calls to the contracts, so that you can use your contract
+    # methods within rule blocks
+    #
+    # @api public
+    class Evaluator
+      extend Dry::Initializer
+      extend Dry::Core::Deprecations[:'dry-validation']
+
+      deprecate :error?, :schema_error?
+
+      # @!attribute [r] _contract
+      #   @return [Contract]
+      #   @api private
+      param :_contract
+
+      # @!attribute [r] result
+      #   @return [Result]
+      #   @api private
+      option :result
+
+      # @!attribute [r] keys
+      #   @return [Array<String, Symbol, Hash>]
+      #   @api private
+      option :keys
+
+      # @!attribute [r] macros
+      #   @return [Array<Symbol>]
+      #   @api private
+      option :macros, optional: true, default: proc { EMPTY_ARRAY.dup }
+
+      # @!attribute [r] _context
+      #   @return [Concurrent::Map]
+      #   @api private
+      option :_context
+
+      # @!attribute [r] path
+      #   @return [Dry::Schema::Path]
+      #   @api private
+      option :path, default: proc { Dry::Schema::Path[(key = keys.first) ? key : ROOT_PATH] }
+
+      # @!attribute [r] values
+      #   @return [Object]
+      #   @api private
+      option :values
+
+      # @!attribute [r] block_options
+      #   @return [Hash<Symbol=>Symbol>]
+      #   @api private
+      option :block_options, default: proc { EMPTY_HASH }
+
+      # @return [Hash]
+      attr_reader :_options
+
+      # Initialize a new evaluator
+      #
+      # @api private
+      def initialize(contract, **options, &block)
+        super(contract, **options)
+
+        @_options = options
+
+        if block
+          exec_opts = block_options.map { |key, value| [key, _options[value]] }.to_h
+          instance_exec(**exec_opts, &block)
+        end
+
+        macros.each do |args|
+          macro = macro(*args.flatten(1))
+          instance_exec(**macro.extract_block_options(_options.merge(macro: macro)), &macro.block)
+        end
+      end
+
+      # Get `Failures` object for the default or provided path
+      #
+      # @param [Symbol,String,Hash,Array<Symbol>] path
+      #
+      # @return [Failures]
+      #
+      # @see Failures#failure
+      #
+      # @api public
+      def key(path = self.path)
+        (@key ||= EMPTY_HASH.dup)[path] ||= Failures.new(path)
+      end
+
+      # Get `Failures` object for base errors
+      #
+      # @return [Failures]
+      #
+      # @see Failures#failure
+      #
+      # @api public
+      def base
+        @base ||= Failures.new
+      end
+
+      # Return aggregated failures
+      #
+      # @return [Array<Hash>]
+      #
+      # @api private
+      def failures
+        @failures ||= []
+        @failures += @base.opts if defined?(@base)
+        @failures.concat(@key.values.flat_map(&:opts)) if defined?(@key)
+        @failures
+      end
+
+      # @api private
+      def with(new_opts, &block)
+        self.class.new(_contract, **_options, **new_opts, &block)
+      end
+
+      # Return default (first) key name
+      #
+      # @return [Symbol]
+      #
+      # @api public
+      def key_name
+        @key_name ||= keys.first
+      end
+
+      # Return the value found under the first specified key
+      #
+      # This is a convenient method that can be used in all the common cases
+      # where a rule depends on just one key and you want a quick access to
+      # the value
+      #
+      # @example
+      #   rule(:age) do
+      #     key.failure(:invalid) if value < 18
+      #   end
+      #
+      # @return [Object]
+      #
+      # @api public
+      def value
+        values[key_name]
+      end
+
+      # Return if the value under the default key is available
+      #
+      # This is useful when dealing with rules for optional keys
+      #
+      # @example use the default key name
+      #   rule(:age) do
+      #     key.failure(:invalid) if key? && value < 18
+      #   end
+      #
+      # @example specify the key name
+      #   rule(:start_date, :end_date) do
+      #     if key?(:start_date) && !key?(:end_date)
+      #       key(:end_date).failure("must provide an end_date with start_date")
+      #     end
+      #   end
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def key?(name = key_name)
+        values.key?(name)
+      end
+
+      # Check if there are any errors on the schema under the provided path
+      #
+      # @param path [Symbol, String, Array] A Path-compatible spec
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def schema_error?(path)
+        result.schema_error?(path)
+      end
+
+      # Check if there are any errors on the current rule
+      #
+      # @param path [Symbol, String, Array] A Path-compatible spec
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def rule_error?(path = nil)
+        if path.nil?
+          !key(self.path).empty?
+        else
+          result.rule_error?(path)
+        end
+      end
+
+      # @api private
+      def respond_to_missing?(meth, include_private = false)
+        super || _contract.respond_to?(meth, true)
+      end
+
+      private
+
+      # Forward to the underlying contract
+      #
+      # @api private
+      def method_missing(meth, *args, &block)
+        # yes, we do want to delegate to private methods too
+        if _contract.respond_to?(meth, true)
+          _contract.__send__(meth, *args, &block)
+        else
+          super
+        end
+      end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+    end
+  end
+end

data/lib/dry/validation/extensions/hints.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Dry
+  module Validation
+    # Hints extension
+    #
+    # @example
+    #   Dry::Validation.load_extensions(:hints)
+    #
+    #   contract = Dry::Validation::Contract.build do
+    #     schema do
+    #       required(:name).filled(:string, min_size?: 2..4)
+    #     end
+    #   end
+    #
+    #   contract.call(name: "fo").hints
+    #   # {:name=>["size must be within 2 - 4"]}
+    #
+    #   contract.call(name: "").messages
+    #   # {:name=>["must be filled", "size must be within 2 - 4"]}
+    #
+    # @api public
+    module Hints
+      # Hints extensions for Result
+      #
+      # @api public
+      module ResultExtensions
+        # Return error messages excluding hints
+        #
+        # @macro errors-options
+        # @return [MessageSet]
+        #
+        # @api public
+        def errors(new_options = EMPTY_HASH)
+          opts = new_options.merge(hints: false)
+          @errors.with(schema_errors(opts), opts)
+        end
+
+        # Return errors and hints
+        #
+        # @macro errors-options
+        #
+        # @return [MessageSet]
+        #
+        # @api public
+        def messages(new_options = EMPTY_HASH)
+          errors.with(hints(new_options).to_a, options.merge(**new_options))
+        end
+
+        # Return hint messages
+        #
+        # @macro errors-options
+        #
+        # @return [MessageSet]
+        #
+        # @api public
+        def hints(new_options = EMPTY_HASH)
+          schema_result.hints(new_options)
+        end
+      end
+
+      Dry::Schema.load_extensions(:hints)
+
+      Result.prepend(ResultExtensions)
+    end
+  end
+end

data/lib/dry/validation/extensions/monads.rb

@@ -1,18 +1,34 @@
-require 'dry/monads/result'
+# frozen_string_literal: true
+
+require "dry/monads/result"
 
 module Dry
   module Validation
+    # Monad extension for contract results
+    #
+    # @example
+    #   Dry::Validation.load_extensions(:monads)
+    #
+    #   contract = Dry::Validation::Contract.build do
+    #     schema do
+    #       required(:name).filled(:string)
+    #     end
+    #   end
+    #
+    #   contract.call(name: nil).to_monad
+    #
+    # @api public
     class Result
       include Dry::Monads::Result::Mixin
 
-      def to_monad(options = EMPTY_HASH)
-        if success?
-          Success(output)
-        else
-          Failure(messages(options))
-        end
+      # Returns a result monad
+      #
+      # @return [Dry::Monads::Result]
+      #
+      # @api public
+      def to_monad
+        success? ? Success(self) : Failure(self)
       end
-      alias_method :to_either, :to_monad
     end
   end
 end

data/lib/dry/validation/extensions/predicates_as_macros.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "dry/schema/predicate_registry"
+require "dry/validation/contract"
+
+module Dry
+  module Validation
+    # Predicate registry with additional needed methods.
+    class PredicateRegistry < Schema::PredicateRegistry
+      # List of predicates to be imported by `:predicates_as_macros`
+      # extension.
+      #
+      # @see Dry::Validation::Contract
+      WHITELIST = %i[
+        filled? format? gt? gteq? included_in? includes? inclusion? is? lt?
+        lteq? max_size? min_size? not_eql? odd? respond_to? size? true?
+        uuid_v4?
+      ].freeze
+
+      # @api private
+      def arg_names(name)
+        arg_list(name).map(&:first)
+      end
+
+      # @api private
+      def call(name, args)
+        self[name].(*args)
+      end
+
+      # @api private
+      def message_opts(name, arg_values)
+        arg_names(name).zip(arg_values).to_h
+      end
+    end
+
+    # Extension to use dry-logic predicates as macros.
+    #
+    # @see Dry::Validation::PredicateRegistry::WHITELIST Available predicates
+    #
+    # @example
+    #   Dry::Validation.load_extensions(:predicates_as_macros)
+    #
+    #   class ApplicationContract < Dry::Validation::Contract
+    #     import_predicates_as_macros
+    #   end
+    #
+    #   class AgeContract < ApplicationContract
+    #     schema do
+    #       required(:age).filled(:integer)
+    #     end
+    #
+    #     rule(:age).validate(gteq?: 18)
+    #   end
+    #
+    #   AgeContract.new.(age: 17).errors.first.text
+    #   # => 'must be greater than or equal to 18'
+    #
+    # @api public
+    class Contract
+      # Make macros available for self and its descendants.
+      def self.import_predicates_as_macros
+        registry = PredicateRegistry.new
+
+        PredicateRegistry::WHITELIST.each do |name|
+          register_macro(name) do |macro:|
+            predicate_args = [*macro.args, value]
+            message_opts = registry.message_opts(name, predicate_args)
+
+            key.failure(name, message_opts) unless registry.(name, predicate_args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/validation/failures.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "dry/schema/path"
+require "dry/validation/constants"
+
+module Dry
+  module Validation
+    # Failure accumulator object
+    #
+    # @api public
+    class Failures
+      # The path for messages accumulated by failures object
+      #
+      # @return [Dry::Schema::Path]
+      #
+      # @api private
+      attr_reader :path
+
+      # Options for messages
+      #
+      # These options are used by MessageResolver
+      #
+      # @return [Hash]
+      #
+      # @api private
+      attr_reader :opts
+
+      # @api private
+      def initialize(path = ROOT_PATH)
+        @path = Dry::Schema::Path[path]
+        @opts = EMPTY_ARRAY.dup
+      end
+
+      # Set failure
+      #
+      # @overload failure(message)
+      #   Set message text explicitly
+      #   @param message [String] The message text
+      #   @example
+      #     failure('this failed')
+      #
+      # @overload failure(id)
+      #   Use message identifier (needs localized messages setup)
+      #   @param id [Symbol] The message id
+      #   @example
+      #     failure(:taken)
+      #
+      # @overload failure(meta_hash)
+      #   Use meta_hash[:text] as a message (either explicitely or as an identifier),
+      #   setting the rest of the hash as error meta attribute
+      #   @param meta [Hash] The hash containing the message as value for the :text key
+      #   @example
+      #     failure({text: :invalid, key: value})
+      #
+      # @see Evaluator#key
+      # @see Evaluator#base
+      #
+      # @api public
+      def failure(message, tokens = EMPTY_HASH)
+        opts << {message: message, tokens: tokens, path: path}
+        self
+      end
+
+      # @api private
+      def empty?
+        opts.empty?
+      end
+    end
+  end
+end

data/lib/dry/validation/function.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/validation/constants"
+
+module Dry
+  module Validation
+    # Abstract class for handling rule blocks
+    #
+    # @see Rule
+    # @see Macro
+    #
+    # @api private
+    class Function
+      extend Dry::Initializer
+
+      # @!attribute [r] block
+      #   @return [Proc]
+      #   @api private
+      option :block
+
+      # @!attribute [r] block_options
+      #   @return [Hash]
+      #   @api private
+      option :block_options, default: -> { block ? map_keywords(block) : EMPTY_HASH }
+
+      private
+
+      # Extract options for the block kwargs
+      #
+      # @param [Proc] block Callable
+      # @return Hash
+      #
+      # @api private
+      def map_keywords(block)
+        block
+          .parameters
+          .select { |arg,| arg.equal?(:keyreq) }
+          .map { |_, name| [name, BLOCK_OPTIONS_MAPPINGS[name]] }
+          .to_h
+      end
+    end
+  end
+end

data/lib/dry/validation/macro.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/validation/constants"
+require "dry/validation/function"
+
+module Dry
+  module Validation
+    # A wrapper for macro validation blocks
+    #
+    # @api public
+    class Macro < Function
+      # @!attribute [r] name
+      #   @return [Symbol]
+      #   @api public
+      param :name
+
+      # @!attribute [r] args
+      #   @return [Array]
+      #   @api public
+      option :args
+
+      # @!attribute [r] block
+      #   @return [Proc]
+      #   @api private
+      option :block
+
+      # @api private
+      def with(args)
+        self.class.new(name, args: args, block: block)
+      end
+
+      # @api private
+      def extract_block_options(options)
+        block_options.map { |key, value| [key, options[value]] }.to_h
+      end
+    end
+  end
+end

data/lib/dry/validation/macros.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "dry/container"
+require "dry/validation/macro"
+
+module Dry
+  module Validation
+    # API for registering and accessing Rule macros
+    #
+    # @api public
+    module Macros
+      module Registrar
+        # Register a macro
+        #
+        # @example register a global macro
+        #   Dry::Validation.register_macro(:even_numbers) do
+        #     key.failure('all numbers must be even') unless values[key_name].all?(&:even?)
+        #   end
+        #
+        # @example register a contract macro
+        #   class MyContract < Dry::Validation::Contract
+        #     register_macro(:even_numbers) do
+        #       key.failure('all numbers must be even') unless values[key_name].all?(&:even?)
+        #     end
+        #   end
+        #
+        # @param [Symbol] name The name of the macro
+        # @param [Array] args Optional default positional arguments for the macro
+        #
+        # @return [self]
+        #
+        # @see Macro
+        #
+        # @api public
+        def register_macro(name, *args, &block)
+          macros.register(name, *args, &block)
+          self
+        end
+      end
+
+      # Registry for macros
+      #
+      # @api public
+      class Container
+        include Dry::Container::Mixin
+
+        # Register a new macro
+        #
+        # @example in a contract class
+        #   class MyContract < Dry::Validation::Contract
+        #     register_macro(:even_numbers) do
+        #       key.failure('all numbers must be even') unless values[key_name].all?(&:even?)
+        #     end
+        #   end
+        #
+        # @param [Symbol] name The name of the macro
+        #
+        # @return [self]
+        #
+        # @api public
+        def register(name, *args, &block)
+          macro = Macro.new(name, args: args, block: block)
+          super(name, macro, call: false, &nil)
+          self
+        end
+      end
+
+      # Return a registered macro
+      #
+      # @param [Symbol] name The name of the macro
+      #
+      # @return [Proc]
+      #
+      # @api public
+      def self.[](name)
+        container[name]
+      end
+
+      # Register a global macro
+      #
+      # @see Container#register
+      #
+      # @return [Macros]
+      #
+      # @api public
+      def self.register(name, *args, &block)
+        container.register(name, *args, &block)
+        self
+      end
+
+      # @api private
+      def self.container
+        @container ||= Container.new
+      end
+    end
+
+    # Acceptance macro
+    #
+    # @api public
+    Macros.register(:acceptance) do
+      key.failure(:acceptance, key: key_name) unless values[key_name].equal?(true)
+    end
+  end
+end