dry-types 0.15.0 → 1.2.0

data/lib/dry/types/result.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/equalizer'
 
 module Dry
   module Types
+    # Result class used by {Type#try}
+    #
+    # @api public
     class Result
       include Dry::Equalizer(:input, inspect: false)
 
@@ -9,22 +14,34 @@ module Dry
       attr_reader :input
 
       # @param [Object] input
+      #
+      # @api private
       def initialize(input)
         @input = input
       end
 
+      # Success result
+      #
+      # @api public
       class Success < Result
         # @return [true]
+        #
+        # @api public
         def success?
           true
         end
 
         # @return [false]
+        #
+        # @api public
         def failure?
           false
         end
       end
 
+      # Failure result
+      #
+      # @api public
       class Failure < Result
         include Dry::Equalizer(:input, :error, inspect: false)
 
@@ -32,23 +49,32 @@ module Dry
         attr_reader :error
 
         # @param [Object] input
+        #
         # @param [#to_s] error
+        #
+        # @api private
         def initialize(input, error)
           super(input)
           @error = error
         end
 
         # @return [String]
+        #
+        # @api private
         def to_s
           error.to_s
         end
 
         # @return [false]
+        #
+        # @api public
         def success?
           false
         end
 
         # @return [true]
+        #
+        # @api public
         def failure?
           true
         end

data/lib/dry/types/schema.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/types/fn_container'
 
 module Dry
@@ -14,6 +16,8 @@ module Dry
     # @see Dry::Types::Default::Callable#evaluate
     #
     # {Schema} implements Enumerable using its keys as collection.
+    #
+    # @api public
     class Schema < Hash
       NO_TRANSFORM = Dry::Types::FnContainer.register { |x| x }
       SYMBOLIZE_KEY = Dry::Types::FnContainer.register(:to_sym.to_proc)
@@ -31,8 +35,11 @@ module Dry
 
       # @param [Class] _primitive
       # @param [Hash] options
+      #
       # @option options [Array[Dry::Types::Schema::Key]] :keys
       # @option options [String] :key_transform_fn
+      #
+      # @api private
       def initialize(_primitive, **options)
         @keys = options.fetch(:keys)
         @name_key_map = keys.each_with_object({}) do |key, idx|
@@ -47,58 +54,96 @@ module Dry
       end
 
       # @param [Hash] hash
+      #
+      # @return [Hash{Symbol => Object}]
+      #
+      # @api private
+      def call_unsafe(hash, options = EMPTY_HASH)
+        resolve_unsafe(coerce(hash), options)
+      end
+
+      # @param [Hash] hash
+      #
       # @return [Hash{Symbol => Object}]
-      def call(hash)
-        coerce(hash)
+      #
+      # @api private
+      def call_safe(hash, options = EMPTY_HASH)
+        resolve_safe(coerce(hash) { return yield }, options) { return yield }
       end
-      alias_method :[], :call
 
       # @param [Hash] hash
+      #
       # @option options [Boolean] :skip_missing If true don't raise error if on missing keys
       # @option options [Boolean] :resolve_defaults If false default value
       #                                             won't be evaluated for missing key
       # @return [Hash{Symbol => Object}]
+      #
+      # @api public
       def apply(hash, options = EMPTY_HASH)
-        coerce(hash, options)
+        call_unsafe(hash, options)
       end
 
       # @param [Hash] hash
+      #
       # @yieldparam [Failure] failure
       # @yieldreturn [Result]
+      #
       # @return [Logic::Result]
       # @return [Object] if coercion fails and a block is given
-      def try(hash)
-        if hash.is_a?(::Hash)
+      #
+      # @api public
+      def try(input)
+        if primitive?(input)
           success = true
-          output  = {}
+          output = {}
+          result = {}
+
+          input.each do |key, value|
+            k = @transform_key.(key)
+            type = @name_key_map[k]
 
-          begin
-            result = try_coerce(hash) do |key, key_result|
+            if type
+              key_result = type.try(value)
+              result[k] = key_result
+              output[k] = key_result.input
               success &&= key_result.success?
-              output[key.name] = key_result.input
+            elsif strict?
+              success = false
+            end
+          end
 
-              key_result
+          if output.size < keys.size
+            resolve_missing_keys(output, options) do
+              success = false
             end
-          rescue ConstraintError, UnknownKeysError, SchemaError, MissingKeyError => e
-            success = false
-            result = e
+          end
+
+          success &&= primitive?(output)
+
+          if success
+            failure = nil
+          else
+            error = CoercionError.new("#{input} doesn't conform schema", meta: result)
+            failure = failure(output, error)
           end
         else
-          success = false
-          output = hash
-          result = "#{hash} must be a hash"
+          failure = failure(input, CoercionError.new("#{input} must be a hash"))
         end
 
-        if success
+        if failure.nil?
           success(output)
+        elsif block_given?
+          yield(failure)
         else
-          failure = failure(output, result)
-          block_given? ? yield(failure) : failure
+          failure
         end
       end
 
       # @param meta [Boolean] Whether to dump the meta to the AST
+      #
       # @return [Array] An AST representation
+      #
+      # @api public
       def to_ast(meta: true)
         if RUBY_VERSION >= "2.5"
           opts = options.slice(:key_transform_fn, :type_transform_fn, :strict)
@@ -110,53 +155,53 @@ module Dry
 
         [
           :schema,
-          [
-            keys.map { |key| key.to_ast(meta: meta) },
-            opts,
-            meta ? self.meta : EMPTY_HASH
-          ]
+          [keys.map { |key| key.to_ast(meta: meta) },
+           opts,
+           meta ? self.meta : EMPTY_HASH]
         ]
       end
 
-      # @param [Hash] hash
-      # @return [Boolean]
-      def valid?(hash)
-        result = try(hash)
-        result.success?
-      end
-      alias_method :===, :valid?
-
       # Whether the schema rejects unknown keys
+      #
       # @return [Boolean]
+      #
+      # @api public
       def strict?
         options.fetch(:strict, false)
       end
 
       # Make the schema intolerant to unknown keys
+      #
       # @return [Schema]
-      def strict
-        with(strict: true)
+      #
+      # @api public
+      def strict(strict = true)
+        with(strict: strict)
       end
 
       # Injects a key transformation function
+      #
       # @param [#call,nil] proc
       # @param [#call,nil] block
+      #
       # @return [Schema]
+      #
+      # @api public
       def with_key_transform(proc = nil, &block)
         fn = proc || block
 
-        if fn.nil?
-          raise ArgumentError, "a block or callable argument is required"
-        end
+        raise ArgumentError, 'a block or callable argument is required' if fn.nil?
 
         handle = Dry::Types::FnContainer.register(fn)
         with(key_transform_fn: handle)
       end
 
       # Whether the schema transforms input keys
+      #
       # @return [Boolean]
+      #
       # @api public
-      def trasform_keys?
+      def transform_keys?
         !options[:key_transform_fn].nil?
       end
 
@@ -164,10 +209,13 @@ module Dry
       #   @param [{Symbol => Dry::Types::Nominal}] type_map
       #   @param [Hash] meta
       #   @return [Dry::Types::Schema]
+      #
       # @overload schema(keys)
       #   @param [Array<Dry::Types::Schema::Key>] key List of schema keys
       #   @param [Hash] meta
       #   @return [Dry::Types::Schema]
+      #
+      # @api public
       def schema(keys_or_map)
         if keys_or_map.is_a?(::Array)
           new_keys = keys_or_map
@@ -182,6 +230,8 @@ module Dry
       # Iterate over each key type
       #
       # @return [Array<Dry::Types::Schema::Key>,Enumerator]
+      #
+      # @api public
       def each(&block)
         keys.each(&block)
       end
@@ -189,12 +239,16 @@ module Dry
       # Whether the schema has the given key
       #
       # @param [Symbol] name Key name
+      #
       # @return [Boolean]
+      #
+      # @api public
       def key?(name)
         name_key_map.key?(name)
       end
 
-      # Fetch key type by a key name.
+      # Fetch key type by a key name
+      #
       # Behaves as ::Hash#fetch
       #
       # @overload key(name, fallback = Undefined)
@@ -206,6 +260,8 @@ module Dry
       #   @param [Symbol] name Key name
       #   @param [Proc] block Fallback block, runs if key is missing
       #   @return [Dry::Types::Schema::Key,Object] key type or block value if key is not in schema
+      #
+      # @api public
       def key(name, fallback = Undefined, &block)
         if Undefined.equal?(fallback)
           name_key_map.fetch(name, &block)
@@ -215,83 +271,124 @@ module Dry
       end
 
       # @return [Boolean]
+      #
+      # @api public
       def constrained?
         true
       end
 
+      # @return [Lax]
+      #
+      # @api public
+      def lax
+        Lax.new(schema(keys.map(&:lax)))
+      end
+
       private
 
       # @param [Array<Dry::Types::Schema::Keys>] keys
+      #
       # @return [Dry::Types::Schema]
+      #
       # @api private
       def merge_keys(*keys)
-        keys.
-          flatten(1).
-          each_with_object({}) { |key, merged| merged[key.name] = key }.
-          values
+        keys
+          .flatten(1)
+          .each_with_object({}) { |key, merged| merged[key.name] = key }
+          .values
       end
 
-      def resolve(hash, options = EMPTY_HASH, &block)
+      # Validate and coerce a hash. Raise an exception on any error
+      #
+      # @api private
+      #
+      # @return [Hash]
+      def resolve_unsafe(hash, options = EMPTY_HASH)
         result = {}
 
         hash.each do |key, value|
-          k = transform_key.(key)
-
-          if name_key_map.key?(k)
-            result[k] = yield(name_key_map[k], value)
+          k = @transform_key.(key)
+          type = @name_key_map[k]
+
+          if type
+            begin
+              result[k] = type.call_unsafe(value)
+            rescue ConstraintError => e
+              raise SchemaError.new(type.name, value, e.result)
+            rescue CoercionError => e
+              raise SchemaError.new(type.name, value, e.message)
+            end
           elsif strict?
-            raise UnknownKeysError.new(*unexpected_keys(hash.keys))
+            raise unexpected_keys(hash.keys)
           end
         end
 
-        if result.size < keys.size
-          resolve_missing_keys(result, options, &block)
+        resolve_missing_keys(result, options) if result.size < keys.size
+
+        result
+      end
+
+      # Validate and coerce a hash. Call a block and halt on any error
+      #
+      # @api private
+      #
+      # @return [Hash]
+      def resolve_safe(hash, options = EMPTY_HASH, &block)
+        result = {}
+
+        hash.each do |key, value|
+          k = @transform_key.(key)
+          type = @name_key_map[k]
+
+          if type
+            result[k] = type.call_safe(value, &block)
+          elsif strict?
+            yield
+          end
         end
 
+        resolve_missing_keys(result, options, &block) if result.size < keys.size
+
         result
       end
 
-      def resolve_missing_keys(result, options)
+      # Try to add missing keys to the hash
+      #
+      # @api private
+      def resolve_missing_keys(hash, options)
         skip_missing = options.fetch(:skip_missing, false)
         resolve_defaults = options.fetch(:resolve_defaults, true)
 
         keys.each do |key|
-          next if result.key?(key.name)
+          next if hash.key?(key.name)
 
           if key.default? && resolve_defaults
-            result[key.name] = yield(key, Undefined)
+            hash[key.name] = key.call_unsafe(Undefined)
           elsif key.required? && !skip_missing
-            raise MissingKeyError, key.name
+            if block_given?
+              return yield
+            else
+              raise missing_key(key.name)
+            end
           end
         end
       end
 
-      # @param keys [Array<Symbol>]
-      # @return [Array<Symbol>]
-      def unexpected_keys(keys)
-        keys.map(&transform_key) - name_key_map.keys
-      end
-
-      # @param [Hash] hash
-      # @return [Hash{Symbol => Object}]
-      def try_coerce(hash)
-        resolve(hash) do |key, value|
-          yield(key, key.try(value))
-        end
+      # @param hash_keys [Array<Symbol>]
+      #
+      # @return [UnknownKeysError]
+      #
+      # @api private
+      def unexpected_keys(hash_keys)
+        extra_keys = hash_keys.map(&transform_key) - name_key_map.keys
+        UnknownKeysError.new(extra_keys)
       end
 
-      # @param [Hash] hash
-      # @return [Hash{Symbol => Object}]
-      def coerce(hash, options = EMPTY_HASH)
-        resolve(hash, options) do |key, value|
-          begin
-            key.(value)
-          rescue ConstraintError => e
-            raise SchemaError.new(key.name, value, e.result)
-          rescue TypeError, ArgumentError => e
-            raise SchemaError.new(key.name, value, e.message)
-          end
-        end
+      # @return [MissingKeyError]
+      #
+      # @api private
+      def missing_key(key)
+        MissingKeyError.new(key)
       end
     end
   end