flow 0.9.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 300011640bd90fa1ca5ac862e617d0bd297d4653680f03a518a71ee5dcc84e03
-  data.tar.gz: ca376a90cb8981bf509c90f4e1ed666add065cb8a952743904af0546b8844b40
+  metadata.gz: 8e881d33993ef70f023c82f8c595d77780487a67625c050849e1688c02dc4ccd
+  data.tar.gz: 7624fed517717e114ba494ce5ae93f252329ee704730a7579f02d4e20f7a53c7
 SHA512:
-  metadata.gz: 5cb710f38dd83e6b7ddb44f2c90235f3aea87f4270e2938a8ef4325ff72e2e281592d92663b51036d95d2617897d9c9eb05932245aa8486ef317ea4cc48fb415
-  data.tar.gz: 98d96900e861b15e13a3f30364628d1f0c8c55584e9e34cb400cd84b5f93c754325166370729997d324054d43aa3b721dc810d734c13850e7833ec36e286d2de
+  metadata.gz: 6a07515e6214de6df0e568d18d3a04692d59d99aa50d8b3fb2ed5f89d394ed4ee0d78dcff05aabd86780df8484f240ca3cb2213bb37ad4e4bc5f8a17ec48454e
+  data.tar.gz: 2d09e0ca74029c270ae49a73287eef064669a5924cfec2fcd8d72ccf959edc6fa49f9625a4aad393213f24a39d498f990ddb3b451d6e08e84e67699c9c1afe9e

data/README.md

@@ -13,7 +13,7 @@
    * [Operations](#operations)
    * [States](#states)
       * [Input](#input)
-      * [Mutable Data](#mutable-data)
+      * [Output](#output)
       * [Derivative Data](#derivative-data)
       * [State Concerns](#state-concerns)
       * [Validations](#validations)
@@ -21,9 +21,6 @@
    * [Exceptions](#exceptions)
    * [Failures](#failures)
    * [Callback Events](#callback-events)
-* [Reverting a Flow](#reverting-a-flow)
-   * [Undoing Operations](#undoing-operations)
-   * [Manual Revert](#manual-revert)
 * [Transactions](#transactions)
    * [Around a Flow](#around-a-flow)
    * [Around an Operation](#around-an-operation)
@@ -275,6 +272,23 @@ ExampleFlow.trigger(foo: :foo) # => ArgumentError (Missing argument: bar)
 ExampleFlow.trigger(foo: :foo, bar: :bar) # => #<ExampleFlow:0x00007ff7b7d92ae0 ...>
 ```
 
+By default, nil is a valid argument:
+
+```ruby
+ExampleFlow.trigger(foo: nil, bar: nil) # => #<ExampleFlow:0x10007ff7b7d92ae0 ...>
+```
+
+If you want to require a non-nil value for your argument, set the `allow_nil` option (`true` by default):
+
+```ruby
+class ExampleState < ApplicationState
+  argument :foo
+  argument :bar, allow_nil: false
+end
+
+ExampleFlow.trigger(foo: nil, bar: nil) # => ArgumentError (Missing argument: bar)
+```
+
 **Options** describe input which may be provided to define or override the initial state.
 
 Options can optionally define a default value. 
@@ -303,28 +317,57 @@ state.favorite_color # => "1a1f1e"
 state.favorite_foods # => ["avocado", "hummus" ,"nutritional_yeast"]
 ```
 
-#### Mutable Data
-    
-States can define objects specifically to be populated by operations as they run.
+#### Output
+
+Output data is created by Operations during runtime and CANNOT be validated or provided as part of the input. It can only be written once the state has been validated successfully, otherwise an error is raised.
+
+```ruby
+class ExampleState < ApplicationState
+  argument :name
+  
+  validates :name, length: { minimum: 3 }
+  output :foo
+end
+
+state = ExampleState.new(name: "fe")
+state.foo # => raises Flow::State::Errors::NotValidated
+state.foo = :something # => raises Flow::State::Errors::NotValidated
+
+state.valid? # => false
+state.foo # => raises Flow::State::Errors::NotValidated
+state.foo = :something # => raises Flow::State::Errors::NotValidated
 
-Mutable operation data is not technically distinct from other operation data.
+state.name = "fefifofum"
+state.valid? # => true
+state.foo # => nil
+state.foo = :something # => :something
+state.outputs.foo # :something
+```
+
+Outputs can optionally define a default value. 
+
+If no default is specified, the value will be `nil`.
 
-This section is really just a heads up that you can do things like this:
+If the default value is static, it can be specified in the class definition.
+
+If the default value is dynamic, you may provide a block to compute the default value.
+
+⚠️‍ **Heads Up**: The default value blocks **DO NOT** provide access to the state or it's other variables!
 
 ```ruby
 class ExampleState < ApplicationState
-  option :string_buffer, default: []
+  output :story, default: []
 end
 
 class AskAQuestion < ApplicationOperation
   def behavior
-    state.string_buffer << "Bah Bah, Black Sheep. Have you any wool?"
+    state.story << "Bah Bah, Black Sheep. Have you any wool?"
   end
 end
 
 class GiveAnAnswer < ApplicationOperation
   def behavior
-    state.string_buffer << "Yes sir, yes sir! Three bags full!"
+    state.story << "Yes sir, yes sir! Three bags full!"
   end
 end
 
@@ -332,75 +375,64 @@ class ExampleFlow < ApplicationFlow
   operations AskAQuestion, GiveAnAnswer
 end
 
-result = ExampleFlow.trigger(string_buffer: ["A conversation, for your consideration:"])
-result.state.string_buffer.join("\n")
-# A conversation, for your consideration:
+result = ExampleFlow.trigger
+result.outputs.story.join("\n")
 # Bah Bah, Black Sheep. Have you any wool?
 # Yes sir, yes sir! Three bags full! 
 ```
 
-If you are planning to create some object during your operation at runtime, use `attribute`:
+If you are creating something in your operation it's usually best practice to use [Transactions](#transactions) on either the Flow or Operation.
+
+🙅‍ *Don't Make This Mistake*: Output is meant to capture data generated at runtime. Do not define data that COULD have been fetched in a standard state method into output:
 
 ```ruby
-class ExampleState < ApplicationState
-  attribute :the_foo
+class BadState < ApplicationState
+  argument :foo
+  output :bar
 end
 
-class CreateFoo < ApplicationOperation
+class BadOperation < ApplicationOperation
   def behavior
-    state.the_foo = Foo.create!
-  end
-  
-  def undo
-    state.the_foo.destroy!
-    state.the_foo = nil
+    state.foo = Bar.where(foo: foo)
   end
 end
 ```
 
-If your attribute should have a default value, you can use a hook to define that default:
+Instead, always define data retrieval within the state and use output for created / generated data:
 
 ```ruby
-class ExampleState < ApplicationState
-  attribute :the_foo
-  set_callback(:initialize, :after) { self.the_foo = [] }
+class GoodState < ApplicationState
+  argument :foo
+  
+  output :gaz
+  
+  def bar
+    Bar.where(foo: foo)
+  end
+  memoize :bar
 end
-```
-
-Under the hood `attribute` uses `attr_accessor` so you could override the default reader instead:
 
-```ruby
-class ExampleState < ApplicationState
-  attribute :the_foo
-  
-  def the_foo
-    @the_foo ||= []
+class GoodOperation < ApplicationOperation
+  def behavior
+    state.gaz = Gaz.create!(name: foo.name, count: bar.count)
   end
 end
 ```
 
-Use whatever method seems more readable to you or appropriate to your use case!
+🚨 *Don't Make This Mistake Either*: You may feel you want to "combine" some of you input data so it shows up in the output hash. **Well don't!** Output narrowly refers to a specific type of runtime created data. It's **not** some kind "result" hash. (Technically, it's not even a hash at all, it's a [Struct](https://ruby-doc.org/core-2.6.2/Struct.html)!)
 
-💁‍ *Pro Tip*: You don't need to use `attribute` for mutable data, but you are highly encouraged to! If you do not use it, and opt instead of a simple `attr_accessor`, the value will not be output in the string.
+If you want to define an explicit results payload, do so explicitly:
 
 ```ruby
-class AccessorState < ApplicationState
-  attr_accessor :foo
-end
-
-class AttributeState < ApplicationState
-  attribute :foo
+class GoodState < ApplicationState
+  argument :foo
+  option :bar, default: :nar
+  output :gaz
+  
+  def results
+    outputs.to_h.dup.merge(foo: foo, bar: bar)
+  end
 end
-
-accr_state = AccessorState.new
-accr_state.foo = "some value!"
-accr_state.to_s # => #<AccessorState >
-accr_state.foo # => "some value!"
-
-attr_state = AttributeState.new
-attr_state.foo = "some value!"
-attr_state.to_s # => #<AttributeState foo="some value!">
-attr_state.foo # => "some value!"
 ```
 
 #### Derivative Data
@@ -675,6 +707,21 @@ operation_failure11.problem # => :too_generous
 operation_failure11.details.disappointment_level # => :wow_very_disappoint
 ```
 
+You can also specify `if:` / `unless:` options to proactively trigger failures as guard clauses:
+
+ ```ruby
+class PassBottlesAround < ApplicationOperation
+  failure :too_dangerous, if: -> { state.bottle_of == "tequila" }
+  failure :not_dangerous_enough, unless: :drink_dangerous?
+  
+  private
+  
+  def drink_dangerous?
+    %[water juice soda].exclude? state.bottle_of 
+  end
+end
+ ```
+
 ### Callback Events
 
 Operations feature error events which are triggered when a problem occurs.
@@ -715,119 +762,6 @@ class OperationThree < ApplicationOperation
 end
 ```
 
-## Reverting a Flow
-
-![Flow Revert](docs/images/revert.png)
-
-When something goes wrong in Flow `#revert` is called. 
-
-This calls `#rewind` on Operations to `#undo` their behavior.
-
-Reverting a Flow rewinds all its executed operations in reverse order (referred to as an **ebb**).
-
-Reverting is automatic and happens by default. You cannot opt out of the revert process, but you can choose to not define any `#undo` methods on your Operations.
- 
-```ruby
-class ExampleState < ApplicationState; end
-
-class GenericOperation < ApplicationOperation
-  def behavior
-    puts "#{self.class.name}#behavior"
-  end
-  
-  def undo
-    puts "#{self.class.name}#undo"
-  end
-end
-
-class ExampleFlow < ApplicationFlow
-  operations OperationOne, OperationTwo, OperationThree, OperationFour
-end
-
-class OperationOne < GenericOperation; end
-class OperationTwo < GenericOperation; end
-class OperationThree < GenericOperation
-  failure :bad_stuff
-  
-  def behavior
-    super
-    bad_stuff_failure!
-  end
-end
-class OperationFour < GenericOperation; end
-
-ExampleFlow.trigger
-
-# Prints:
-#  OperationOne#behavior
-#  OperationTwo#behavior
-#  OperationThree#behavior
-#  OperationTwo#undo
-#  OperationOne#undo
-```
-
-⚠️ **Heads Up**: For the Operation that failed, `#undo` is **NOT** called. Only operations which execute successfully can be undone.
-
-### Undoing Operations
-
-```ruby
-class ReserveQuantity < ApplicationOperation
-  delegate :product, :quantity, to: :state
-  delegate :available_inventory_count, to: :product
-  
-  def behavior
-    product.update!(available_inventory_count: available_inventory_count - quantity)
-  end
-  
-  def undo
-    product.update!(available_inventory_count: available_inventory_count + quantity)
-  end
-end
-```
-
-💁‍ *Note*: If you omit the `#undo`, a revert will essentially pass over that Operation. 
-
-If your Operation should not be undone and you want it to halt reverting, call a defined failure in `#undo`.
-
-```ruby
-class ExampleOperation < ApplicationOperation
-  failure :irreversible_behavior
-  
-  def behavior
-    PurchaseService.charge_customer(state.customer)
-  end
-  
-  def undo
-    irreversible_behavior_failure!
-  end
-end
-```
-
-### Manual Revert
-
-Flows in which an error occur are reverted automatically.
-
-You can also manually revert a completed flow, even if it was fully successful.
-
-```ruby
-class ExampleFlow < ApplicationFlow
-  operations OperationOne, OperationTwo, OperationThree, OperationFour
-end
-
-flow = SomeExampleFlow.trigger
-#  OperationOne#behavior
-#  OperationTwo#behavior
-#  OperationThree#behavior
-#  OperationFour#behavior
-flow.success? # => true
-flow.revert
-#  OperationFour#undo
-#  OperationThree#undo
-#  OperationTwo#undo
-#  OperationOne#undo
-flow.reverted? # => true
-```
-
 ## Transactions
 
 ![Flow Transactions](docs/images/transaction.png)
@@ -836,8 +770,6 @@ Flow features a callback driven approach to wrap business logic within database
 
 Both **Flows** and **Operations** can be wrapped with a transaction.
 
-🚨 *Be Aware*: Unless otherwise specified, transactions apply to **both** success **and** failure cases. You can pass `only:` or `except:` options to `wrap_in_transaction` to alter this behavior.
- 
 ### Around a Flow
 
 Flows where no operation should be persisted unless all are successful should use a transaction.
@@ -850,18 +782,6 @@ class ExampleFlow < ApplicationFlow
 end
 ```
 
-Flows can transaction wrap `:flux` (caused by `#trigger`) or `:ebb` (caused by `#revert`).
-
-```ruby
-class ExampleFlow < ApplicationFlow
-  wrap_in_transaction only: :flux
-end
-
-class ExampleFlow < ApplicationFlow
-  wrap_in_transaction except: :ebb
-end
-```
-
 ### Around an Operation
 
 Operations which modify several persisted objects together should use a transaction.
@@ -876,32 +796,32 @@ class OperationTwo < ApplicationFlow
 end
 ```
 
-Operations can transaction wrap `:behavior` or `:undo`.
+## Statuses
 
-```ruby
-class ExampleOperation < ApplicationOperation
-  wrap_in_transaction only: :behavior
-end
+Flows, Operations, and States all have a set of predicate methods to describe their current status.
 
-class ExampleOperation < ApplicationOperation
-  wrap_in_transaction except: :undo
-end
-```
+### Flows
 
-## Statuses
+| Status       | Description               |
+| ------------ | ------------------------- |
+| `pending?`   | `#trigger` not called.    |
+| `triggered?` | `#trigger` was called.    |
+| `failed?`    | Some operation failed.    |
+| `success?`   | All operations succeeded. |
 
-Flows and Operations each have a set of predicate methods to describe their current status.
+### Operations
+
+| Status       | Description               |
+| ------------ | ------------------------- |
+| `executed?`  | `#execute` was called.    |
+| `failed?`    | Execution failed.         |
+| `success?`   | Execution succeeded.      |
 
-| Object    | Status       | Description               |
-| --------- | ------------ | ------------------------- |
-| Operation | `executed?`  | `#execute` was called.    |
-| Operation | `failed?`    | Execution failed.         |
-| Operation | `success?`   | Execution succeeded.      |
-| Flow      | `pending?`   | `#trigger` not called.    |
-| Flow      | `triggered?` | `#trigger` was called.    |
-| Flow      | `failed?`    | Some operation failed.    |
-| Flow      | `success?`   | All operations succeeded. |
-| Flow      | `reverted?`  | `#revert` was called.     |
+### States
+
+| Status       | Description               |
+| ------------ | ------------------------- |
+| `validated?` | `#vaild?` returned true.  |
 
 ## Utilities
 
@@ -912,7 +832,7 @@ Flow offers a number of utilities which allow you to tap into and extend it's fu
 Flows, Operations, and States all make use of [ActiveSupport::Callbacks](https://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html) to compose advanced functionality.
 
 ```ruby
-class TakeBottlesDown < OperationBase
+class TakeBottlesDown < ApplicationOperation
   set_callback(:execute, :before) { bottle_count_term }
   set_callback(:execute, :after) { state.output.push("You take #{bottle_count_term} down.") }
   
@@ -934,13 +854,9 @@ The callbacks which are available on each class are:
 | Flow          | `:initialize` | When a new flow is being constructed.  |
 | Flow          | `:trigger`    | When `#trigger` is called on a flow.   |
 | Flow          | `:flux`       | When `#trigger` is called on a flow.   |
-| Flow          | `:revert`     | When `#revert` is called on a flow.    |
-| Flow          | `:ebb`        | When `#revert` is called on a flow.    |
 | State         | `:initialize` | When a new state is being constructed. |
 | Operation     | `:execute`    | When `#execute` is called.             |
 | Operation     | `:behavior`   | When `#execute` is called.             |
-| Operation     | `:rewind`     | When `#rewind` is called.              |
-| Operation     | `:undo`       | When `#rewind` is called.              |
 | Operation     | `:failure`    | When any type of error occurs.         |
 | Operation     | `$problem`    | When an error of type $problem occurs. |
 
@@ -951,7 +867,7 @@ Flow includes the very awesome [ShortCircuIt](https://github.com/Freshly/spicera
 To leverage it, just add `memoize :method_name` to your Flows, Operations, or States.
 
 ```ruby
-class TakeBottlesDown < OperationBase
+class TakeBottlesDown < ApplicationOperation
   def bottle_count_term
     return "it" if state.bottles.number_on_the_wall == 1
     return "one" if state.taking_down_one?
@@ -979,7 +895,7 @@ The gems adds methods to Flows, Operations, and States which share names with lo
 | `fatal` | Highly actionable and critical issues. |
 
 ```ruby
-class ExampleOperation < OperationBase
+class ExampleOperation < ApplicationOperation
   def behavior
     warn(:nothing_to_do, { empty_object: obj }) and return if obj.empty? 
     
@@ -1091,10 +1007,15 @@ end
 ```
 
 This will allow you to use the following custom matchers:
- * [define_argument](lib/flow/custom_matchers/define_argument.rb)
- * [define_attribute](lib/flow/custom_matchers/define_attribute.rb)
- * [define_option](lib/flow/custom_matchers/define_option.rb)
- * [use_operations](lib/flow/custom_matchers/use_operations.rb)
+ * [define_argument](lib/flow/custom_matchers/define_argument.rb) tests usage of `ApplicationState.argument`
+ * [define_attribute](lib/flow/custom_matchers/define_attribute.rb) tests usage of `ApplicationState.attribute`
+ * [define_failure](lib/flow/custom_matchers/define_failure.rb) tests usage of `ApplicationOperation.failure`
+ * [define_option](lib/flow/custom_matchers/define_option.rb) tests usage of `ApplicationState.option`
+ * [define_output](lib/flow/custom_matchers/define_output.rb) tests usage of `ApplicationState.output`
+ * [handle_error](lib/flow/custom_matchers/handle_error.rb) tests usage of `ApplicationOperation.handle_error`
+ * [use_operations](lib/flow/custom_matchers/use_operations.rb) tests usage of `ApplicationFlow.operations`
+ * [wrap_in_transaction](lib/flow/custom_matchers/wrap_in_transaction.rb) tests usage of `.wrap_in_transaction` for `ApplicationFlow` or `ApplicationOperation`
+ * [have_on_state](lib/flow/custom_matchers/have_on_state.rb) tests for data on State after a `ApplicationFlow` or `ApplicationOperation` has been run
 
 ### Testing Flows
 
@@ -1124,14 +1045,6 @@ RSpec.describe FooFlow, type: :flow do
  
     pending "describe the effects of a successful `Flow#flux` (or delete) #{__FILE__}"
   end
- 
-  describe "#revert" do
-    before { flow.trigger! }
- 
-    subject(:revert) { flow.revert }
- 
-    pending "describe the effects of a successful `Flow#ebb` (or delete) #{__FILE__}"
-  end 
 end
 ```
 
@@ -1151,11 +1064,13 @@ require "rails_helper"
 RSpec.describe MakeTheThingDoTheStuff, type: :operation do
   subject(:operation) { described_class.new(state) }
 
-  let(:state) { example_state_class.new(**state_input) }
+  let(:state) { example_state_class.new(**state_input).tap(&:validate) }
   let(:example_state_class) do
     Class.new(ApplicationState) do
       # argument :foo
       # option :bar
+      # attribute :baz 
+      # output :gaz 
     end
   end
   let(:state_input) do
@@ -1164,19 +1079,11 @@ RSpec.describe MakeTheThingDoTheStuff, type: :operation do
 
   it { is_expected.to inherit_from ApplicationOperation }
 
-  describe "#execute!" do
-    subject(:execute!) { operation.execute! }
+  describe "#execute" do
+    subject(:execute) { operation.execute }
   
     pending "describe `Operation#behavior` (or delete) #{__FILE__}"
   end
-  
-  describe "#rewind" do
-    before { operation.execute! }
-  
-    subject(:execute!) { operation.rewind }
-  
-    pending "describe `Operation#undo` (or delete) #{__FILE__}"
-  end
 end
 ```
 
@@ -1189,6 +1096,8 @@ let(:example_state_class) do
   Class.new(ApplicationState) do
     # argument :foo
     # option :bar
+    # attribute :baz
+    # output :gaz
   end
 end
 ```
@@ -1211,6 +1120,7 @@ let(:example_state_class) do
     argument :foo
     option :bar
     attribute :baz
+    output :gaz
   end
   
   let(:state_input) do
@@ -1220,7 +1130,31 @@ let(:example_state_class) do
   let(:foo) { ... }
   let(:bar) { ... }
 end
-``` 
+```
+
+You are encouraged to use `execute`, rather than `execute!` in testing. You can trust that if an `operation_failure` is present, the operation _would_ have raised an `Operation::Failures::OperationFailure` if you used `execute!`.
+
+Doing so will allow you to make assertions on the failure without having to expect errors:
+```ruby
+class SomeOperation < ApplicationOperation
+  failure :somethings_invalid
+
+  def behavior
+    somethings_invalid_failure! baz: "relevant data" if state.foo == "something invalid"
+  end
+end
+```
+
+```ruby
+let(:state_input) { foo: "something invalid" }
+
+before { operation.execute }
+
+it "fails with the expected data" do
+  expect(operation.operation_failure.problem).to eq :somethings_invalid
+  expect(operation.operation_failure.details.baz).to eq "relevant data"
+end
+```
 
 ### Testing States
 
@@ -1234,19 +1168,17 @@ States are generated with the following RSPec template:
 require "rails_helper"
 
 RSpec.describe FooState, type: :state do
-  subject(:state) { described_class.new(**input) }
-
-  let(:input) do
-    {}
-  end
+  subject(:state) { described_class }
 
   it { is_expected.to inherit_from ApplicationState }
-  # it { is_expected.to define_argument :foo }
-  # it { is_expected.to define_option(:foo) }
-  # it { is_expected.to define_option(:foo).with_default_value(:bar) }
-  # it { is_expected.to define_option(:foo).with_default_value_block }
+  # it { is_expected.to define_argument :required_input }
+  # it { is_expected.to define_argument :necessary_input, allow_nil: false }
+  # it { is_expected.to define_option(:optional_input) }
+  # it { is_expected.to define_option(:option_with_default, default: :default_static_value) }
+  # it { is_expected.to define_option(:option_with_default_from_block, default: default_block_value) }
   # it { is_expected.to validate_presence_of ... }
-  # it { is_expected.to define_attribute :foo }
+  # it { is_expected.to define_output :foo }
+  # it { is_expected.to define_output :foo, default: :bar }
 end
 ```