dry-types 1.0.0 → 1.2.1

data/docsite/source/index.html.md

@@ -0,0 +1,156 @@
+---
+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
+  - extensions
+---
+
+`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](docs::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](docs::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](docs::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](docs::constraints)
+* Support for [optional values](docs::optional-values)
+* Support for [default values](docs::default-values)
+* Support for [sum types](docs::sum)
+* Support for [enums](docs::enum)
+* Support for [hash type with type schemas](docs::hash-schemas)
+* Support for [array type with members](docs::array-with-member)
+* Support for arbitrary meta information
+* Support for typed struct objects via [dry-struct](/gems/dry-struct)
+* Types are [categorized](docs::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,35 @@
+---
+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
+
+See [Maybe](docs::extensions/maybe) extension for another approach to handling optional values by returning a [_Monad_](/gems/dry-monads/) object.

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/any.rb

@@ -15,7 +15,7 @@ module Dry
 
       # @api private
       def initialize(**options)
-        super(::Object, options)
+        super(::Object, **options)
       end
 
       # @return [String]
@@ -30,7 +30,7 @@ module Dry
       # @return [Type]
       #
       # @api public
-      def with(new_options)
+      def with(**new_options)
         self.class.new(**options, meta: @meta, **new_options)
       end
 

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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'dry/types/array/constructor'
+
 module Dry
   module Types
     class Array < Nominal
@@ -16,7 +18,7 @@ module Dry
         # @option options [Type] :member
         #
         # @api private
-        def initialize(primitive, options = {})
+        def initialize(primitive, **options)
           @member = options.fetch(:member)
           super
         end
@@ -87,7 +89,7 @@ module Dry
               block ? yield(failure) : failure
             end
           else
-            failure = failure(input, "#{input} is not an array")
+            failure = failure(input, CoercionError.new("#{input} is not an array"))
             block ? yield(failure) : failure
           end
         end
@@ -98,7 +100,7 @@ module Dry
         #
         # @api public
         def lax
-          Lax.new(Member.new(primitive, { **options, member: member.lax }))
+          Lax.new(Member.new(primitive, **options, member: member.lax, meta: meta))
         end
 
         # @see Nominal#to_ast
@@ -111,6 +113,11 @@ module Dry
             [:array, [member, meta ? self.meta : EMPTY_HASH]]
           end
         end
+
+        # @api private
+        def constructor_type
+          ::Dry::Types::Array::Constructor
+        end
       end
     end
   end