dry-types 0.15.0 → 1.0.0

data/lib/dry/types/any.rb

@@ -1,36 +1,47 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
-    Any = Class.new(Nominal) do
+    # Any is a nominal type that defines Object as the primitive class
+    #
+    # This type is useful in places where you can't be specific about the type
+    # and anything is acceptable.
+    #
+    # @api public
+    class AnyClass < Nominal
       def self.name
         'Any'
       end
 
+      # @api private
       def initialize(**options)
         super(::Object, options)
       end
 
       # @return [String]
+      #
+      # @api public
       def name
         'Any'
       end
 
-      # @param [Object] any input is valid
-      # @return [true]
-      def valid?(_)
-        true
-      end
-      alias_method :===, :valid?
-
       # @param [Hash] new_options
+      #
       # @return [Type]
-      def with(**new_options)
+      #
+      # @api public
+      def with(new_options)
         self.class.new(**options, meta: @meta, **new_options)
       end
 
       # @return [Array]
+      #
+      # @api public
       def to_ast(meta: true)
         [:any, meta ? self.meta : EMPTY_HASH]
       end
-    end.new
+    end
+
+    Any = AnyClass.new
   end
 end

data/lib/dry/types/array.rb

@@ -1,10 +1,20 @@
+# frozen_string_literal: true
+
 require 'dry/types/array/member'
 
 module Dry
   module Types
+    # Array type can be used to define an array with optional member type
+    #
+    # @api public
     class Array < Nominal
-      # @param [Type] type
+      # Build an array type with a member type
+      #
+      # @param [Type,#call] type
+      #
       # @return [Array::Member]
+      #
+      # @api public
       def of(type)
         member =
           case type

data/lib/dry/types/array/member.rb

@@ -1,46 +1,89 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
     class Array < Nominal
+      # Member arrays define their member type that is applied to each element
+      #
+      # @api public
       class Member < Array
         # @return [Type]
         attr_reader :member
 
         # @param [Class] primitive
         # @param [Hash] options
+        #
         # @option options [Type] :member
+        #
+        # @api private
         def initialize(primitive, options = {})
           @member = options.fetch(:member)
           super
         end
 
         # @param [Object] input
-        # @param [Symbol] meth
+        #
         # @return [Array]
-        def call(input, meth = :call)
-          input.map { |el| member.__send__(meth, el) }
+        #
+        # @api private
+        def call_unsafe(input)
+          if primitive?(input)
+            input.each_with_object([]) do |el, output|
+              coerced = member.call_unsafe(el)
+
+              output << coerced unless Undefined.equal?(coerced)
+            end
+          else
+            super
+          end
         end
-        alias_method :[], :call
 
-        # @param [Array, #all?, Object] value
-        # @return [Boolean]
-        def valid?(value)
-          super && value.all? { |el| member.valid?(el) }
+        # @param [Object] input
+        # @return [Array]
+        #
+        # @api private
+        def call_safe(input)
+          if primitive?(input)
+            failed = false
+
+            result = input.each_with_object([]) do |el, output|
+              coerced = member.call_safe(el) { |out = el|
+                failed = true
+                out
+              }
+
+              output << coerced unless Undefined.equal?(coerced)
+            end
+
+            failed ? yield(result) : result
+          else
+            yield
+          end
         end
 
         # @param [Array, Object] input
         # @param [#call,nil] block
+        #
         # @yieldparam [Failure] failure
         # @yieldreturn [Result]
+        #
         # @return [Result,Logic::Result]
+        #
+        # @api public
         def try(input, &block)
-          if input.is_a?(::Array)
-            result = call(input, :try).reject { |r| r.input.equal?(Undefined) }
-            output = result.map(&:input)
+          if primitive?(input)
+            output = []
+
+            result = input.map { |el| member.try(el) }
+            result.each do |r|
+              output << r.input unless Undefined.equal?(r.input)
+            end
 
             if result.all?(&:success?)
               success(output)
             else
-              failure = failure(output, result.select(&:failure?))
+              error = result.find(&:failure?).error
+              failure = failure(output, error)
               block ? yield(failure) : failure
             end
           else
@@ -49,9 +92,18 @@ module Dry
           end
         end
 
-        # @api public
+        # Build a lax type
+        #
+        # @return [Lax]
         #
+        # @api public
+        def lax
+          Lax.new(Member.new(primitive, { **options, member: member.lax }))
+        end
+
         # @see Nominal#to_ast
+        #
+        # @api public
         def to_ast(meta: true)
           if member.respond_to?(:to_ast)
             [:array, [member.to_ast(meta: meta), meta ? self.meta : EMPTY_HASH]]

data/lib/dry/types/builder.rb

@@ -1,43 +1,72 @@
+# frozen_string_literal: true
+
 require 'dry/core/deprecations'
 
 module Dry
   module Types
+    # Common API for building types and composition
+    #
+    # @api public
     module Builder
       include Dry::Core::Constants
 
       # @return [Class]
+      #
+      # @api private
       def constrained_type
         Constrained
       end
 
       # @return [Class]
+      #
+      # @api private
       def constructor_type
         Constructor
       end
 
+      # Compose two types into a Sum type
+      #
       # @param [Type] other
+      #
       # @return [Sum, Sum::Constrained]
+      #
+      # @api private
       def |(other)
         klass = constrained? && other.constrained? ? Sum::Constrained : Sum
         klass.new(self, other)
       end
 
+      # Turn a type into an optional type
+      #
       # @return [Sum]
+      #
+      # @api public
       def optional
         Types['strict.nil'] | self
       end
 
+      # Turn a type into a constrained type
+      #
       # @param [Hash] options constraining rule (see {Types.Rule})
+      #
       # @return [Constrained]
+      #
+      # @api public
       def constrained(options)
         constrained_type.new(self, rule: Types.Rule(options))
       end
 
+      # Turn a type into a type with a default value
+      #
       # @param [Object] input
       # @param [Hash] options
       # @param [#call,nil] block
+      #
       # @raise [ConstraintError]
+      #
       # @return [Default]
+      #
+      # @api public
       def default(input = Undefined, options = EMPTY_HASH, &block)
         unless input.frozen? || options[:shared]
           where = Dry::Core::Deprecations::STACK.()
@@ -60,8 +89,13 @@ module Dry
         end
       end
 
+      # Define an enum on top of the existing type
+      #
       # @param [Array] values
+      #
       # @return [Enum]
+      #
+      # @api public
       def enum(*values)
         mapping =
           if values.length == 1 && values[0].is_a?(::Hash)
@@ -73,15 +107,25 @@ module Dry
         Enum.new(constrained(included_in: mapping.keys), mapping: mapping)
       end
 
-      # @return [Safe]
-      def safe
-        Safe.new(self)
+      # Turn a type into a lax type that will rescue from type-errors and
+      # return the original input
+      #
+      # @return [Lax]
+      #
+      # @api public
+      def lax
+        Lax.new(self)
       end
 
+      # Define a constructor for the type
+      #
       # @param [#call,nil] constructor
       # @param [Hash] options
       # @param [#call,nil] block
+      #
       # @return [Constructor]
+      #
+      # @api public
       def constructor(constructor = nil, **options, &block)
         constructor_type.new(with(options), fn: constructor || block)
       end
@@ -92,5 +136,5 @@ end
 require 'dry/types/default'
 require 'dry/types/constrained'
 require 'dry/types/enum'
-require 'dry/types/safe'
+require 'dry/types/lax'
 require 'dry/types/sum'

data/lib/dry/types/builder_methods.rb

@@ -1,5 +1,12 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
+    # Common API for building type objects in a convenient way
+    #
+    # rubocop:disable Naming/MethodName
+    #
+    # @api public
     module BuilderMethods
       # @api private
       def included(base)
@@ -8,7 +15,8 @@ module Dry
       end
 
       # Build an array type.
-      # It is a shortcut for Array.of
+      #
+      # Shortcut for Array#of.
       #
       # @example
       #   Types::Strings = Types.Array(Types::String)
@@ -25,7 +33,6 @@ module Dry
       # @param [Hash{Symbol => Dry::Types::Type}] type_map
       #
       # @return [Dry::Types::Array]
-      # @api public
       def Hash(type_map)
         self::Hash.schema(type_map)
       end
@@ -41,7 +48,6 @@ module Dry
       # @param [Class,Module] klass Class or module
       #
       # @return [Dry::Types::Type]
-      # @api public
       def Instance(klass)
         Nominal.new(klass).constrained(type: klass)
       end
@@ -53,7 +59,6 @@ module Dry
       # @param [Object] value
       #
       # @return [Dry::Types::Type]
-      # @api public
       def Value(value)
         Nominal.new(value.class).constrained(eql: value)
       end
@@ -64,7 +69,6 @@ module Dry
       # @param [Object] object
       #
       # @return [Dry::Types::Type]
-      # @api public
       def Constant(object)
         Nominal.new(object.class).constrained(is: object)
       end
@@ -77,7 +81,6 @@ module Dry
       # @param [#call,nil] block Value constructor
       #
       # @return [Dry::Types::Type]
-      # @api public
       def Constructor(klass, cons = nil, &block)
         Nominal.new(klass).constructor(cons || block || klass.method(:new))
       end
@@ -87,7 +90,6 @@ module Dry
       # @param [Class] klass
       #
       # @return [Dry::Types::Type]
-      # @api public
       def Nominal(klass)
         Nominal.new(klass)
       end
@@ -102,7 +104,6 @@ module Dry
       # @param [Type] value_type Value type
       #
       # @return [Dry::Types::Map]
-      # @api public
       def Map(key_type, value_type)
         Types['nominal.hash'].map(key_type, value_type)
       end

data/lib/dry/types/coercions.rb

@@ -1,50 +1,102 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
+    # Common coercion functions used by the built-in `Params` and `JSON` types
+    #
+    # @api public
     module Coercions
       include Dry::Core::Constants
 
       # @param [String, Object] input
-      # @return [nil] if the input is an empty string
-      # @return [Object] otherwise the input object is returned
-      def to_nil(input)
-        input unless empty_str?(input)
+      #
+      # @return [nil] if the input is an empty string or nil
+      #
+      # @raise CoercionError
+      #
+      # @api public
+      def to_nil(input, &_block)
+        if input.nil? || empty_str?(input)
+          nil
+        elsif block_given?
+          yield
+        else
+          raise CoercionError, "#{input.inspect} is not nil"
+        end
       end
 
       # @param [#to_str, Object] input
+      #
       # @return [Date, Object]
+      #
       # @see Date.parse
-      def to_date(input)
-        return input unless input.respond_to?(:to_str)
-        Date.parse(input)
-      rescue ArgumentError, RangeError
-        input
+      #
+      # @api public
+      def to_date(input, &block)
+        if input.respond_to?(:to_str)
+          begin
+            ::Date.parse(input)
+          rescue ArgumentError, RangeError => error
+            CoercionError.handle(error, &block)
+          end
+        elsif block_given?
+          yield
+        else
+          raise CoercionError, "#{input.inspect} is not a string"
+        end
       end
 
       # @param [#to_str, Object] input
+      #
       # @return [DateTime, Object]
+      #
       # @see DateTime.parse
-      def to_date_time(input)
-        return input unless input.respond_to?(:to_str)
-        DateTime.parse(input)
-      rescue ArgumentError
-        input
+      #
+      # @api public
+      def to_date_time(input, &block)
+        if input.respond_to?(:to_str)
+          begin
+            ::DateTime.parse(input)
+          rescue ArgumentError => error
+            CoercionError.handle(error, &block)
+          end
+        elsif block_given?
+          yield
+        else
+          raise CoercionError, "#{input.inspect} is not a string"
+        end
       end
 
       # @param [#to_str, Object] input
+      #
       # @return [Time, Object]
+      #
       # @see Time.parse
-      def to_time(input)
-        return input unless input.respond_to?(:to_str)
-        Time.parse(input)
-      rescue ArgumentError
-        input
+      #
+      # @api public
+      def to_time(input, &block)
+        if input.respond_to?(:to_str)
+          begin
+            ::Time.parse(input)
+          rescue ArgumentError => error
+            CoercionError.handle(error, &block)
+          end
+        elsif block_given?
+          yield
+        else
+          raise CoercionError, "#{input.inspect} is not a string"
+        end
       end
 
       private
 
       # Checks whether String is empty
+      #
       # @param [String, Object] value
+      #
       # @return [Boolean]
+      #
+      # @api private
       def empty_str?(value)
         EMPTY_STRING.eql?(value)
       end