Add docsite for version 1.0
This commit is contained in:
Piotr Solnica
parent
9102c01bdc
commit
1d4fa6a18b
|
|
@ -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"]
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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">
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
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
|
||||
|
||||
The [dry-monads gem](/gems/dry-monads/) provides another 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"
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in New Issue