dry-types 1.0.1 → 1.2.0

data/docsite/source/index.html.md

@@ -0,0 +1,155 @@
+---
+title: Introduction
+layout: gem-single
+type: gem
+name: dry-types
+sections:
+  - getting-started
+  - built-in-types
+  - optional-values
+  - default-values
+  - sum
+  - constraints
+  - hash-schemas
+  - array-with-member
+  - enum
+  - map
+  - custom-types
+---
+
+`dry-types` is a simple and extendable type system for Ruby; useful for value coercions, applying constraints, defining complex structs or value objects and more. It was created as a successor to [Virtus](https://github.com/solnic/virtus).
+
+### Example usage
+
+```ruby
+require 'dry-types'
+require 'dry-struct'
+
+module Types
+  include Dry.Types()
+end
+
+User = Dry.Struct(name: Types::String, age: Types::Integer)
+
+User.new(name: 'Bob', age: 35)
+# => #<User name="Bob" age=35>
+```
+
+See [Built-in Types](/gems/dry-types/1.0/built-in-types/) for a full list of available types.
+
+By themselves, the basic type definitions like `Types::String` and `Types::Integer` don't do anything except provide documentation about which type an attribute is expected to have. However, there are many more advanced possibilities:
+
+- `Strict` types will raise an error if passed an attribute of the wrong type:
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::Strict::String
+  attribute :age,  Types::Strict::Integer
+end
+
+User.new(name: 'Bob', age: '18')
+# => Dry::Struct::Error: [User.new] "18" (String) has invalid type for :age
+```
+
+- `Coercible` types will attempt to convert an attribute to the correct class
+  using Ruby's built-in coercion methods:
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::Coercible::String
+  attribute :age,  Types::Coercible::Integer
+end
+
+User.new(name: 'Bob', age: '18')
+# => #<User name="Bob" age=18>
+User.new(name: 'Bob', age: 'not coercible')
+# => ArgumentError: invalid value for Integer(): "not coercible"
+```
+
+- Use `.optional` to denote that an attribute can be `nil` (see [Optional Values](/gems/dry-types/1.0/optional-values)):
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::String
+  attribute :age,  Types::Integer.optional
+end
+
+User.new(name: 'Bob', age: nil)
+# => #<User name="Bob" age=nil>
+# name is not optional:
+User.new(name: nil, age: 18)
+# => Dry::Struct::Error: [User.new] nil (NilClass) has invalid type for :name
+# keys must still be present:
+User.new(name: 'Bob')
+# => Dry::Struct::Error: [User.new] :age is missing in Hash input
+```
+
+- Add custom constraints (see [Constraints](/gems/dry-types/1.0/constraints.html)):
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::Strict::String
+  attribute :age,  Types::Strict::Integer.constrained(gteq: 18)
+end
+
+User.new(name: 'Bob', age: 17)
+# => Dry::Struct::Error: [User.new] 17 (Fixnum) has invalid type for :age
+```
+
+- Add custom metadata to a type:
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::String
+  attribute :age,  Types::Integer.meta(info: 'extra info about age')
+end
+```
+
+- Pass values directly to `Dry::Types` without creating an object using `[]`:
+
+```ruby
+Types::Strict::String["foo"]
+# => "foo"
+Types::Strict::String["10000"]
+# => "10000"
+Types::Coercible::String[10000]
+# => "10000"
+Types::Strict::String[10000]
+# Dry::Types::ConstraintError: 1000 violates constraints
+```
+
+### Features
+
+* Support for [constrained types](/gems/dry-types/1.0/constraints)
+* Support for [optional values](/gems/dry-types/1.0/optional-values)
+* Support for [default values](/gems/dry-types/1.0/default-values)
+* Support for [sum types](/gems/dry-types/1.0/sum)
+* Support for [enums](/gems/dry-types/1.0/enum)
+* Support for [hash type with type schemas](/gems/dry-types/1.0/hash-schemas)
+* Support for [array type with members](/gems/dry-types/1.0/array-with-member)
+* Support for arbitrary meta information
+* Support for typed struct objects via [dry-struct](/gems/dry-struct)
+* Types are [categorized](/gems/dry-types/1.0/built-in-types), which is especially important for optimized and dedicated coercion logic
+* Types are composable and reusable objects
+* No const-missing magic and complicated const lookups
+* Roughly 6-10 x faster than Virtus
+
+### Use cases
+
+`dry-types` is suitable for many use-cases, for example:
+
+  * Value coercions
+  * Processing arrays
+  * Processing hashes with explicit schemas
+  * Defining various domain-specific information shared between multiple parts of your application
+  * Annotating objects
+
+### Other gems using dry-types
+
+`dry-types` is often used as a low-level abstraction. The following gems use it already:
+
+* [dry-struct](/gems/dry-struct)
+* [dry-initializer](/gems/dry-initializer)
+* [Hanami](http://hanamirb.org)
+* [rom-rb](http://rom-rb.org)
+* [Trailblazer](http://trailblazer.to)

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,47 +1,47 @@
 # frozen_string_literal: true
 
-lib = File.expand_path('../lib', __FILE__)
+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.4.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', '~> 1.0'
+  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

@@ -33,7 +33,7 @@ module Dry
     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)
@@ -45,7 +45,7 @@ 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
@@ -89,7 +89,7 @@ module Dry
     def self.[](name)
       type_map.fetch_or_store(name) do
         case name
-        when String
+        when ::String
           result = name.match(TYPE_SPEC_REGEX)
 
           if result
@@ -98,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)

data/lib/dry/types/array.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'dry/types/array/member'
+require 'dry/types/array/constructor'
 
 module Dry
   module Types
@@ -24,6 +25,11 @@ module Dry
 
         Array::Member.new(primitive, **options, member: member)
       end
+
+      # @api private
+      def constructor_type
+        ::Dry::Types::Array::Constructor
+      end
     end
   end
 end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'dry/types/constructor'
+
+module Dry
+  module Types
+    # @api public
+    class Array < Nominal
+      # @api private
+      class Constructor < ::Dry::Types::Constructor
+        # @api private
+        def constructor_type
+          ::Dry::Types::Array::Constructor
+        end
+
+        # @return [Lax]
+        #
+        # @api public
+        def lax
+          Lax.new(type.lax.constructor(fn, meta: meta))
+        end
+
+        # @see Dry::Types::Array#of
+        #
+        # @api public
+        def of(member)
+          type.of(member).constructor(fn, meta: meta)
+        end
+      end
+    end
+  end
+end