dry-types 1.1.0 → 1.2.0

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

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)