dry-types 1.0.0 → 1.2.1

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/extensions.html.md

@@ -0,0 +1,15 @@
+---
+title: Extensions
+layout: gem-single
+name: dry-types
+sections:
+  - maybe
+  - monads
+---
+
+`dry-types` can be extended with extension. Those extensions are loaded with `Dry::Types.load_extensions`.
+
+Available extensions:
+
+- [Maybe](docs::extensions/maybe)
+- [Monads](docs::extensions/monads)

data/docsite/source/extensions/maybe.html.md

@@ -0,0 +1,57 @@
+---
+title: Maybe
+layout: gem-single
+name: dry-types
+---
+
+The [dry-monads gem](/gems/dry-monads/) provides approach to handling optional values by returning a [_Monad_](/gems/dry-monads/) object. This allows you to pass your type to a `Maybe(x)` block that only executes if `x` returns `Some` or `None`.
+
+> NOTE: Requires the [dry-monads gem](/gems/dry-monads/) to be loaded.
+1. Load the `:maybe` extension in your application.
+
+```ruby
+require 'dry-types'
+
+Dry::Types.load_extensions(:maybe)
+module Types
+  include Dry.Types()
+end
+```
+
+2. Append `.maybe` to a _Type_ to return a _Monad_ object  
+
+```ruby
+x = Types::Maybe::Strict::Integer[nil]
+Maybe(x) { puts(x) }
+x = Types::Maybe::Coercible::String[nil]
+Maybe(x) { puts(x) }
+x = Types::Maybe::Strict::Integer[123]
+Maybe(x) { puts(x) }
+x = Types::Maybe::Strict::String[123]
+Maybe(x) { puts(x) }
+```
+
+```ruby
+Types::Maybe::Strict::Integer[nil] # None
+Types::Maybe::Strict::Integer[123] # Some(123)
+Types::Maybe::Coercible::Float[nil] # None
+Types::Maybe::Coercible::Float['12.3'] # Some(12.3)
+# 'Maybe' types can also accessed by calling '.maybe' on a regular type:
+Types::Strict::Integer.maybe # equivalent to Types::Maybe::Strict::Integer
+```
+
+You can define your own optional types:
+
+``` ruby
+maybe_string = Types::Strict::String.maybe
+maybe_string[nil]
+# => None
+maybe_string[nil].fmap(&:upcase)
+# => None
+maybe_string['something']
+# => Some('something')
+maybe_string['something'].fmap(&:upcase)
+# => Some('SOMETHING')
+maybe_string['something'].fmap(&:upcase).value_or('NOTHING')
+# => "SOMETHING"
+```

data/docsite/source/extensions/monads.html.md

@@ -0,0 +1,61 @@
+---
+title: Monads
+layout: gem-single
+name: dry-types
+---
+
+The monads extension makes `Dry::Types::Result` objects compatible with `dry-monads`.
+
+To enable the extension:
+
+```ruby
+require 'dry/types'
+Dry::Types.load_extensions(:monads)
+```
+
+After loading the extension, you can leverage monad API:
+
+```ruby
+Types = Dry.Types()
+
+result = Types::String.try('Jane')
+result.class #=> Dry::Types::Result::Success
+monad = result.to_monad
+monad.class #=> Dry::Monads::Result::Success
+monad.value!  # => 'Jane'
+result = Types::String.try(nil)
+result.class #=> Dry::Types::Result::Failure
+monad = result.to_monad
+monad.class #=> Dry::Monads::Result::Failure
+monad.failure  # => [#<Dry::Types::ConstraintError>, nil]
+Types::String.try(nil)
+  .to_monad
+  .fmap { |result| puts "passed: #{result.inspect}" }
+  .or   { |error, input| puts "input '#{input.inspect}' failed with error: #{error.to_s}" }
+```
+
+This can be useful when used with `dry-monads` and the [`do` notation](/gems/dry-monads/1.0/do-notation/):
+
+```ruby
+require 'dry/types'
+Types = Dry.Types()
+Dry::Types.load_extensions(:monads)
+
+class AddTen
+  include Dry::Monads[:result, :do]
+
+  def call(input)
+    integer = yield Types::Coercible::Integer.try(input)
+
+    Success(integer + 10)
+  end
+end
+
+add_ten = AddTen.new
+
+add_ten.call(10)
+# => Success(20)
+
+add_ten.call('integer')
+# => Failure([#<Dry::Types::CoercionError: invalid value for Integer(): "integer">, "integer"])
+```

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](docs::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
+```