plumb 0.0.3 → 0.0.5

data/README.md

@@ -10,13 +10,19 @@ If you're after raw performance and versatility I strongly recommend you use the
 
 For a description of the core architecture you can read [this article](https://ismaelcelis.com/posts/composable-pipelines-in-ruby/).
 
+Some use cases in the [examples directory](https://github.com/ismasan/plumb/tree/main/examples)
+
 ## 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 +45,8 @@ 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.
@@ -47,12 +55,12 @@ Use `#[]` to make your types match a class.
 module Types
   include Plumb::Types
   
-  String = Types::Any[::String]
-  Integer = Types::Any[::Integer]
+  String = Any[::String]
+  Integer = Any[::Integer]
 end
 
 Types::String.parse("hello") # => "hello"
-Types::String.parse(10) # raises "Must be a String" (Plumb::TypeError)
+Types::String.parse(10) # raises "Must be a String" (Plumb::ParseError)
 ```
 
 Plumb ships with basic types already defined, such as `Types::String` and `Types::Integer`. See the full list below.
@@ -69,7 +77,7 @@ 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)
+AdultAge.parse(17) # raises "Must be within 18.."" (Plumb::ParseError)
 
 # Or literal values
 Twenty = Types::Integer[20]
@@ -107,7 +115,7 @@ result.errors # 'must be an Integer'
 
 ```ruby
 Types::Integer.parse(10) # 10
-Types::Integer.parse('10') # raises Plumb::TypeError
+Types::Integer.parse('10') # raises Plumb::ParseError
 ```
 
 
@@ -127,13 +135,13 @@ joe = User.parse({ name: 'Joe', email: 'joe@email.com', age: 20}) # returns vali
 Users.parse([joe]) # returns valid array of user hashes
 ```
 
-More about [Types::Array](#typeshash) and [Types::Array](#typesarray). There's also tuples and hash maps, and it's possible to create your own composite types.
+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
+### 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.
+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")
+#### Composing types with `#>>` ("And")
 
 ```ruby
 Email = Types::String[/@/]
@@ -143,13 +151,19 @@ Greeting = Email >> ->(result) { result.valid("Your email is #{result.value}") }
 Greeting.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
 ```
 
-### Disjunction with `#|` ("Or")
+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
+StringOrInt.parse({}) # raises Plumb::ParseError
 ```
 
 Custom default value logic for non-emails
@@ -160,9 +174,13 @@ EmailOrDefault.parse('joe@bloggs.com') # "Your email is joe@bloggs.com"
 EmailOrDefault.parse('nope') # "no email"
 ```
 
-## Composing with `#>>` and `#|`
+#### Composing with `#>>` and `#|`
 
-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.
+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'
@@ -170,12 +188,22 @@ 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
 
@@ -184,9 +212,9 @@ 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](/ismasan/plumb/tree/main/examples)
+You can see more use cases in [the examples directory](https://github.com/ismasan/plumb/tree/main/examples)
 
-## Built-in types
+### Built-in types
 
 * `Types::Value`
 * `Types::Array`
@@ -196,7 +224,6 @@ You can see more use cases in [the examples directory](/ismasan/plumb/tree/main/
 * `Types::Interface`
 * `Types::False`
 * `Types::Tuple`
-* `Types::Split`
 * `Types::Any`
 * `Types::Static`
 * `Types::Undefined`
@@ -205,6 +232,9 @@ You can see more use cases in [the examples directory](/ismasan/plumb/tree/main/
 * `Types::Numeric`
 * `Types::String`
 * `Types::Hash`
+* `Types::UUID::V4`
+* `Types::Email`
+* `Types::Date`
 * `Types::Lax::Integer`
 * `Types::Lax::String`
 * `Types::Lax::Symbol`
@@ -212,14 +242,15 @@ You can see more use cases in [the examples directory](/ismasan/plumb/tree/main/
 * `Types::Forms::Nil`
 * `Types::Forms::True`
 * `Types::Forms::False`
+* `Types::Forms::Date`
 
-
+TODO: datetime, others.
 
 ### Policies
 
-Policies are methods that encapsulate common compositions. Plumb ships with some, listed below, and you can also define your own.
+Policies are helpers that encapsulate common compositions. Plumb ships with some handy ones, listed below, and you can also define your own.
 
-### `#present`
+#### `#present`
 
 Checks that the value is not blank (`""` if string, `[]` if array, `{}` if Hash, or `nil`)
 
@@ -228,7 +259,7 @@ Types::String.present.resolve('') # Failure with errors
 Types::Array[Types::String].resolve([]) # Failure with errors
 ```
 
-### `#nullable`
+#### `#nullable`
 
 Allow `nil` values.
 
@@ -236,7 +267,7 @@ Allow `nil` values.
 nullable_str = Types::String.nullable
 nullable_srt.parse(nil) # nil
 nullable_str.parse('hello') # 'hello'
-nullable_str.parse(10) # TypeError
+nullable_str.parse(10) # ParseError
 ```
 
 Note that this just encapsulates the following composition:
@@ -245,7 +276,7 @@ Note that this just encapsulates the following composition:
 nullable_str = Types::String | Types::Nil
 ```
 
-### `#not`
+#### `#not`
 
 Negates a type. 
 ```ruby
@@ -255,7 +286,7 @@ NotEmail.parse('hello') # "hello"
 NotEmail.parse('hello@server.com') # error
 ```
 
-### `#options`
+#### `#options`
 
 Sets allowed options for value.
 
@@ -273,7 +304,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.
 
@@ -285,7 +316,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.
 
@@ -311,7 +342,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.
 
@@ -322,7 +353,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).
 
@@ -356,7 +387,7 @@ Same if you want to apply a default to several cases.
 str = Types::String | ((Types::Nil | Types::Undefined) >> Types::Static['nope'.freeze])
 ```
 
-### `#build`
+#### `#build`
 
 Build a custom object or class.
 
@@ -389,7 +420,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
 
@@ -399,9 +430,7 @@ type.parse('Role: Manager') # 'Role: Manager'
 type.parse('Manager') # fails
 ```
 
-
-
-### `#value` 
+####  `#value` 
 
 Constrain a type to a specific value. Compares with `#==`
 
@@ -418,19 +447,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'
 ```
@@ -497,7 +528,52 @@ CSVLine = Types::String.split(/\s*;\s*/)
 CSVLine.parse('a;b;c') # => ['a', 'b', 'c']
 ```
 
+#### `:rescue`
 
+Wraps a step's execution, rescues a specific exception and returns an invalid result.
+
+Useful for turning a 3rd party library's exception into an invalid result that plays well with Plumb's type compositions.
+
+Example: this is how `Types::Forms::Date` uses the `:rescue` policy to parse strings with `Date.parse` and turn `Date::Error` exceptions into Plumb errors.
+
+```ruby
+# Accept a string that can be parsed into a Date
+# via Date.parse
+# If Date.parse raises a Date::Error, return a Result::Invalid with
+# the exception's message as error message.
+type = Types::String
+	.build(::Date, :parse)
+	.policy(:rescue, ::Date::Error)
+
+type.resolve('2024-02-02') # => Result::Valid with Date object
+type.resolve('2024-') # => Result::Invalid with error message
+```
+
+### `Types::Interface`
+
+Use this for objects that must respond to one or more methods.
+
+```ruby
+Iterable = Types::Interface[:each, :map]
+Iterable.parse([1,2,3]) # => [1,2,3]
+Iterable.parse(10) # => raises error
+```
+
+This can be useful combined with `case` statements, too:
+
+```ruby
+value = [1,2,3]
+case value
+when Iterable
+  # do something with array
+when Stringable
+  # do something with string
+when Readable
+  # do something with IO or similar
+end
+```
+
+TODO: make this a bit more advanced. Check for method arity.
 
 ### `Types::Hash`
 
@@ -614,11 +690,9 @@ intersection = User & Employee # Hash[:name]
 
 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,
@@ -664,7 +738,7 @@ 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' }
 ```
@@ -729,7 +803,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
 
@@ -851,15 +925,363 @@ 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.
+
+#### `[]` Syntax
+
+The `[]` syntax is a short-hand for struct definition.
+Like `Plumb::Types::Hash`, suffixing a key with `?` makes it optional.
+
+```ruby
+Person = Types::Data[name: String, age?: Integer]
+person = Person.new(name: 'Jane')
+```
+
+This syntax creates subclasses too.
+
+```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
+person = Person.new(name: 'Joe')
+person.name # 'Joe'
+person.valid? # false
+person.errors[:age] # 'must be an integer'
+```
+
+Data structs can also be defined from `Types::Hash` instances.
+
+```ruby
+PersonHash = Types::Hash[name: String, age?: Integer]
+PersonStruct = Types::Data[PersonHash]
+```
+
+#### `#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
+
+This syntax allows defining struct classes with typed attributes, including nested structs.
+
+```ruby
+class Person < Types::Data
+  attribute :name, Types::String.present
+  attribute :age, Types::Integer
+end
+```
+
+It supports nested attributes:
+
+```ruby
+class Person < Types::Data
+  attribute :friend do
+    attribute :name, String
+  end
+end
+
+person = Person.new(friend: { name: 'John' })
+person.friend_count # 1
+```
+
+Or arrays of nested attributes:
+
+```ruby
+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
+
+person = Person.new(friends: [{ name: 'John' }])
+```
+
+Or use struct classes defined separately:
+
+```ruby
+class Company < Types::Data
+  attribute :name, String
+end
+
+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::Pipeline
 
-TODO
+`Plumb::Pipeline` offers a sequential, step-by-step syntax for composing processing steps, as well as a simple middleware API to wrap steps for metrics, logging, debugging, caching and more. See the [command objects](https://github.com/ismasan/plumb/blob/main/examples/command_objects.rb) example for a worked use case.
+
+#### `#pipeline` helper
 
-### Plumb::Struct
+All plumb steps have a `#pipeline` helper.
+
+```ruby
+User = Types::Data[name: String, age: Integer]
+
+CreateUser = User.pipeline do |pl|
+  # Add steps as #call(Result) => Result interfaces
+  pl.step ValidateUser.new
+  
+  # Or as procs
+  pl.step do |result|
+    Logger.info "We have a valid user #{result.value}"
+    result
+  end
+  
+  # Or as other Plumb steps
+  pl.step User.transform(User) { |user| user.with(name: user.name.upcase) }
+  
+  pl.step do |result|
+    DB.create(result.value)
+  end
+end
+
+# User normally as any other Plumb step
+result = CreateUser.resolve(name: 'Joe', age: 40)
+# result.valid?
+# result.errors
+# result.value => User
+```
+
+Pipelines are Plumb steps, so they can be composed further.
+
+```ruby
+IsJoe = User.check('must be named joe') { |user| 
+  result.value.name == 'Joe' 
+}
+
+CreateIfJoe = IsJoe >> CreateUser
+```
+
+##### `#around`
+
+Use `#around` in a pipeline definition to add a middleware step that wraps all other steps registered.
+
+```ruby
+# The #around interface is #call(Step, Result::Valid) => Result::Valid | Result::Invalid
+StepLogger = proc do |step, result|
+  Logger.info "Processing step #{step}"
+  step.call(result)
+end
+
+CreateUser = User.pipeline do |pl|
+  # Around middleware will wrap all other steps registered below
+  pl.around StepLogger
+  
+  pl.step ValidateUser.new
+  pl.step ...etc
+end
+```
+
+Note that order matters: an _around_ step will only wrap steps registered _after it_.
+
+```ruby
+# This step will not be wrapper by StepLogger
+pl.step Step1
+
+pl.around StepLogger
+# This step WILL be wrapped
+pl.step Step2
+```
+
+Like regular steps, `around` middleware can be a class, an instance, a proc, or anything that implements the middleware interface.
+
+```ruby
+# As class instance
+#   pl.around StepLogger.new(:warn)
+class StepLogger
+  def initialize(level = :info)
+    @level = level
+  end
+  
+  def call(step, result)
+    Logger.send(@level) "Processing step #{step}"
+    step.call(result)
+  end
+end
+
+# As proc
+pl.around do |step, result|
+  Logger.info "Processing step #{step}"
+  step.call(result)
+end
+```
+
+#### As stand-alone `Plumb::Pipeline` class
+
+`Plumb::Pipeline` can also be used on its own, sub-classed, and it can take class-level `around` middleware.
+
+```ruby
+class LoggedPipeline < Plumb::Pipeline
+  # class-level midleware will be inherited by sub-classes
+  around StepLogged
+end
+
+# Subclass inherits class-level middleware stack,
+# and it can also add its own class or instance-level middleware
+class ChildPipeline < LoggedPipeline
+  # class-level middleware
+  around Telemetry.new
+end
+
+# Instantiate and add instance-level middleware
+pipe = ChildPipeline.new do |pl|
+  pl.around NotifyErrors
+  pl.step Step1
+  pl.step Step2
+end
+```
+
+Sub-classing `Plumb::Pipeline` can be useful to add helpers or domain-specific functionality
+
+```ruby
+class DebuggablePipeline < LoggedPipeline
+  # Use #debug! for inserting a debugger between steps
+  def debug!
+    step do |result|
+      debugger
+      result
+    end
+  end
+end
+
+pipe = DebuggablePipeline.new do |pl|
+  pl.step Step1
+  pl.debug!
+  pl.step Step2
+end
+```
+
+#### Pipelines all the way down :turtle:
+
+Pipelines are full Plumb steps, so they can themselves be used as steps.
+
+```ruby
+Pipe1 = DebuggablePipeline.new do |pl|
+  pl.step Step1
+  pl.step Step2
+end
+
+Pipe2 = DebuggablePipeline.new do |pl|
+  pl.step Pipe1 # <= A pipeline instance as step
+  pl.step Step3
+end
+```
+
+### Plumb::Schema
 
 TODO
 
@@ -898,13 +1320,46 @@ LinkedList = Types::Hash[
 
 ### Custom types
 
-Compose procs or lambdas directly
+Every Plumb type exposes the following one-method interface:
+
+```
+#call(Result::Valid) => Result::Valid | Result::Invalid
+```
+
+As long as an object implements this interface, it can be composed into Plumb workflows.
+
+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
@@ -912,6 +1367,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
@@ -920,6 +1378,55 @@ end
 MyType = Types::String >> Greeting.new('Hola')
 ```
 
+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.
@@ -946,8 +1453,6 @@ The `#policy` helper supports applying multiply policies.
 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.
@@ -963,9 +1468,21 @@ 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 only applies for types that return `Integer` values.
+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|
@@ -975,7 +1492,7 @@ end
 Doubled = Types::Integer.multiply_by(2)
 Doubled.parse(2) # 4
 
-# Tryin to apply this policy to a non Integer will raise an exception
+# Trying to apply this policy to a non Integer will raise an exception
 DoubledString = Types::String.multiply_by(2) # raises error
 ```
 
@@ -997,7 +1514,7 @@ DoubledMoney = Types::Any[Money].multiply_by(2)
 
 #### Self-contained policy modules
 
-You can register a module, class or module 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.
+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
@@ -1016,6 +1533,21 @@ 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,
@@ -1035,7 +1567,7 @@ json_schema = Plumb::JSONSchemaVisitor.call(User)
 }
 ```
 
-The built-in JSON Schema generator handles most standard types and compositions. You can add or override handles on a per-type basis with:
+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|
@@ -1047,11 +1579,31 @@ type = Types::Decimal.not
 schema = Plumb::JSONSchemaVisitor.visit(type) # { 'not' => { 'type' => 'number' } }
 ```
 
-#### JSON Schema handlers for custom policies
+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. See `Plumb::JSONSchemaVisitor`.
 
+## TODO:
 
+- [ ] benchmarks and performace. Compare with `Parametric`, `ActiveModel::Attributes`, `ActionController::StrongParameters`
+- [ ] flesh out `Plumb::Schema`
+- [x] `Plumb::Struct`
+- [x] flesh out and document `Plumb::Pipeline`
+- [ ] document custom visitors
+- [ ] Improve errors, support I18n ?
 
 ## Development