dry-types 0.15.0 → 1.2.0

data/benchmarks/hash_schemas.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $LOAD_PATH.unshift('lib')
 
 require 'bundler/setup'
@@ -5,11 +7,13 @@ require 'dry-types'
 
 module SchemaBench
   def self.hash_schema(type)
-    Dry::Types['nominal.hash'].public_send(type,
-      email:   Dry::Types['nominal.string'],
-      age:     Dry::Types['params.integer'],
-      admin:   Dry::Types['params.bool'],
-      address: Dry::Types['nominal.hash'].public_send(type,
+    Dry::Types['nominal.hash'].public_send(
+      type,
+      email: Dry::Types['nominal.string'],
+      age: Dry::Types['params.integer'],
+      admin: Dry::Types['params.bool'],
+      address: Dry::Types['nominal.hash'].public_send(
+        type,
         city: Dry::Types['nominal.string'],
         street: Dry::Types['nominal.string']
       )
@@ -29,7 +33,7 @@ module SchemaBench
     age: '20',
     admin: '1',
     address: { city: 'NYC', street: 'Street 1/2' }
-  }
+  }.freeze
 end
 
 require 'benchmark/ips'

data/benchmarks/lax_schema.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'setup'
+
+schema = Dry::Types['params.hash'].schema(
+  email?: 'string',
+  age?: 'params.integer'
+).lax
+
+params = { email: 'jane@doe.org', age: '19' }
+
+Benchmark.ips do |x|
+  x.report("valid input") { schema.(params) }
+  x.compare!
+end

data/benchmarks/profile_invalid_input.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'setup'
+
+INVALID_INPUT = {
+  name: :John,
+  age: '20',
+  email: nil
+}.freeze
+
+profile do
+  10_000.times do
+    PersonSchema.(INVALID_INPUT)
+  end
+end

data/benchmarks/profile_lax_schema_valid.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'setup'
+
+Schema = Dry::Types['params.hash'].schema(
+  email?: 'string',
+  age?: 'coercible.integer'
+).lax
+
+ValidInput = { email: 'jane@doe.org', age: '19' }.freeze
+
+profile do
+  10_000.times do
+    Schema.(ValidInput)
+  end
+end

data/benchmarks/profile_valid_input.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'setup'
+
+VALID_INPUT = {
+  name: 'John',
+  age: 20,
+  email: 'john@doe.com'
+}.freeze
+
+profile do
+  10_000.times do
+    PersonSchema.(VALID_INPUT)
+  end
+end

data/benchmarks/schema_valid_vs_invalid.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'setup'
+
+VALID_INPUT = {
+  name: 'John',
+  age: 20,
+  email: 'john@doe.com'
+}
+
+INVALID_INPUT = {
+  name: :John,
+  age: '20',
+  email: nil
+}
+
+Benchmark.ips do |x|
+  x.report("valid input") { PersonSchema.(VALID_INPUT) }
+  x.report("invalid input") { PersonSchema.(INVALID_INPUT) }
+  x.compare!
+end

data/benchmarks/setup.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+require 'hotch'
+ENV['HOTCH_VIEWER'] ||= 'open'
+
+require 'dry/types'
+
+PersonSchema = Dry::Types['hash'].schema(
+  name: 'string',
+  age: 'integer',
+  email: 'string'
+).lax
+
+def profile(&block)
+  Hotch(filter: 'Dry', &block)
+end

data/docsite/source/array-with-member.html.md

@@ -0,0 +1,13 @@
+---
+title: Array With Member
+layout: gem-single
+name: dry-types
+---
+
+The built-in array type supports defining the member's type:
+
+``` ruby
+PostStatuses = Types::Array.of(Types::Coercible::String)
+
+PostStatuses[[:foo, :bar]] # ["foo", "bar"]
+```

data/docsite/source/built-in-types.html.md

@@ -0,0 +1,116 @@
+---
+title: Built-in Types
+layout: gem-single
+name: dry-types
+---
+
+Built-in types are grouped under 6 categories:
+
+- `nominal` - base type definitions with a primitive class and options
+- `strict` - constrained types with a primitive type check applied to input
+- `coercible` - types with constructors using kernel coercions
+- `params` - types with constructors performing non-strict coercions specific to HTTP parameters
+- `json` - types with constructors performing non-strict coercions specific to JSON
+- `maybe` - types accepting either nil or a specific primitive type
+
+### Categories
+
+Assuming you included `Dry::Types` ([see instructions](/gems/dry-types/1.0/getting-started)) in a module called `Types`:
+
+* Nominal types:
+  - `Types::Nominal::Any`
+  - `Types::Nominal::Nil`
+  - `Types::Nominal::Symbol`
+  - `Types::Nominal::Class`
+  - `Types::Nominal::True`
+  - `Types::Nominal::False`
+  - `Types::Nominal::Bool`
+  - `Types::Nominal::Integer`
+  - `Types::Nominal::Float`
+  - `Types::Nominal::Decimal`
+  - `Types::Nominal::String`
+  - `Types::Nominal::Date`
+  - `Types::Nominal::DateTime`
+  - `Types::Nominal::Time`
+  - `Types::Nominal::Array`
+  - `Types::Nominal::Hash`
+
+* `Strict` types will raise an error if passed a value of the wrong type:
+  - `Types::Strict::Nil`
+  - `Types::Strict::Symbol`
+  - `Types::Strict::Class`
+  - `Types::Strict::True`
+  - `Types::Strict::False`
+  - `Types::Strict::Bool`
+  - `Types::Strict::Integer`
+  - `Types::Strict::Float`
+  - `Types::Strict::Decimal`
+  - `Types::Strict::String`
+  - `Types::Strict::Date`
+  - `Types::Strict::DateTime`
+  - `Types::Strict::Time`
+  - `Types::Strict::Array`
+  - `Types::Strict::Hash`
+
+> All types in the `strict` category are [constrained](/gems/dry-types/1.0/constraints) by a type-check that is applied to make sure that the input is an instance of the primitive:
+
+``` ruby
+Types::Strict::Integer[1] # => 1
+Types::Strict::Integer['1'] # => raises Dry::Types::ConstraintError
+```
+
+* `Coercible` types will attempt to cast values to the correct class using kernel coercion methods:
+  - `Types::Coercible::String`
+  - `Types::Coercible::Integer`
+  - `Types::Coercible::Float`
+  - `Types::Coercible::Decimal`
+  - `Types::Coercible::Array`
+  - `Types::Coercible::Hash`
+
+* Types suitable for `Params` param processing with coercions:
+  - `Types::Params::Nil`
+  - `Types::Params::Date`
+  - `Types::Params::DateTime`
+  - `Types::Params::Time`
+  - `Types::Params::True`
+  - `Types::Params::False`
+  - `Types::Params::Bool`
+  - `Types::Params::Integer`
+  - `Types::Params::Float`
+  - `Types::Params::Decimal`
+  - `Types::Params::Array`
+  - `Types::Params::Hash`
+
+* Types suitable for `JSON` processing with coercions:
+  - `Types::JSON::Nil`
+  - `Types::JSON::Date`
+  - `Types::JSON::DateTime`
+  - `Types::JSON::Time`
+  - `Types::JSON::Decimal`
+  - `Types::JSON::Array`
+  - `Types::JSON::Hash`
+
+* `Maybe` strict types:
+  - `Types::Maybe::Strict::Class`
+  - `Types::Maybe::Strict::String`
+  - `Types::Maybe::Strict::Symbol`
+  - `Types::Maybe::Strict::True`
+  - `Types::Maybe::Strict::False`
+  - `Types::Maybe::Strict::Integer`
+  - `Types::Maybe::Strict::Float`
+  - `Types::Maybe::Strict::Decimal`
+  - `Types::Maybe::Strict::Date`
+  - `Types::Maybe::Strict::DateTime`
+  - `Types::Maybe::Strict::Time`
+  - `Types::Maybe::Strict::Array`
+  - `Types::Maybe::Strict::Hash`
+
+* `Maybe` coercible types:
+  - `Types::Maybe::Coercible::String`
+  - `Types::Maybe::Coercible::Integer`
+  - `Types::Maybe::Coercible::Float`
+  - `Types::Maybe::Coercible::Decimal`
+  - `Types::Maybe::Coercible::Array`
+  - `Types::Maybe::Coercible::Hash`
+
+> `Maybe` types are not available by default - they must be loaded using `Dry::Types.load_extensions(:maybe)`. See [Optional Values](/gems/dry-types/1.0/optional-values) for more information.

data/docsite/source/constraints.html.md

@@ -0,0 +1,31 @@
+---
+title: Constraints
+layout: gem-single
+name: dry-types
+---
+
+You can create constrained types that will use validation rules to check that the input is not violating any of the configured constraints. You can treat it as a lower level guarantee that you're not instantiating objects that are broken.
+
+All types support the constraints API, but not all constraints are suitable for a particular primitive, it's up to you to set up constraints that make sense.
+
+Under the hood it uses [`dry-logic`](/gems/dry-logic) and all of its predicates are supported.
+
+``` ruby
+string = Types::String.constrained(min_size: 3)
+
+string['foo']
+# => "foo"
+
+string['fo']
+# => Dry::Types::ConstraintError: "fo" violates constraints
+
+email = Types::String.constrained(
+  format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i
+)
+
+email["jane@doe.org"]
+# => "jane@doe.org"
+
+email["jane"]
+# => Dry::Types::ConstraintError: "jane" violates constraints
+```

data/docsite/source/custom-types.html.md

@@ -0,0 +1,93 @@
+---
+title: Custom Types
+layout: gem-single
+name: dry-types
+---
+
+There are a bunch of helpers for building your own types based on existing classes and values. These helpers are automatically defined if you're imported types in a module.
+
+### `Types.Instance`
+
+`Types.Instance` builds a type that checks if a value has the given class.
+
+```ruby
+range_type = Types.Instance(Range)
+range_type[1..2] # => 1..2
+```
+
+### `Types.Value`
+
+`Types.Value` builds a type that checks a value for equality (using `==`).
+
+```ruby
+valid = Types.Value('valid')
+valid['valid'] # => 'valid'
+valid['invalid']
+# => Dry::Types::ConstraintError: "invalid" violates constraints (eql?("valid", "invalid") failed)
+```
+
+### `Types.Constant`
+
+`Types.Constant` builds a type that checks a value for identity (using `equal?`).
+
+```ruby
+valid = Types.Constant(:valid)
+valid[:valid] # => :valid
+valid[:invalid]
+# => Dry::Types::ConstraintError: :invalid violates constraints (is?(:valid, :invalid) failed)
+```
+
+### `Types.Constructor`
+
+`Types.Constructor` builds a new constructor type for the given class. By default uses the `new` method as a constructor.
+
+```ruby
+user_type = Types.Constructor(User)
+
+# It is equivalent to User.new(name: 'John')
+user_type[name: 'John']
+
+# Using a block
+user_type = Types.Constructor(User) { |values| User.new(values) }
+```
+
+### `Types.Nominal`
+
+`Types.Nominal` wraps the given class with a simple definition without any behavior attached.
+
+```ruby
+int = Types.Nominal(Integer)
+int[1] # => 1
+
+# The type doesn't have any checks
+int['one'] # => 'one'
+```
+
+### `Types.Hash`
+
+`Types.Hash` builds a new hash schema.
+
+```ruby
+# In the full form
+Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer)
+
+# Using Types.Hash()
+Types.Hash(:permissive, name: Types::String, age: Types::Coercible::Integer)
+```
+
+### `Types.Array`
+
+`Types.Array` is a shortcut for `Types::Array.of`
+
+```ruby
+ListOfStrings = Types.Array(Types::String)
+```
+
+### `Types.Interface`
+
+`Types.Interface` builds a type that checks a value responds to given methods.
+
+```ruby
+Callable = Types.Interface(:call)
+Contact = Types.Interface(:name, :phone)
+```

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

@@ -0,0 +1,91 @@
+---
+title: Default Values
+layout: gem-single
+name: dry-types
+---
+
+A type with a default value will return the configured value when the input is not defined:
+
+``` ruby
+PostStatus = Types::String.default('draft')
+
+PostStatus[] # "draft"
+PostStatus["published"] # "published"
+PostStatus[true] # raises ConstraintError
+```
+
+It works with a callable value:
+
+``` ruby
+CallableDateTime = Types::DateTime.default { DateTime.now }
+
+CallableDateTime[]
+# => #<DateTime: 2017-05-06T00:43:06+03:00 ((2457879j,78186s,649279000n),+10800s,2299161j)>
+CallableDateTime[]
+# => #<DateTime: 2017-05-06T00:43:07+03:00 ((2457879j,78187s,635494000n),+10800s,2299161j)>
+```
+
+`Dry::Types::Undefined` can be passed explicitly as a missing value:
+
+```ruby
+PostStatus = Types::String.default('draft')
+
+PostStatus[Dry::Types::Undefined] # "draft"
+```
+
+It also receives the type constructor as an argument:
+
+```ruby
+CallableDateTime = Types::DateTime.constructor(&:to_datetime).default { |type| type[Time.now] }
+
+CallableDateTime[Time.now]
+# => #<DateTime: 2017-05-06T01:13:06+03:00 ((2457879j,79986s,63464000n),+10800s,2299161j)>
+CallableDateTime[Date.today]
+# => #<DateTime: 2017-05-06T00:00:00+00:00 ((2457880j,0s,0n),+0s,2299161j)>
+CallableDateTime[]
+# => #<DateTime: 2017-05-06T01:13:06+03:00 ((2457879j,79986s,63503000n),+10800s,2299161j)>
+```
+
+**Be careful:** types will return the **same instance** of the default value every time. This may cause problems if you mutate the returned value after receiving it:
+
+```ruby
+default_0 = PostStatus.()
+# => "draft"
+default_1 = PostStatus.()
+# => "draft"
+
+# Both variables point to the same string:
+default_0.object_id == default_1.object_id
+# => true
+
+# Mutating the string will change the default value of type:
+default_0 << '_mutated'
+PostStatus.(nil)
+# => "draft_mutated" # not "draft"
+```
+
+You can guard against these kind of errors by calling `freeze` when setting the default:
+
+```ruby
+PostStatus = Types::Params::String.default('draft'.freeze)
+default = PostStatus.()
+default << 'attempt to mutate default'
+# => RuntimeError: can't modify frozen string
+
+# If you really want to mutate it, call `dup` on it first:
+default = default.dup
+default << "this time it'll work"
+```
+
+**Warning on using with constrained types**: If the value passed to the `.default` block does not match the type constraints, this will not throw an exception, because it is not passed to the constructor and will be used as is.
+
+```ruby
+CallableDateTime = Types::DateTime.constructor(&:to_datetime).default { Time.now }
+
+CallableDateTime[Time.now]
+# => #<DateTime: 2017-05-06T00:50:09+03:00 ((2457879j,78609s,839588000n),+10800s,2299161j)>
+CallableDateTime[Date.today]
+# => #<DateTime: 2017-05-06T00:00:00+00:00 ((2457880j,0s,0n),+0s,2299161j)>
+CallableDateTime[]
+# => 2017-05-06 00:50:15 +0300
+```