foobara 0.0.34 → 0.0.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc9733f9966487e9f526b01792182ff02718e7f3ac445256d24397942eddf4ec
-  data.tar.gz: 4e611e1bfae4bc3418108ad93680555e6497d1426a465697827064523ed940d5
+  metadata.gz: f2cf6302b2afba48242f5cc283a4029ebb6337cccc367a633752cd9866c69d69
+  data.tar.gz: 05b4068afedd82c0712e977d9810ebc1bcacb9c06ab90205e1985966f5ece820
 SHA512:
-  metadata.gz: a57062ce5885cc626ac32c66dcf9902c1ace2d50d2182c0ec188ba01e3bc662f9e0d6e2fe4d8b6626a23b25f1046e71da813d0b35e8b3d37c895f074d901feb7
-  data.tar.gz: 7d6724fff8dc1ee6961f6585ab9c5b78560962725511cd3d316451dda387d8455ddc0a9808c8617aabed61d4aeb656698a1b7a92ef2b760a7248c96bc6b84f81
+  metadata.gz: 48722536d6aee98bebaad5934153c5d46223857343292054f6f053c80a7784d187f853514bb3271831c6158056490326731501d2a890d51a386c6626cbd76932
+  data.tar.gz: 1371ff6d6b3a81b4cf7228f6cd15a70265955da87dca6bcc580a938217f2443d3add0f8aaad85e705cca00cb101cb8587723360ada4f8a9b765895400d4b44e6

data/CHANGELOG.md

@@ -1,6 +1,7 @@
-## [0.0.34] - 2024-12-10
+## [0.0.35] - 2024-12-10
 
 - Fix bug with command-named convenience functions
+- Make domain mappers cast their inputs
 
 ## [0.0.33] - 2024-12-09
 

data/README.md

@@ -1,4 +1,3 @@
-
 <!-- TOC -->
 * [What is/Why Foobara?](#what-iswhy-foobara)
   * [Commands](#commands)
@@ -19,6 +18,7 @@
       * [Async Command Connectors](#async-command-connectors)
       * [Scheduler Command Connectors](#scheduler-command-connectors)
   * [Intermediate Foobara](#intermediate-foobara)
+    * [Metadata manifests for discoverability](#metadata-manifests-for-discoverability)
     * [Remote Commands](#remote-commands)
     * [Subcommands](#subcommands)
     * [Custom Errors](#custom-errors)
@@ -979,34 +979,495 @@ Great! We can now move commands, types, etc, around between systems without need
 errors work the same way:
 
 ```
-
+> puts FindCapybara.run(id: "asdf").errors_sentence
+At id: Cannot cast "asdf" to an integer. Expected it to be a Integer, or be a string of digits optionally with a minus sign in front
 ```
 
 ### Subcommands
 
-TODO
+Inevitably, we'll want one high-level domain operation to be able to invoke another high-level domain operation. And
+because Foobara commands are the public interfaces to our systems/subsystems, we really really want to be able to do
+this when a command needs a behavior from another domain as an implementation detail.
+
+Let's create a command that calls another. Remember our `Add` command from earlier?
+Let's implement a contrived Subtract command that is implemented using Add:
+
+```ruby
+
+class Subtract < Foobara::Command
+  inputs do
+    operand1 :integer, :required
+    operand2 :integer, :required
+  end
+
+  result :integer
+
+  depends_on Add
+
+  def execute
+    subtract_operands
+
+    difference
+  end
+
+  attr_accessor :difference
+
+  def subtract_operands
+    self.difference = run_subcommand!(Add, operand1:, operand2: -operand2)
+  end
+end
+```
+
+We call our subcommand using `#run_subcommand!`. This will run the command and return the result. If an error occurs,
+the errors from Add will be appended to our errors for Subtract, causing it to fail.
+
+Note that we declare that Subtract depends on Add. We do this using `.depends_on`. This helps in a few ways.
+For one, Subtract.possible_errors can include errors that might happen in Add.
+This allows us to see a command dependencies using graphing tools and what-not and enforce a unidirectional
+dependency graph of commands.
+
+Let's play with it:
+
+```ruby
+> Subtract.run!(operand1: 5, operand2: 2)
+==> 3
+```
+
+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",
+ "add>data.missing_required_attribute",
+ "add>data.operand1.cannot_cast",
+ "add>data.operand1.missing_required_attribute",
+ "add>data.operand2.cannot_cast",
+ "add>data.operand2.missing_required_attribute",
+ "add>data.unexpected_attributes",
+ "data.cannot_cast",
+ "data.missing_required_attribute",
+ "data.operand1.cannot_cast",
+ "data.operand1.missing_required_attribute",
+ "data.operand2.cannot_cast",
+ "data.operand2.missing_required_attribute",
+ "data.unexpected_attributes"]
+```
+
+We can see some errors from Add here.  Note: we actually know in this case that we don't expect these errors to occur.
+We could filter these out to improve the information to the outside world/tooling/generators but that's beyond
+the intermediate level.
 
 ### Custom Errors
 
+Speaking of errors, an intermediate Foobara skill is defining a custom error.
+
 #### Input Errors
 
-TODO
+Let's make a DivideByZeroError as an example. First, let's make a command that would use it. Q: can you
+guess which command we're going to make next? A: Divide!
+
+```ruby
+class Divide < Foobara::Command
+  inputs do
+    dividend :integer, :required
+    divisor :integer, :required
+  end
+
+  result :integer
+
+  depends_on Subtract
+
+  def execute
+    initialize_quotient_to_zero
+    make_operands_positive_and_determine_if_result_is_negative
+
+    until dividend_less_than_divisor?
+      increment_quotient
+      subtract_divisor_from_dividend
+    end
+
+    negate_quotient if negative_result?
+
+    quotient
+  end
+
+  attr_accessor :negative_result, :quotient
+
+  def make_operands_positive_and_determine_if_result_is_negative
+    self.negative_result = false
+
+    if dividend < 0
+      self.dividend = -dividend
+      self.negative_result = !negative_result
+    end
+
+    if divisor < 0
+      self.divisor = -divisor
+      self.negative_result = !negative_result
+    end
+  end
+
+  def negate_quotient
+    self.quotient = -quotient
+  end
+
+  def dividend_less_than_divisor?
+    dividend < divisor
+  end
+
+  def negative_result?
+    negative_result
+  end
+
+  def increment_quotient
+    self.quotient += 1
+  end
+
+  def subtract_divisor_from_dividend
+    self.dividend = run_subcommand!(Subtract, operand1: dividend, operand2: divisor)
+  end
+
+  def initialize_quotient_to_zero
+    self.quotient = 0
+  end
+
+  attr_writer :dividend, :divisor
+
+  def dividend
+    @dividend || super
+  end
+
+  def divisor
+    @divisor || super
+  end
+end
+```
+
+This one is pretty long because it has a more complex algorithm. Note how the #execute method
+has a self-documenting form of the algorithm in it. That is a good best-practice when it comes to commands.
+In a real project, this would be encapsulating a high-level domain operation. Having various levels
+of abstraction of the algorithm mixed together can harm our ability to see what the domain
+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)
+==> 1
+> Divide.run!(dividend: 49, divisor: 7)
+==> 7
+```
+
+We get the expected integer division results. However, if we pass
+0 as the divisor, it will hang forever.
+
+Time for our custom error!
+
+```ruby
+class Divide < Foobara::Command
+  possible_input_error :divisor, :divide_by_zero, message: "Cannot divide by zero"
+
+  ...
+```
+
+This is one way we can express a custom error for associated with a specific input.
+
+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}}
+> 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"]
+```
+
+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]
+==> [:command, "Divide"]
+```
+
+There's an alternative way to express these custom errors:
+
+```ruby
+class Divide < Foobara::Command
+  class DivideByZeroError < Foobara::DataError
+    def message
+      "Cannot divide by zero"
+    end
+  end
+  
+  possible_input_error :divisor, DivideByZeroError
+```
+
+Both do the same thing.
 
 #### Runtime Errors
 
-TODO
+Often, you a command will have to fail due to an error that isn't related to a specific input.  For these situations,
+you want a runtime error.  Let's convert our DivideByZeroError to a runtime error just for demonstration purposes:
+
+```ruby
+class Divide < Foobara::Command
+  possible_error :divide_by_zero, message: "Cannot divide by zero"
+
+  def execute
+    validate_divisor
+
+    ...
+  end
+
+  def validate_divisor
+    if divisor == 0
+      add_runtime_error DivideByZeroError
+    end
+  end
+
+  ...
+```
+
+And let's try it out:
+
+```irb
+> outcome = Divide.run(dividend: 49, divisor: 0)
+==> #<Foobara::Outcome:0x00007f030fe3b8b8...
+> outcome.success?
+==> false
+> outcome.errors_sentence
+==> "Cannot divide by zero"
+> outcome.errors_hash
+==>
+{"runtime.divide_by_zero"=>
+  {:key=>"runtime.divide_by_zero",
+   :path=>[],
+   :runtime_path=>[],
+   :category=>:runtime,
+   :symbol=>:divide_by_zero,
+   :message=>"Cannot divide by zero",
+   :context=>{},
+   :is_fatal=>false}}
+```
+
+Very similar behavior to before but this time it's a runtime error.
 
 ## Advanced Foobara
 
 ### Domain Mappers
 
+We should really move our various commands into their proper orgs/domains now for the remaining advanced/expert
+examples.
+
+In an integer_math_server.rb file, let's put Add/Subtract/Divide and expose them via HTTP:
+
+```ruby
+#!/usr/bin/env ruby
+
+require "foobara/rack_connector"
+require "rackup/server"
+
+module FoobaraDemo
+  foobara_organization!
+
+  module IntegerMath
+    foobara_domain!
+
+    class Add < Foobara::Command
+      ...
+end
+
+
+command_connector = Foobara::CommandConnectors::Http::Rack.new
+command_connector.connect(FoobaraDemo)
+
+Rackup::Server.start(app: command_connector)
+```
+
+Note: here we have just connected the entire organization. This is just a lazy way for us to expose all commands.
+
+Let's do the same for our capybara commands.
+In a capy_cafe_server.rb file, let's put CreateCapybara/IncrementAge/FindCapybara and expose them via HTTP:
+
+```ruby
+#!/usr/bin/env ruby
+
+require "foobara/local_files_crud_driver"
+require "foobara/rack_connector"
+require "rackup/server"
+
+crud_driver = Foobara::LocalFilesCrudDriver.new
+Foobara::Persistence.default_crud_driver = crud_driver
+
+module FoobaraDemo
+  foobara_organization!
+
+  module CapyCafe
+    foobara_domain!
+
+    class Capybara < Foobara::Entity
+      ...
+
+command_connector = Foobara::CommandConnectors::Http::Rack.new
+
+command_connector.connect(FoobaraDemo)
+
+Rackup::Server.start(app: command_connector, Port: 9293)
+```
+
+We'll start this one on 9293 since it will have the same URL as our integer math server.
+
+Now, let's come up with a contrived use-case for a domain mapper. Let's say there's some information about capybaras
+in some other model in some other domain that we could import into our CapyCafe domain.
+
+Let's code up such a domain/model in yet another file called capy_cafe_import.rb,
+let's set import our other two domains:
+
+```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
+```
+
+And now let's define an Animal model that could be imported into our CapyCafe domain as a Capybara record:
+
+```ruby
+module FoobaraDemo
+  module AnimalHouse
+    foobara_domain!
+
+    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
+```
+
+And now let's define a domain mapper that knows how to map an AnimalHouse::Animal to a CapyCafe::Capybara:
+
+```ruby
+module FoobaraDemo
+  module CapyCafe
+    foobara_depends_on AnimalHouse
+
+    class AnimalToCapybara < Foobara::DomainMapper
+      from AnimalHouse::Animal
+      to CreateCapybara
+
+      def map(animal)
+        age = birthday_to_age(animal.birthday)
+
+        {
+                name: "#{animal.first_name} #{animal.last_name}",
+                age:
+        }
+      end
+
+      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)
+
+        today < birthday_this_year ? age - 1 : age
+      end
+    end
+  end
+end
+```
+
+Note: that we have a bit of an unusual architecture here: we are defining CapyCafe commands in two different systems.
+A point of Foobara is that regardless of how these commands are distributed calling code doesn't change as this
+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
+
+```
+
+```ruby
+    class ImportAnimal < Foobara::Command
+      class NotACapybara < Foobara::DataError
+        context species: :symbol, animal: AnimalHouse::Animal
+
+        def message
+          "Can only import a capybara not a #{species}"
+        end
+      end
+
+      inputs animal: AnimalHouse::Animal
+      result Capybara
+
+      possible_input_error :animal, NotACapybara
+
+      depends_on CreateCapybara
+
+      def execute
+        create_capybara
+
+        capybara
+      end
+
+      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
+    end
+```
+
 TODO
 
 ### Code Generators
 
 #### Generating a new Foobara Ruby project
 #### Generating a new Foobara Typescript/React project
-#### Geerating commands, models, entities, types, domains, organizations, etc...
+#### Generating commands, models, entities, types, domains, organizations, etc...
 
 TODO
 

data/projects/domain/src/domain_mapper.rb

@@ -140,11 +140,15 @@ module Foobara
     end
 
     def call(from_value)
+      from_value = from_type.process_value!(from_value)
+
       mapped_value = map(from_value)
 
       to_type.process_value!(mapped_value)
     end
 
+    # TODO: can we make _from_value passed to #initialize instead? That way it doesn't have to be passed around
+    # between various helper methods
     def map(_from_value)
       # :nocov:
       raise "subclass repsonsibility"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foobara
 version: !ruby/object:Gem::Version
-  version: 0.0.34
+  version: 0.0.35
 platform: ruby
 authors:
 - Miles Georgi