dry-types 0.15.0 → 1.2.0

data/docsite/source/map.html.md

@@ -0,0 +1,17 @@
+---
+title: Map
+layout: gem-single
+name: dry-types
+---
+
+`Map` describes a homogeneous hashmap. This means only types of keys and values are known. You can simply imagine a map input as a list of key-value pairs.
+
+```ruby
+int_float_hash = Types::Hash.map(Types::Integer, Types::Float)
+int_float_hash[100 => 300.0, 42 => 70.0]
+# => {100=>300.0, 42=>70.0}
+
+# Only accepts mappings of integers to floats
+int_float_hash[name: 'Jane']
+# => Dry::Types::MapError: input key :name is invalid: type?(Integer, :name)
+```

data/docsite/source/optional-values.html.md

@@ -0,0 +1,96 @@
+---
+title: Type Attributes
+layout: gem-single
+name: dry-types
+---
+
+Types themselves have optional attributes you can apply to get further functionality.
+
+### Append `.optional` to a _Type_ to allow `nil` 
+
+By default, nil values raise an error:
+
+``` ruby
+Types::Strict::String[nil]
+# => raises Dry::Types::ConstraintError
+```
+
+Add `.optional` and `nil` values become valid:
+
+```ruby
+optional_string = Types::Strict::String.optional
+
+optional_string[nil]
+# => nil
+optional_string['something']
+# => "something"
+optional_string[123]
+# raises Dry::Types::ConstraintError
+```
+
+`Types::String.optional` is just syntactic sugar for `Types::Strict::Nil | Types::Strict::String`.
+
+### Handle optional values using Monads
+
+The [dry-monads gem](/gems/dry-monads/) provides another approach to handling optional values by returning a [_Monad_](/gems/dry-monads/) object. This allows you to pass your type to a `Maybe(x)` block that only executes if `x` returns `Some` or `None`.
+
+> NOTE: Requires the [dry-monads gem](/gems/dry-monads/) to be loaded.
+
+1. Load the `:maybe` extension in your application.
+
+    ```ruby
+    require 'dry-types'
+    
+    Dry::Types.load_extensions(:maybe)
+    module Types
+      include Dry.Types()
+    end
+    ```
+   
+2. Append `.maybe` to a _Type_ to return a _Monad_ object  
+
+```ruby
+x = Types::Maybe::Strict::Integer[nil]
+Maybe(x) { puts(x) }
+
+x = Types::Maybe::Coercible::String[nil]
+Maybe(x) { puts(x) }
+
+x = Types::Maybe::Strict::Integer[123]
+Maybe(x) { puts(x) }
+
+x = Types::Maybe::Strict::String[123]
+Maybe(x) { puts(x) }
+```
+
+```ruby
+Types::Maybe::Strict::Integer[nil] # None
+Types::Maybe::Strict::Integer[123] # Some(123)
+
+Types::Maybe::Coercible::Float[nil] # None
+Types::Maybe::Coercible::Float['12.3'] # Some(12.3)
+
+# 'Maybe' types can also accessed by calling '.maybe' on a regular type:
+Types::Strict::Integer.maybe # equivalent to Types::Maybe::Strict::Integer
+```
+
+You can define your own optional types:
+
+``` ruby
+maybe_string = Types::Strict::String.maybe
+
+maybe_string[nil]
+# => None
+
+maybe_string[nil].fmap(&:upcase)
+# => None
+
+maybe_string['something']
+# => Some('something')
+
+maybe_string['something'].fmap(&:upcase)
+# => Some('SOMETHING')
+
+maybe_string['something'].fmap(&:upcase).value_or('NOTHING')
+# => "SOMETHING"
+```

data/docsite/source/sum.html.md

@@ -0,0 +1,21 @@
+---
+title: Sum
+layout: gem-single
+name: dry-types
+order: 7
+---
+
+You can specify sum types using `|` operator, it is an explicit way of defining what the valid types of a value are.
+
+For example `dry-types` defines the `Bool` type which is a sum consisting of the `True` and `False` types, expressed as `Types::True | Types::False`.
+
+Another common case is defining that something can be either `nil` or something else:
+
+``` ruby
+nil_or_string = Types::Nil | Types::String
+
+nil_or_string[nil] # => nil
+nil_or_string["hello"] # => "hello"
+
+nil_or_string[123] # raises Dry::Types::ConstraintError
+```

data/dry-types.gemspec

@@ -1,45 +1,47 @@
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dry/types/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "dry-types"
+  spec.name          = 'dry-types'
   spec.version       = Dry::Types::VERSION.dup
-  spec.authors       = ["Piotr Solnica"]
-  spec.email         = ["piotr.solnica@gmail.com"]
+  spec.authors       = ['Piotr Solnica']
+  spec.email         = ['piotr.solnica@gmail.com']
   spec.license       = 'MIT'
 
   spec.summary       = 'Type system for Ruby supporting coercions, constraints and complex types like structs, value objects, enums etc.'
   spec.description   = spec.summary
-  spec.homepage      = "https://github.com/dry-rb/dry-types"
+  spec.homepage      = 'https://github.com/dry-rb/dry-types'
 
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
-    spec.metadata['changelog_uri'] = "https://github.com/dry-rb/dry-types/blob/master/CHANGELOG.md"
-    spec.metadata['source_code_uri'] = "https://github.com/dry-rb/dry-types"
-    spec.metadata['bug_tracker_uri'] = "https://github.com/dry-rb/dry-types/issues"
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+    spec.metadata['changelog_uri'] = 'https://github.com/dry-rb/dry-types/blob/master/CHANGELOG.md'
+    spec.metadata['source_code_uri'] = 'https://github.com/dry-rb/dry-types'
+    spec.metadata['bug_tracker_uri'] = 'https://github.com/dry-rb/dry-types/issues'
   else
-    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
   end
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) } - ['bin/console', 'bin/setup']
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 2.3.0"
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.4.0'
 
   spec.add_runtime_dependency 'concurrent-ruby', '~> 1.0'
-  spec.add_runtime_dependency 'dry-core', '~> 0.4', '>= 0.4.4'
-  spec.add_runtime_dependency 'dry-inflector', '~> 0.1', '>= 0.1.2'
   spec.add_runtime_dependency 'dry-container', '~> 0.3'
+  spec.add_runtime_dependency 'dry-core', '~> 0.4', '>= 0.4.4'
   spec.add_runtime_dependency 'dry-equalizer', '~> 0.2', '>= 0.2.2'
-  spec.add_runtime_dependency 'dry-logic', '~> 0.5', '>= 0.5'
+  spec.add_runtime_dependency 'dry-inflector', '~> 0.1', '>= 0.1.2'
+  spec.add_runtime_dependency 'dry-logic', '~> 1.0', '>= 1.0.2'
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake", "~> 11.0"
-  spec.add_development_dependency "rspec", "~> 3.3"
+  spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'dry-monads', '~> 0.2'
+  spec.add_development_dependency 'rake', '~> 11.0'
+  spec.add_development_dependency 'rspec', '~> 3.3'
   spec.add_development_dependency 'yard', '~> 0.9.5'
 end

data/lib/dry-types.rb

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

data/lib/dry/types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bigdecimal'
 require 'date'
 require 'set'
@@ -22,13 +24,16 @@ 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)
@@ -40,34 +45,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 +98,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,19 +115,29 @@ 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('/', '.')
     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>]
+    # List of type keys defined in {Dry::Types.container}
+    #
+    # @return [String]
+    #
+    # @api private
     def self.type_keys
       container.keys
     end
@@ -112,8 +149,8 @@ module Dry
       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'
+              'You can access the predefined types with [], e.g. Dry::Types["integer"] '\
+              'or generate a module with types using Dry.Types()'
       else
         super
       end
@@ -126,26 +163,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 +191,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,12 +199,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
+  #
+  # rubocop:disable Naming/MethodName
   def self.Types(*namespaces, default: Types::Undefined, **aliases)
     Types::Module.new(Types.container, *namespaces, default: default, **aliases)
   end
+  # rubocop:enable Naming/MethodName
 end
 
 require 'dry/types/core' # load built-in types

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