dry-types 1.2.2 → 1.3.0

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

@@ -1,169 +0,0 @@
----
-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

@@ -1,156 +0,0 @@
----
-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
-  - extensions
----
-
-`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](docs::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](docs::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](docs::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](docs::constraints)
-* Support for [optional values](docs::optional-values)
-* Support for [default values](docs::default-values)
-* Support for [sum types](docs::sum)
-* Support for [enums](docs::enum)
-* Support for [hash type with type schemas](docs::hash-schemas)
-* Support for [array type with members](docs::array-with-member)
-* Support for arbitrary meta information
-* Support for typed struct objects via [dry-struct](/gems/dry-struct)
-* Types are [categorized](docs::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)

data/docsite/source/map.html.md

@@ -1,17 +0,0 @@
----
-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)
-```

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

@@ -1,35 +0,0 @@
----
-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
-
-See [Maybe](docs::extensions/maybe) extension for another approach to handling optional values by returning a [_Monad_](/gems/dry-monads/) object.

data/docsite/source/sum.html.md

@@ -1,21 +0,0 @@
----
-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
-```