dry-types 0.15.0 → 1.5.1

data/lib/dry/types/sum.rb

@@ -1,13 +1,21 @@
-require 'dry/types/options'
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+require "dry/types/options"
+require "dry/types/meta"
 
 module Dry
   module Types
+    # Sum type
+    #
+    # @api public
     class Sum
       include Type
       include Builder
       include Options
+      include Meta
       include Printable
-      include Dry::Equalizer(:left, :right, :options, :meta, inspect: false)
+      include Dry::Equalizer(:left, :right, :options, :meta, inspect: false, immutable: true)
 
       # @return [Type]
       attr_reader :left
@@ -15,6 +23,7 @@ module Dry
       # @return [Type]
       attr_reader :right
 
+      # @api private
       class Constrained < Sum
         # @return [Dry::Logic::Operations::Or]
         def rule
@@ -25,55 +34,69 @@ module Dry
         def constrained?
           true
         end
-
-        # @param [Object] input
-        # @return [Object]
-        # @raise [ConstraintError] if given +input+ not passing {#try}
-        def call(input)
-          try(input) { |result|
-            raise ConstraintError.new(result, input)
-          }.input
-        end
-        alias_method :[], :call
       end
 
       # @param [Type] left
       # @param [Type] right
       # @param [Hash] options
-      def initialize(left, right, options = {})
+      #
+      # @api private
+      def initialize(left, right, **options)
         super
         @left, @right = left, right
         freeze
       end
 
       # @return [String]
+      #
+      # @api public
       def name
-        [left, right].map(&:name).join(' | ')
+        [left, right].map(&:name).join(" | ")
       end
 
       # @return [false]
+      #
+      # @api public
       def default?
         false
       end
 
       # @return [false]
+      #
+      # @api public
       def constrained?
         false
       end
 
       # @return [Boolean]
+      #
+      # @api public
       def optional?
         primitive?(nil)
       end
 
       # @param [Object] input
+      #
       # @return [Object]
-      def call(input)
-        try(input).input
+      #
+      # @api private
+      def call_unsafe(input)
+        left.call_safe(input) { right.call_unsafe(input) }
       end
-      alias_method :[], :call
 
-      def try(input, &block)
+      # @param [Object] input
+      #
+      # @return [Object]
+      #
+      # @api private
+      def call_safe(input, &block)
+        left.call_safe(input) { right.call_safe(input, &block) }
+      end
+
+      # @param [Object] input
+      #
+      # @api public
+      def try(input)
         left.try(input) do
           right.try(input) do |failure|
             if block_given?
@@ -85,6 +108,7 @@ module Dry
         end
       end
 
+      # @api private
       def success(input)
         if left.valid?(input)
           left.success(input)
@@ -95,6 +119,7 @@ module Dry
         end
       end
 
+      # @api private
       def failure(input, _error = nil)
         if !left.valid?(input)
           left.failure(input, left.try(input).error)
@@ -104,28 +129,44 @@ module Dry
       end
 
       # @param [Object] value
+      #
       # @return [Boolean]
+      #
+      # @api private
       def primitive?(value)
         left.primitive?(value) || right.primitive?(value)
       end
 
-      # @param [Object] value
-      # @return [Boolean]
-      def valid?(value)
-        left.valid?(value) || right.valid?(value)
+      # Manage metadata to the type. If the type is an optional, #meta delegates
+      # to the right branch
+      #
+      # @see [Meta#meta]
+      #
+      # @api public
+      def meta(data = Undefined)
+        if Undefined.equal?(data)
+          optional? ? right.meta : super
+        elsif optional?
+          self.class.new(left, right.meta(data), **options)
+        else
+          super
+        end
       end
-      alias_method :===, :valid?
 
-      # @api public
-      #
       # @see Nominal#to_ast
+      #
+      # @api public
       def to_ast(meta: true)
         [:sum, [left.to_ast(meta: meta), right.to_ast(meta: meta), meta ? self.meta : EMPTY_HASH]]
       end
 
       # @param [Hash] options
+      #
       # @return [Constrained,Sum]
+      #
       # @see Builder#constrained
+      #
+      # @api public
       def constrained(options)
         if optional?
           right.constrained(options).optional
@@ -133,6 +174,15 @@ module Dry
           super
         end
       end
+
+      # Wrap the type with a proc
+      #
+      # @return [Proc]
+      #
+      # @api public
+      def to_proc
+        proc { |value| self.(value) }
+      end
     end
   end
 end

data/lib/dry/types/type.rb

@@ -1,6 +1,55 @@
+# frozen_string_literal: true
+
+require "dry/core/deprecations"
+
 module Dry
   module Types
+    # Common Type module denoting an object is a Type
+    #
+    # @api public
     module Type
+      extend ::Dry::Core::Deprecations[:'dry-types']
+
+      deprecate(:safe, :lax)
+
+      # Whether a value is a valid member of the type
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def valid?(input = Undefined)
+        call_safe(input) { return false }
+        true
+      end
+      # Anything can be coerced matches
+      alias_method :===, :valid?
+
+      # Apply type to a value
+      #
+      # @overload call(input = Undefined)
+      #   Possibly unsafe coercion attempt. If a value doesn't
+      #   match the type, an exception will be raised.
+      #
+      #   @param [Object] input
+      #   @return [Object]
+      #
+      # @overload call(input = Undefined)
+      #   When a block is passed, {#call} will never throw an exception on
+      #   failed coercion, instead it will call the block.
+      #
+      #   @param [Object] input
+      #   @yieldparam [Object] output Partially coerced value
+      #   @return [Object]
+      #
+      # @api public
+      def call(input = Undefined, &block)
+        if block_given?
+          call_safe(input, &block)
+        else
+          call_unsafe(input)
+        end
+      end
+      alias_method :[], :call
     end
   end
 end

data/lib/dry/types/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
-    VERSION = '0.15.0'.freeze
+    VERSION = "1.5.1"
   end
 end

data/lib/dry/types.rb

@@ -1,38 +1,42 @@
-require 'bigdecimal'
-require 'date'
-require 'set'
+# frozen_string_literal: true
 
-require 'concurrent'
+require "bigdecimal"
+require "date"
+require "set"
 
-require 'dry-container'
-require 'dry-equalizer'
-require 'dry/core/extensions'
-require 'dry/core/constants'
-require 'dry/core/class_attributes'
+require "concurrent/map"
 
-require 'dry/types/version'
-require 'dry/types/container'
-require 'dry/types/inflector'
-require 'dry/types/type'
-require 'dry/types/printable'
-require 'dry/types/nominal'
-require 'dry/types/constructor'
-require 'dry/types/module'
+require "dry/container"
+require "dry/core/extensions"
+require "dry/core/constants"
+require "dry/core/class_attributes"
 
-require 'dry/types/errors'
+require "dry/types/version"
+require "dry/types/container"
+require "dry/types/inflector"
+require "dry/types/type"
+require "dry/types/printable"
+require "dry/types/nominal"
+require "dry/types/constructor"
+require "dry/types/module"
+
+require "dry/types/errors"
 
 module Dry
+  # Main library namespace
+  #
+  # @api public
   module Types
     extend Dry::Core::Extensions
     extend Dry::Core::ClassAttributes
     extend Dry::Core::Deprecations[:'dry-types']
     include Dry::Core::Constants
 
-    TYPE_SPEC_REGEX = %r[(.+)<(.+)>].freeze
+    TYPE_SPEC_REGEX = /(.+)<(.+)>/.freeze
 
     # @see Dry.Types
     def self.module(*namespaces, default: :nominal, **aliases)
-      Module.new(container, *namespaces, default: default, **aliases)
+      ::Module.new(container, *namespaces, default: default, **aliases)
     end
     deprecate_class_method :module, message: <<~DEPRECATION
       Use Dry.Types() instead. Beware, it exports strict types by default, for old behavior use Dry.Types(default: :nominal). See more options in the changelog
@@ -40,34 +44,51 @@ module Dry
 
     # @api private
     def self.included(*)
-      raise RuntimeError, "Import Dry.Types, not Dry::Types"
+      raise "Import Dry.Types, not Dry::Types"
     end
 
+    # Return container with registered built-in type objects
+    #
     # @return [Container{String => Nominal}]
+    #
+    # @api private
     def self.container
       @container ||= Container.new
     end
 
+    # Check if a give type is registered
+    #
+    # @return [Boolean]
+    #
     # @api private
     def self.registered?(class_or_identifier)
       container.key?(identifier(class_or_identifier))
     end
 
+    # Register a new built-in type
+    #
     # @param [String] name
     # @param [Type] type
     # @param [#call,nil] block
+    #
     # @return [Container{String => Nominal}]
+    #
     # @api private
     def self.register(name, type = nil, &block)
       container.register(name, type || block.call)
     end
 
+    # Get a built-in type by its name
+    #
     # @param [String,Class] name
+    #
     # @return [Type,Class]
+    #
+    # @api public
     def self.[](name)
       type_map.fetch_or_store(name) do
         case name
-        when String
+        when ::String
           result = name.match(TYPE_SPEC_REGEX)
 
           if result
@@ -76,7 +97,12 @@ module Dry
           else
             container[name]
           end
-        when Class
+        when ::Class
+          warn(<<~DEPRECATION)
+            Using Dry::Types.[] with a class is deprecated, please use string identifiers: Dry::Types[Integer] -> Dry::Types['integer'].
+            If you're using dry-struct this means changing `attribute :counter, Integer` to `attribute :counter, Dry::Types['integer']` or to `attribute :counter, 'integer'`.
+          DEPRECATION
+
           type_name = identifier(name)
 
           if container.key?(type_name)
@@ -88,36 +114,64 @@ module Dry
       end
     end
 
+    # Infer a type identifier from the provided class
+    #
     # @param [#to_s] klass
+    #
     # @return [String]
     def self.identifier(klass)
-      Inflector.underscore(klass).tr('/', '.')
+      Inflector.underscore(klass).tr("/", ".")
     end
 
+    # Cached type map
+    #
     # @return [Concurrent::Map]
+    #
+    # @api private
     def self.type_map
-      @type_map ||= Concurrent::Map.new
-    end
-
-   # List of type keys defined in {Dry::Types.container}
-    # @return [<String>]
-    def self.type_keys
-      container.keys
+      @type_map ||= ::Concurrent::Map.new
     end
 
     # @api private
     def self.const_missing(const)
       underscored = Inflector.underscore(const)
 
-      if container.keys.any? { |key| key.split('.')[0] == underscored }
-        raise NameError,
-              'dry-types does not define constants for default types. '\
-              'You can access the predefined types with [], e.g. Dry::Types["strict.integer"] '\
-              'or generate a module with types using Dry::Types.module'
+      if container.keys.any? { |key| key.split(".")[0] == underscored }
+        raise ::NameError,
+              "dry-types does not define constants for default types. "\
+              'You can access the predefined types with [], e.g. Dry::Types["integer"] '\
+              "or generate a module with types using Dry.Types()"
       else
         super
       end
     end
+
+    # Add a new type builder method. This is a public API for defining custom
+    # type constructors
+    #
+    # @example simple custom type constructor
+    #   Dry::Types.define_builder(:or_nil) do |type|
+    #     type.optional.fallback(nil)
+    #   end
+    #
+    #   Dry::Types["integer"].or_nil.("foo") # => nil
+    #
+    # @example fallback alias
+    #   Dry::Types.define_builder(:or) do |type, fallback|
+    #     type.fallback(fallback)
+    #   end
+    #
+    #   Dry::Types["integer"].or(100).("foo") # => 100
+    #
+    # @param [Symbol] method
+    # @param [#call] block
+    #
+    # @api public
+    def self.define_builder(method, &block)
+      Builder.define_method(method) do |*args|
+        block.(self, *args)
+      end
+    end
   end
 
   # Export registered types as a module with constants
@@ -126,26 +180,26 @@ module Dry
   #
   #   module Types
   #     # imports all types as constants, uses modules for namespaces
-  #     include Dry::Types.module
+  #     include Dry::Types()
   #   end
-  #   # nominal types are exported by default
+  #   # strict types are exported by default
   #   Types::Integer
-  #   # => #<Dry::Types[Nominal<Integer>]>
-  #   Types::Strict::Integer
   #   # => #<Dry::Types[Constrained<Nominal<Integer> rule=[type?(Integer)]>]>
+  #   Types::Nominal::Integer
+  #   # => #<Dry::Types[Nominal<Integer>]>
   #
   # @example changing default types
   #
   #   module Types
-  #     include Dry::Types(default: :strict)
+  #     include Dry::Types(default: :nominal)
   #   end
   #   Types::Integer
-  #   # => #<Dry::Types[Constrained<Nominal<Integer> rule=[type?(Integer)]>]>
+  #   # => #<Dry::Types[Nominal<Integer>]>
   #
   # @example cherry-picking namespaces
   #
   #   module Types
-  #     include Dry::Types.module(:strict, :coercible)
+  #     include Dry::Types(:strict, :coercible)
   #   end
   #   # cherry-picking discards default types,
   #   # provide the :default option along with the list of
@@ -154,7 +208,7 @@ module Dry
   #
   # @example custom names
   #   module Types
-  #     include Dry::Types.module(coercible: :Kernel)
+  #     include Dry::Types(coercible: :Kernel)
   #   end
   #   Types::Kernel::Integer
   #   # => #<Dry::Types[Constructor<Nominal<Integer> fn=Kernel.Integer>]>
@@ -162,14 +216,18 @@ module Dry
   # @param [Array<Symbol>] namespaces List of type namespaces to export
   # @param [Symbol] default Default namespace to export
   # @param [Hash{Symbol => Symbol}] aliases Optional renamings, like strict: :Draconian
+  #
   # @return [Dry::Types::Module]
   #
-  # @see Dry::types::Module
+  # @see Dry::Types::Module
+  #
+  # @api public
+  #
   def self.Types(*namespaces, default: Types::Undefined, **aliases)
     Types::Module.new(Types.container, *namespaces, default: default, **aliases)
   end
 end
 
-require 'dry/types/core' # load built-in types
-require 'dry/types/extensions'
-require 'dry/types/printer'
+require "dry/types/core" # load built-in types
+require "dry/types/extensions"
+require "dry/types/printer"

data/lib/dry-types.rb

@@ -1 +1,3 @@
-require 'dry/types'
+# frozen_string_literal: true
+
+require "dry/types"