plumb 0.0.2 → 0.0.4

data/README.md

@@ -12,11 +12,15 @@ For a description of the core architecture you can read [this article](https://i
 
 ## Installation
 
-TODO
+Install in your environment with `gem install plumb`, or in your `Gemfile` with
+
+```ruby
+gem 'plumb'
+```
 
 ## Usage
 
-### Include base types
+### Include base types.
 
 Include base types in your own namespace:
 
@@ -39,6 +43,54 @@ result.valid? # false
 result.errors # ""
 ```
 
+Note that this is not mandatory. You can also work with the `Plumb::Types` module directly, ex. `Plumb::Types::String`
+
+### Specialize your types with `#[]`
+
+Use `#[]` to make your types match a class.
+
+```ruby
+module Types
+  include Plumb::Types
+  
+  String = Any[::String]
+  Integer = Any[::Integer]
+end
+
+Types::String.parse("hello") # => "hello"
+Types::String.parse(10) # raises "Must be a String" (Plumb::TypeError)
+```
+
+Plumb ships with basic types already defined, such as `Types::String` and `Types::Integer`. See the full list below.
+
+The `#[]` method is not just for classes. It works with anything that responds to `#===`
+
+```ruby
+# Match against a regex
+Email = Types::String[/@/] # ie Types::Any[String][/@/]
+
+Email.parse('hello') # fails
+Email.parse('hello@server.com') # 'hello@server.com'
+
+# Or a Range
+AdultAge = Types::Integer[18..]
+AdultAge.parse(20) # 20
+AdultAge.parse(17) # raises "Must be within 18.."" (Plumb::TypeError)
+
+# Or literal values
+Twenty = Types::Integer[20]
+Twenty.parse(20) # 20
+Twenty.parse(21) # type error
+```
+
+It can be combined with other methods. For example to cast strings as integers, but only if they _look_ like integers.
+
+```ruby
+StringToInt = Types::String[/^\d+$/].transform(::Integer, &:to_i)
+
+StringToInt.parse('100') # => 100
+StringToInt.parse('100lol') # fails
+```
 
 ### `#resolve(value) => Result`
 
@@ -55,8 +107,6 @@ result.value # '10'
 result.errors # 'must be an Integer'
 ```
 
-
-
 ### `#parse(value) => value`
 
 `#parse` takes an input value and returns the parsed/coerced value if successful. or it raises an exception if failed.
@@ -68,7 +118,101 @@ Types::Integer.parse('10') # raises Plumb::TypeError
 
 
 
-## Built-in types
+### Composite types
+
+Some built-in types such as `Types::Array` and `Types::Hash` allow defininig array or hash data structures composed of other types.
+
+```ruby
+# A user hash
+User = Types::Hash[name: Types::String, email: Email, age: AdultAge]
+
+# An array of User hashes
+Users = Types::Array[User]
+
+joe = User.parse({ name: 'Joe', email: 'joe@email.com', age: 20}) # returns valid hash
+Users.parse([joe]) # returns valid array of user hashes
+```
+
+More about [Types::Array](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps) and [data structs](#typesdata), and it's possible to create your own composite types.
+
+### Type composition
+
+At the core, Plumb types are little [Railway-oriented pipelines](https://ismaelcelis.com/posts/composable-pipelines-in-ruby/) that can be composed together with _AND_, _OR_ and _NOT_ semantics. Everything else builds on top of these two ideas.
+
+#### Composing types with `#>>` ("And")
+
+```ruby
+Email = Types::String[/@/]
+# You can compose procs and lambdas, or other types.
+Greeting = Email >> ->(result) { result.valid("Your email is #{result.value}") }
+
+Greeting.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
+```
+
+Similar to Ruby's built-in [function composition](https://thoughtbot.com/blog/proc-composition-in-ruby), `#>>` pipes the output of a "type" to the input of the next type. However, if a type returns an "invalid" result, the chain is halted there and subsequent steps are never run. 
+
+In other words, `A >> B` means "if A succeeds, pass its result to B. Otherwise return A's failed result."
+
+#### Disjunction with `#|` ("Or")
+
+`A | B` means "if A returns a valid result, return that. Otherwise try B with the original input."
+
+```ruby
+StringOrInt = Types::String | Types::Integer
+StringOrInt.parse('hello') # "hello"
+StringOrInt.parse(10) # 10
+StringOrInt.parse({}) # raises Plumb::TypeError
+```
+
+Custom default value logic for non-emails
+
+```ruby
+EmailOrDefault = Greeting | Types::Static['no email']
+EmailOrDefault.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
+EmailOrDefault.parse('nope') # "no email"
+```
+
+#### Composing with `#>>` and `#|`
+
+Combine `#>>` and `#|` to compose branching workflows, or types that accept and output several possible data types.
+
+`((A >> B) | C | D) >> E)`
+
+This more elaborate example defines a combination of types which, when composed together with `>>` and `|`, can coerce strings or integers into Money instances with currency. It also shows some of the built-in [policies](#policies) or helpers.
+
+```ruby
+require 'money'
+
+module Types
+  include Plumb::Types
+  
+  # Match any Money instance
+  Money = Any[::Money]
+  
+  # Transform Integers into Money instances
+  IntToMoney = Integer.transform(::Money) { |v| ::Money.new(v, 'USD') }
+  
+  # Transform integer-looking Strings into Integers
+  StringToInt = String.match(/^\d+$/).transform(::Integer, &:to_i)
+  
+  # Validate that a Money instance is USD
+  USD = Money.check { |amount| amount.currency.code == 'UDS' }
+  
+  # Exchange a non-USD Money instance into USD
+  ToUSD = Money.transform(::Money) { |amount| amount.exchange_to('USD') }
+  
+  # Compose a pipeline that accepts Strings, Integers or Money and returns USD money.
+  FlexibleUSD = (Money | ((Integer | StringToInt) >> IntToMoney)) >> (USD | ToUSD)
+end
+
+FlexibleUSD.parse('1000') # Money(USD 10.00)
+FlexibleUSD.parse(1000) # Money(USD 10.00)
+FlexibleUSD.parse(Money.new(1000, 'GBP')) # Money(USD 15.00)
+```
+
+You can see more use cases in [the examples directory](https://github.com/ismasan/plumb/tree/main/examples)
+
+### Built-in types
 
 * `Types::Value`
 * `Types::Array`
@@ -78,13 +222,10 @@ Types::Integer.parse('10') # raises Plumb::TypeError
 * `Types::Interface`
 * `Types::False`
 * `Types::Tuple`
-* `Types::Split`
-* `Types::Blank`
 * `Types::Any`
 * `Types::Static`
 * `Types::Undefined`
 * `Types::Nil`
-* `Types::Present`
 * `Types::Integer`
 * `Types::Numeric`
 * `Types::String`
@@ -97,9 +238,13 @@ Types::Integer.parse('10') # raises Plumb::TypeError
 * `Types::Forms::True`
 * `Types::Forms::False`
 
+TODO: date and datetime, UUIDs, Email, others.
 
+### Policies
 
-### `#present`
+Policies are helpers that encapsulate common compositions. Plumb ships with some handy ones, listed below, and you can also define your own.
+
+#### `#present`
 
 Checks that the value is not blank (`""` if string, `[]` if array, `{}` if Hash, or `nil`)
 
@@ -108,7 +253,7 @@ Types::String.present.resolve('') # Failure with errors
 Types::Array[Types::String].resolve([]) # Failure with errors
 ```
 
-### `#nullable`
+#### `#nullable`
 
 Allow `nil` values.
 
@@ -119,15 +264,13 @@ nullable_str.parse('hello') # 'hello'
 nullable_str.parse(10) # TypeError
 ```
 
-Note that this is syntax sugar for 
+Note that this just encapsulates the following composition:
 
 ```ruby
 nullable_str = Types::String | Types::Nil
 ```
 
-
-
-### `#not`
+#### `#not`
 
 Negates a type. 
 ```ruby
@@ -137,7 +280,7 @@ NotEmail.parse('hello') # "hello"
 NotEmail.parse('hello@server.com') # error
 ```
 
-### `#options`
+#### `#options`
 
 Sets allowed options for value.
 
@@ -155,9 +298,7 @@ type.resolve(['a', 'a', 'b']) # Valid
 type.resolve(['a', 'x', 'b']) # Failure
 ```
 
-
-
-### `#transform`
+#### `#transform`
 
 Transform value. Requires specifying the resulting type of the value after transformation.
 
@@ -169,7 +310,7 @@ StringToInt = Types::String.transform(Integer, &:to_i)
 StringToInteger.parse('10') # => 10
 ```
 
-### `#invoke`
+#### `#invoke`
 
 `#invoke` builds a Step that will invoke one or more methods on the value.
 
@@ -195,7 +336,7 @@ UpcaseToSym = Types::String.invoke(%i[downcase to_sym])
 UpcaseToSym.parse('FOO_BAR') # :foo_bar
 ```
 
-That that, as opposed to `#transform`, this modified does not register a type in `#metadata[:type]`, which can be valuable for introspection or documentation (ex. JSON Schema).
+Note, as opposed to `#transform`, this helper does not register a type in `#metadata[:type]`, which can be valuable for introspection or documentation (ex. JSON Schema).
 
 Also, there's no definition-time checks that the method names are actually supported by the input values.
 
@@ -206,7 +347,7 @@ type.parse([1, 2]) # raises NoMethodError because Array doesn't respond to #stri
 
 Use with caution.
 
-### `#default`
+#### `#default`
 
 Default value when no value given (ie. when key is missing in Hash payloads. See `Types::Hash` below).
 
@@ -240,46 +381,7 @@ Same if you want to apply a default to several cases.
 str = Types::String | ((Types::Nil | Types::Undefined) >> Types::Static['nope'.freeze])
 ```
 
-
-
-### `#match` and `#[]`
-
-Checks the value against a regular expression (or anything that responds to `#===`).
-
-```ruby
-email = Types::String.match(/@/)
-# Same as
-email = Types::String[/@/]
-email.parse('hello') # fails
-email.parse('hello@server.com') # 'hello@server.com'
-```
-
-It can be combined with other methods. For example to cast strings as integers, but only if they _look_ like integers.
-
-```ruby
-StringToInt = Types::String[/^\d+$/].transform(::Integer, &:to_i)
-
-StringToInt.parse('100') # => 100
-StringToInt.parse('100lol') # fails
-```
-
-It can be used with other `#===` interfaces.
-
-```ruby
-AgeBracket = Types::Integer[21..45]
-
-AgeBracket.parse(22) # 22
-AgeBracket.parse(20) # fails
-
-# With literal values
-Twenty = Types::Integer[20]
-Twenty.parse(20) # 20
-Twenty.parse(21) # type error
-```
-
-
-
-### `#build`
+#### `#build`
 
 Build a custom object or class.
 
@@ -312,9 +414,7 @@ Note that this case is identical to `#transform` with a block.
 StringToMoney = Types::String.transform(Money) { |value| Monetize.parse(value) }
 ```
 
-
-
-### `#check`
+#### `#check`
 
 Pass the value through an arbitrary validation
 
@@ -324,9 +424,7 @@ type.parse('Role: Manager') # 'Role: Manager'
 type.parse('Manager') # fails
 ```
 
-
-
-### `#value` 
+####  `#value` 
 
 Constrain a type to a specific value. Compares with `#==`
 
@@ -343,21 +441,21 @@ All scalar types support this:
 ten = Types::Integer.value(10)
 ```
 
-
-
-### `#meta` and `#metadata`
+#### `#metadata`
 
 Add metadata to a type
 
 ```ruby
-type = Types::String.meta(description: 'A long text')
+# A new type with metadata
+type = Types::String.metadata(description: 'A long text')
+# Read a type's metadata
 type.metadata[:description] # 'A long text'
 ```
 
 `#metadata` combines keys from type compositions.
 
 ```ruby
-type = Types::String.meta(description: 'A long text') >> Types::String.match(/@/).meta(note: 'An email address')
+type = Types::String.metadata(description: 'A long text') >> Types::String.match(/@/).metadata(note: 'An email address')
 type.metadata[:description] # 'A long text'
 type.metadata[:note] # 'An email address'
 ```
@@ -373,7 +471,60 @@ Types::String.transform(Integer, &:to_i).metadata[:type] # Integer
 
 TODO: document custom visitors.
 
-## `Types::Hash`
+### Other policies
+
+There's some other built-in "policies" that can be used via the `#policy` method. Helpers such as `#default` and `#present` are shortcuts for this and can also be used via `#policy(default: 'Hello')` or `#policy(:present)` See [custom policies](#custom-policies) for how to define your own policies.
+
+#### `:respond_to`
+
+Similar to `Types::Interface`, this is a quick way to assert that a value supports one or more methods.
+
+```ruby
+List = Types::Any.policy(respond_to: :each)
+# or
+List = Types::Any.policy(respond_to: [:each, :[], :size)
+```
+
+#### `:excluded_from`
+
+The opposite of `#options`, this policy validates that the value _is not_ included in a list.
+
+```ruby
+Name = Types::String.policy(excluded_from: ['Joe', 'Joan'])
+```
+
+#### `:size`
+
+Works for any value that responds to `#size` and validates that the value's size matches the argument.
+
+```ruby
+LimitedArray = Types::Array[String].policy(size: 10)
+LimitedString = Types::String.policy(size: 10)
+LimitedSet = Types::Any[Set].policy(size: 10)
+```
+
+The size is matched via `#===`, so ranges also work.
+
+```ruby
+Password = Types::String.policy(size: 10..20)
+```
+
+#### `:split` (strings only)
+
+Splits string values by a separator (default: `,`).
+
+```ruby
+CSVLine = Types::String.split
+CSVLine.parse('a,b,c') # => ['a', 'b', 'c']
+
+# Or, with custom separator
+CSVLine = Types::String.split(/\s*;\s*/)
+CSVLine.parse('a;b;c') # => ['a', 'b', 'c']
+```
+
+
+
+### `Types::Hash`
 
 ```ruby
 Employee = Types::Hash[
@@ -466,8 +617,6 @@ Types::Hash[
 ]
 ```
 
-
-
 #### Merging hash definitions
 
 Use `Types::Hash#+` to merge two definitions. Keys in the second hash override the first one's.
@@ -478,8 +627,6 @@ Employee = Types::Hash[name: Types::String, company: Types::String]
 StaffMember = User + Employee # Hash[:name, :age, :company]
 ```
 
-
-
 #### Hash intersections
 
 Use `Types::Hash#&` to produce a new Hash definition with keys present in both.
@@ -488,17 +635,13 @@ Use `Types::Hash#&` to produce a new Hash definition with keys present in both.
 intersection = User & Employee # Hash[:name]
 ```
 
-
-
 #### `Types::Hash#tagged_by`
 
 Use `#tagged_by` to resolve what definition to use based on the value of a common key.
 
-Key used as index must be a `Types::Static`
-
 ```ruby
-NameUpdatedEvent = Types::Hash[type: Types::Static['name_updated'], name: Types::String]
-AgeUpdatedEvent = Types::Hash[type: Types::Static['age_updated'], age: Types::Integer]
+NameUpdatedEvent = Types::Hash[type: 'name_updated', name: Types::String]
+AgeUpdatedEvent = Types::Hash[type: 'age_updated', age: Types::Integer]
 
 Events = Types::Hash.tagged_by(
   :type,
@@ -509,8 +652,6 @@ Events = Types::Hash.tagged_by(
 Events.parse(type: 'name_updated', name: 'Joe') # Uses NameUpdatedEvent definition
 ```
 
-
-
 #### `Types::Hash#inclusive`
 
 Use `#inclusive` to preserve input keys not defined in the hash schema.
@@ -546,13 +687,11 @@ InputHandler.parse(price: 100_000, name: 'iPhone 15', category: 'smartphones')
 The `#filtered` modifier returns a valid Hash with the subset of values that were valid, instead of failing the entire result if one or more values are invalid.
 
 ```ruby
-User = Types::Hash[name: String, age: Integer]
+User = Types::Hash[name: String, age: Integer].filtered
 User.parse(name: 'Joe', age: 40) # => { name: 'Joe', age: 40 }
 User.parse(name: 'Joe', age: 'nope') # => { name: 'Joe' }
 ```
 
-
-
 ### Hash maps
 
 You can also use Hash syntax to define a hash map with specific types for all keys and values:
@@ -613,7 +752,7 @@ emails = Types::Array[/@/]
 emails = Types::Array[Types::String[/@/]]
 ```
 
-Prefer the latter (`Types::Array[Types::String[/@/]]`), as that first validates that each element is a `String` before matching agains the regular expression.
+Prefer the latter (`Types::Array[Types::String[/@/]]`), as that first validates that each element is a `String` before matching against the regular expression.
 
 #### Concurrent arrays
 
@@ -735,68 +874,203 @@ Str.parse(data).each do |row|
 end
 ```
 
-### Plumb::Schema
+### Types::Data
 
-TODO
+`Types::Data` provides a superclass to define **inmutable** structs or value objects with typed / coercible attributes.
 
-### Plumb::Pipeline
+#### `[]` Syntax
 
-TODO
+The `[]` syntax is a short-hand for struct definition.
+Like `Plumb::Types::Hash`, suffixing a key with `?` makes it optional.
 
-### Plumb::Struct
+```ruby
+Person = Types::Data[name: String, age?: Integer]
+person = Person.new(name: 'Jane')
+```
 
-TODO
+This syntax creates subclasses too.
 
-## Composing types with `#>>` ("And")
+```ruby
+# Subclass Person with and redefine the :age type.
+Adult = Person[age?: Types::Integer[18..]]
+```
+
+These classes can be instantiated normally, and expose `#valid?` and `#error`
 
 ```ruby
-Email = Types::String.match(/@/)
-Greeting = Email >> ->(result) { result.valid("Your email is #{result.value}") }
+person = Person.new(name: 'Joe')
+person.name # 'Joe'
+person.valid? # false
+person.errors[:age] # 'must be an integer'
+```
 
-Greeting.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
+#### `#with`
+
+Note that these instances cannot be mutated (there's no attribute setters), but they can be copied with partial attributes with `#with`
+
+```ruby
+another_person = person.with(age: 20)
 ```
 
+#### `.attribute` syntax
 
-## Disjunction with `#|` ("Or")
+This syntax allows defining struct classes with typed attributes, including nested structs.
 
 ```ruby
-StringOrInt = Types::String | Types::Integer
-StringOrInt.parse('hello') # "hello"
-StringOrInt.parse(10) # 10
-StringOrInt.parse({}) # raises Plumb::TypeError
+class Person < Types::Data
+  attribute :name, Types::String.present
+  attribute :age, Types::Integer
+end
 ```
 
-Custom default value logic for non-emails
+It supports nested attributes:
 
 ```ruby
-EmailOrDefault = Greeting | Types::Static['no email']
-EmailOrDefault.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
-EmailOrDefault.parse('nope') # "no email"
+class Person < Types::Data
+  attribute :friend do
+    attribute :name, String
+  end
+end
+
+person = Person.new(friend: { name: 'John' })
+person.friend_count # 1
 ```
 
-## Composing with `#>>` and `#|`
+Or arrays of nested attributes:
 
 ```ruby
-require 'money'
+class Person < Types::Data
+  attribute :friends, Types::Array do
+    atrribute :name, String
+  end
+    
+  # Custom methods like any other class
+  def friend_count = friends.size
+end
 
-module Types
-  include Plumb::Types
-  
-  Money = Any[::Money]
-  IntToMoney = Integer.transform(::Money) { |v| ::Money.new(v, 'USD') }
-  StringToInt = String.match(/^\d+$/).transform(::Integer, &:to_i)
-  USD = Money.check { |amount| amount.currency.code == 'UDS' }
-  ToUSD = Money.transform(::Money) { |amount| amount.exchange_to('USD') }
-  
-  FlexibleUSD = (Money | ((Integer | StringToInt) >> IntToMoney)) >> (USD | ToUSD)
+person = Person.new(friends: [{ name: 'John' }])
+```
+
+Or use struct classes defined separately:
+
+```ruby
+class Company < Types::Data
+  attribute :name, String
 end
 
-FlexibleUSD.parse('1000') # Money(USD 10.00)
-FlexibleUSD.parse(1000) # Money(USD 10.00)
-FlexibleUSD.parse(Money.new(1000, 'GBP')) # Money(USD 15.00)
+class Person < Types::Data
+  # Single nested struct
+  attribute :company, Company
+
+  # Array of nested structs
+  attribute :companies, Types::Array[Company]
+end
+```
+
+Arrays and other types support composition and helpers. Ex. `#default`.
+
+```ruby
+attribute :companies, Types::Array[Company].default([].freeze)
+```
+
+Passing a named struct class AND a block will subclass the struct and extend it with new attributes:
+
+```ruby
+attribute :company, Company do
+  attribute :address, String
+end
+```
+
+The same works with arrays:
+
+```ruby
+attribute :companies, Types::Array[Company] do
+  attribute :address, String
+end
+```
+
+Note that this does NOT work with union'd or piped structs.
+
+```ruby
+attribute :company, Company | Person do
+```
+
+#### Optional Attributes
+Using `attribute?` allows for optional attributes. If the attribute is not present, these attribute values will be `nil`
+
+```ruby
+attribute? :company, Company
+```
+
+#### Inheritance
+Data structs can inherit from other structs. This is useful for defining a base struct with common attributes.
+
+```ruby
+class BasePerson < Types::Data
+  attribute :name, String
+end
+
+class Person < BasePerson
+  attribute :age, Integer
+end
+```
+
+#### Equality with `#==`
+
+`#==` is implemented to compare attributes, recursively.
+
+```ruby
+person1 = Person.new(name: 'Joe', age: 20)
+person2 = Person.new(name: 'Joe', age: 20)
+person1 == person2 # true
+```
+
+#### Struct composition
+
+`Types::Data` supports all the composition operators and helpers.
+
+Note however that, once you wrap a struct in a composition, you can't instantiate it with `.new` anymore (but you can still use `#parse` or `#resolve` like any other Plumb type).
+
+```ruby
+Person = Types::Data[name: String]
+Animal = Types::Data[species: String]
+# Compose with |
+Being = Person | Animal
+Being.parse(name: 'Joe') # <Person [valid] name: 'Joe'>
+
+# Compose with other types
+Beings = Types::Array[Person | Animal]
+
+# Default
+Payload = Types::Hash[
+  being: Being.default(Person.new(name: 'Joe Bloggs'))
+]
 ```
 
+#### Recursive struct definitions
+
+You can use `#defer`. See [recursive types](#recursive-types).
+
+```ruby
+Person = Types::Data[
+  name: String,
+  friend?: Types::Any.defer { Person }
+]
+
+person = Person.new(name: 'Joe', friend: { name: 'Joan'})
+person.friend.name # 'joan'
+person.friend.friend # nil
+```
+
+
+
+### Plumb::Schema
+
+TODO
+
+### Plumb::Pipeline
 
+TODO
 
 ### Recursive types
 
@@ -831,19 +1105,48 @@ LinkedList = Types::Hash[
 
 
 
-### Type-specific Rules
+### Custom types
 
-TODO
+Every Plumb type exposes the following one-method interface:
 
-### Custom types
+```
+#call(Result::Valid) => Result::Valid | Result::Invalid
+```
+
+As long as an object implements this interface, it can be composed into Plumb workflows.
 
-Compose procs or lambdas directly
+The `Result::Valid` class has helper methods `#valid(value) => Result::Valid` and `#invalid(errors:) => Result::Invalid` to facilitate returning valid or invalid values from your own steps.
+
+#### Compose procs or lambdas directly
+
+Piping any `#call` object onto Plumb types will wrap your object in a `Plumb::Step` with all methods necessary for further composition.
 
 ```ruby
 Greeting = Types::String >> ->(result) { result.valid("Hello #{result.value}") }
 ```
 
-or a custom class that responds to `#call(Result::Valid) => Result::Valid | Result::Invalid`
+#### Wrap a `#call` object in `Plumb::Step` explicitely
+
+You can also wrap a proc in `Plumb::Step` explicitly.
+
+```ruby
+Greeting = Plumb::Step.new do |result|
+  result.valid("Hello #{result.value}")
+end
+```
+
+Note that this example is not prefixed by `Types::String`, so it doesn't first validate that the input is indeed a string.
+
+However, this means that `Greeting` is a `Plumb::Step` which comes with all the Plumb methods and policies.
+
+```ruby
+# Greeting responds to #>>, #|, #default, #transform, etc etc
+LoudGreeting = Greeting.default('no greeting').invoke(:upcase)
+```
+
+#### A custom `#call` class
+
+Or write a custom class that responds to `#call(Result::Valid) => Result::Valid | Result::Invalid`
 
 ```ruby
 class Greeting
@@ -851,6 +1154,9 @@ class Greeting
     @gr = gr
   end
 
+  # The Plumb Step interface
+  # @param result [Plumb::Result::Valid]
+  # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
   def call(result)
     result.valid("#{gr} #{result.value}")
   end
@@ -859,11 +1165,176 @@ end
 MyType = Types::String >> Greeting.new('Hola')
 ```
 
-You can return `result.invalid(errors: "this is invalid")` to halt processing.
+This is useful when you want to parameterize your custom steps, for example by initialising them with arguments like the example above.
+
+#### Include `Plumb::Composable` to make instance of a class full "steps"
+
+The class above will be wrapped by `Plumb::Step` when piped into other steps, but it doesn't support Plumb methods on its own.
 
+Including `Plumb::Composable` makes it support all Plumb methods directly.
+
+```ruby
+class Greeting
+  # This module mixes in Plumb methods such as #>>, #|, #default, #[], 
+  # #transform, #policy, etc etc
+  include Plumb::Composable
+  
+  def initialize(gr = 'Hello')
+    @gr = gr
+  end
+  
+  # The Step interface
+  def call(result)
+    result.valid("#{gr} #{result.value}")
+  end
+  
+  # This is optional, but it allows you to control your object's #inspect
+  private def _inspect = "Greeting[#{@gr}]"
+end
+```
+
+Now you can use your class as a composition starting point directly.
+
+```ruby
+LoudGreeting = Greeting.new('Hola').default('no greeting').invoke(:upcase)
+```
+
+#### Extend a class with `Plumb::Composable` to make the class itself a composable step.
+
+```ruby
+class User
+  extend Composable
+  
+  def self.class(result)
+    # do something here. Perhaps returning a Result with an instance of this class
+    return result.valid(new)
+  end
+end
+```
+
+This is how [Plumb::Types::Data](#typesdata) is implemented.
+
+### Custom policies
+
+`Plumb.policy` can be used to encapsulate common type compositions, or compositions that can be configurable by parameters.
+
+This example defines a `:default_if_nil` policy that returns a default if the value is `nil`.
+
+```ruby
+Plumb.policy :default_if_nil do |type, default_value|
+  type | (Types::Nil >> Types::Static[default_value])
+end
+```
+
+It can be used for any of your own types.
+
+```ruby
+StringWithDefault = Types::String.policy(default_if_nil: 'nothing here')
+StringWithDefault.parse('hello') # 'hello'
+StringWithDefault.parse(nil) # 'nothing here'
+```
+
+The `#policy` helper supports applying multiply policies.
+
+```ruby
+Types::String.policy(default_if_nil: 'nothing here', size: (10..20))
+```
+
+#### Policies as helper methods
+
+Use the `helper: true` option to register the policy as a method you can call on types directly.
+
+```ruby
+Plumb.policy :default_if_nil, helper: true do |type, default_value|
+  type | (Types::Nil >> Types::Static[default_value])
+end
+
+# Now use #default_if_nil directly
+StringWithDefault = Types::String.default_if_nil('nothing here')
+```
+
+Many built-in helpers such as `#default` and `#options` are implemented as policies. This means that you can overwrite their default behaviour by defining a policy with the same name (use with caution!).
+
+This other example adds a boolean to type metadata.
+
+```ruby
+Plumb.policy :admin, helper: true do |type|
+  type.metadata(admin: true)
+end
+
+# Usage: annotate fields in a schema
+AccountName = Types::String.admin
+AccountName.metadata # => { type: String, admin: true }
+```
+
+#### Type-specific policies
+
+You can use the `for_type:` option to define policies that only apply to steps that output certain types. This example is only applicable for types that return `Integer` values.
+
+```ruby
+Plumb.policy :multiply_by, for_type: Integer, helper: true do |type, factor|
+  type.invoke(:*, factor)
+end
+
+Doubled = Types::Integer.multiply_by(2)
+Doubled.parse(2) # 4
+
+# Trying to apply this policy to a non Integer will raise an exception
+DoubledString = Types::String.multiply_by(2) # raises error
+```
+
+#### Interface-specific policies
+
+`for_type`also supports a Symbol for a method name, so that the policy can be applied to any types that support that method.
+
+This example allows the `multiply_by` policy to work with any type that can be multiplied (by supporting the `:*` method).
+
+```ruby
+Plumb.policy :multiply_by, for_type: :*, helper: true do |type, factor|
+  type.invoke(:*, factor)
+end
+
+# Now it works with anything that can be multiplied.
+DoubledNumeric = Types::Numeric.multiply_by(2)
+DoubledMoney = Types::Any[Money].multiply_by(2)
+```
+
+#### Self-contained policy modules
+
+You can register a module, class or object with a three-method interface as a policy. This is so that policies can have their own namespace if they need local constants or private methods. For example, this is how the `:split` policy for strings is defined.
+
+```ruby
+module SplitPolicy
+  DEFAULT_SEPARATOR = /\s*,\s*/
+
+  def self.call(type, separator = DEFAULT_SEPARATOR)
+    type.transform(Array) { |v| v.split(separator) }
+  end
+
+  def self.for_type = ::String
+  def self.helper = false
+end
+
+Plumb.policy :split, SplitPolicy
+```
 
 ### JSON Schema
 
+Plumb ships with a JSON schema visitor that compiles a type composition into a JSON Schema Hash. All Plumb types support a `#to_json_schema` method.
+
+```ruby
+Payload = Types::Hash[name: String]
+Payload.to_json_schema(root: true)
+# {
+#   "$schema"=>"https://json-schema.org/draft-08/schema#", 
+#   "type"=>"object", 
+#   "properties"=>{"name"=>{"type"=>"string"}}, 
+#   "required"=>["name"]
+# }
+```
+
+The visitor can be used directly, too.
+
 ```ruby
 User = Types::Hash[
   name: Types::String,
@@ -883,7 +1354,43 @@ json_schema = Plumb::JSONSchemaVisitor.call(User)
 }
 ```
 
+The built-in JSON Schema generator handles most standard types and compositions. You can add or override handlers on a per-type basis with:
+
+```ruby
+Plumb::JSONSchemaVisitor.on(:not) do |node, props|
+  props.merge('not' => visit(node.step))
+end
+
+# Example
+type = Types::Decimal.not
+schema = Plumb::JSONSchemaVisitor.visit(type) # { 'not' => { 'type' => 'number' } }
+```
+
+You can also register custom classes or types that are wrapped by Plumb steps.
+
+```ruby
+module Types
+  DateTime = Any[::DateTime]
+end
+
+Plumb::JSONSchemaVisitor.on(::DateTime) do |node, props|
+  props.merge('type' => 'string', 'format' => 'date-time')
+end
+
+Types::DateTime.to_json_schema
+# {"type"=>"string", "format"=>"date-time"}
+```
+
+
+
+## TODO:
 
+- [ ] benchmarks and performace. Compare with `Parametric`, `ActiveModel::Attributes`, `ActionController::StrongParameters`
+- [ ] flesh out `Plumb::Schema`
+- [x] `Plumb::Struct`
+- [ ] flesh out and document `Plumb::Pipeline`
+- [ ] document custom visitors
+- [ ] Improve errors, support I18n ?
 
 ## Development