added documentation for intersection types

docsite/source/combining-types.html.md

@@ -0,0 +1,12 @@
+---
+title: Combining Types
+layout: gem-single
+name: dry-types
+sections:
+  - intersection
+  - sum
+order: 11
+---
+
+Types can be combined to create new types, using [intersection types](docs::combining-types/intersection)
+to further restrict values, and [sum types](docs::combining-types/sum) to allow more acceptable values.

docsite/source/sum.html.md → docsite/source/combining-types/sum.html.md

@@ -2,7 +2,6 @@
 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.

docsite/source/intersection.html.md

@@ -0,0 +1,23 @@
+---
+title: Intersection
+layout: gem-single
+name: dry-types
+order: 8
+---
+
+Intersection types are specified using the `&` operator. It combines two
+compatible types into a single one with properties from each.
+
+One example is a `Hash` that allows any keys, but requires one of them to be named `id`:
+
+```ruby
+Id = Types::Hash.schema(id: Types::Integer)
+HashWithId = Id & Types::Hash
+
+Id[{id: 1}]                             # => {:id=>1}
+Id[{id: 1, message: 'foo'}]             # => {:id=>1}
+Id[{message: 'foo'}]                    # => Dry::Types::MissingKeyError: :id is missing in Hash input
+
+HashWithId[{ message: 'hello' }]        # => Dry::Types::MissingKeyError: :id is missing in Hash input
+HashWithId[{ id: 1, message: 'hello' }] # => {:id=>1, :message=>"hello"}
+```