From 490b0b4e72ecb60418eb91a01c85cbab2474f7b3 Mon Sep 17 00:00:00 2001
From: Jon Roberts <jon@emptyflask.net>
Date: Thu, 25 Jan 2024 11:19:23 -0600
Subject: [PATCH] added documentation for intersection types

---
 docsite/source/combining-types.html.md        | 12 ++++++++++
 .../source/{ => combining-types}/sum.html.md  |  1 -
 docsite/source/intersection.html.md           | 23 +++++++++++++++++++
 3 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 docsite/source/combining-types.html.md
 rename docsite/source/{ => combining-types}/sum.html.md (98%)
 create mode 100644 docsite/source/intersection.html.md

diff --git a/docsite/source/combining-types.html.md b/docsite/source/combining-types.html.md
new file mode 100644
index 00000000..3fcf1092
--- /dev/null
+++ b/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.
diff --git a/docsite/source/sum.html.md b/docsite/source/combining-types/sum.html.md
similarity index 98%
rename from docsite/source/sum.html.md
rename to docsite/source/combining-types/sum.html.md
index fe2f4661..4db36f57 100644
--- a/docsite/source/sum.html.md
+++ b/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.
diff --git a/docsite/source/intersection.html.md b/docsite/source/intersection.html.md
new file mode 100644
index 00000000..048c23ad
--- /dev/null
+++ b/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"}
+```