foobara 0.0.37 → 0.0.39

data/README.md

@@ -1,13 +1,20 @@
+Foobara is a software framework with a focus on projects that have
+a complicated business domain. It accomplishes this by helping to
+build projects that are command-centric and discoverable, as well as some other features that aid in the mission.
+
+You can watch a video that gives a good overview of what Foobara is and its goals here:
+[Introduction to the Foobara software framework](https://youtu.be/SSOmQqjNSVY)
+
 <!-- TOC -->
-* [What is/Why Foobara?](#what-iswhy-foobara)
-  * [Commands](#commands)
+* [Overview of Features/Concepts/Goals](#overview-of-featuresconceptsgoals)
+  * [Command-centric](#command-centric)
   * [Discoverability](#discoverability)
   * [Implications of command-centric + discoverability](#implications-of-command-centric--discoverability)
   * [Other features for helping with Domain complexity](#other-features-for-helping-with-domain-complexity)
 * [Installation](#installation)
 * [Usage/Tutorial](#usagetutorial)
   * [Foobara 101](#foobara-101)
-    * [Commands](#commands-1)
+    * [Commands](#commands)
     * [Organizations and Domains](#organizations-and-domains)
     * [Types](#types)
     * [Models](#models)
@@ -15,6 +22,8 @@
     * [Command connectors](#command-connectors)
       * [Command-line connectors](#command-line-connectors)
       * [HTTP Command Connectors](#http-command-connectors)
+        * [Rack Connector](#rack-connector)
+        * [Rails Connector](#rails-connector)
       * [Async Command Connectors](#async-command-connectors)
       * [Scheduler Command Connectors](#scheduler-command-connectors)
   * [Intermediate Foobara](#intermediate-foobara)
@@ -26,20 +35,21 @@
       * [Runtime Errors](#runtime-errors)
   * [Advanced Foobara](#advanced-foobara)
     * [Domain Mappers](#domain-mappers)
+    * [Types](#types-1)
+      * [Builtin types](#builtin-types)
+      * [Custom types](#custom-types)
     * [Code Generators](#code-generators)
       * [Generating a new Foobara Ruby project](#generating-a-new-foobara-ruby-project)
       * [Generating a new Foobara Typescript/React project](#generating-a-new-foobara-typescriptreact-project)
-      * [Geerating commands, models, entities, types, domains, organizations, etc...](#geerating-commands-models-entities-types-domains-organizations-etc)
-    * [Custom types](#custom-types)
   * [Expert Foobara](#expert-foobara)
     * [Callbacks](#callbacks)
     * [Transactions in Commands](#transactions-in-commands)
     * [Transactions in tests/console](#transactions-in-testsconsole)
     * [Custom crud drivers](#custom-crud-drivers)
     * [Custom command connectors](#custom-command-connectors)
-    * [Value processors](#value-processors)
     * [Custom types from scratch](#custom-types-from-scratch)
     * [Namespaces](#namespaces)
+    * [Value processors](#value-processors)
 * [Additional learning materials/Documentation](#additional-learning-materialsdocumentation)
 * [Contributing](#contributing)
   * [Developing locally](#developing-locally)
@@ -47,13 +57,9 @@
 * [Licensing](#licensing)
 <!-- TOC -->
 
-# What is/Why Foobara?
+# Overview of Features/Concepts/Goals
 
-Foobara is a software framework meant to help with projects that have
-a complicated business domain. It accomplishes this by helping to
-build projects that are command-centric and discoverable, as well as some other features.
-
-## Commands
+## Command-centric
 
 * Foobara commands are meant to encapsulate high-level domain operations.
 * They serve as the public interface to Foobara systems/subsystems.
@@ -122,6 +128,9 @@ Let's explore various Foobara concepts with some code examples!
 
 ## Foobara 101
 
+NOTE: We will create various scripts for the first parts of these tutorials but normally we'd generate a project, which
+will be covered later in the tutorial.
+
 ### Commands
 
 Foobara commands are meant to encapsulate high-level domain operations and are meant
@@ -176,7 +185,7 @@ Let's play with it!
 
 We can run our Add command several ways. First, let's create an instance of it and call the #run method:
 
-```irb
+```
 $ ./add.rb
 > command = Add.new(operand1: 2, operand2: 5)
 ==> #<Add:0xad20 @raw_inputs={:operand1=>2, :operand2=>5}, @error_collectio...
@@ -193,7 +202,7 @@ we can also get the result with #result and errors with #errors and other helper
 
 We can also just run it with .run without creating an instance:
 
-```irb
+```
 > outcome = Add.run(operand1: 2, operand2: 5)
 ==> #<Foobara::Outcome:0x00007ffbcc641318...
 > outcome.success?
@@ -204,14 +213,14 @@ We can also just run it with .run without creating an instance:
 
 And we can use .run! if we want just the result or an exception raised:
 
-```irb
+```
 > Add.run!(operand1: 2, operand2: 5)
 ==> 7
 ```
 
 Let's cause some errors!
 
-```irb
+```
 > outcome = Add.run(operand1: "foo", operand2: 5)
 ==> #<Foobara::Outcome:0x00007ffbcc60aea8...
 > outcome.success?
@@ -222,7 +231,7 @@ At operand1: Cannot cast "foo" to an integer. Expected it to be a Integer, or be
 
 Here we used something that wasn't castable to an integer.
 
-```irb
+```
 > outcome = Add.run
 ==> #<Foobara::Outcome:0x00007ffbcb9d97b0...
 > outcome.success?
@@ -276,7 +285,7 @@ The typical way of putting commands and other Foobara concepts into a domain is
 
 We can play a bit with our new domain:
 
-```irb
+```
 > IntegerMath.foobara_command_classes
 ==> [IntegerMath::Add]
 > IntegerMath.foobara_lookup(:Add)
@@ -321,7 +330,7 @@ end
 
 And we can play with our Organization:
 
-```irb
+```
 > FoobaraExamples.foobara_domains
 ==> [FoobaraExamples::IntegerMath]
 ```
@@ -409,7 +418,7 @@ end
 
 Let's increment some ages!
 
-```irb
+```
 > barbara = Capybara.new(name: "Barbara", age: 200, nickname: "bar")
 ==> #<Capybara:0x00007f0ac121dbf8 @attributes={:name=>"Barbara", :age=>200, :nickname=>"bar"}, @mutable=true>
 > barbara.age
@@ -424,7 +433,7 @@ Here we incremented Barbara's age.
 
 Check this out though...
 
-```ruby
+```
 > basil = IncrementAge.run!(capybara: { name: "Basil", age: 300, nickname: "baz" })
 ==> #<Capybara:0x00007f0ac1295f40 @attributes={:name=>"Basil", :age=>301, :nickname=>"baz"}, @mutable=true>
 > basil.age
@@ -458,73 +467,7 @@ Here, we added an InMemory CRUD driver and set it as the default. This lets us w
 
 An entity is like a model except it has a primary key and can be written/read to/from a data store using a CRUD driver.
 
-In fact, `entity` inherits `model`. We could look at the hierarchy of Capybara with the following hack:
-
-```ruby
-def print_type_inheritance(type)
-  types = Enumerator.produce(type, &:base_type).take_while { |t| !t.nil? }
-  Foobara::Util.print_tree(types, to_parent: :base_type, to_name: :name)
-end
-
-capybara_type = Foobara.foobara_lookup(:Capybara)
-print_type_inheritance(capybara_type)
-```
-
-Which gives us:
-
-```irb
-
-* def print_type_inheritance(type)
-*   types = Enumerator.produce(type, &:base_type).take_while { |t| !t.nil? }
-*   Foobara::Util.print_tree(types, to_parent: :base_type, to_name: :name)
-> end
-==> :print_type_inheritance
-> capybara_type = Foobara.foobara_lookup(:Capybara)
-==> #<Type:Capybara:0x88b8 {:type=>:model, :name=>"Capybara", :model_class=>"Capybara", :model_base_class=>"Foobara::Model", :attributes_declaration=>{:typ...
-> print_type_inheritance(capybara_type)
-> print_type_inheritance(capybara_type)
-╭──────╮
-│ duck │
-╰──┬───╯
-   │ ╭─────────────╮
-   └─┤ atomic_duck │
-     ╰──────┬──────╯
-            │ ╭───────╮
-            └─┤ model │
-              ╰───┬───╯
-                  │ ╭────────╮
-                  └─┤ entity │
-                    ╰───┬────╯
-                        │ ╭──────────╮
-                        └─┤ Capybara │
-                          ╰──────────╯
-```
-
-While we're in here we could look at another type, like Capybara's attributes type
-
-```irb
-> print_type_inheritance(Capybara.attributes_type)
-╭──────╮
-│ duck │
-╰──┬───╯
-   │ ╭──────────╮
-   └─┤ duckture │
-     ╰────┬─────╯
-          │ ╭───────────────────╮
-          └─┤ associative_array │
-            ╰─────────┬─────────╯
-                      │ ╭────────────╮
-                      └─┤ attributes │
-                        ╰─────┬──────╯
-                              │ ╭────────────────────────────────╮
-                              └─┤ Anonymous attributes extension │
-                                ╰────────────────────────────────╯
-
-```
-
-Whoa... this is supposed to be Foobara 101... let's get back to basics.
-
-Let's make a basic CreateCapybara command:
+Let's make a CreateCapybara command that creates a Capybara record for us:
 
 ```ruby
 class CreateCapybara < Foobara::Command
@@ -573,7 +516,7 @@ end
 
 And now let's create some Capybara records and manipulate them:
 
-```ruby
+```
 > fumiko = CreateCapybara.run!(name: "Fumiko", nickname: "foo", age: 100)
 ==> <Capybara:1>
 > barbara = CreateCapybara.run!(name: "Barbara", nickname: "bar", age: 200)
@@ -597,8 +540,8 @@ We were able to increment Basil's age using his primary key and we were also abl
 But there is a problem... Basil's record won't be persisted across runs of our script.  That's because it is stored in
 ephemeral memory. Let's instead persist it to a file. Let's install a file crud driver:
 
-```bash
-> gem install foobara-local-files-crud-driver
+```
+$ gem install foobara-local-files-crud-driver
 ```
 
 And now let's swap out the InMemory crud driver with our file crud driver:
@@ -612,7 +555,7 @@ Foobara::Persistence.default_crud_driver = crud_driver
 
 Now let's create our records again and look at them on disk:
 
-```irb
+```
 > CreateCapybara.run!(name: "Fumiko", nickname: "foo", age: 100)
 ==> <Capybara:1>
 > CreateCapybara.run!(name: "Barbara", nickname: "bar", age: 200)
@@ -643,7 +586,7 @@ capybara:
 
 Great! Now let's re-run our script and manipulate some data:
 
-```irb
+```
 > basil = FindCapybara.run!(id: 3)
 ==> <Capybara:3>
 > basil.age
@@ -658,7 +601,7 @@ We were able to find Basil in a fresh run of our script!
 
 Let's find Basil again in another fresh run:
 
-```irb
+```
 > basil = FindCapybara.run!(id: 3)
 ==> <Capybara:3>
 > basil.age
@@ -675,7 +618,7 @@ Command connectors allow us to expose our commands to the outside world using va
 
 Let's install a command-line connector for bash:
 
-```bash
+```
 gem install foobara-sh-cli-connector
 ```
 
@@ -698,7 +641,7 @@ And either rename the script to capy-cafe or symlink it.
 
 Now let's run our script again:
 
-```irb
+```
 $ ./capy-cafe
 Usage: capy-cafe [GLOBAL_OPTIONS] [ACTION] [COMMAND_OR_TYPE] [COMMAND_INPUTS]
 
@@ -760,6 +703,8 @@ Yay! Now Basil is an even more respectable 302 years old!
 
 #### HTTP Command Connectors
 
+##### Rack Connector
+
 Let's now replace our command-line connector with an HTTP connector:
 
 We'll choose a Rack connector for now:
@@ -816,7 +761,7 @@ Yay!  We found Fumiko!
 
 Let's celebrate her birthday:
 
-```ruby
+```
 $ curl http://localhost:9292/run/IncrementAge?capybara=1
 {"id":1,"name":"Fumiko","nickname":"foo","age":101}
 $ curl http://localhost:9292/run/FindCapybara?id=1
@@ -825,11 +770,13 @@ $ curl http://localhost:9292/run/FindCapybara?id=1
 
 And now she is 101 as expected.
 
+##### Rails Connector
+
 Let's try exposing our commands through the Rails router.
 
 We'll create an a test rails app with (you can just do --api if you are too lazy to skip all the other stuff):
 
-```ruby
+```
 gem install rails
 rails rails new --api --skip-docker --skip-asset-pipeline --skip-javascript --skip-hotwire --skip-jbuilder --skip-test --skip-brakeman --skip-kamal --skip-solid rails_test_app
 ```
@@ -883,11 +830,163 @@ This has the same effect as the previous code and is just a stylistic alternativ
 
 #### Async Command Connectors
 
-TODO
+Let's connect a command to some sort of async job solution. We'll connect our IncrementAge command to Resque:
+
+```ruby
+require "foobara/resque_connector"
+
+async_connector = Foobara::CommandConnectors::ResqueConnector.new
+
+async_connector.connect(IncrementAge)
+```
+
+This gives us a new command called IncrementAgeAsync.  Let's expose this new command to our CLI connector and try
+it out on the command line:
+
+```ruby
+
+require "foobara/resque_connector"
+
+async_connector = Foobara::CommandConnectors::ResqueConnector.new
+
+async_connector.connect(IncrementAge)
+
+require "foobara/sh_cli_connector"
+
+cli_connector = Foobara::CommandConnectors::ShCliConnector.new
+
+cli_connector.connect(IncrementAge)
+cli_connector.connect(IncrementAgeAsync)
+cli_connector.connect(FindCapybara)
+
+cli_connector.run(ARGV)
+```
+
+And now let's call it:
+
+```
+$ ./part_5b_async_command_connector.rb FindCapybara --id 1 | grep age
+age: 100
+$ ./part_5a_async_command_connector.rb IncrementAgeAsync --capybara 1
+true
+$ /part_5b_async_command_connector.rb FindCapybara --id 1 | grep age
+age: 100
+```
+
+So we can see that we only got back "true" when we ran IncrementAgeAsync. But the age still hasn't gone up.
+This is because we're not running a worker. Normally, one would fire up a worker on the command line with
+`rake resque:work`, however, we will just hack something up so we can stay within one script.  We normally wouldn't
+make such a hack in a real project with multiple files.  But here's our hack:
+
+```ruby
+...
+
+require "foobara/resque_connector"
+
+async_connector = Foobara::CommandConnectors::ResqueConnector.new
+
+async_connector.connect(IncrementAge)
+
+require "foobara/sh_cli_connector"
+
+cli_connector = Foobara::CommandConnectors::ShCliConnector.new
+
+cli_connector.connect(IncrementAge)
+cli_connector.connect(IncrementAgeAsync)
+cli_connector.connect(FindCapybara)
+
+if ARGV == ["work"]
+  worker = Resque::Worker.new("*")
+  worker.verbose = true
+  worker.work(1)
+else
+  cli_connector.run(ARGV)
+end
+```
+
+So now we can run it with just "work" to fire up a worker and process our async jobs:
+
+```
+$ ./part_5b_async_command_connector.rb work
+*** got: (Job{general} | Foobara::CommandConnectors::ResqueConnector::CommandJob | [{"command_name"=>"IncrementAge", "inputs"=>{"capybara"=>"1"}}])
+*** done: (Job{general} | Foobara::CommandConnectors::ResqueConnector::CommandJob | [{"command_name"=>"IncrementAge", "inputs"=>{"capybara"=>"1"}}])
+```
+
+And now let's check Fumiko's age:
+
+```
+$ /part_5b_async_command_connector.rb FindCapybara --id 1 | grep age
+age: 101
+```
+
+Cool! We asynchronously ran our IncrementAge command and we did it without writing a Resque job!  That's cool
+because it means we can't accidentally place domain logic in our job code because there is no job code.
 
 #### Scheduler Command Connectors
 
-TODO
+Let's connect a command to a scheduler now. We will use resque-scheduler in this example:
+
+```ruby
+require "foobara/resque_scheduler_connector"
+
+cron_connector = Foobara::CommandConnectors::ResqueSchedulerConnector.new
+
+cron_connector.cron(
+  [
+    #   ╭─Second (0-59)
+    #   │ ╭─Minute (0-59)
+    #   │ │ ╭─Hour (0-23)
+    #   │ │ │ ╭─Day-of-Month (1-31)
+    #   │ │ │ │ ╭─Month (1-12)
+    #   │ │ │ │ │ ╭─Day-of-Week (0-6)
+    #   │ │ │ │ │ │ ╭─Timezone
+    #   │ │ │ │ │ │ │   ╭─Command,      ╭─Inputs
+    ["*/5 * * * * *  ", IncrementAge, { capybara: 1 }]
+  ]
+)
+```
+
+We could connect IncrementAge to our connector and that would give us a IncrementAgeAsyncAt command which takes a time
+when we want the command to be ran. But in this example we will make a recurring job. We will increment Fumiko's age
+every 5 seconds.  That's 6307200 birthdays a year for the curious (moar in leap years.)
+
+We will expand our hack to fire up a scheduler in a separate thread:
+
+```ruby
+...
+
+if ARGV == ["work"]
+  Thread.new do
+    Resque::Scheduler.verbose = true
+    Resque::Scheduler.run
+  end
+
+  worker = Resque::Worker.new("*")
+  worker.verbose = true
+  worker.work(1)
+else
+  cli_connector.run(ARGV)
+end
+```
+
+Now when we run it with just "work" we see the scheduler start:
+
+```
+$ ./part_6_scheduler_command_connector.rb work
+resque-scheduler: [INFO] 2024-12-12T14:47:41-08:00: Starting
+resque-scheduler: [DEBUG] 2024-12-12T14:47:41-08:00: Setting procline "resque-scheduler-4.10.2: Starting"
+resque-scheduler: [DEBUG] 2024-12-12T14:47:41-08:00: Setting procline "resque-scheduler-4.10.2: Schedules Loaded"
+```
+
+And every 5 seconds we see it outputting:
+
+```
+resque-scheduler: [INFO] 2024-12-12T14:47:45-08:00: queueing Foobara::CommandConnectors::ResqueConnector::CommandJob (IncrementAge)
+*** got: (Job{general} | Foobara::CommandConnectors::ResqueConnector::CommandJob | [{"command_name"=>"IncrementAge", "inputs"=>{"capybara"=>1}}])
+*** done: (Job{general} | Foobara::CommandConnectors::ResqueConnector::CommandJob | [{"command_name"=>"IncrementAge", "inputs"=>{"capybara"=>1}}])
+```
+
+And if we check Fumiko's age like before we see it going up every 5 seconds.
 
 ## Intermediate Foobara
 
@@ -900,7 +999,7 @@ Let's take a quick look at some metadata in our existing systems.
 
 Let's for example ask our Capybara entity for its manifest:
 
-```irb
+```
 > Capybara.foobara_manifest
 ==>
 {:attributes_type=>
@@ -922,14 +1021,14 @@ Let's for example ask our Capybara entity for its manifest:
 
 Let's ask our Rack connector for a list of commands it exposes:
 
-```irb
+```
 > command_connector.foobara_manifest[:command].keys
 ==> [:CreateCapybara, :FindCapybara, :IncrementAge]
 ```
 
 We can see all the different categories of concepts available by looking at the top-level keys:
 
-```irb
+```
 > puts command_connector.foobara_manifest.keys.sort
 command
 domain
@@ -993,7 +1092,6 @@ Let's create a command that calls another. Remember our `Add` command from earli
 Let's implement a contrived Subtract command that is implemented using Add:
 
 ```ruby
-
 class Subtract < Foobara::Command
   inputs do
     operand1 :integer, :required
@@ -1028,7 +1126,7 @@ dependency graph of commands.
 
 Let's play with it:
 
-```ruby
+```
 > Subtract.run!(operand1: 5, operand2: 2)
 ==> 3
 ```
@@ -1037,7 +1135,7 @@ We get the answer we expected!
 
 A little bit advanced but let's look at the possible errors for Subtract:
 
-```irb
+```
 > Subtract.possible_errors.map(&:key).map(&:to_s).sort
 ==>
 ["add>data.cannot_cast",
@@ -1154,7 +1252,7 @@ operation entails at a high-level.
 
 Let's play with it:
 
-```irb
+```
 > Divide.run!(dividend: 6, divisor: 7)
 ==> 0
 > Divide.run!(dividend: 8, divisor: 7)
@@ -1179,29 +1277,29 @@ This is one way we can express a custom error for associated with a specific inp
 
 Let's try it out!
 
-```irb
+```
 > outcome = Divide.run(dividend: 49, divisor: 0)
 ==> #<Foobara::Outcome:0x00007f504d178e38...
         > outcome.success?
 ==> false
 > outcome.errors_hash
 ==>
-        {"data.divisor.divide_by_zero"=>
-                 {:key=>"data.divisor.divide_by_zero",
-                  :path=>[:divisor],
-                  :runtime_path=>[],
-                  :category=>:data,
-                  :symbol=>:divide_by_zero,
-                  :message=>"Cannot divide by zero",
-                  :context=>{},
-                  :is_fatal=>false}}
+{"data.divisor.divide_by_zero"=>
+  {:key=>"data.divisor.divide_by_zero",
+   :path=>[:divisor],
+   :runtime_path=>[],
+   :category=>:data,
+   :symbol=>:divide_by_zero,
+   :message=>"Cannot divide by zero",
+   :context=>{},
+   :is_fatal=>false}}
 > outcome.errors_sentence
 ==> "Cannot divide by zero"
 ```
 
 And we can see the error in the command's list of possible errors:
 
-```irb
+```
 > Divide.possible_errors.map(&:key).map(&:to_s).grep /zero/
 ==> ["data.divisor.divide_by_zero"]
 ```
@@ -1209,7 +1307,7 @@ And we can see the error in the command's list of possible errors:
 And of course, as expected, tooling has access to information about this error and the command's possible error through manifest
 metadata:
 
-```irb
+```
 > Foobara.manifest[:command][:Divide][:possible_errors]["data.divisor.divide_by_zero"][:error]
 ==> "Divide::DivideByZeroError"
 > Foobara.manifest[:error][:"Divide::DivideByZeroError"][:parent]
@@ -1225,7 +1323,7 @@ class Divide < Foobara::Command
       "Cannot divide by zero"
     end
   end
-  
+
   possible_input_error :divisor, DivideByZeroError
 ```
 
@@ -1257,7 +1355,7 @@ class Divide < Foobara::Command
 
 And let's try it out:
 
-```irb
+```
 > outcome = Divide.run(dividend: 49, divisor: 0)
 ==> #<Foobara::Outcome:0x00007f030fe3b8b8...
 > outcome.success?
@@ -1386,25 +1484,29 @@ module FoobaraDemo
   module CapyCafe
     foobara_depends_on AnimalHouse
 
-    class AnimalToCapybara < Foobara::DomainMapper
-      from AnimalHouse::Animal
-      to CreateCapybara
+    module DomainMappers
+      class MapAnimalToCapybara < Foobara::DomainMapper
+        from AnimalHouse::Animal
+        to CreateCapybara
 
-      def map(animal)
-        age = birthday_to_age(animal.birthday)
+        def map
+          {
+                  name: "#{first_name} #{last_name}",
+                  age: birthday_to_age
+          }
+        end
 
-        {
-                name: "#{animal.first_name} #{animal.last_name}",
-                age:
-        }
-      end
+        alias animal from
 
-      def birthday_to_age(birthday)
-        today = Date.today
-        age = today.year - birthday.year
-        birthday_this_year = Date.new(birthday.year + age, birthday.month, birthday.day)
+        foobara_delegate :first_name, :last_name, :birthday, to: :animal
 
-        today < birthday_this_year ? age - 1 : age
+        def birthday_to_age
+          today = Date.today
+          age = today.year - birthday.year
+          birthday_this_year = Date.new(birthday.year + age, birthday.month, birthday.day)
+
+          today < birthday_this_year ? age - 1 : age
+        end
       end
     end
   end
@@ -1418,9 +1520,9 @@ distribution changes.
 Normally, we wouldn't make use of a domain mapper in isolation. Like everything else, it should be used in the context
 of a command. But we can play with it directly:
 
-```irb
+```
 $ ./animal_house_import.rb
-> create_capybara_inputs = FoobaraDemo::CapyCafe::AnimalToCapybara.call(species: :capybara, first_name: "Barbara", last_name: "Doe", birthday: "1000-01-01")
+> create_capybara_inputs = FoobaraDemo::CapyCafe::DomainMappers::MapAnimalToCapybara.map!(species: :capybara, first_name: "Barbara", last_name: "Doe", birthday: "1000-01-01")
 ==> {:name=>"Barbara Doe", :age=>1024}
 > barbara = FoobaraDemo::CapyCafe::CreateCapybara.run!(create_capybara_inputs)
 ==> <Capybara:2>
@@ -1430,47 +1532,15 @@ $ ./animal_house_import.rb
 ==> 2
 ```
 
-And we can increment Barbara's age now that she has been imported into our CapyCafe:
+Now let's make use of our domain mapper in a command, which is its intended purpose:
+
+```ruby
 
-```irb
-> FoobaraDemo::CapyCafe::IncrementAge.run!(capybara: barbara)
-==> <Capybara:2>
-> FoobaraDemo::CapyCafe::FindCapybara.run!(id: barbara)
-==> <Capybara:2>
-> FoobaraDemo::CapyCafe::FindCapybara.run!(id: barbara).age
-==> 1025
 ```
 
 Now let's create a command that makes use of our domain mapper which is the typical usage pattern:
 
 ```ruby
-#!/usr/bin/env ruby
-
-require "foobara/remote_imports"
-
-[9292, 9293].each do |port|
-  Foobara::RemoteImports::ImportCommand.run!(manifest_url: "http://localhost:#{port}/manifest")
-end
-
-module FoobaraDemo
-  module AnimalHouse
-    foobara_domain!
-  end
-end
-
-module FoobaraDemo
-  module AnimalHouse
-    class Animal < Foobara::Model
-      attributes do
-        first_name :string
-        last_name :string
-        birthday :date
-        species :symbol, one_of: %i[capybara cat tartigrade]
-      end
-    end
-  end
-end
-
 module FoobaraDemo
   module CapyCafe
     class ImportAnimal < Foobara::Command
@@ -1487,7 +1557,7 @@ module FoobaraDemo
 
       possible_input_error :animal, NotACapybara
 
-      depends_on CreateCapybara
+      depends_on CreateCapybara, DomainMappers::MapAnimalToCapybara
 
       def execute
         create_capybara
@@ -1497,14 +1567,6 @@ module FoobaraDemo
 
       attr_accessor :capybara
 
-      def validate
-        species = animal.species
-
-        unless species == :capybara
-          add_input_error :animal, NotACapybara, animal: animal, species: species
-        end
-      end
-
       def create_capybara
         self.capybara = run_mapped_subcommand!(CreateCapybara, animal)
       end
@@ -1517,66 +1579,456 @@ Note that we can automatically map `animal` to CreateCapybara inputs by calling
 
 Let's play with it:
 
-```irb
+```
+$ ./animal_house_import.rb
 > basil = FoobaraDemo::CapyCafe::ImportAnimal.run!(animal: { species: :capybara, first_name: "Basil", last_name: "Doe", birthday: "1000-01-01" })
 ==> <Capybara:3>
-> basil.age
+> FoobaraDemo::CapyCafe::FindCapybara.run!(id: basil).age
 ==> 1024
-> basil.id
-==> 3
 > FoobaraDemo::CapyCafe::IncrementAge.run!(capybara: basil)
 ==> <Capybara:3>
 > FoobaraDemo::CapyCafe::FindCapybara.run!(id: basil).age
 ==> 1025
 ```
 
-TODO
+Great! Notice how we have avoided putting pieces of the AnimalHouse mental model in our ImportAnimal command which
+is part of the CapyCafe mental model.  Even pieces of error-handling/validation could be moved out using domain mappers
+as we've done here.
+
+And we can even discover that an error might occur when running the command:
+
+```
+> FoobaraDemo::CapyCafe::ImportAnimal.possible_errors.map(&:key).map(&:to_s).grep /not_a/
+==> ["foobara_demo::capy_cafe::domain_mappers::map_animal_to_capybara>runtime.not_a_capybara"]
+```
+
+This is pretty nice because it means that tooling/external systems can discover and make use of these errors!  This
+again helps with abstracting away integration code and putting the spotlight on implementing the actual
+problem/solution domain.
+
+Let's actually go ahead and cause NotACapybara error:
+
+```
+> outcome = FoobaraDemo::CapyCafe::ImportAnimal.run(animal: { species: :tartigrade, first_name: "Tara", last_name: "Tigrade", birthday: "1000-01-01" })
+==>
+#<Foobara::Outcome:0x00007fc310fb2c98
+...
+> outcome.errors_sentence
+==> "Can only import a capybara not a tartigrade"
+```
+
+### Types
+
+#### Builtin types
+
+Foobara comes with a number of builtin types. Let's see what they are with this little hack:
+
+```
+> Foobara::Util.print_tree(Foobara::Namespace.global.foobara_all_type, to_parent: :base_type, to_name: :full_type_name)
+╭──────╮
+│ duck │
+╰──┬───╯
+   │ ╭─────────────╮
+   ├─┤ atomic_duck │
+   │ ╰──────┬──────╯
+   │        │ ╭─────────╮
+   │        ├─┤ boolean │
+   │        │ ╰─────────╯
+   │        │ ╭──────╮
+   │        ├─┤ date │
+   │        │ ╰──────╯
+   │        │ ╭──────────╮
+   │        ├─┤ datetime │
+   │        │ ╰──────────╯
+   │        │ ╭───────╮
+   │        ├─┤ model │
+   │        │ ╰───┬───╯
+   │        │     │ ╭──────────────────────────────────╮
+   │        │     ├─┤ FoobaraDemo::AnimalHouse::Animal │
+   │        │     │ ╰──────────────────────────────────╯
+   │        │     │ ╭─────────────────╮
+   │        │     └─┤ detached_entity │
+   │        │       ╰────────┬────────╯
+   │        │                │ ╭─────────────────────────────────╮
+   │        │                ├─┤ FoobaraDemo::CapyCafe::Capybara │
+   │        │                │ ╰─────────────────────────────────╯
+   │        │                │ ╭────────╮
+   │        │                └─┤ entity │
+   │        │                  ╰────────╯
+   │        │ ╭────────╮
+   │        ├─┤ number │
+   │        │ ╰───┬────╯
+   │        │     │ ╭─────────────╮
+   │        │     ├─┤ big_decimal │
+   │        │     │ ╰─────────────╯
+   │        │     │ ╭───────╮
+   │        │     ├─┤ float │
+   │        │     │ ╰───────╯
+   │        │     │ ╭─────────╮
+   │        │     └─┤ integer │
+   │        │       ╰─────────╯
+   │        │ ╭────────╮
+   │        ├─┤ string │
+   │        │ ╰───┬────╯
+   │        │     │ ╭───────╮
+   │        │     └─┤ email │
+   │        │       ╰───────╯
+   │        │ ╭────────╮
+   │        └─┤ symbol │
+   │          ╰────────╯
+   │ ╭──────────╮
+   └─┤ duckture │
+     ╰────┬─────╯
+          │ ╭───────╮
+          ├─┤ array │
+          │ ╰───┬───╯
+          │     │ ╭───────╮
+          │     └─┤ tuple │
+          │       ╰───────╯
+          │ ╭───────────────────╮
+          └─┤ associative_array │
+            ╰─────────┬─────────╯
+                      │ ╭────────────╮
+                      └─┤ attributes │
+                        ╰────────────╯
+```
+
+Obviously Capybara and Animal are not builtin types but you get the point.
+
+#### Custom types
+
+Let's have a capybara diving competition. Which means we need judges. So let's create a new domain,
+`CapybaraDivingCompetition`, and a new entity, `Judge`:
+
+```ruby
+module FoobaraDemo
+  module CapybaraDivingCompetition
+    foobara_domain!
+
+    depends_on CapyCafe
+
+    class Judge < Foobara::Model
+      attributes do
+        email :string
+        favorite_diver CapyCafe::Capybara, :allow_nil
+      end
+    end
+  end
+end
+```
+
+So we have an email to identify the judge and which diver is their favorite.
+But wait... there's an age-old problem... email addresses are case-insensitive. One way to solve this is to make
+sure to downcase the emails whenever we receive them anywhere in the app. If we don't want to worry about that, we
+can just make that behavior be part of the type itself:
+
+```ruby
+...
+    class Judge < Foobara::Model
+      attributes do
+        email :string, :downcase
+...
+```
+
+Here we are using a downcase transformer. This will always downcase the value everywhere.
+
+Let's go ahead and a validator while we're at it because why not?
+
+```ruby
+...
+    class Judge < Foobara::Model
+      attributes do
+        email :string, :downcase, matches: /\A[^@]+@[^@]+\.[^@]+\z/
+...
+```
+
+OK let's play with this really quickly:
+
+```
+$ ./part_1c_custom_types.rb
+> judge = FoobaraDemo::CapybaraDivingCompetition::Judge.new(email: "ASDF@asdf.com")
+==> #<FoobaraDemo::CapybaraDivingCompetition::Judge:0x00007f780b978418 @attributes={:email=>"asdf@asdf.com"}, @mutable=true>
+> judge.valid?
+==> true
+> judge.email
+==> "asdf@asdf.com"
+> judge = FoobaraDemo::CapybaraDivingCompetition::Judge.new(email: "asdf.com")
+==> #<FoobaraDemo::CapybaraDivingCompetition::Judge:0x00007f780ba3cb88 @attributes={:email=>"asdf.com"}, @mutable=true>
+> judge.valid?
+==> false
+> judge.validation_errors.first.to_h
+==>
+{:key=>"data.email.does_not_match",
+ :path=>[:email],
+ :runtime_path=>[],
+ :category=>:data,
+ :symbol=>:does_not_match,
+ :message=>"\"asdf.com\" did not match /\\A[^@]+@[^@]+\\.[^@]+\\z/",
+ :context=>{:value=>"asdf.com", :regex=>"(?-mix:\\A[^@]+@[^@]+\\.[^@]+\\z)"},
+ :is_fatal=>false}
+```
+
+So we can see that our email was automatically downcased. We can also see that if we leave out @ we get an error.
+
+But what if we want to use this type all over the place? It would be not great to copy/paste it around because,
+for example, it would be nice to improve the validation error message. Do we want to find/fix all its usages when we
+do that?
+
+Instead, we can create a custom type and use it:
+
+```ruby
+    class Judge < Foobara::Model
+      email_address_type = domain.foobara_type_from_declaration(:string, :downcase, matches: /\A[^@]+@[^@]+\.[^@]+\z/)
+
+      attributes do
+        email email_address_type, :required
+      end
+    end
+```
+
+However, it is better to register it on the domain. Then it can be used by name and will appear in the manifests
+by name. So let's do that:
+
+```ruby
+module FoobaraDemo
+  module CapybaraDivingCompetition
+    foobara_domain!
+
+    depends_on CapyCafe
+
+    foobara_register_type :email_address, :string, :downcase, matches: /\A[^@]+@[^@]+\.[^@]+\z/
+
+    class Judge < Foobara::Model
+      attributes do
+        email :email_address, :required
+        favorite_diver CapyCafe::Capybara, :allow_nil
+      end
+    end
+  end
+end
+```
 
 ### Code Generators
 
+There are a number of code generators we can use that are available through the foob CLI tool. Let's install it:
+
+```
+$ gem install foob
+```
+
 #### Generating a new Foobara Ruby project
+
+We've been piling our code into one script so far but out in the real world we would need to organize different
+code units into different files into directories with some sort of project structure to it.
+
+We can use foob to generate a project with such a structure:
+
+```
+$ foob generate ruby-project --name foobara-demo/capybara-diving-competition
+```
+
+Let's generate a bunch of the code we've written so far in this demo. We can see all of the available generators
+by running:
+
+```
+$ foob g
+Usage: foob generate [GENERATOR_KEY] [GENERATOR_OPTIONS]
+
+Available Generators:
+
+autocrud
+command
+domain
+domain-mapper
+organization
+rack-connector
+redis-crud-driver
+remote-imports
+resque-connector
+resque-scheduler-connector
+ruby-project
+sh-cli-connector
+type
+typescript-react-command-form
+typescript-react-project
+typescript-remote-commands
+```
+
+We can get help for a specific generator with `foob help [GENERATOR_NAME]`.  For example:
+
+```
+$ foob help type
+Usage: foob [GLOBAL_OPTIONS] type [COMMAND_INPUTS]
+
+Command inputs:
+
+-n, --name NAME
+-t, --type TYPE                       One of: entity, model, type. Default: :type
+-d, --description DESCRIPTION
+--domain DOMAIN
+-o, --organization ORGANIZATION
+--output-directory OUTPUT_DIRECTORY
+```
+
+So let's use these generators to generate files for various classes/modules we've created so far in this tutorial:
+
+```
+$ cd foobara-demo/capybara-diving-competition
+$ foob g domain --name FoobaraDemo::IntegerMath
+$ foob g domain --name FoobaraDemo::CapyCafe
+$ foob g type -t entity --organization FoobaraDemo --domain CapyCafe --name Capybara
+$ foob g type --organization FoobaraDemo --domain CapybaraDivingCompetition --name email_address
+$ foob g type -t entity --organization FoobaraDemo --domain CapybaraDivingCompetition --name Judge
+$ foob g command --name FoobaraDemo::IntegerMath::Add
+$ foob g command --name FoobaraDemo::IntegerMath::Subtract
+$ foob g command --name FoobaraDemo::IntegerMath::Divide
+$ foob g command --name FoobaraDemo::CapyCafe::CreateCapybara
+$ foob g command --name FoobaraDemo::CapyCafe::FindCapybara
+$ foob g command --name FoobaraDemo::CapyCafe::IncrementAge
+$ foob g sh-cli-connector --name capy-cafe
+$ foob g local-files-crud-driver
+```
+
+This results in the following directory structure:
+
+```
+$ tree -a --dirsfirst --prune --matchdirs -I '.git'
+.
+├── bin
+│   ├── capy-cafe
+│   └── console
+├── boot
+│   ├── config.rb
+│   ├── crud.rb
+│   ├── finish.rb
+│   └── start.rb
+├── .github
+│   └── workflows
+│       └── ci.yml
+├── lib
+│   └── foobara_demo
+│       └── capybara_diving_competition.rb
+├── spec
+│   ├── foobara_demo
+│   │   ├── capy_cafe
+│   │   │   ├── create_capybara_spec.rb
+│   │   │   ├── find_capybara_spec.rb
+│   │   │   └── increment_age_spec.rb
+│   │   ├── integer_math
+│   │   │   ├── add_spec.rb
+│   │   │   ├── divide_spec.rb
+│   │   │   └── subtract_spec.rb
+│   │   └── capybara_diving_competition_spec.rb
+│   ├── support
+│   │   ├── rubyprof.rb
+│   │   ├── simplecov.rb
+│   │   ├── term_trap.rb
+│   │   └── vcr.rb
+│   └── spec_helper.rb
+├── src
+│   └── foobara_demo
+│       ├── capybara_diving_competition
+│       │   └── types
+│       │       ├── email_address.rb
+│       │       └── judge.rb
+│       ├── capy_cafe
+│       │   ├── types
+│       │   │   └── capybara.rb
+│       │   ├── create_capybara.rb
+│       │   ├── find_capybara.rb
+│       │   └── increment_age.rb
+│       ├── integer_math
+│       │   ├── add.rb
+│       │   ├── divide.rb
+│       │   └── subtract.rb
+│       ├── capybara_diving_competition.rb
+│       ├── capy_cafe.rb
+│       └── integer_math.rb
+├── boot.rb
+├── foobara-demo-capybara-diving-competition.gemspec
+├── Gemfile
+├── .gitignore
+├── Guardfile
+├── Rakefile
+├── README.md
+├── .rspec
+├── .rubocop.yml
+└── version.rb
+```
+
 #### Generating a new Foobara Typescript/React project
-#### Generating commands, models, entities, types, domains, organizations, etc...
 
-TODO
+We can generate a Typescript React project with the following generator:
 
-### Custom types
+```
+$ foob g typescript-react-project -p foobara-demo-frontend
+```
 
-TODO
+We can import remote commands into our typescript project with:
+
+```
+$ foob g typescript-remote-commands --manifest-url http://localhost:9292/manifest
+```
+
+And we can generate UI forms automatically with:
+
+```
+$ foob g typescript-react-command-form --manifest-url http://localhost:9292/manifest --command-name CreateCapybara
+```
 
 ## Expert Foobara
 
 ### Callbacks
 
-TODO
+There are several callbacks on commands that you can hook into. Also on entities.
+
+TODO: give some code examples
 
 ### Transactions in Commands
 
-TODO
+You can rollback/commit transactions in Commands. You can do this successfully even if the underlying data storage
+doesn't support transactions.
+
+TODO: give some code examples
 
 ### Transactions in tests/console
 
-TODO
+You should normally not be creating entities outside of commands. But if you find yourself wanting to, perhaps
+in a test suite or console, you can open a transaction so that you can do it.
+
+TODO: give some code examples
 
 ### Custom crud drivers
 
-TODO
+You can write your own CRUD drivers to read/write data from/to wherever you want.
 
-### Custom command connectors
+TODO: give some code examples/cover the CRUD driver API
 
-TODO
+### Custom command connectors
 
-### Value processors
+You can write your own command connectors so that you can expose commands using whatever technology you wish.
 
-TODO
+TODO: give some code examples/cover the command connector API
 
 ### Custom types from scratch
 
-TODO
+Instead of creating new types by extending existing types with existing processors/transformers/validators, as we did
+in this tutorial with our email_address custom type,
+you can also write your own new types from scratch.
+
+TODO: give some code examples/cover the type API
 
 ### Namespaces
 
-TODO
+Several of the concepts we've explored so far are also namespaces.
+
+TODO: give some code examples
+
+### Value processors
+
+A low-level concept upon which several things like types and serializers are built in Foobara are value processors.
+
+TODO: give some code examples
 
 # Additional learning materials/Documentation
 
@@ -1603,7 +2055,7 @@ The build will fail if test coverage is below 100%
 
 You should be able to do the typical stuff:
 
-```bash
+```
 git clone git@github.com:foobara/foobara
 cd foobara
 bundle