dry-types 1.1.1 → 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/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/member.rb

@@ -18,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
@@ -89,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
@@ -100,7 +100,7 @@ module Dry
         #
         # @api public
         def lax
-          Lax.new(Member.new(primitive, { **options, member: member.lax, meta: meta }))
+          Lax.new(Member.new(primitive, **options, member: member.lax, meta: meta))
         end
 
         # @see Nominal#to_ast

data/lib/dry/types/builder.rb

@@ -127,7 +127,7 @@ module Dry
       #
       # @api public
       def constructor(constructor = nil, **options, &block)
-        constructor_type.new(with(options), fn: constructor || block)
+        constructor_type.new(with(**options), fn: constructor || block)
       end
     end
   end

data/lib/dry/types/builder_methods.rb

@@ -25,7 +25,7 @@ module Dry
       #
       # @return [Dry::Types::Array]
       def Array(type)
-        self::Array.of(type)
+        Strict(::Array).of(type)
       end
 
       # Build a hash schema
@@ -34,7 +34,7 @@ module Dry
       #
       # @return [Dry::Types::Array]
       def Hash(type_map)
-        self::Hash.schema(type_map)
+        Strict(::Hash).schema(type_map)
       end
 
       # Build a type which values are instances of a given class
@@ -49,7 +49,7 @@ module Dry
       #
       # @return [Dry::Types::Type]
       def Instance(klass)
-        Nominal.new(klass).constrained(type: klass)
+        Nominal(klass).constrained(type: klass)
       end
       alias_method :Strict, :Instance
 
@@ -60,7 +60,7 @@ module Dry
       #
       # @return [Dry::Types::Type]
       def Value(value)
-        Nominal.new(value.class).constrained(eql: value)
+        Nominal(value.class).constrained(eql: value)
       end
 
       # Build a type with a single value
@@ -70,7 +70,7 @@ module Dry
       #
       # @return [Dry::Types::Type]
       def Constant(object)
-        Nominal.new(object.class).constrained(is: object)
+        Nominal(object.class).constrained(is: object)
       end
 
       # Build a constructor type
@@ -82,7 +82,11 @@ module Dry
       #
       # @return [Dry::Types::Type]
       def Constructor(klass, cons = nil, &block)
-        Nominal.new(klass).constructor(cons || block || klass.method(:new))
+        if klass.is_a?(Type)
+          klass.constructor(cons || block || klass.method(:new))
+        else
+          Nominal(klass).constructor(cons || block || klass.method(:new))
+        end
       end
 
       # Build a nominal type
@@ -91,7 +95,13 @@ module Dry
       #
       # @return [Dry::Types::Type]
       def Nominal(klass)
-        Nominal.new(klass)
+        if klass <= ::Array
+          Array.new(klass)
+        elsif klass <= ::Hash
+          Hash.new(klass)
+        else
+          Nominal.new(klass)
+        end
       end
 
       # Build a map type
@@ -105,7 +115,7 @@ module Dry
       #
       # @return [Dry::Types::Map]
       def Map(key_type, value_type)
-        Types['nominal.hash'].map(key_type, value_type)
+        Nominal(::Hash).map(key_type, value_type)
       end
 
       # Builds a constrained nominal type accepting any value that

data/lib/dry/types/compiler.rb

@@ -68,12 +68,12 @@ module Dry
 
       def visit_hash(node)
         opts, meta = node
-        registry['nominal.hash'].with(opts.merge(meta: meta))
+        registry['nominal.hash'].with(**opts, meta: meta)
       end
 
       def visit_schema(node)
         keys, options, meta = node
-        registry['nominal.hash'].schema(keys.map { |key| visit(key) }).with(options.merge(meta: meta))
+        registry['nominal.hash'].schema(keys.map { |key| visit(key) }).with(**options, meta: meta)
       end
 
       def visit_json_hash(node)

data/lib/dry/types/constrained.rb

@@ -24,7 +24,7 @@ module Dry
       # @param [Hash] options
       #
       # @api public
-      def initialize(type, options)
+      def initialize(type, **options)
         super
         @rule = options.fetch(:rule)
       end

data/lib/dry/types/constructor.rb

@@ -12,15 +12,13 @@ module Dry
     class Constructor < Nominal
       include Dry::Equalizer(:type, :options, inspect: false)
 
-      private :meta
-
       # @return [#call]
       attr_reader :fn
 
       # @return [Type]
       attr_reader :type
 
-      undef :constrained?
+      undef :constrained?, :meta, :optional?, :primitive, :default?, :name
 
       # @param [Builder, Object] input
       # @param [Hash] options
@@ -46,31 +44,6 @@ module Dry
         super(type, **options, fn: fn)
       end
 
-      # Return the inner type's primitive
-      #
-      # @return [Class]
-      #
-      # @api public
-      def primitive
-        type.primitive
-      end
-
-      # Return the inner type's name
-      #
-      # @return [String]
-      #
-      # @api public
-      def name
-        type.name
-      end
-
-      # @return [Boolean]
-      #
-      # @api public
-      def default?
-        type.default?
-      end
-
       # @return [Object]
       #
       # @api private
@@ -112,7 +85,7 @@ module Dry
       #
       # @api public
       def constructor(new_fn = nil, **options, &block)
-        with({**options, fn: fn >> (new_fn || block)})
+        with(**options, fn: fn >> (new_fn || block))
       end
       alias_method :append, :constructor
       alias_method :>>, :constructor
@@ -141,7 +114,7 @@ module Dry
       #
       # @api public
       def prepend(new_fn = nil, **options, &block)
-        with({**options, fn: fn << (new_fn || block)})
+        with(**options, fn: fn << (new_fn || block))
       end
       alias_method :<<, :prepend
 
@@ -150,7 +123,7 @@ module Dry
       # @return [Lax]
       # @api public
       def lax
-        Lax.new(Constructor.new(type.lax, options))
+        Lax.new(Constructor.new(type.lax, **options))
       end
 
       # Wrap the type with a proc
@@ -182,10 +155,10 @@ module Dry
       # @api private
       def method_missing(method, *args, &block)
         if type.respond_to?(method)
-          response = type.__send__(method, *args, &block)
+          response = type.public_send(method, *args, &block)
 
           if response.is_a?(Type) && type.class == response.class
-            response.constructor_type.new(response, options)
+            response.constructor_type.new(response, **options)
           else
             response
           end

data/lib/dry/types/decorator.rb

@@ -14,7 +14,7 @@ module Dry
       attr_reader :type
 
       # @param [Type] type
-      def initialize(type, *)
+      def initialize(type, *, **)
         super
         @type = type
       end
@@ -90,7 +90,7 @@ module Dry
       # @api private
       def method_missing(meth, *args, &block)
         if type.respond_to?(meth)
-          response = type.__send__(meth, *args, &block)
+          response = type.public_send(meth, *args, &block)
 
           if decorate?(response)
             __new__(response)
@@ -101,6 +101,7 @@ module Dry
           super
         end
       end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
 
       # Replace underlying type
       #

data/lib/dry/types/enum.rb

@@ -27,7 +27,7 @@ module Dry
       # @option options [Array] :values
       #
       # @api private
-      def initialize(type, options)
+      def initialize(type, **options)
         super
         @mapping = options.fetch(:mapping).freeze
         @values = @mapping.keys.freeze

data/lib/dry/types/extensions/monads.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'dry/monads/result'
+
+module Dry
+  module Types
+    # Monad extension for Result
+    #
+    # @api public
+    class Result
+      include Dry::Monads::Result::Mixin
+
+      # Turn result into a monad
+      #
+      # This makes result objects work with dry-monads (or anything with a compatible interface)
+      #
+      # @return [Dry::Monads::Success,Dry::Monads::Failure]
+      #
+      # @api public
+      def to_monad
+        if success?
+          Success(input)
+        else
+          Failure([error, input])
+        end
+      end
+    end
+  end
+end

data/lib/dry/types/extensions.rb

@@ -3,3 +3,7 @@
 Dry::Types.register_extension(:maybe) do
   require 'dry/types/extensions/maybe'
 end
+
+Dry::Types.register_extension(:monads) do
+  require 'dry/types/extensions/monads'
+end

data/lib/dry/types/hash.rb

@@ -113,7 +113,7 @@ module Dry
 
         type_map.map do |map_key, type|
           name, options = key_name(map_key)
-          key = Schema::Key.new(resolve_type(type), name, options)
+          key = Schema::Key.new(resolve_type(type), name, **options)
           type_transform.(key)
         end
       end
@@ -121,7 +121,8 @@ module Dry
       # @api private
       def resolve_type(type)
         case type
-        when String, Class then Types[type]
+        when Type then type
+        when ::Class, ::String then Types[type]
         else type
         end
       end

data/lib/dry/types/lax.rb

@@ -15,7 +15,7 @@ module Dry
       include Printable
       include Dry::Equalizer(:type, inspect: false)
 
-      private :options, :constructor
+      undef :options, :constructor
 
       # @param [Object] input
       #

data/lib/dry/types/meta.rb

@@ -16,7 +16,7 @@ module Dry
       # @return [Type]
       #
       # @api public
-      def with(options)
+      def with(**options)
         super(meta: @meta, **options)
       end
 

data/lib/dry/types/module.rb

@@ -18,10 +18,10 @@ module Dry
     #
     # @api public
     class Module < ::Module
-      def initialize(registry, *args)
+      def initialize(registry, *args, **kwargs)
         @registry = registry
-        check_parameters(*args)
-        constants = type_constants(*args)
+        check_parameters(*args, **kwargs)
+        constants = type_constants(*args, **kwargs)
         define_constants(constants)
         extend(BuilderMethods)
 

data/lib/dry/types/params.rb

@@ -55,5 +55,10 @@ module Dry
     register('params.symbol') do
       self['nominal.symbol'].constructor(Coercions::Params.method(:to_symbol))
     end
+
+    COERCIBLE.each_key do |name|
+      next if name.equal?(:string)
+      register("optional.params.#{name}", self['params.nil'] | self["params.#{name}"])
+    end
   end
 end