dry-types 0.15.0 → 1.0.0

data/lib/dry/types/extensions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Dry::Types.register_extension(:maybe) do
   require 'dry/types/extensions/maybe'
 end

data/lib/dry/types/extensions/maybe.rb

@@ -1,31 +1,58 @@
+# frozen_string_literal: true
+
 require 'dry/monads/maybe'
 require 'dry/types/decorator'
 
 module Dry
   module Types
+    # Maybe extension provides Maybe types where values are wrapped using `Either` monad
+    #
+    # @api public
     class Maybe
       include Type
       include Dry::Equalizer(:type, :options, inspect: false)
       include Decorator
       include Builder
+      include Printable
       include Dry::Monads::Maybe::Mixin
 
       # @param [Dry::Monads::Maybe, Object] input
+      #
+      # @return [Dry::Monads::Maybe]
+      #
+      # @api private
+      def call_unsafe(input = Undefined)
+        case input
+        when Dry::Monads::Maybe
+          input
+        when Undefined
+          None()
+        else
+          Maybe(type.call_unsafe(input))
+        end
+      end
+
+      # @param [Dry::Monads::Maybe, Object] input
+      #
       # @return [Dry::Monads::Maybe]
-      def call(input = Undefined)
+      #
+      # @api private
+      def call_safe(input = Undefined, &block)
         case input
         when Dry::Monads::Maybe
           input
         when Undefined
           None()
         else
-          Maybe(type[input])
+          Maybe(type.call_safe(input, &block))
         end
       end
-      alias_method :[], :call
 
       # @param [Object] input
+      #
       # @return [Result::Success]
+      #
+      # @api public
       def try(input = Undefined)
         res = if input.equal?(Undefined)
                 None()
@@ -37,13 +64,19 @@ module Dry
       end
 
       # @return [true]
+      #
+      # @api public
       def default?
         true
       end
 
       # @param [Object] value
+      #
       # @see Dry::Types::Builder#default
+      #
       # @raise [ArgumentError] if nil provided as default value
+      #
+      # @api public
       def default(value)
         if value.nil?
           raise ArgumentError, "nil cannot be used as a default of a maybe type"
@@ -54,18 +87,24 @@ module Dry
     end
 
     module Builder
+      # Turn a type into a maybe type
+      #
       # @return [Maybe]
+      #
+      # @api public
       def maybe
         Maybe.new(Types['strict.nil'] | self)
       end
     end
 
+    # @api private
     class Printer
       MAPPING[Maybe] = :visit_maybe
 
+      # @api private
       def visit_maybe(maybe)
         visit(maybe.type) do |type|
-          yield "Maybe<#{ type }>"
+          yield "Maybe<#{type}>"
         end
       end
     end

data/lib/dry/types/fn_container.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/types/container'
 
 module Dry
   module Types
+    # Internal container for constructor functions used by the built-in types
+    #
+    # @api private
     class FnContainer
       # @api private
       def self.container

data/lib/dry/types/hash.rb

@@ -1,18 +1,26 @@
+# frozen_string_literal: true
+
 require 'dry/types/hash/constructor'
 
 module Dry
   module Types
+    # Hash types can be used to define maps and schemas
+    #
+    # @api public
     class Hash < Nominal
       NOT_REQUIRED = { required: false }.freeze
 
-      # @overload schmea(type_map, meta = EMPTY_HASH)
+      # @overload schema(type_map, meta = EMPTY_HASH)
       #   @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, meta = EMPTY_HASH)
         if keys_or_map.is_a?(::Array)
           keys = keys_or_map
@@ -27,7 +35,10 @@ module Dry
       #
       # @param [Type] key_type
       # @param [Type] value_type
+      #
       # @return [Map]
+      #
+      # @api public
       def map(key_type, value_type)
         Map.new(
           primitive,
@@ -37,8 +48,7 @@ module Dry
         )
       end
 
-      # @param [{Symbol => Nominal}] type_map
-      # @return [Schema]
+      # @api private
       def weak(*)
         raise "Support for old hash schemas was removed, please refer to the CHANGELOG "\
               "on how to proceed with the new API https://github.com/dry-rb/dry-types/blob/master/CHANGELOG.md"
@@ -49,9 +59,13 @@ module Dry
       alias_method :symbolized, :weak
 
       # Injects a type transformation function for building schemas
+      #
       # @param [#call,nil] proc
       # @param [#call,nil] block
+      #
       # @return [Hash]
+      #
+      # @api public
       def with_type_transform(proc = nil, &block)
         fn = proc || block
 
@@ -69,14 +83,19 @@ module Dry
       end
 
       # Whether the type transforms types of schemas created by {Dry::Types::Hash#schema}
+      #
       # @return [Boolean]
+      #
       # @api public
       def transform_types?
         !options[:type_transform_fn].nil?
       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(:type_transform_fn)

data/lib/dry/types/hash/constructor.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/types/constructor'
 
 module Dry
   module Types
+    # Hash type exposes additional APIs for working with schema hashes
+    #
+    # @api public
     class Hash < Nominal
       class Constructor < ::Dry::Types::Constructor
         # @api private
@@ -9,8 +14,16 @@ module Dry
           ::Dry::Types::Hash::Constructor
         end
 
+        # @return [Lax]
+        #
+        # @api public
+        def lax
+          type.lax.constructor(fn, meta: meta)
+        end
+
         private
 
+        # @api private
         def composable?(value)
           super && !value.is_a?(Schema::Key)
         end

data/lib/dry/types/inflector.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/inflector'
 
 module Dry

data/lib/dry/types/json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/types/coercions/json'
 
 module Dry
@@ -22,12 +24,8 @@ module Dry
       self['nominal.decimal'].constructor(Coercions::JSON.method(:to_decimal))
     end
 
-    register('json.array') do
-      self['nominal.array'].safe
-    end
+    register('json.array') { self['array'] }
 
-    register('json.hash') do
-      self['nominal.hash'].safe
-    end
+    register('json.hash') { self['hash'] }
   end
 end

data/lib/dry/types/{safe.rb → lax.rb}

@@ -1,61 +1,78 @@
+# frozen_string_literal: true
+
+require 'dry/core/deprecations'
 require 'dry/types/decorator'
 
 module Dry
   module Types
-    class Safe
+    # Lax types rescue from type-related errors when constructors fail
+    #
+    # @api public
+    class Lax
       include Type
       include Decorator
       include Builder
       include Printable
       include Dry::Equalizer(:type, inspect: false)
 
-      private :options, :meta
+      private :options, :constructor
 
       # @param [Object] input
+      #
       # @return [Object]
+      #
+      # @api public
       def call(input)
-        result = try(input)
-
-        if result.respond_to?(:input)
-          result.input
-        else
-          input
-        end
+        type.call_safe(input) { |output = input| output }
       end
       alias_method :[], :call
+      alias_method :call_safe, :call
+      alias_method :call_unsafe, :call
 
       # @param [Object] input
       # @param [#call,nil] block
+      #
       # @yieldparam [Failure] failure
       # @yieldreturn [Result]
+      #
       # @return [Result,Logic::Result]
+      #
+      # @api public
       def try(input, &block)
         type.try(input, &block)
-      rescue TypeError, ArgumentError => e
-        result = failure(input, e.message)
+      rescue CoercionError => error
+        result = failure(input, error.message)
         block ? yield(result) : result
       end
 
-      # @api public
-      #
       # @see Nominal#to_ast
+      #
+      # @api public
       def to_ast(meta: true)
-        [:safe, [type.to_ast(meta: meta), EMPTY_HASH]]
+        [:lax, type.to_ast(meta: meta)]
       end
 
+      # @return [Lax]
+      #
       # @api public
-      # @return [Safe]
-      def safe
+      def lax
         self
       end
 
       private
 
       # @param [Object, Dry::Types::Constructor] response
+      #
       # @return [Boolean]
+      #
+      # @api private
       def decorate?(response)
-        super || response.kind_of?(Constructor)
+        super || response.is_a?(constructor_type)
       end
     end
+
+    extend ::Dry::Core::Deprecations[:'dry-types']
+    Safe = Lax
+    deprecate_constant(:Safe)
   end
 end

data/lib/dry/types/map.rb

@@ -1,44 +1,76 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
+    # Homogeneous mapping. It describes a hash with unknown keys that match a certain type.
+    #
+    # @example
+    #   type = Dry::Types['hash'].map(
+    #     Dry::Types['integer'].constrained(gteq: 1, lteq: 10),
+    #     Dry::Types['string']
+    #   )
+    #
+    #   type.(1 => 'right')
+    #   # => {1 => 'right'}
+    #
+    #   type.('1' => 'wrong')
+    #   # Dry::Types::MapError: "1" violates constraints (type?(Integer, "1") AND gteq?(1, "1") AND lteq?(10, "1") failed)
+    #
+    #   type.(11 => 'wrong')
+    #   # Dry::Types::MapError: 11 violates constraints (lteq?(10, 11) failed)
+    #
+    # @api public
     class Map < Nominal
       def initialize(_primitive, key_type: Types['any'], value_type: Types['any'], meta: EMPTY_HASH)
         super(_primitive, key_type: key_type, value_type: value_type, meta: meta)
-        validate_options!
       end
 
       # @return [Type]
+      #
+      # @api public
       def key_type
         options[:key_type]
       end
 
       # @return [Type]
+      #
+      # @api public
       def value_type
         options[:value_type]
       end
 
       # @return [String]
+      #
+      # @api public
       def name
-        "Map"
+        'Map'
       end
 
       # @param [Hash] hash
+      #
       # @return [Hash]
-      def call(hash)
-        try(hash) do |failure|
-          raise MapError, failure.error.join("\n")
-        end.input
+      #
+      # @api private
+      def call_unsafe(hash)
+        try(hash) { |failure|
+          raise MapError, failure.error.message
+        }.input
       end
-      alias_method :[], :call
 
       # @param [Hash] hash
-      # @return [Boolean]
-      def valid?(hash)
-        coerce(hash).success?
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def call_safe(hash)
+        try(hash) { return yield }.input
       end
-      alias_method :===, :valid?
 
       # @param [Hash] hash
+      #
       # @return [Result]
+      #
+      # @api public
       def try(hash)
         result = coerce(hash)
         return result if result.success? || !block_given?
@@ -46,51 +78,53 @@ module Dry
       end
 
       # @param meta [Boolean] Whether to dump the meta to the AST
+      #
       # @return [Array] An AST representation
+      #
+      # @api public
       def to_ast(meta: true)
         [:map,
-         [key_type.to_ast(meta: true), value_type.to_ast(meta: true),
+         [key_type.to_ast(meta: true),
+          value_type.to_ast(meta: true),
           meta ? self.meta : EMPTY_HASH]]
       end
 
       # @return [Boolean]
+      #
+      # @api public
       def constrained?
         value_type.constrained?
       end
 
       private
 
+      # @api private
       def coerce(input)
         return failure(
-          input, "#{input.inspect} must be an instance of #{primitive}"
+          input, CoercionError.new("#{input.inspect} must be an instance of #{primitive}")
         ) unless primitive?(input)
 
         output, failures = {}, []
 
-        input.each do |k,v|
-          res_k = options[:key_type].try(k)
-          res_v = options[:value_type].try(v)
+        input.each do |k, v|
+          res_k = key_type.try(k)
+          res_v = value_type.try(v)
+
           if res_k.failure?
-            failures << "input key #{k.inspect} is invalid: #{res_k.error}"
+            failures << res_k.error
           elsif output.key?(res_k.input)
-            failures << "duplicate coerced hash key #{res_k.input.inspect}"
+            failures << CoercionError.new("duplicate coerced hash key #{res_k.input.inspect}")
           elsif res_v.failure?
-            failures << "input value #{v.inspect} for key #{k.inspect} is invalid: #{res_v.error}"
+            failures << res_v.error
           else
             output[res_k.input] = res_v.input
           end
         end
 
-        return success(output) if failures.empty?
-
-        failure(input, failures)
-      end
-
-      def validate_options!
-        %i(key_type value_type).each do |opt|
-          type = send(opt)
-          next if type.is_a?(Type)
-          raise MapError, ":#{opt} must be a #{Type}, got: #{type.inspect}"
+        if failures.empty?
+          success(output)
+        else
+          failure(input, MultipleError.new(failures))
         end
       end
     end