dry-types 1.0.1 → 1.2.0

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
+```

data/docsite/source/enum.html.md

@@ -0,0 +1,69 @@
+---
+title: Enum
+layout: gem-single
+name: dry-types
+---
+
+In many cases you may want to define an enum. For example, in a blog application a post may have a finite list of statuses. Apart from accessing the current status value, it is useful to have all possible values accessible too. Furthermore, an enum can be a map from, e.g., strings to integers. This is useful for mapping externally-provided integer values to human-readable strings without explicit conversions, see examples.
+
+``` ruby
+require 'dry-types'
+require 'dry-struct'
+
+module Types
+  include Dry.Types()
+end
+
+class Post < Dry::Struct
+  Statuses = Types::String.enum('draft', 'published', 'archived')
+
+  attribute :title, Types::String
+  attribute :body, Types::String
+  attribute :status, Statuses
+end
+
+# enum values are frozen, let's be paranoid, doesn't hurt and have potential to
+# eliminate silly bugs
+Post::Statuses.values.frozen? # => true
+Post::Statuses.values.all?(&:frozen?) # => true
+
+Post::Statuses['draft'] # => "draft"
+
+# it'll raise if something silly was passed in
+Post::Statuses['something silly']
+# => Dry::Types::ConstraintError: "something silly" violates constraints
+
+# nil is considered as something silly too
+Post::Statuses[nil]
+# => Dry::Types::ConstraintError: nil violates constraints
+```
+
+Note that if you want to define an enum type with a default, you must call `.default` *before* calling `.enum`, not the other way around:
+
+```ruby
+# this is the correct usage:
+Dry::Types::String.default('red').enum('blue', 'green', 'red')
+
+# this will raise an error:
+Dry::Types::String.enum('blue', 'green', 'red').default('red')
+```
+
+### Mappings
+
+A classic example is mapping integers coming from somewhere (API/database/etc) to something more understandable:
+
+```ruby
+class Cell < Dry::Struct
+  attribute :state, Types::String.enum('locked' => 0, 'open' => 1)
+end
+
+
+Cell.new(state: 'locked')
+# => #<Cell state="locked">
+
+# Integers are accepted too
+Cell.new(state: 0)
+# => #<Cell state="locked">
+Cell.new(state: 1)
+# => #<Cell state="open">
+```

data/docsite/source/getting-started.html.md

@@ -0,0 +1,57 @@
+---
+title: Getting Started
+layout: gem-single
+name: dry-types
+---
+
+### Using `Dry::Types` in Your Application
+
+1. Make `Dry::Types` available to the application by creating a namespace that includes `Dry::Types`:
+
+    ```ruby
+    module Types
+     include Dry.Types()
+    end
+    ```
+   
+2. Reload the environment, & type `Types::Coercible::String` in the ruby console to confirm it worked:
+
+    ``` ruby
+    Types::Coercible::String
+    # => #<Dry::Types::Constructor type=#<Dry::Types::Definition primitive=String options={}>>
+    ```
+
+### Creating Your First Type
+
+1. Define a struct's types by passing the name & type to the `attribute` method:
+
+    ```ruby
+    class User < Dry::Struct
+      attribute :name, Types::String
+    end
+    ```
+
+2. Define [Custom Types](/gems/dry-types/1.0/custom-types) in the `Types` module, then pass the name & type to `attribute`:
+
+    ```ruby
+    module Types
+      include Dry.Types()
+    
+      Email = String.constrained(format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i)
+      Age = Integer.constrained(gt: 18)
+    end
+    class User < Dry::Struct
+      attribute :name, Types::String
+      attribute :email, Types::Email
+      attribute :age, Types::Age
+    end
+    ```
+
+3. Use a `Dry::Struct` as a type:
+
+    ```ruby
+    class Message < Dry::Struct
+      attribute :body, Types::String
+      attribute :to, User
+    end
+    ```

data/docsite/source/hash-schemas.html.md

@@ -0,0 +1,169 @@
+---
+title: Hash Schemas
+layout: gem-single
+name: dry-types
+---
+
+It is possible to define a type for a hash with a known set of keys and corresponding value types. Let's say you want to describe a hash containing the name and the age of a user:
+
+```ruby
+# using simple kernel coercions
+user_hash = Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer)
+
+user_hash[name: 'Jane', age: '21']
+# => { name: 'Jane', age: 21 }
+# :name left untouched and :age was coerced to Integer
+```
+
+If a value doesn't conform to the type, an error is raised:
+
+```ruby
+user_hash[name: :Jane, age: '21']
+# => Dry::Types::SchemaError: :Jane (Symbol) has invalid type
+#    for :name violates constraints (type?(String, :Jane) failed)
+```
+
+All keys are required by default:
+
+```ruby
+user_hash[name: 'Jane']
+# => Dry::Types::MissingKeyError: :age is missing in Hash input
+```
+
+Extra keys are omitted by default:
+
+```ruby
+user_hash[name: 'Jane', age: '21', city: 'London']
+# => { name: 'Jane', age: 21 }
+```
+
+### Default values
+
+Default types are **only** evaluated if the corresponding key is missing in the input:
+
+```ruby
+user_hash = Types::Hash.schema(
+  name: Types::String,
+  age: Types::Integer.default(18)
+)
+user_hash[name: 'Jane']
+# => { name: 'Jane', age: 18 }
+
+# nil violates the constraint
+user_hash[name: 'Jane', age: nil]
+# => Dry::Types::SchemaError: nil (NilClass) has invalid type
+#    for :age violates constraints (type?(Integer, nil) failed)
+```
+
+In order to evaluate default types on `nil`, wrap your type with a constructor and map `nil` to `Dry::Types::Undefined`:
+
+```ruby
+user_hash = Types::Hash.schema(
+  name: Types::String,
+  age: Types::Integer.
+         default(18).
+         constructor { |value|
+           value.nil? ? Dry::Types::Undefined : value
+         }
+)
+
+user_hash[name: 'Jane', age: nil]
+# => { name: 'Jane', age: 18 }
+```
+
+The process of converting types to constructors like that can be automated, see "Type transformations" below.
+
+### Optional keys
+
+By default, all keys are required to present in the input. You can mark a key as optional by adding `?` to its name:
+
+```ruby
+user_hash = Types::Hash.schema(name: Types::String, age?: Types::Integer)
+
+user_hash[name: 'Jane']
+# => { name: 'Jane' }
+```
+
+### Extra keys
+
+All keys not declared in the schema are silently ignored. This behavior can be changed by calling `.strict` on the schema:
+
+```ruby
+user_hash = Types::Hash.schema(name: Types::String).strict
+user_hash[name: 'Jane', age: 21]
+# => Dry::Types::UnknownKeysError: unexpected keys [:age] in Hash input
+```
+
+### Transforming input keys
+
+Keys are supposed to be symbols but you can attach a key tranformation to a schema, e.g. for converting strings into symbols:
+
+```ruby
+user_hash = Types::Hash.schema(name: Types::String).with_key_transform(&:to_sym)
+user_hash['name' => 'Jane']
+
+# => { name: 'Jane' }
+```
+
+### Inheritance
+
+Hash schemas can be inherited in a sense you can define a new schema based on an existing one. Declared keys will be merged, key and type transformations will be preserved. The `strict` option is also passed to the new schema if present.
+
+```ruby
+# Building an empty base schema
+StrictSymbolizingHash = Types::Hash.schema({}).strict.with_key_transform(&:to_sym)
+
+user_hash = StrictSymbolizingHash.schema(
+  name: Types::String
+)
+
+user_hash['name' => 'Jane']
+# => { name: 'Jane' }
+
+user_hash['name' => 'Jane', 'city' => 'London']
+# => Dry::Types::UnknownKeysError: unexpected keys [:city] in Hash input
+```
+
+### Transforming types
+
+A schema can transform types with a block. For example, the following code makes all keys optional:
+
+```ruby
+user_hash = Types::Hash.with_type_transform { |type| type.required(false) }.schema(
+  name: Types::String,
+  age: Types::Integer
+)
+
+user_hash[name: 'Jane']
+# => { name: 'Jane' }
+user_hash[{}]
+# => {}
+```
+
+Type transformations work perfectly with inheritance, you don't have to define same rules more than once:
+
+```ruby
+SymbolizeAndOptionalSchema = Types::Hash.
+  .schema({})
+  .with_key_transform(&:to_sym)
+  .with_type_transform { |type| type.required(false) }
+
+user_hash = SymbolizeAndOptionalSchema.schema(
+  name: Types::String,
+  age: Types::Integer
+)
+
+user_hash['name' => 'Jane']
+```
+
+You can check key name by calling `.name` on the type argument:
+
+```ruby
+Types::Hash.with_type_transform do |key|
+  if key.name.to_s.end_with?('_at')
+    key.constructor { |v| Time.iso8601(v) }
+  else
+    key
+  end
+end
+```